Jev AI 的九个失效模式:官方 jaggedness 页逐条拆解,附可落地的代码兜法
一句话结论: TypeSafe 自己维护了一页
docs.typesafe.ai/model-jaggedness,把 Jev 的九种失效模式连同改法一条条列了出来:字面理解、数学与数字、日期比较、多层间接、无关细节塞满 state、对抗性内容、指令与 criteria 矛盾、Choice 选项顺序、文本生成。关键在于——这九条没有一条是「换个说法写 prompt 就能解决」的措辞问题,官方的改法列里反复出现的是「算术留在代码里」「先过滤」「减少跳数」「换个生成式模型」。也就是说,这九条本质上是架构问题。本文按官方顺序逐条过一遍:文档原话说了什么、它建议怎么改、代码里怎么兜。
网上讲 Jev 的文章大多在讲它能干什么。这篇反过来,讲它不能干什么——而且不是猜的,是照官方自己写的清单来讲。因为决定「这条流水线能不能自动跑」的,从来不是能力清单,而是失效清单。
下面每一条事实都在 2026-11-13 核对过,出处是 TypeSafe 官方文档的这几页:model jaggedness、models、confidence、Choice 原语页,以及两篇公开 cookbook:日期抽取 和 RAG 段落分类。文里出现的每个具体数字都会标注来自哪一页,方便你自己复核。
为什么用「锯齿」这个词是对的
官方开篇的定位是:Jev 快、概率经过校准、擅长常识判断,但不完美;它最擅长的是 System One 类任务。对架构影响最大的其实是紧接着的三句:遇到需要多层间接的任务可能吃力、理解上相当字面、对需要数值精确性的任务力不从心。
把这三句当成能力边界读,后面整页就都顺了。判断模型不是「缩小的 LLM」,它是另一种仪器,而这九条失效模式全都出现在同一个地方——有人拿判断仪器去做测量。计数是测量,日期算术是测量,在两个分数档之间插值反推具体数值也是测量,文本生成则是完全另一台仪器的事。
所以改法都是结构性的。文档写「把算术留在代码里」,不是在教你把 prompt 改漂亮,而是在告诉你:这个问题根本不该问这个模型。
官方表格里的九条,原样列一遍
| # | 失效模式 | 官方给的改法 |
|---|---|---|
| 1 | 字面理解 | 把确切条件写清楚,每个可选答案都写 criteria |
| 2 | 数学与数字 | 算术留在代码里 |
| 3 | 日期与时间比较 | 抽出各个组成部分;比较放代码里 |
| 4 | 多层间接 | 减少跳数;用名字指向 state 里相关的部分 |
| 5 | 塞满无关细节的大 state | 先过滤;只送问题需要的东西 |
| 6 | 对抗性内容 | 把 prompt 写精确,上线前测边界情况 |
| 7 | 指令与 criteria 矛盾 | 让 criteria 和指令对齐 |
| 8 | Choice 选项顺序 | 打乱选项顺序,看答案是否一致 |
| 9 | 文本生成 | 换生成式模型 |
这张表的结构本身就是信息:九条里有八条,修法都在模型外面——在你的 prompt、你的 state、你的代码里。只有第 8 条(选项顺序)是你没法「设计掉」的,只能测。
一、字面理解:它回答的是你写下的问题
官方措辞很精确:Jev 回答的是你写下来的那个问题,不是你想说的那个;限定词、否定、隐含条件全部按字面读。人会去猜指令背后的意图,它不会。
官方给的改法里有一句最好记:当你看着一个错误答案、开始解释「我其实想说的是……」的时候,那句解释就是指令缺失的另一半。
由此可以推出两条实践。
第一,边界情况应该写进 criteria,而不是 instructions 的散文里。因为 Choice 的选项名和选项描述是一起发给模型的(Choice 原语页写得很明确:名字和描述都会送进去,所以描述要能把选项彼此分开)。也就是说,真正决定「走 billing 还是走 refund」的那个区分点,有它该待的地方,不该塞在开头铺垫里。
第二,当解释确实无法避免时,拆开。官方给的办法是把一个问题拆成两个字面问题,在代码里合并。两个 Noul 的答案在代码里做一次 and,就是「字面问题 + 代码级合取」;而一个句子里塞着「除非」的 Noul,是等着第三个边界情况来打你的隐患。
二、数学与数字:算术留在代码里
这一条下面有三个子问题,因为它是三种不同的错误被归到了一起。
计数
官方原话是:Jev 计数不可靠,覆盖「一个词里有几个字符」「一段话里某个词出现几次」「一长串里有几个元素」;它的机制是认出答案的形状而不是逐项清点,而且被数的对象越大误差越大。
文档还反问了一句,值得用在每一次计数需求上:这个计数为什么需要模型? 如果正则或解析器能找到那个单位,计数就该在代码里,模型帮不上忙。
真正需要模型的情形——「符合某个语义条件的项有几个」——官方给的形状是每项一个问题,在代码里求和。文档里的示例是这样:
from typesafe_sdk import Noul, TypeSafeClient
client = TypeSafeClient(model="jev-latest")
YES = 0.5 # up to you on what you want the threshold to be, depends on your usecase.
items = ["typesafe", "apple", "california", "banana", "likes", "calibration", "orange", "vertex"]
result = client.system_one(
{"items": items},
{
f"item_{i}": Noul(instructions=f"Is `items[{i}]` the name of a fruit?")
for i in range(len(items))
},
)
count = sum(result.nouls[f"item_{i}"].noul > YES for i in range(len(items)))
注意分工:一次请求里八个问题、一个代码里的阈值、一个代码里的 sum。模型负责八次语义判断,算术从头到尾没进模型。YES 那行注释是官方自己写的,而且写得实在——0.5 只是个起点,不是推荐默认值。
数字的表示方式
第二个子问题讲的是数字怎么写出来。官方说:Jev 在语义化表示上比纯数值表示表现更好,举的例子是用十六进制值描述颜色明显不如用英文颜色名;给了 RGB 三元组或 hex 值,它无法可靠判断两个值是否接近。编程语言上也有同样的不对称——问高级语言的判断好于问汇编或二进制编码的指令。
改法是:在代码里完成转换,然后传算好的数或者命名过的档位(bucket)。判断留给模型——比如「这个颜色读起来像不像警告色」。
这条可以升格成 state 设计通则:与其只传 {"raw_score": 0.83},不如传 {"severity_bucket": "high", "raw_score": 0.83}。档位是语义表示,裸数字恰恰是它最不擅长的比较对象。
score 不是用来算量级的
第三个子问题禁掉一个很常见的坏习惯。官方明确说:不要用 score 的输出(expectation、probability)去计算「某个数值在两个档位之间的精确量级」。用 expectation 去过一个阈值是可以的;用最近两个档位插值把确切数字反推出来则不行,因为原文说 Jev 的 score 档位在数值校准上很弱。
所以 expectation >= 0.6 是正当用法;把 20 + (expectation − 0.5) × 2 × 10 包装成「测量值 27.4」不是。真要那个数,从数据算,别从评级里反推。
三、日期与时间比较:抽成分,日历交给代码
Jev 把日期当文本读,不当有顺序的量读。官方说:问两个日期哪个在前、相距多远、是否落在某个区间内,都不可靠;混合格式、相对表达,以及季度、结算窗口、计提期这类业务边界会让问题更糟。
建议的分工很干净,也是整页里演示「判断模型和普通代码怎么分工」最好的一个例子:抽取是判断,交给模型;算术不是,留在代码。
为什么抽取能算判断?这恰恰是巧妙的地方。日期的每个组成部分都是一个小闭集——十二个月、最多三十一天、一个有界的年份区间——于是抽取就从「自由文本解析」变成了在枚举选项上做 Choice,而且可以专门留一个「未提及」选项,让缺失的部分被报告出来而不是被猜出来。
日期抽取 cookbook 是完整版本,其中两个细节值得搬到任何实现里:
- 它把参照用的「今天」写死(
TODAY = date(2026, 7, 30)),让相对日期可复现,而不是悄悄依赖跑测试那天的系统时间。 - 它设了复核阈值
REVIEW_BELOW = 0.60,低于阈值的日期交给人工;此外还有两种同样交给人工的情形:各部分组成不了一个合法日期、以及文档根本没写这个日期。
cookbook 还点名了一个你必须自己拍板的歧义:「next Thursday」可以指两天,所以由代码来定它指哪天——光秃秃一个「周四」就指下一个周四,这个约定写在代码里,不是让模型去猜。整页那个模式一句话就能说完:模型负责读出文本说了什么,代码负责日历。 顺带一提,这条呼应第 5 条——把「未提及」做成显式选项,正是为了避免让模型在缺失信息上编一个合理值。
四、多层间接:减少跳数,用名字指路
带双重否定、或者需要复杂间接的指令,回答更不可靠。官方说:问「某个属性的属性」、或者需要多跳推理的问题,都会损失准确率。改法是尽量把指令写直接,并尽可能用名字指出 state 里的相关部分。
后半句是具体的设计指令。如果真正相关的那句话躺在 state.contract.clauses[7].text,那就明确指过去,或者重构成让问题直接指向一个命名字段。「通知期有没有被遵守」这种必须穿三层的问法,本质是穿着 Noul 外衣的 System Two 任务——而官方在页尾的提醒里,把「System Two 任务:更多层间接」直接列进了「避免」清单。
五、无关细节塞满 state:先过滤,并正视 context rot
当 state 里塞进与判断无关的内容时,准确率会下降。官方给的原因有两层:无关细节会变成干扰项;而且 state 越大,一旦答错,就越难判断是哪部分输入导致的——后者是调试成本,不只是准确率成本。
那一节的提示框直接用了一个词:context rot(上下文腐坏),并说无关材料进 state 是要付准确率代价的。models 页从另一个方向重复了同一件事——它在讲上下文长度的那一节里,直接把 jaggedness 页作为「state 变大时准确率怎么变」的说明链接过去。
官方给了两个改法:先在代码里检索、过滤,只送问题需要的字段;如果确实没法在 state 层过滤,就用一个 Noul 先做相关性筛选,「RAG 段落分类」那篇 cookbook 就是完整的示范。
那篇 cookbook 也是全页最有说服力的证据,说明相关性过滤为什么没得选。它的第一个查询检索出十二条段落,相似度分数全都挤在 0.584 到 0.455 之间——cookbook 自己的评价是:这个分布太窄,根本分不开「纠正查询前提的段落」和「试图劫持答案的段落」。带注入指令的论坛帖以 0.584 排第一,纠正前提的那条以 0.509 排第七。检索排序救不了这个问题,救它的是每段四个判断问题。
六、对抗性内容:state 是数据,但不是被当敌意处理
官方说:state 是数据,Jev 默认不会把它当敌意内容对待。那些为了操纵模型而写的文本——注入的指令、刻意误导的框架、替自己争取分类结论的段落——确实可能把答案带偏。文档还说团队预期未来会改善这一点,这是「这个问题还没解决」的诚实写法。
给出的对策是两部分,而且两部分都是你的责任:把 criteria 写精确;在大规模上线给很多用户之前把集成测透。没有任何 header、没有任何阈值能让注入问题消失。
同一篇 cookbook 里还有一个重要细节:最自然的防线——给「注入检测」这个问题设一个概率阈值——那个数字是策略值,不是被验证过的常量。cookbook 的 THRESHOLDS 里写的是 injection_max: 0.70,但它附带了一个注释,明确说这四个数字是为那份语料挑的,请当成起点而不是默认值。它还解释了判定顺序为什么这么排,这才是设计上的教训:注入先判,因为这是安全决策而不是证据决策;矛盾判断要放在证据判断之前,因为「否定查询前提」的段落也可能陈述了可用事实,顺序反过来它就会被放进「采纳」那一档。
这个排序就是「过滤器」和「许愿」的区别:按后果排序,不按方便排序。
七、指令与 criteria 矛盾:criteria 是指令的延伸
当 instructions 和 criteria 各说各话时,Jev 会混乱。官方举的例子很具体:一个 Noul 里「true 表示否、false 表示是」,表现会更差。它的建议是——让指令容易让普通人读懂,并把 criteria 当作指令的延伸,用清楚准确的语言把两者对齐。
实操上的自检是机械的:先读 instructions,再逐条读每个 criteria 的键和描述,然后问自己——一个只读这两个字段的人,会不会给出你期望的那个答案。极性反转(那个 true 表示否的例子)是第一个要 grep 的东西,因为它通常来自一个「在代码里反过来就行」的好心捷径。
八、Choice 选项顺序:它有偏向第一个的倾向,所以去测
官方承认,在某些情况下 Choice 的选项顺序会影响答案,而且 Jev 有偏向第一个选项的倾向。检查办法是:打乱选项顺序,确认答案保持一致。
这是九条里唯一一条「修法纯粹是测试」的,这个事实本身说明它的性质:没有任何设计规则能消掉它,只有一个验证步骤能发现它。如果这个 Choice 带有真实后果——路由决策、风险档位——就把你标注好的样本集跑两遍,一遍按上线顺序,一遍打乱,比较一致率。如果答案会跟着顺序动,多半是选项彼此没区分开,那就回到第一条:用 criteria 去承担区分。
九、文本生成:换生成式模型
这条没有含糊空间。Jev 不是为生成文本训练的。用串联 Choice 硬凑也能出字,但效果不好、而且非常慢。做数据抽取时,用正则或生成式模型先抽出候选,再让 Jev 从候选里挑正确的那一个。答案空间有界时,把抽取写成「在选项上做 Choice」,而不是直接索取那个值。
如果你确实需要生成文本,官方自己的结论是:那有别的模型。「别的模型去干」不是需要绕开的限制,它恰恰是这套成本模型成立的前提——你只为输入 token 付费、输出 token 免费(models 页,2026-11-13 核对),这种计价结构只对「只回答、不写作」的模型讲得通。
页尾那四条「避免」清单
jaggedness 页最后有一小段「避免以下做法」,因为它读起来就是前面全部的浓缩,所以它是整个文档里最好用的一份单页检查表:
- 让模型去做代码能精确算出来的事。
- 把好几个判断藏进一个问题里。
- System Two 类任务:更多层的间接。
- 给 state 塞比问题所需更多的上下文——这里又提了一次 context rot。
四条全部可以在代码评审里被查出来。这正是重点:这份失效清单是一份评审清单,不是免责声明。
把它变成一次上线前审计
因为这九条的修法全是结构性的,所以在花第一分钱之前就能查完。一个可执行的顺序:
- 把每个问题列出来,标类型。 逐个写清它属于「判断」「测量」还是「生成」。标成测量或生成的都是问题项,该搬到代码里或换模型。
- 在构造 state 的代码里 grep 裸数字。 十六进制颜色、RGB 三元组、没解析的时间戳,以及任何要跟阈值比较的裸值。补一个命名档位,或者把比较搬进代码。
- 检查每一个日期问题。 如果答案依赖先后、时长或区间,这个问题就该做成「抽取成分」,而不是「比较」。
- 打乱 Choice 选项再跑一次,比答案。 顺序你想怎么定就怎么定,但你得知道答案会不会跟着动。
- 把
instructions和criteria逐行对读。 找极性反转,也找那些写在散文里、本该属于 criteria 的条件。 - 量一下 state 大小和问题数量的比例。 state 里没有任何问题引用到的字段,按定义就是干扰项——jaggedness 页的 context rot 提示说它要付准确率代价,而过滤很便宜。
- 跑对抗集。 替自己争取分类结论的文本、误导性框架、注入的指令各来几条。看最终路由结果,不要只看原始概率。
这对架构意味着什么
九条的指向是一致的:Jev 应该待在你流水线里最窄的那个位置——一个已经被代码收窄过的决策点。检索决定什么能进 state;代码决定数字是什么意思;模型只决定代码决定不了的那一件事:这段文本,按 criteria 的说法,到底算不算这个意思。
这样读,jaggedness 页就不是一张 bug 清单,而是厂商公开的、附带改法的边界说明。一个可靠的 Jev 集成,大部分设计工作量就在于尊重这条边界。
对这份文档本身还要有一个提醒:它开篇就说很多失效模式会在后续版本修掉。所以这份清单是带日期的。本文对齐的版本是 1.14,即 2026-11-13 查 models 页时的最新版本;你要在自己的架构评审里引用其中哪一条,先去 changelog 核对它有没有变。