3.9 KiB
DEMO-006/007 千帆与 Mochow 配置
本文记录 Knowledge Platform Demo 的安全连接方式和 Mochow 表契约。配置参考现有
Embedding与数据库配置说明.md,但不复制其中的环境地址或任何凭证。
Canonical 数据库
本项目继续使用 DATABASE_URL 连接 PostgreSQL。参考项目中的 MySQL 配置不适用于
本仓库,也不会替换 Accepted ADR 中的 PostgreSQL canonical storage。
千帆 Embedding
EMBEDDING_PROVIDER=qianfan
EMBEDDING_MODEL=bge-large-zh
EMBEDDING_ENDPOINT=https://qianfan.baidubce.com/v2/embeddings
BAIDU_QIANFAN_API_KEY=<运行环境注入>
EMBEDDING_TIMEOUT_SECONDS=30
bge-large-zh 固定输出 1024 维向量。Adapter 将每次请求限制为最多 16 条,并校验
输入字符数、响应数量、顺序、维度和有限数值。API Key 使用 SecretStr 保存,异常中
不记录请求头、请求正文或响应正文。
Mochow 连接
VECTOR_STORE_PROVIDER=mochow
BAIDU_MOCHOW_ACCOUNT=root
BAIDU_MOCHOW_API_KEY=<运行环境注入>
BAIDU_MOCHOW_ENDPOINT=<已授权实例地址>
KNOWLEDGE_VDB_DB_NAME=<专用数据库名>
MOCHOW_TABLE=knowledge_chunks
MOCHOW_BATCH_SIZE=100
MOCHOW_SEARCH_EF=200
MOCHOW_TIMEOUT_SECONDS=30
INDEX_PROFILE_ID=demo-bge-large-zh-structure-v1
DENSE_TOP_N=20
配置说明中的 endpoint 可作为运行环境的值,但不得提交到 .env.example 或代码。
建议为本 Demo 使用独立表,禁止直接写入字段契约未知的既有业务表。
Mochow 表契约
MOCHOW_TABLE 必须由受控的部署/运维步骤预先创建。应用不会在启动或入库时隐式创建、
修改或删除数据库结构。
| 字段 | Mochow 类型 | 要求 |
|---|---|---|
index_record_id |
STRING | 主键、分区键、非空;由 Chunk/profile 确定性生成 |
chunk_id |
STRING | 非空 |
document_id |
STRING | 非空,建议建立过滤索引 |
filename |
STRING | 非空 |
page |
UINT32 | 可空,一基页码 |
page_end |
UINT32 | 可空,一基页码 |
section |
TEXT | 可空 |
chunk_index |
UINT32 | 非空 |
content |
TEXT | 非空 |
embedding |
FLOAT_VECTOR | 非空,dimension=1024 |
embedding_model |
STRING | 非空 |
index_profile_id |
STRING | 非空,建议建立过滤索引 |
向量字段建议建立 HNSW/COSINE 索引。document_id 与 index_profile_id 必须支持标量
过滤,以便失败补偿和后续按文档删除。切换模型或 Chunk 策略时应使用新的
INDEX_PROFILE_ID 和 shadow index,不得原地覆盖已记录的 profile。
Dense Retrieval 契约
DEMO-007 使用同一 EmbeddingProvider 将 Query 转换为 1024 维向量,然后调用 Mochow
VectorTopkSearchRequest:
- 向量字段固定为
embedding; - 默认
DENSE_TOP_N=20,调用方可在 1~1000 范围内覆盖; - HNSW 搜索候选参数默认
MOCHOW_SEARCH_EF=200,运行时至少提升到本次 Top-N; index_profile_id过滤随 Dense Search 请求下推,禁止混入其他模型/Chunk 版本;- 返回值是尚未 Rerank 的候选集,
score原样保留 Mochow 返回值,不在此阶段设置阈值。
Demo 明确不实现 RBAC/Document ACL;正式 V1 引入权限后,允许范围仍必须在召回阶段下推,
不得先做全局 Top-K 再过滤。Reranker 与最终 Source Result 的配置参见
docs/development/RERANKER_SETUP.md;REST API 参见
docs/development/REST_API_SETUP.md。
验证边界
默认测试使用 FakeEmbeddingProvider 和 FakeVectorStore,不访问互联网或生产凭证。
真实联调前需确认:专用表已按上述 Schema 创建、1024 维向量索引正常、Endpoint 网络
可达、运行身份拥有 upsert/delete/vector_search 权限。默认回归已离线验证 Query
Embedding → profile 过滤 → Dense Top20 及来源元数据保持;真实 Mochow 的网络联调需要由
受控运行环境注入凭证后单独执行。