jev

编写和改进 Jev 程序

Jev 是一种判断模型。它读取一个 state，独立并行地回答请求中的每个问题，并返回你定义的答案的概率分布。它不会分步骤推理，也不会生成文本。控制流、算术运算和策略由代码负责。Jev 负责快速判断。

好的 Jev 问题，是指在给出恰当上下文后，知识渊博的人能在一秒内回答的问题。“这条消息是否传达了紧迫感？”就合适。“分析这条消息并决定该怎么做”则不合适。把这项任务拆分成小问题，并在代码中组合答案。

本指南适用于 jev-1.13。文档指出，后续版本可能会改进若干限制，因此模型更新后请重新查看 jaggedness 页面。

工作流

1. 列出代码必须做出的决策。将每项写成分支、阈值或排序。
2. 每项判断写一个问题。将同时权衡两种属性的问题拆开。
3. 选择代码可直接据此采取行动的基本类型。
4. 构建能够回答所有问题的最小状态。代码能计算的内容，就用代码计算。
5. 将共享同一状态的所有问题放入一个请求，包括只与部分输入相关的问题。
6. 在代码中组合答案：分支、权重和置信度门槛。
7. 使用已标注示例进行测试。检查错误样例中的 probabilities，然后每次修改一两个问题。

选择基本类型

基本类型	适用情形	返回值	代码据此采取行动的方式
Choice	答案属于一组已知选项，且选项没有顺序	choice、probabilities、confidence	为每个选项设置一个分支
Score	答案是一个可用分级描述的连续区间位置	score、probabilities、confidence、legend	阈值、排名或权重
Noul	答案明确为是或否，且概率就是信号	noul，取值范围为 0 到 1	根据阈值执行 if 判断

• 如果 Choice 的选项列表可能无法涵盖所有输入，请添加 other 或 none of the above 选项。
• Noul 为 0.5 表示 Jev 不确定，不表示“中等”。要衡量程度，请使用 Score。
• Noul 需要明确的条件。“这位候选人的 Python 能力强吗？”比较含糊。“简历是否注明候选人在工作中使用过 Python？”则很明确。
• 如果答案没有中间状态，请使用 Choice 或多个 Noul。

编写指令

• 明确说明具体条件。Jev 会按照你写下的文字作答，并按字面理解范围限定词、否定词和隐含条件。
• 每个问题只询问一种属性。隐藏的第二项判断会降低准确度和置信度。
• 用反引号括起路径，指出问题判断的状态部分：`ticket.messages[0].text`。
• 直接表述。避免双重否定、对属性的属性进行判断，以及需要多次跳转才能回答的问题。
• 不要在指令中使用表示级别的数字。“从 0 到 2 评分”不会给 Jev 提供任何可匹配的信息。
• 在 instructions 中写出完整问题。问题 ID 不会传给模型。
• 不要把决策策略放进问题中。“共享地址不能推翻姓名冲突”应由代码处理。
• 如果 Jev 回答错误后，你才解释自己真正想表达的意思，那么这段解释就是缺失的指令。请将其补上。

指令可以是字符串、对象或数组。如果问题包含带标签的部分或需要辅助数据，请使用对象。将架构、分类体系或行作为 JSON 传入。不要将其序列化为字符串模板。

"instructions": {
  "question": "Does the `message` ask the recipient to disclose a sensitive credential?",
  "inspect": "message",
  "focus": "Look for a request to send the credential itself, not a request to change or reset it."
}

文档中的实用键包括：question、focus、inspect、note、compare（状态路径列表），以及 field（一个包含 name、type、unit、description 的记录，可供多个问题共享）。

编写评判标准

将评判标准视为指令的扩展。两者必须要求同一件事，方向也要一致。如果 Noul 的 true 一侧描述的是“否”，效果会更差。

Choice. 将每个选项映射到一段描述。如果选项彼此接近，请让描述形成对比：

"billing": {
  "what": "Charges, invoices, refunds, or subscriptions",
  "not_for": "Order tracking or account access",
  "examples": ["I was charged twice", "Where is my refund?"]
}

Score. 按从低到高的顺序列出各等级。使用 2 到 10 个等级，且只使用你能清晰区分的等级。

• 描述具体情形。“功能损坏，但有变通方法”是有效的。“中度严重”则不行。
• 让每个等级都能独立成立。Jev 会分别评判每个等级，既看不到它的编号，也看不到相邻等级。“比上一个等级更差”对它毫无意义。
• 每个 Score 只对应一个维度。“守时、聪明且有经验”衡量了三件事。
• 如果某种罕见的极端情况需要在代码中区别处理，请为它单独设置一个等级。
• 等级可以是一个对象：{"summary": "One change, clearly stated", "signals": ["A single fix or feature", "..."]}。

