# ARCH-003 OceanBase Vector 配置与索引契约 ARCH-003 在既有 `VectorStore` 契约后新增 OceanBase Vector Adapter。PostgreSQL 仍保存 canonical Document、Chunk、Index Profile 和 Chunk Index State;OceanBase 表只保存可由这些 数据重建的检索行。ARCH-005 已完成运行时默认切换,并移除 Mochow 运行配置与依赖。 ## 数据库前提 - OceanBase MySQL 租户版本至少为 4.6.0:1024 维 Cosine HNSW 本身可由更早版本支持, 但本项目要求使用 `VECTOR_INDEX(... pre_filter)` 显式保证 Profile 在 ANN 前过滤; - 目标数据库和最小权限账号由受控部署流程预创建; - 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= 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)