发布日期：2026-09-21 | 话题：Jev 使用教程 / TypeSafe API / System One 模型 / Choice Score Noul

Jev 是 TypeSafe AI 于 2026 年 9 月 15 日发布的首个 System One 决策模型，开发者通过一个 POST 接口发送一段状态文本和若干类型化问题，模型并行返回带校准概率的结构化答案而不生成任何文字。本指南基于 TypeSafe 官方文档、Python 与 JavaScript SDK 仓库以及模型页 2026 年 9 月 21 日的内容，完整走一遍 Jev 的使用流程：在 Playground 试用、到控制台申请 API Key、用 curl 或 Python SDK 发起首次调用、理解 Choice、Score、Noul 三种问题的字段与返回值、用 confidence 阈值做三档路由、用开源适配器把同一套问题跑到大模型上做对照，以及速率限制、上下文预算、语言支持等落地前必须知道的限制。当前模型版本为 jev-1.13.0，输入每百万 Token 0.042 美元、输出免费，速率上限每秒 25 万 Token、每分钟 1200 请求，状态加最长问题不超过 32K Token。

Jev 是什么，适合拿来做什么

Jev 是 TypeSafe AI 的旗舰模型，官方定义为"发送状态与类型化问题，得到代码可直接使用的结构化答案"。它不做文本生成，只从开发者定义的选项、等级或是非中作答，每个答案附带概率分布，所以适合放在代码的判断节点上，而不是替代大模型写内容。

据 TypeSafe 官方文档 2026 年 9 月数据，Jev 的四项关键规格如下：

项目

规格

当前版本

jev-1.13.0，别名 jev-latest 与 jev-preview 均指向它

价格

输入每百万 Token 0.042 美元，输出免费

速率限制

每秒 25 万 Token、每分钟 1200 请求，超限返回 429

上下文

每请求 64K Token，其中状态加最长单个问题不超过 32K

典型用途是工单分派、意图识别、内容打分、真伪判断、去重和大模型输出的护栏检查。官方明确 Jev 只接受文本，图片、音频、视频需先转成文本或结构化字段。

第一步：在 Playground 试用并申请 API Key

Jev 目前处于早期访问阶段，使用流程分三步：

  1. 登录 Playground：https://docs.typesafe.ai/introduction/quickstart，打开 console.typesafe.ai/playground，粘贴任意一段文本作为状态，添加一个 Noul 问题如"Does this message express urgency?"，即可看到返回的概率。

  2. 申请 API Key：在控制台的 Keys 页面创建密钥，官方文档写明"Get your API key from the dashboard"。

  3. 设置环境变量：SDK 默认读取 TYPESAFE_API_KEY，无需在代码中硬编码。

export TYPESAFE_API_KEY="你的密钥"
pip install typesafe-sdk        # Python 3.10 以上
npm install @typesafe-ai/sdk    # Node.js 20 以上

据 PyPI 与 npm 2026 年 9 月 21 日数据，Python 包 typesafe-sdk 最新版为 0.7.0，JavaScript 包 @typesafe-ai/sdk 最新版为 0.6.0。名为 typesafe-ai 的 PyPI 包只是跳转壳，实际安装的仍是 typesafe-sdk。

第二步：用 curl 发起第一次调用

Jev 的全部模型共用一个端点，请求体只有三个顶层字段：state、model、questions。

curl -X POST https://api.typesafe.ai/v1/systemone \
  -H "Authorization: Bearer $TYPESAFE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "state": "Hi, I have been trying to connect my Stripe account for 3 days and the integration keeps failing. I am losing sales. Please help ASAP.",
    "model": "jev-latest",
    "questions": {
      "urgency": {
        "type": "noul",
        "instructions": "Does this message express urgency?"
      }
    }
  }'

返回体的顶层字段为 model、answers、usage。model 字段返回实际作答的版本号，即使请求里写的是别名，便于日志记录。

{
  "model": "jev-1.13.0",
  "answers": {
    "urgency": { "type": "noul", "noul": 0.99 }
  },
  "usage": { "input_tokens": 360, "output_tokens": 39 }
}

第三步：理解三种问题类型

Jev 只有三种问题原语，可在同一次请求中任意混用，所有问题针对同一状态并行独立评估，官方称"增加问题几乎不改变响应时间"。

原语

用途

请求字段

返回字段