Noul. 评判标准是可选的。当边界不明显时，添加 true 和 false 两侧，各自包含 what 和 examples。在所属一侧的描述中写明相邻情况。

Examples. 编写简短、具体的实例，例如“我被收了两次钱”。不要描述某个实例，例如“一条关于账单问题的消息”。

构建状态

• 只发送问题所需的字段。无关细节会降低准确性，而且过大的状态会让人难以判断哪个输入导致了错误答案。
• 先在代码中检索和筛选。当代码无法筛选时，为每段内容询问一个相关性 Noul，并保留通过评判的内容。
• 保持状态结构化，以便问题能通过路径指向其中的内容。
• 在发送前，将数字编码转换为文字。用颜色名称代替十六进制值。用计算后的数字或命名类别代替原始数据。
• 在代码中计算日期顺序、时长、时间窗口、数量和总和，并发送计算结果。
• 预算：状态和所有问题共用 64k 个 token。状态加上最长的单个问题必须不超过 32k 个 token。
• 将状态中的文本视为可能会引导答案。Jev 不会将状态视为恶意内容。请在评判标准中说明哪些内容应计入，并在部署前测试注入内容和自我描述内容。

在代码中组织答案

推测式扇出。 在一次请求中提出代码可能需要的所有问题，包括只在某些分支上才有用的问题。问题会并行处理，因此额外的问题几乎不会增加延迟，也只会增加少量令牌。代码会忽略不需要的答案。

第二次请求。 只有当代码没有第一次回答就无法构建请求时，才进行第二次请求，例如答案决定了要获取哪些数据。同一次请求中的问题无法看到彼此的答案。

基于置信度的路由。 答案说明要做什么，置信度说明是否要采取行动。设置一个下限，低于该值时不执行任何操作；然后为每项操作设置阈值，错误调用的代价越高，阈值就越高。文档中，高风险操作的下限为 0.5 到 0.6，阈值为 0.85 到 0.9。先采用保守设置，再根据你的数据进行调整。三种标准路径是：执行、确认或标记，以及移交。

复合评分。 将复杂判断拆分为每个维度一个 Score。在代码中将每个分数除以 len(criteria) - 1 进行归一化，然后按权重合并。优先级变化时，调整权重即可。不要为了改变策略而重写问题。

意图路由。 使用 Choice 进行分类，并在旁边添加一个复杂度 Score。将每种意图路由到确定性代码、专用大模型或人员。将低置信度的分类交由人员处理。

分类树遍历。 对树的每一层各提一个 Choice，并在代码中遍历分类树。将每个选项的子树作为 criteria 值，让 Jev 知道该分支下包含哪些内容。对于大型子树，可精简为直接子项和部分叶节点示例。概率接近时，沿多个分支继续遍历。

计数。 Jev 不负责计数。在单次请求中为每个项目各提一个 Noul，然后累加通过阈值的答案。

日期。 使用包含枚举选项的 Choice 提取每个日期部分，并包含“未说明”选项。在代码中组合并比较日期。

提取。 使用正则表达式或生成式模型生成候选项。让 Jev 使用 Choice 从中挑选，或使用 Noul 验证其中一项。

from typesafe_sdk import Choice, Noul, Score, TypeSafeClient

SEVERITY = [
    "Cosmetic; no impact to functionality",
    "Broken or degraded feature; a workaround exists",
    "Blocking issue; no workaround exists",
]

with TypeSafeClient() as client:
    response = client.system_one(
        state={"ticket": ticket_text},
        questions={
            "category": Choice(
                instructions="Which category fits the main request in `ticket`?",
                criteria={
                    "bug_report": "Something is broken or producing errors",
                    "billing": "Charges, invoices, refunds, or subscriptions",
                    "other": "Anything else",
                },
            ),
            # Speculative: only used when the ticket is a bug report.
            "severity": Score(instructions="How severe is the issue reported in `ticket`?", criteria=SEVERITY),
            "refund_requested": Noul(instructions="Does `ticket` explicitly ask for a refund or credit?"),
        },
    )

category = response.answers["category"]
severity = response.answers["severity"]
if category.confidence < 0.6:
    route_to_human(ticket_id)
elif category.choice == "bug_report":
    normalized = severity.score / (len(SEVERITY) - 1)
    if normalized > 0.75 and severity.confidence > 0.5:
        escalate(ticket_id)
    else:
        add_to_backlog(ticket_id)
