knowledge-platform/docs/development/RERANKER_SETUP.md
2026-09-01 16:10:14 +08:00

2.7 KiB
Raw Blame History

DEMO-008 千帆 Reranker 与 Source Result 配置

本文记录 Knowledge Platform Demo 的重排序连接方式、请求边界和 canonical Source Result 契约。真实 API Key 只允许由运行环境注入,不得写入代码、示例配置、日志或提交记录。

运行配置

RERANKER_PROVIDER=qianfan
RERANKER_MODEL=qwen3-reranker-0.6b
RERANKER_ENDPOINT=https://qianfan.baidubce.com/v2/rerank
RERANKER_API_KEY=<运行环境注入,可空>
RERANKER_TIMEOUT_SECONDS=30
DENSE_TOP_N=20
SEARCH_TOP_K=5

RERANKER_API_KEY 未单独配置时,Demo 会复用 BAIDU_QIANFAN_API_KEY。两者都不存在时 Provider 创建失败。凭证使用 SecretStr,HTTP/JSON 异常不会包含请求头、请求正文或 响应正文。

Reranker 请求契约

DEMO-008 固定使用千帆 POST /v2/rerank,模型基线为 qwen3-reranker-0.6b:

  • Query 去除首尾空白后不能为空,最多 1600 字符;
  • documents 不能为空,最多 64 条,每条最多 4096 字符;
  • 当前标准链路发送 Dense Top20,并请求 Reranker Top5;
  • 响应必须恰好返回请求的 Top-N,index 唯一且指向原输入位置;
  • relevance_score 必须是有限数值,并保持降序;
  • 响应若回显 document,必须与对应输入文本完全一致。

Adapter 只向业务层返回原候选索引和 Reranker 分数,不暴露千帆响应结构。默认测试使用 FakeRerankerProvider 的确定性字符覆盖率排序,不发起网络请求。

Source Result 契约

Reranker 对 Mochow Dense Candidate 的 content 评分;选出 Top5 后,SearchService 使用 chunk_id 一次性回查 PostgreSQL canonical chunks 表,并由 canonical row 生成:

document_id
filename
page
section
chunk_id
content
score
rerank_score

其中 score 保留 Dense 分数,rerank_score 保存精排分数。若 Chunk 缺失、document_id 不一致或 Mochow content 已与 canonical content 不一致,搜索会失败关闭,避免返回来源与 评分文本不一致的结果。

DEMO-009 已通过 POST /api/v1/search 提供序列化和错误映射,参见 docs/development/REST_API_SETUP.md。Demo 仍不实现 RBAC/Document ACL,正式 V1 权限 范围必须在 Dense 召回阶段下推,不能在 Reranker 后过滤。

验证边界

默认测试离线覆盖 Dense Top20 → Reranker → Top5 → canonical Source Result,并使用合成 Golden Dataset 验证预期文档和章节升至首位。真实千帆联调前还需在受控运行环境确认:

  • API Key 已开通目标 Reranker 模型权限;
  • Endpoint 网络可达;
  • 模型 API 名称与控制台服务一致;
  • 真实中文 Query 的延迟、配额和 Top5 质量满足 Demo 演示需求。