Choice

从固定选项中选一个

instructions、criteria（选项名到描述的映射，最多 255 项）

choice、probabilities、confidence

Score

按有序等级打分

instructions、criteria（从低到高的等级描述数组，2 到 10 级）

score、probabilities、confidence、legend

Noul

判断是非

instructions，可选 criteria 说明 true 与 false 各指什么

noul（0 到 1 的"是"概率）

三个字段的设计细节：

  • 问题 id 不会发给模型。字典键只用于回传答案，模型看到的是 instructions 和 criteria 的内容，因此选项描述必须能彼此区分。

  • Score 的分值等于等级在数组中的下标。三级量表返回 0 到 2 之间的加权均值，如 0.57 概率落在第 1 级、0.43 落在第 2 级则 score 为 1.43。官方建议"描述情境而非程度"，纯数字等级会导致概率分散。

  • Noul 没有 confidence 字段。二元分布用一个数即可完整描述，接近 1 为强"是"，接近 0 为强"否"。

用 Python SDK 一次问三个问题：

from typesafe_sdk import Choice, Noul, Score, TypeSafeClient

ticket = "Hi, I have been trying to connect my Stripe account for 3 days and the integration keeps failing. I am losing sales. Please help ASAP."

with TypeSafeClient() as client:
    response = client.system_one(
        state=ticket,
        questions={
            "department": Choice(
                instructions="Which team should handle this",
                criteria={
                    "billing": "Payments, invoices, refunds",
                    "technical": "Integration errors, API failures, bugs",
                    "sales": "Pricing questions, upgrades, new purchases",
                },
            ),
            "frustration": Score(
                instructions="How frustrated is the customer",
                criteria=[
                    "Neutral or polite, no complaint",
                    "Annoyed, mentions a problem but stays civil",
                    "Angry, threatens to leave or uses hostile language",
                ],
            ),
            "is_urgent": Noul(instructions="Does this message express urgency?"),
        },
    )

print(response.answers["department"].choice)       # technical
print(response.answers["frustration"].score)       # 1.0
print(response.answers["is_urgent"].noul)          # 1.0

状态字段可以是字符串，也可以是 JSON 对象或数组。官方建议多数请求用对象，把工单、订单、退款政策等相关信息放进同一个 state 并各自命名，模型只读取一次状态再并行回答所有问题。

第四步：用 confidence 做三档路由

confidence 是从概率分布形状压缩出的 0 到 1 单值，全部概率集中在一个选项时为 1.0，分布越平均越低。官方给出的三选项近似公式为最大概率乘 3 减 1 再除 2。它只描述模型输出的分布形状，官方明确"不是答案正确的保证"。

官方推荐的用法是把 confidence 作为第二个决策维度，按操作风险设不同门槛：

from typesafe_sdk import Choice, TypeSafeClient

with TypeSafeClient() as client:
    response = client.system_one(
        state=user_message,
        questions={
            "action": Choice(
                instructions="What does the user want to do",
                criteria={
                    "check_balance": "View account balance",
                    "approve_transfer": "Approve a pending withdrawal",
                    "support": "Get help with something else",
                },
            )
        },
    )

# route_to_human、show_balance 等为业务侧自定义函数
answer = response.answers["action"]

if answer.confidence < 0.5:
    route_to_human(user_message)            # 模型确实不确定，不要猜
elif answer.choice == "check_balance":
    show_balance(account_id)                # 低风险、可恢复，直接执行
elif answer.choice == "approve_transfer":
    if answer.confidence > 0.9:
        confirm_then_execute(account_id)    # 高风险操作要求更高门槛
    else:
        ask_user_to_confirm(account_id)

官方文档把这一模式命名为 Confidence-Gated Routing，另外三种官方模式是 Speculative Fan-Out（一次发出多个推测性问题、由代码决定用哪些）、Composite Scoring（多个原子 Score 在代码中加权合成）和 Intent Routing（分类后分别交给确定性逻辑、专用大模型或人工）。阈值的原则是先保守、用自己的数据测、再调整。

第五步：用开源适配器和大模型做对照

TypeSafe 开源了 system-one-adapter-python，它是 TypeSafeClient 的替代实现，用同一套 Choice、Score、Noul 接口调用大模型，方便在成本、速度、准确率上做同题对比。据 GitHub 2026 年 9 月 21 日数据，该仓库有 209 个星标，PyPI 版本 0.2.0。

