用 Jev API 做句级语义检索:218 个行 ID 一次 Choice 排序,再补一个 Noul 判定有没有答案
文档问答这条线上,最容易翻车的地方通常不在生成,在检索:把切好的段落递上去,段落切得挺对题,可真正回答那句话根本不在里面。模型于是拿段落里剩下的内容凑出一个看着很顺的答案,最后引用的那段九百字里没有一句是它说的那个意思。
这篇讲的就是把这一步做窄一点的做法,用的还是 Jev API。不排段落,只排一份文档里的每一行,所以输出是一个行 ID 加一句原话。它对应官方 semantic_find cookbook:下面所有数字都来自官方公布的那一次运行,测试文档是 GitHub 服务条款,218 行、43,980 字符,模型 jev-1.14.0。这里没有「按理说应该能到多少」的估算。
为什么把检索单位压到行
检索一般做在段落这一层,原因有两个:embedding 模型返回的是段落,塞进 prompt 最省事的也是段落。但这两条都是机器这边的方便,跟用户问的问题没关系。用户想在一份合同里找到的,是写着这件事的那一条;而一个四百字的段落里既然装着那一句,也就一并装着三条没关系的。
把粒度对到行,好处是引用和被引的说法一样长:
- 答案是一个 ID 加一行字,
L052,复核的人只看一句。 - 文档按自己的行结构切,跨三行的条款就是三个候选,而不是揉成一块。
- ID 能跟答案一起存下来,日后复查只是查个表,不必再把整份文档读一遍。
代价是同一份文档的候选变多了。这是这个构建必须付的账,255 个选项的天花板就是它最后显形的地方。
第一步:给每一行打上 ID
测试文档是 GitHub 服务条款,切成 218 条,这样每条搜索结果都指向一句可引用的原文。cookbook 从自己的示例仓库拉文件,并做了下载缓存:
LINES = fetch_document(DOCUMENT_URL).splitlines()
然后给每行加前缀,再把行拼回一份文档:
def line_id(i: int) -> str:
return f"L{i:03d}"
DOCUMENT = "\n".join(f"{line_id(i)}| {line}" for i, line in enumerate(LINES))
这一行代码里有三个细节,后面都会用到。
ID 补零到三位,L052 和 L0520 当字符串不会混,按 ID 排序就是按文档顺序排。
分隔符是竖线加空格,模型看到的是 ID 和它所指的文字之间有明确的边界,ID 不属于那句话本身。
进 state 的是打好标记的这份文档,不是原文。没有第二份副本、没有元数据块、也没有单独一张行号表——ID 就长在模型要读的文字里。
cookbook 印出来的样子是这样:
L052| You own Your Content. If you post Content you did not create, you are responsible for...
L053| You grant us and other Users the licenses in Sections D.4–D.8. These licenses apply...
L054| 4. License Grant to Us
第二步:用一个 Choice 问「答案在哪一行」
排序就是一个 Choice 问题,选项是全部行 ID:
def where_question(query: str) -> Choice:
return Choice(
instructions=f'Which line of the document contains the answer to: "{query}"?',
criteria={line_id(i): None for i in range(len(LINES))},
)
criteria 里每个选项的说明都是 None。这不是漏写:state 里的文档本来就装着每个选项的文字,再给每个选项写一遍说明,等于在问题里把 218 行重复一次。问题本身放进 instructions,文档在多次检索之间一动不动。
返回的是每个选项一个概率,所有值加起来等于 1。就这一条,决定了这一页的多数设计取舍:
- 排序是一个分布,不是一个分数。
L052是 0.77,意思是模型把 77% 的概率质量放在这一行,不是说这行有 77% 的相关性。 - 不管文档答不答得上,总有一行概率最高。
- 选项加得越多,同一份概率质量铺得越薄,所以候选集大和答案笃定这两件事是互相拉扯的。
255 个选项的天花板
一个 Choice 问题最多 255 个选项。cookbook 把后果直接写出来了:这套做法一次请求检索最多 255 行的文档,超过就分两遍——先用一个 Choice 问题挑出一个窗口,再用第二个在窗口内部排序。
测试文档 218 行,正好在这条线下面,所以单请求的形式能成立。你要是把 DOCUMENT_URL 换成更长的东西,这个天花板就是第一个要设计进去的东西,而不是上线之后才发现的那种边角情况。
第三步:用 Noul 判定文档里到底有没有答案
第二个问题是个 Noul,问的是另一类事情:
def exists_question(query: str) -> Noul:
return Noul(
instructions=f'Does any line of the document address or answer: "{query}"?',
criteria=NoulCriteria(
true="At least one line of the document states or directly implies the answer",
false="No line of the document addresses this",
),
)
Noul 的回答是 0 到 1 之间的一个数,也就是「是」的概率。它没有单独的 confidence,因为是非题的分布只有两种结果,一个数就说完了。
这两条 criteria 的文字是真在干活的。「至少有一行写明或直接蕴含答案」是通过条件,「没有任何一行涉及这件事」是不通过条件。两条之间的空档就是「部分涉及」住的地方,cookbook 用 verdict 函数把这个空档显式处理掉了,没丢给读者自己猜。
第四步:两个问题塞进一个请求
两个问题一起进一次 system_one 调用,文档只发一次:
response = client.system_one(
state=state,
questions={"where": where, "exists": exists},
model=model,
)
probabilities = response.answers["where"].probabilities
return {
"exists": response.answers["exists"].noul,
"relevance": [probabilities.get(line_id(i), 0.0) for i in range(len(LINES))],
}
Jev 把 state 摄入一次,然后并行地对每个问题求值。存在性判定之所以在边际上几乎是白送的,原因全在这:排序要的那份文档,跟判定要的那份文档是逐字符相同的同一份,合在一起问只摄入一次,拆开问就是两次。
relevance 这个列表按文档顺序存每行的分数,响应里没出现的 ID 一律填 0.0。顺序这件事对界面有用:前三名如果散在文档各处,读起来比挨着的四行费劲得多。
也值得说清这个函数不做什么。它不按 confidence 重排,不把零分的选项剔掉,不合并相邻行。分布是什么样就返回什么样,所有判断留给上面那层代码。这是本站反复回到的那个套路:Jev 给概率,阈值留在你自己的代码里,那里才调得动、审得了。
第五步:把 exists 概率折成三档判定
cookbook 用两个截点把 exists 折成三种状态:
FOUND, ABSENT = 0.7, 0.35 # `exists` cutoffs for answered and not in this document
def verdict(exists: float) -> str:
if exists >= FOUND:
return "answered in this document"
return "not in this document" if exists < ABSENT else "partially addressed"
三档而不是两档,因为一刀切会逼你做一个模型已经帮你省掉的二选一。0.65 不是「没有」,它是「文档绕着问题说了一圈」这种状态,对用户是另一种答复,对管线是另一条路由规则。
关于这两个数,cookbook 自己的话很简短,意思值得照抄:上生产之前,拿你自己的文档重新调这两个数。0.7 和 0.35 是一次公布运行在一份合同上的设置,不是模型的常量。
第六步:四个示例问题实际返回了什么
那次运行问了两条能直接答的、一条只能部分涉及的、一条文档里没有的。下面是官方公布的输出,逐字照录:
218 lines, 43,980 characters
"who owns the code I upload?"
exists 0.99 -> answered in this document
L052 0.77 ######### You own Your Content. If you post Content you did not crea
L046 0.12 # Short version: You own content you create, but you allow u
L051 0.06 # 3. Ownership and License Grants
L053 0.05 # You grant us and other Users the licenses in Sections D.4–
"can GitHub kick me off the platform without warning?"
exists 0.98 -> answered in this document
L168 0.96 ############ GitHub has the right to suspend or terminate your access t
L167 0.04 # 3. GitHub May Terminate
L000 0.00 # Effective date: April 27, 2026 · A. Definitions
L001 0.00 # Short version: We use these basic terms throughout the agr
"do I have to take disputes to arbitration?"
exists 0.65 -> partially addressed
L205 0.80 ########## Except to the extent applicable law provides otherwise, th
L204 0.11 # S. Miscellaneous · 1. Governing Law
"can I join a class action lawsuit against GitHub?"
exists 0.05 -> not in this document
L205 0.23 ### Except to the extent applicable law provides otherwise, th
L197 0.19 ## If you have a dispute with one or more Users, you agree to
四条问题,四种结局,有意思的是那两条失败的。
仲裁那条回来 0.65,落在「部分涉及」。服务条款通篇没提仲裁(arbitration),排第一的那行 0.80 是管辖条款,把争议交给旧金山的法院。排序并没有找错位置——它找的是最接近的材料,回答的是稍微另一个问题,而 exists 分数正是把这个偏离标出来的东西。
集体诉讼那条回来 0.05,「本文档没有」,可排序还是给了某一行 0.23。这就是第二个问题存在的完整理由,一个例子就够了:218 个选项的分布不可能返回空,没有 Noul 这道闸,你就会把管辖条款拿去回答集体诉讼的问题。
另外两条直接能答的,展示了「干净命中」长什么样。版权归属那条把 0.77 压在 L052、0.12 放在上面那行通俗摘要上,前两名正好是完整条款加它的大白话版本,这正是复核的人想要的一对。终止那条更干脆:L168 拿 0.96,上一级的章节标题只留 0.04。
两个数要一起读
cookbook 自己总结这条规则只用了一句话:排序告诉你该往哪看,exists 分数告诉你这个结果到底算不算答案。
一条同时产出这两个数的管线,于是有两个互相独立的决定:
| exists 判定 | 拿排第一的那行怎么办 | 谁来看 |
|---|---|---|
| 本文档能答(≥ 0.7) | 当答案引用 | 终端用户 |
| 部分涉及(0.35 – 0.7) | 当相关材料给出,并标明不是答案 | 终端用户,带标注 |
| 本文档没有(< 0.35) | 整个排序丢弃 | 没人看,除非你要留日志 |
多数构建翻车的是中间那一行。把「部分涉及」直接丢掉,就丢了「文档确实在讲这件事、只是没给定论」这一类——而这恰好是客服收件箱最需要转人工的那类。把「部分涉及」当答案更糟:用户问仲裁,你回他一条 0.80 的管辖条款,那个 0.80 看着还挺有说服力。
一次检索花多少钱
每次检索都是一次请求,把打好标记的文档带上一遍。按 models 页公布的价格,每十亿输入 token 收 $42、输出 token 免费,那么一次检索的成本就是摄入一份文档的成本:
单次检索成本 ≈ 文档 token 数 × $42 / 1,000,000,000
cookbook 公布的是文档字符数 43,980,没公布 token 数,所以这个算术故意停在这里。真正有用的那个推论不依赖精确的 token 数:单次成本跟文档长度成正比,跟排序看了多少行无关。排 218 行和排 40 行一样贵,因为问题那边每个选项只花几个 token,贵的是文档。
重复检索的上限也在这。同一份文档问十个问题,就是把这同一份文档摄入十次。如果一类活儿就是对着同一份合同反复问,把问题合进一个请求才是那个杠杆,因为 Jev 对一次请求里的每个问题,都是对着同一份摄入好的 state 求值。
超过 255 行怎么办
cookbook 给的路子是两遍:先用一个 Choice 问题挑出一个窗口,再用第二个在窗口内部排序。这个结构被两件事逼出来——选项上限,以及概率质量的行为:
- 第一遍把每个窗口当选项,说明要短到能区分窗口。选项文字得装够信息才选得动,通常是一个标题加几行有代表性的原文。
- 第二遍拿赢下来的窗口,照旧给行打 ID,在更窄的 state 上问同一个
where问题。 exists问题要对着你真正想要判定的那份 state 问。拿窗口去问,回答的已经是比用户问题更窄的问题了。
实践里还有两种形状,都跟 cookbook 的结构相容(但官方没有把它们写成 recipe):按章节切开,每节跑一遍完整检索;或者整份文档不动,先在 Choice 之前用一道便宜的筛子把候选压下来。不管是哪种,天花板都是设计输入,而 exists 那道闸要留在原地——它是保护输出的那部分。
跟「几千个候选里找一个」那篇的区别
本站另有一篇讲在海量候选中找一件东西的,做法是每个候选问一个 Noul,再对前若干名做一次 Choice。两篇能并存,是因为失败模式不一样。
句级检索排的选项,本来就都在模型手里。每一行都在 state 里,所以问题是答案在这份读得全的文档的哪一处;决定成败的数字是 exists 概率,天花板是选项个数。
找东西那篇排的候选,根本不在 state 里。每个候选都得在问题里被描述一遍,所以成本随候选数涨,关键的设计决定是「怎么在昂贵的打分之前把短名单缩下来」。
如果你的候选本来就在 255 个选项以内、文本也发得起,用这一篇就够简单。如果不在,得先做短名单。
第一版构建里常见的几个坑
把第一名那个概率当成相关性分数。 它是分布里的一份,加起来永远等于 1。在一份 218 行的文档上,正确答案拿 0.77 和拿 0.23 都可能是对的。只在同一次查询内部比较,永远别跨查询比。
因为「排序看起来很笃定」就不问 exists。 集体诉讼那条 0.23 就是反例:排序看着挺有把握,文档里却什么都没有。
在两次检索之间改了文档,还指望 ID 不变。 ID 是对切出来的行做 enumerate 来的,加一行或删一行,后面全部重编号,存下来的引用会悄悄变错。要存 ID,先给文档定版本。
把 0.7 / 0.35 抄进一个新领域。 这两个数是一份合同、一种法律语体上定下来的。cookbook 说按文档调,调参集就是你自己的、带已知答案的那批问题。
该按条款切的地方按句子切。 跨行的条款在这里就是三个候选,这正是合同的预期行为——每行都能单独引。一篇散文想要的切法不一样,ID 方案得跟着你的切法走。
忘了缓存就是缓存。 没配 API key 时 cookbook 的客户端用占位值 cache-only 顶上,而且已经在盘上的缓存文件永远不会被覆盖。这让公布的那次运行不带 key 也能复现,也意味着你改了代码、忘了删缓存的话,它会很乐意把昨天的答案再放一遍。
接进检索管线
这套东西最自然的位置是摆在常规 embedding 检索旁边,而不是替掉它。embedding 那步决定搜哪份文档,句级检索决定引哪一行:
- 用你现有的办法取回最相关的几份文档。
- 对最前面的那一两份,拼出打好标记的文档,一个请求里问
where和exists。 - 先读 exists 判定。低于「没有」的截点,跳过这份文档,看下一份。
- 高于「能答」的截点,引第一名那一行;第二、三名如果跟它相邻,留作佐证。
- 落在中间那截,连第一名一起转人工队列,当上下文用。
第 3 步改的是输出的形状,因为它把「没有答案」变成一种正常结果,而不是异常。一条敢说「这份文档没覆盖你问的事」的客服管线,比一条永远能引出一句什么的管线有用。
用到的两种问题类型
上面这些只用同一个请求里的两种问题类型:
Choice,做排序。最多 255 个选项,每个选项返回一个概率,另外给一个按分布铺开程度算出来的confidence。Noul,做存在性判定。返回一个概率,没有单独的 confidence,读法就是「答案是是」的概率。
两者都把 state、model、questions 当顶层字段,所以能共用一个请求。文档是 state,查询躺在每个问题的 instructions 里,这样 state 在多次检索之间不变,一次摄入同时供两个问题用。
字段级的细节,本站讲三个原语的那篇和讲 state 与问题的那篇有请求结构;如果要看「核查大模型答案有没有出处」的配套做法,讲出处核查的那篇有三 Noul 版本的同一种思路。
这篇不主张什么
cookbook 在一份文档上公布了四个查询,没有跨标注集的准确率。没有测出的召回,没有在检索这个任务上跟 embedding 检索的对比,也没有句级检索的阈值表。所以这一页不对「第一名有多常是对的」作任何断言。
官方那次运行确实立住的东西窄一点,但一样有用:在一份真合同上,排序为两个能直接作答的问题找对了条款,exists 问题把 0.65 的部分涉及和 0.05 的完全缺失分开了。这套东西在你的文档上成不成立,得你自己量一遍——用你自己的问题,用你手上真实的复核产能去定那两个截点。