elif category.choice == "billing" and response.answers["refund_requested"].noul > 0.7:
    route_to_billing(ticket_id, refund_likely=True)

读取答案

• score 是按概率加权计算的等级编号均值。分数为 1.0，可能表示确定选择等级 1，也可能表示等级 0 和 2 各占一半。请结合 probabilities 阅读。
• 可以按分数设置阈值、排序，或将其四舍五入到最接近的等级。不要根据它推算数量。Jev 的等级作为数字时校准较弱。
• confidence 衡量分布的集中程度。它描述模型答案的分布，并不保证答案正确。需要使用其他统计量时，可查看完整的 probabilities。
• Noul 没有 confidence。它与 0.5 的距离起到类似作用。
• 每个答案都局限于你提供的选项，因此代码无需解析散文。

改进程序

在做任何改动前，先找出出错的问题。收集带标签的示例，运行它们，并将每个问题的答案和概率与标签进行比较。

症状	可能原因	修复方法
答案错误但置信度高	Jev 按字面理解了指令	明确说明确切条件。将边界情况纳入标准。
某个 Choice 的置信度低	选项有重叠，或没有选项符合	添加 what、not_for 和 examples。添加 other 选项。
某个 Score 的置信度低	各等级有重叠、问题衡量了两件事，或状态信息不足	将各等级改写为不同情境。拆分问题。将缺失字段添加到状态中。
分数集中在中间	各等级只是程度差异或数字	为每个等级描述一个具体情境。删除数字。
最高等级的情况看起来相似	没有为极端情况设置等级	添加一个适用于极端情况的等级。
某个 Noul 的概率徘徊在 0.5 附近	条件含糊不清	明确定义条件。添加带有示例的 true 和 false 标准。
输入增多时准确率下降	状态包含无关细节	在代码中过滤。仅发送必要字段。
计数、求和、日期或数值接近度出错	Jev 在进行算术运算	将算术运算移到代码中。只让 Jev 提取信息或逐项判断。
嵌套或否定问题出错	间接层次太多	直接提问。注明状态路径。将问题拆成两个直白的问题，并在代码中合并结果。
答案受状态中的文本影响	内容在引导模型	收紧标准。测试对抗性案例。根据置信度决定是否执行操作。
改写一个问题后，一种错误减少、另一种错误增加	一个问题权衡了多个属性	将其拆成原子问题，并在代码中合并结果。
每个答案都正确，但最终决策错误	策略有误	在代码中更改权重或阈值。不要改动问题。
程序运行缓慢或成本高	问题分散在多个顺序调用中	将它们合并为一个请求。只有在第二个请求确实依赖第一个答案时才保留它。

修改规则：

• 每次修改一到两个问题。Jev 的概率变化难以预测，因此不要改动区分效果好的问题。
• 在带标签的数据上评估修改。仅有更高的置信度并不代表问题更好，而且同一量表的两种表述在你的数据上可能表现不同。
• 一旦代码依赖答案空间，就保持其稳定。添加或删除等级或选项，会改变此前所有答案的含义。
• 在指令和标准中编写通用规则。具体名称和值只放在 examples 中。

检查清单

• 每个问题只询问一个属性，而且一个人能在一秒内作答。
• 基元类型与代码使用答案的方式相匹配。
• 指令明确说明确切条件，并用反引号标出状态路径。
• 标准与指令一致，且指向相同的方向。
• Score 等级描述具体情境、含义独立，且不包含数字。
• 可能无法涵盖所有输入的 Choice 均有 other 选项。
• 所有计数、算术运算和日期比较均由代码完成。
• 状态只包含问题所需的内容，且符合令牌限制。
• 针对同一状态的所有问题都在同一个请求中发送。
• 每项操作都有与风险相匹配的置信度阈值，且低置信度时有回退方案。
• 权重和阈值都在代码中。
• 每项修改都有带标签的示例作为依据。

来源

• https://docs.typesafe.ai/model-jaggedness/jev-1.13
• https://docs.typesafe.ai/primitives/advanced
• https://docs.typesafe.ai/patterns，包含 /fan-out、/confidence-routing、/composite-scoring 和 /intent-routing
• https://docs.typesafe.ai/primitives、https://docs.typesafe.ai/primitives/score 和 https://docs.typesafe.ai/confidence，模式页面默认读者已了解这些内容
• https://docs.typesafe.ai/llms.txt 列出了所有页面。在文档 URL 后附加 .md 可获取原始 Markdown。