pip install 'system-one-adapter[openai]'
from system_one_adapter import SystemOneAdapterClient, Noul
from system_one_adapter.providers.openai import OpenAIProvider

client = SystemOneAdapterClient(
    structured_outputs=True,
    llm_answer_mode="probabilities",
    normalize_probabilities=True,
)

response = client.system_one(
    state="This book was a delight to read.",
    questions={"positive": Noul(instructions="The book review is positive.")},
    model=OpenAIProvider("模型名", base_url="https://你的兼容端点/v1"),
)
print(response.answers["positive"].noul)
print(response.usage.latency, response.usage.input_tokens_total)

适配器的 OpenAIProvider 接受任意 OpenAI 兼容端点作为对照组，响应对象额外带 latency、重试次数和每次请求的原始记录。国内开发者做对照实验时，七牛云 AI 大模型广场提供多款主流大模型的 OpenAI 兼容接口，Token Plan 按用量计费。

第六步：落地前必须知道的限制

据 TypeSafe 模型页与独立测试者 Emil Lindfors 2026 年 9 月 18 日的报告，Jev 有六项限制：

  1. 速率限制动态调整。官方警告在 GPU 供给到位前限制"可能不经通知变化"，SDK 默认按 retry-after 头退避重试，Python 中超限抛出 TypeSafeRateLimitError。

  2. 上下文预算双重约束。64K 覆盖状态加全部问题，32K 覆盖状态加最长单个问题，超长文档需先切分。

  3. 英语优先。官方称中日韩文字"可以处理但准确率较低"，Lindfors 的挪威语测试发现每 Token 约 2.06 字符，32K 只能装约 6.4 万字符。

  4. 按字面读指令。测试者发现问题写得越谨慎间接，与参考标签的一致率越低，官方建议措辞直接、让高值对应"是"。

  5. 不可微调。同一套权重服务所有账户，领域知识只能通过 state 和 criteria 注入。

  6. 不解释理由。输出只有选项与概率，需要推理链的合规场景不适用。

官方另提供 Agent Skill，在 Claude Code 中运行 claude plugin marketplace add typesafe-ai/skills 后可让 AI 编程助手按官方规范生成集成代码，据 GitHub 数据该仓库有 1270 个星标。

常见问题

Jev 现在可以直接注册使用吗？

处于早期访问阶段，需登录 console.typesafe.ai 加入候补名单后获得 API Key。Playground 登录后可直接体验。第三方网关 OpenCode Zen 已上架 jev-1.13 与免费版 jev-1.13-free，可作为试用入口。

model 字段填 jev-latest 还是 jev-1.13.0？

官方建议开发阶段用 jev-latest，生产环境若已按某版本调好 confidence 阈值则锁定版本号，因为别名随新版本发布会自动迁移。响应中的 model 字段始终返回实际版本号，可用于日志核对。

Jev 会记录我的数据吗？

官方模型页写明 Jev 不使用客户请求与响应训练，企业客户可申请零数据保留。服务部署于美国西海岸，跨境数据传输需自行评估合规。

一次请求最多能问多少个问题？

官方未给出问题数上限，约束来自 64K 总上下文。每个 Choice 最多 255 个选项，每个 Score 最多 10 级。官方推荐把可能用到的问题一次全发出去，代码只读需要的答案，代价是全部问题都计入输入 Token。

Jev 输出的 score 是 1.0，能说明什么？

只能说明加权均值为 1.0，不能说明分布。它可能是全部概率集中在第 1 级，也可能是第 0 级和第 2 级各占一半。官方要求 score 必须和 probabilities、confidence 一起读。

总结

使用 Jev 的核心步骤是：在控制台申请 API Key，向 api.typesafe.ai/v1/systemone 发送 state 与 questions，用 Choice、Score、Noul 三种原语把复杂判断拆成原子问题，再用 confidence 阈值在代码中决定自动执行、请用户确认或转人工。它的价值在于毫秒级延迟和校准过的概率，前提是任务能被表述为选择、评分或是非题，且输入以英语文本为主。本文所有字段名、限制与版本号取自 TypeSafe 官方文档、SDK 仓库及 PyPI、npm 2026 年 9 月 21 日数据，Jev 处于早期访问阶段，速率限制与定价可能调整。

延伸阅读