2026-09-01 16:10:14 +08:00

3.9 KiB
Raw Blame History

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 的网络联调需要由 受控运行环境注入凭证后单独执行。