第二篇介绍了 v3 Agent 的工具循环。Agent 有八个工具,其中两个用来查参考库:search_library 搜索候选,get_entry 读取详情。这篇讲参考库的检索机制:800 条条目,五层打分器,以及每一层为什么存在。
两段式检索#
Agent 在建造过程中可以查一个参考库。库里有两类条目。Part 是可直接放置的体素构件,比如一扇窗户、一棵树或一座风车塔。详情里附有 place_component 的用法说明,Agent 可以直接在建造中放置。Ref 是整景参考卡,提供体量、配色和工艺信息,供 Agent 参考设计方向。当前库有 800 个条目:737 个体素 stamp、11 个参数化构件、42 张整景参考卡和 10 张风格卡。
检索分两步。第一步调 search_library,系统打分排序后返回两组摘要列表:Part 至多 6 条,Ref 至多 2 条。每条结果包含条目 id、证据类型和一行摘要。第二步,Agent 根据摘要判断哪些条目值得细看,对感兴趣的条目调 get_entry 读取全文。风格卡通过另一条路径随建造意图注入,不参与检索排序。
有参考库之后,模型在需要现成构件时可以直接搜索和放置,减少逐块描述已知结构的工作量。
五层打分器#
一次搜索的总分由五项信号叠加。
id 匹配。 如果查询包含某个条目的完整 id 或其空格形式,该条目得 +3 分。查 windmill tower 能精确命中 windmill-tower。
关键词。 每个条目有一组从标题、标题拆词、标签和策展字段派生的关键词。查询逐项匹配,每命中一个加 2 分,不设上限。英文匹配使用词边界,大小写不敏感。
BM25 正文。 对查询和条目的索引文本做 BM25 打分。BM25 通过文档频率区分稀有词和常见词,通过词频饱和和文档长度归一化排序。原始 BM25 分在当前候选集内按最高分归一化到 0 至 2。后面会展开为什么用 BM25 替换了早期的子串匹配。
条件。 与查询的类别相同加 2,风格相同加 3,没有标注类别的通用条目加 1。条件分同时参与已有命中的排序和零命中时的回退。
语义余弦。 查询和条目映射到同一个嵌入空间,1024 维,L2 归一化后用点积计算余弦。余弦低于 0.32 的候选不参与语义计分。达到门槛的候选在当前集合内按最高余弦相似度归一化,上限 3 分。语义层的设计和实验结果在后面单独展开。
最终加权公式:
3I + 2K + 2B/Bmax + cond + 3C/Cmaxplaintext分母为零时该项取零。同分按条目类型和 id 排序。
返回结果标注四种证据类型:词法命中、语义命中、两者兼有、条件回退。语义命中的构件会提示 Agent 先核对身份再放置,条件回退明确说明与查询没有直接匹配。Part 列表和 Ref 列表各自独立排序,共享同一次查询嵌入和 BM25 索引。当某类候选中完全没有查询命中时,才从条件分大于零的条目中选取回退结果。
评测集与指标#
评测用 50 条人工标注的查询,按用途分成六个互不重叠的类别。
| 类别 | 用例数 | 计分数 | 观察目标 |
|---|---|---|---|
| direct | 8 | 8 | 名称查询 |
| lexical | 11 | 11 | 正文词汇 |
| semantic | 10 | 10 | 描述与条目用词差异 |
| zh | 6 | 6 | 中文查询 |
| conditioned | 7 | 6 | 类别和风格条件 |
| negative | 8 | 2 | 禁止结果和空集 |
50 条查询中 43 条有相关集并参与均值计算。hit@6 是前六条结果中包含至少一个标注相关条目的查询占比。MRR 是首个相关结果的倒数排名在 43 条上的平均值,未命中记 0。归一化 recall 以相关集大小和实际返回数的较小值为分母。
production 视角将同一批 50 条查询附上生产环境的类别和风格条件再跑一次,沿用原有的相关标注。这个视角覆盖到条件回退的行为:50 条中有 3 条 Part 回退和 8 条 Ref 回退。
评测还包括七个退化检索器:忽略查询、只认 id、朴素分词、只回构件、只用语义、常量向量和复合词拆分。每个退化实现用来验证评测能发现对应的问题。评测离线运行,复用已保存的查询向量,不调用嵌入模型。
从子串匹配到 BM25#
最早的正文检索对查询逐词做子串匹配,每个词命中加 1,封顶 2。问题是通用词容易制造大量同分候选。库中包含 glass 的条目有 232 条,包含 window 的有 167 条。搜 stained glass windows,前六条里没有一个标注为相关的条目。
BM25 解决同分问题的方式是区分词的稀有度。它在全库统计文档频率(IDF),稀有词的贡献高于常见词。词频有饱和效应,一个词在文档中出现十次和三次的差距远小于零次和一次。文档长度也参与归一化,避免长文本仅靠篇幅占优。
替换成 BM25 后,stained glass windows 的首个相关条目 enchanting-pavilion 排到第一。lexical 类查询整体 MRR 从 0.700 升到 0.894。
检索覆盖率提高的同时,部分查询的排序也发生了变化。direct 类查询的 hit@6 保持 100%,但 MRR 从 1.000 降到 0.838。原因是 BM25 的文档频率改变了已命中条目之间的排序。recall 从 89.6% 升到 91.7%,说明返回的相关条目总数增加了。
关键词层也做过清理。查询 a place of worship 曾误匹配标题拆词产生的单字符 a,前六条全部无关。过滤单字符碎片消除了这条误匹配。参考卡和 stamp 曾共用 windmill 这个 id,导致读取详情时一个条目覆盖另一个。参考卡后来改名为 windmill-farmstead,构建参考库时按全局唯一 id 合并条目。
语义层与余弦门槛#
BM25 依赖文本重叠。如果查询和条目的用词完全不同,词法检索就可能漏掉相关条目。a way to get across a river 和 diagonal-azalea-wood-bridge 没有共同词根,vessel that travels under the sea 和 submarine 也是。
语义层把查询和条目映射到同一个嵌入空间。模型是 OpenAI text-embedding-3-large,输出 1024 维向量。L2 归一化后用点积计算余弦相似度,门槛 0.32。
四条从未命中变为命中的查询:
| 查询 | 命中条目 | 余弦 | 加向量后名次 |
|---|---|---|---|
| a way to get across a river | diagonal-azalea-wood-bridge | 0.326 | 2 |
| a place of worship | abbey | 0.382 | 1 |
| vessel that travels under the sea | submarine | 0.476 | 2 |
| 风车 | spartan-windmill | 0.394 | 1 |
heavy machine for digging 在无向量时已经命中 excavator,排在第 5。加向量后余弦 0.508 把它提到第 1。
门槛选 0.32 是在覆盖率和精度之间取的平衡。roller coaster 和 colorful-ferris-wheel 的余弦为 0.398,风车 和 spartan-windmill 为 0.394。如果把门槛提到 0.40,两条候选同时被排除。
词法分和语义分的融合选择了加权方案。同批实验中 RRF 的总 MRR 为 0.771,高于加权的 0.760,但 conditioned 类查询的 hit@6 从 100% 降到 83.3%。条件分在加权中可以直接叠加,RRF 的排名融合削弱了条件信号的表达。
首次加入向量后,semantic 类查询 hit@6 从 30% 升到 60%,mixed 总体从 76.7% 升到 88.4%。后续把语义权重从 2 调到 3,semantic 类查询进一步升到 70%,mixed 总体达到 90.7%。
返回结果中只有语义证据的条目会特别标注。构件的语义命中要求 Agent 先核对身份再放置,参考卡标为相关灵感。中文查询在词法层落空时,系统会提示 Agent 继续使用语义检索找到的有效构件。
Part 与 Ref 的独立列表#
参考库早期只有 137 个 Part 和 42 个 Ref,混在一起排序后 Ref 在返回结果中占 40.8%。随着 Part 增长到 748,Ref 占比降到 14.1%。Part 数量是 Ref 的近 18 倍,数量失衡让 Ref 在混排中被稀释。
旧方案用保底槽位试图解决这个问题。但保底也有代价:查询 heavy machine for digging 的相关构件在保底 2 个 Ref 的设定下全部被挤出前六条。这一版后来把保底数量降到 1,但问题的根源在混排本身。
现行实现改为独立列表。Part 至多返回 6 条,Ref 至多返回 2 条,各自排序,互不挤占。50 条评测查询在当前设定下的结果:
| 视角 | 计分样本 | hit@6 | MRR |
|---|---|---|---|
| mixed 兼容 top-6 | 43 | 90.7% | 0.806 |
| 生产条件 Part@6 | 42 | 92.9% | 0.819 |
| 生产条件 Ref@2 | 5 | 100% | 1.000 |
Ref 的 5 条计分样本全部命中。Part 在生产条件下 MRR 略高于 mixed 兼容视角,独立列表消除了跨类型的排序干扰。
向量存储与计算规模#
向量表以 JSON 保存在服务端,800 条 ×1024 维,文件 4.2 MiB。原始浮点载荷 800×1024×4 = 3.3 MB,其余是 base64 编码开销和元数据。装载时检查模型、声明维度、实际维度和文本指纹,失效条目保留词法检索,装载器报告原因。
每次计算全库余弦相似度,需要完成 819,200 次逐维乘加。在 800 条的规模下,进程内全量计算完全可行。ADR 列出了重新评估数据库的条件:语料达到十万量级、用户直接检索、跨实例共享、按用户或工坊过滤。在这些条件触发之前,不引入额外的基础设施依赖。
同一建造轮内,相同查询的嵌入结果会缓存复用。评测离线运行,复用已保存的查询向量,不调用嵌入模型。新模型或新查询需要重建向量 fixture,现有分数只对应已保存的向量空间。
后续做过关键词实验。把计分的关键词命中数限制为 2 后,mixed MRR 从 0.806 降到 0.783。删除文档频率超过 40 的关键词,对计分用例也没有收益。最终保留了每命中加 2、不封顶的规则。
当前评测使用 800 个有效条目及其向量。在 50 条查询中参与计分的 43 条上,mixed hit@6 为 90.7%,MRR 为 0.806。端到端的建造质量和 token 节省幅度缺少独立对照。逐层加入五项信号的完整消融矩阵尚未留档,现有证据覆盖 BM25、语义和权重三组各自的前后对照以及具体查询的案例分析。