knowledge-platform/docs/development/OCEANBASE_VECTOR_SETUP.md

3.5 KiB
Raw Permalink Blame History

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 在专用数据库中创建索引表。脚本固定:

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、 镜像、日志、测试快照或提交记录。

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 的受控资源中验证。凭据只能在运行时 临时注入,禁止进入仓库、日志或测试快照。

官方参考: