knowledge-platform/docs/development/OCEANBASE_VECTOR_SETUP.md
2026-09-02 11:28:13 +08:00

73 lines
3.5 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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=<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)