Google Developer Knowledge API 新增 relevance_score 怎么用：过滤、排序与回归验收

Google Developer Knowledge API 最近的更新，对做官方文档检索的开发团队非常实用：DocumentChunk 新增了 relevance_score，AnswerQueryRequest 也增加了 filter。前者可以直观判断单条结果和用户查询的匹配程度，后者能提前收紧进入回答链路的候选结果范围。这两项新能力目前都要按照 v1alpha 版本的特性波动要求来做验收校验。

这次更新解决了什么问题

之前做文档检索场景时，开发者拿到的返回结果往往只有零散的内容块，只能靠经验做截断、重排或者追加补查逻辑。现在每个 DocumentChunk 都附带 0.0 到 1.0 区间的相关性分数，能把之前全靠经验判断的「候选结果是否匹配查询」变成可沉淀、可回溯的量化信号。

官方在 2026 年 8 月 7 日的更新日志里同步列出了 AnswerQueryRequest.filter 相关说明。两个能力的定位要区分开：相关性分数用来描述单条结果和查询的匹配程度，filter 参数用来限定请求侧允许进入后续回答链路的结果准入范围。

最小试用：先把分数当作排序信号

如果你正在对接 SearchDocumentChunks，刚上手的时候不用急着把阈值写死。可以先完整保存返回结果里的文档 URI、chunk 标识和 relevance_score，默认按照分数从高到低做排序展示：

chunk.uri              relevance_score
docs.example.dev/a     0.91
docs.example.dev/b     0.63
docs.example.dev/c     0.24

整理出来的结果表可以直接验证两个核心问题：查询条件调整之后，排在前列的结果排序是否稳定；同一篇源文档更新之后，对应的所有结果分数会不会出现整体性的漂移。千万不要直接把 0.8 的分值等同于「回答正确率 80%」，它只是 API 侧给出的参考相关性信号。

阈值和过滤怎么配合

一套可落地的灰度上线方案可以参考：先全量记录所有返回分数不做任何拦截，确认分布规律之后再把阈值作为候选结果的缩减条件，最后用人工标注集或者固定测试问题集校验最终回答效果。阈值设置得越高，符合条件的候选结果数量越少；阈值设置得越低，结果召回范围越广，但无关文档也更容易被误放进后续生成回答的上下文里。

filter 的具体编写规则要以当前版本的 API reference 为准，不要直接照搬其他 Google Cloud 服务的过滤语法直接复用，避免报错。

把更新放进回归测试

• 固定选取 20 到 50 个真实的业务开发场景问题，提前记录对应的基准答案、引用文档和内容块的基准分数。
• 对每个测试问题完整保留 top-k 的返回结果，对比版本更新前后首位匹配结果的变化情况。
• 把 filter 参数开启和关闭两种状态分别跑一遍测试，确认无关的域名或者非目标文档不会混入候选集。
• 针对返回空结果、结果分值过低、接口字段缺失这三类异常场景提前做好降级处理。
• 全程监控接口响应延迟和上下文占用长度，不要为了盲目拉高召回率把调用成本推到不合理的区间。

AnswerQuery 已经在 2026 年 7 月 17 日正式进入 GA 稳定阶段，但本次新增的相关字段在发布说明里仍标注为 v1alpha 预览属性。上线时建议把响应解析逻辑做成兼容模式：对应字段存在就正常记录，字段临时缺失也不会打断主流程继续执行。

命令行入口和 API 入口的关系

官方更新记录同时说明，2026 年 8 月 18 日 gcloud alpha developer-knowledge 对应的命令行工具已经开放可用，覆盖了 answer-query、documents describe 和 documents search-chunks 几类操作。对人工调试复查非常友好：可以先用命令行快速验证数据源和返回结果的正确性，确认逻辑没问题之后再把固化的检查项集成到业务侧的 API 客户端里。

命令行适合快速复现问题排查现场，但服务端正式集成的时候还是要以 REST 或 RPC reference 的字段定义为准。不要把两套通道的返回字段、认证规则、版本号逻辑混写在一起，避免出问题。

常见问题

relevance_score 是准确率吗？

不是。它是 0.0 到 1.0 的相关性信号，适合排序和检索观察，不能直接代表回答正确率。

应该一开始就设置很高的阈值吗？

不建议。先记录分数分布，再用固定问题集评估召回和精度，最后选择业务能接受的阈值。

AnswerQuery 的 filter 能过滤所有业务字段吗？

不能直接推断。过滤语法和可用字段由当前接口 reference 决定，需按实际版本测试。

AnswerQuery GA 后还需要兼容 v1alpha 字段吗？

需要。稳定的端点和新增的预览字段是两个维度，解析器仍应容忍新增字段暂时缺失或形状变化。

这次更新上手最优先做的事不是上来就把阈值硬编码写死，而是把相关性分数统计、过滤规则校验、答案来源引用核查、固定问题集测试这几个环节串成完整的回归校验链路。等分数分布规律摸清楚、候选结果范围的逻辑完全可解释之后，再把这套能力推到生产环境的回答流程里。