73 lines
3.5 KiB
Markdown
73 lines
3.5 KiB
Markdown
# ARCH-003 OceanBase Vector 配置与索引契约
|
||
|
||
ARCH-003 在既有 `VectorStore` 契约后新增 OceanBase Vector Adapter。ARCH-006 确认 OceanBase
|
||
MySQL 关系表保存 canonical Document、Chunk、Index Profile 和 Chunk Index State;同库向量表
|
||
只保存可由这些数据重建的检索行。ARCH-005 已完成运行时默认切换,并移除 Mochow 运行配置与依赖。
|
||
|
||
## 数据库前提
|
||
|
||
- OceanBase MySQL 租户版本至少为 4.3.5.4:ARCH-006 已在目标 test 集群用只读
|
||
`EXPLAIN` 验证 `VECTOR_INDEX(... pre_filter)` 产生 PRE-FILTER 执行计划;
|
||
- 目标数据库和最小权限账号由受控部署流程预创建;
|
||
- Vector 内存、资源规格和 HNSW 参数由 DBA 在受控环境确认;
|
||
- 应用启动和请求路径不会创建、修改或删除表结构。
|
||
|
||
使用 [001_knowledge_chunks_v1.sql](../../deploy/oceanbase/001_knowledge_chunks_v1.sql)
|
||
在专用数据库中创建索引表。脚本固定:
|
||
|
||
```text
|
||
VECTOR(1024)
|
||
DISTANCE = COSINE
|
||
TYPE = HNSW
|
||
EF_CONSTRUCTION = 256
|
||
EF_SEARCH = 200
|
||
```
|
||
|
||
表的 `index_record_id` 是确定性的 Chunk/Profile 主键;`document_id + index_profile_id` 和
|
||
`index_profile_id` 是清理与 Profile 过滤的标量索引。表名或向量维度变化必须建立新表或
|
||
Shadow Profile,验证后再激活,禁止在生产索引上原地修改。
|
||
|
||
## 运行配置
|
||
|
||
配置只能由部署环境或 Secret Manager 注入,禁止把真实地址、用户名和密码写入 `.env`、
|
||
镜像、日志、测试快照或提交记录。
|
||
|
||
```text
|
||
VECTOR_STORE_PROVIDER=oceanbase
|
||
OCEANBASE_VECTOR_URI=<host:port>
|
||
OCEANBASE_VECTOR_USER=<运行时注入>
|
||
OCEANBASE_VECTOR_PASSWORD=<运行时注入>
|
||
OCEANBASE_VECTOR_DATABASE=<预创建数据库>
|
||
OCEANBASE_VECTOR_TABLE=knowledge_chunks_v1
|
||
OCEANBASE_VECTOR_INDEX=vidx_knowledge_chunks_embedding
|
||
OCEANBASE_VECTOR_BATCH_SIZE=100
|
||
OCEANBASE_VECTOR_TIMEOUT_SECONDS=30
|
||
```
|
||
|
||
- URI 只接受 `host:port`,不得包含 Scheme、用户信息、Path、Query 或 Fragment;
|
||
- Database/Table/Index 只接受安全标识符;
|
||
- Password 使用 `SecretStr`,Provider 异常只返回收敛后的错误,不回显 SQL、连接信息、
|
||
Chunk 内容或 SDK Response;
|
||
- `pyobvector` 只存在于 Adapter/Factory 内,业务服务不依赖其 Row、Engine 或距离函数类型。
|
||
|
||
## 写入、删除和检索语义
|
||
|
||
- Upsert 使用 `index_record_id` 主键,按可配置批次写入;
|
||
- 删除使用参数化的 `document_id + index_profile_id` 条件,不拼接用户输入;
|
||
- Dense Search 在同一 ANN 查询中使用 `VECTOR_INDEX(... pre_filter)`,保证
|
||
`index_profile_id` 在候选近邻搜索前过滤,并返回 Dense Top20;禁止依赖普通 `WHERE`
|
||
的自适应过滤语义,也禁止全局 TopK 后再过滤;
|
||
- OceanBase `cosine_distance` 是低值优先距离,Adapter 统一转换为
|
||
`score = 1 - cosine_distance`,保持 `VectorStore` 的高分优先契约;
|
||
- 返回 UUID、Profile、字段数、距离范围和排序不满足契约时失败关闭,不生成 Source Result。
|
||
|
||
默认测试使用 Fake Client,不连接 OceanBase。真实版本、DDL、权限、Cosine HNSW 召回、过滤
|
||
行为与 30~50 条脱敏 Golden Query 统一在 ARCH-006 的受控资源中验证。凭据只能在运行时
|
||
临时注入,禁止进入仓库、日志或测试快照。
|
||
|
||
官方参考:
|
||
|
||
- [pyobvector 官方仓库](https://github.com/oceanbase/pyobvector)
|
||
- [OceanBase 创建向量索引](https://en.oceanbase.com/docs/common-oceanbase-database-10000000003075357)
|
||
- [OceanBase 向量索引查询 Hint](https://en.oceanbase.com/docs/common-oceanbase-database-10000000004311163)
|