用 Jev API 做句级语义检索:218 个行 ID 一次 Choice 排序,再补一个 Noul 判定有没有答案

更新于 适用版本 Jev 1.14

文档问答这条线上,最容易翻车的地方通常不在生成,在检索:把切好的段落递上去,段落切得挺对题,可真正回答那句话根本不在里面。模型于是拿段落里剩下的内容凑出一个看着很顺的答案,最后引用的那段九百字里没有一句是它说的那个意思。

这篇讲的就是把这一步做窄一点的做法,用的还是 Jev API。不排段落,只排一份文档里的每一行,所以输出是一个行 ID 加一句原话。它对应官方 semantic_find cookbook:下面所有数字都来自官方公布的那一次运行,测试文档是 GitHub 服务条款,218 行、43,980 字符,模型 jev-1.14.0。这里没有「按理说应该能到多少」的估算。

为什么把检索单位压到行

检索一般做在段落这一层,原因有两个:embedding 模型返回的是段落,塞进 prompt 最省事的也是段落。但这两条都是机器这边的方便,跟用户问的问题没关系。用户想在一份合同里找到的,是写着这件事的那一条;而一个四百字的段落里既然装着那一句,也就一并装着三条没关系的。

把粒度对到行,好处是引用和被引的说法一样长:

代价是同一份文档的候选变多了。这是这个构建必须付的账,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。就这一条,决定了这一页的多数设计取舍:

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 问题挑出一个窗口,再用第二个在窗口内部排序。这个结构被两件事逼出来——选项上限,以及概率质量的行为:

实践里还有两种形状,都跟 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 那步决定搜哪份文档,句级检索决定引哪一行:

  1. 用你现有的办法取回最相关的几份文档。
  2. 对最前面的那一两份,拼出打好标记的文档,一个请求里问 where 和 exists。
  3. 先读 exists 判定。低于「没有」的截点,跳过这份文档,看下一份。
  4. 高于「能答」的截点,引第一名那一行;第二、三名如果跟它相邻,留作佐证。
  5. 落在中间那截,连第一名一起转人工队列,当上下文用。

第 3 步改的是输出的形状,因为它把「没有答案」变成一种正常结果,而不是异常。一条敢说「这份文档没覆盖你问的事」的客服管线,比一条永远能引出一句什么的管线有用。

用到的两种问题类型

上面这些只用同一个请求里的两种问题类型:

两者都把 state、model、questions 当顶层字段,所以能共用一个请求。文档是 state,查询躺在每个问题的 instructions 里,这样 state 在多次检索之间不变,一次摄入同时供两个问题用。

字段级的细节,本站讲三个原语的那篇和讲 state 与问题的那篇有请求结构;如果要看「核查大模型答案有没有出处」的配套做法,讲出处核查的那篇有三 Noul 版本的同一种思路。

这篇不主张什么

cookbook 在一份文档上公布了四个查询,没有跨标注集的准确率。没有测出的召回,没有在检索这个任务上跟 embedding 检索的对比,也没有句级检索的阈值表。所以这一页不对「第一名有多常是对的」作任何断言。

官方那次运行确实立住的东西窄一点,但一样有用:在一份真合同上,排序为两个能直接作答的问题找对了条款,exists 问题把 0.65 的部分涉及和 0.05 的完全缺失分开了。这套东西在你的文档上成不成立,得你自己量一遍——用你自己的问题,用你手上真实的复核产能去定那两个截点。

常见问题

+ 为什么返回一行,而不是一段?

因为一整段说得通,不代表里面有回答这个问题的那一句。每行自带 ID 之后,排第一的那个 ID 就是你要引的那句原话,复核的人看一眼就够,不用把前后文一起读完。官方 cookbook 用的测试文档是 GitHub 服务条款,切成 218 条,所以每条结果都指向一句可引用的原文。

+ 一个 Choice 问题最多能塞多少选项?

255 个。cookbook 原话就是这个数:一次请求最多检索 255 行的文档,超了就得走两遍——先用一个 Choice 问题挑出一个窗口,再用第二个在窗口内部排序。

+ 有了 Choice 排序,为什么还要 Noul?

要一个下限。Choice 的概率加起来永远是 1,所以哪怕文档根本没提这件事,也总有一行排第一。Noul 的概率不跟别的行分摊,掉到接近 0 是可以的。官方那次跑出来,文档没答案的问题 exists 只有 0.05,可排序照样给了一行 0.23。

+ 有答案/没答案的阈值是多少?

脚本里 FOUND 取 0.7、ABSENT 取 0.35,判的是 exists 概率:大于等于 0.7 当作文档能答,小于 0.35 当作答不了,中间那截算「部分涉及」。cookbook 自己的提醒是:上生产之前,拿你自己的文档重新调这两个数。

+ 每查一次都要把文档重发一遍吗?

要,一次请求发一次,所以两个问题才要塞进同一个 system_one 调用里。Jev 把 state 摄入一次,然后并行地对每个问题求值,于是排序和存在性判定共用这一次摄入。想再问第二个问题,就是第二次请求,同一批行再摄入一遍。

继续阅读