TypeSafe Jev 中文上手：从 API Key 到第一个决策请求

本教程的目标：跑通你的第一个 Jev 决策请求，并理解返回的每个字段。请求结构全部逐字对照官方文档（2026-09-20 快照，jev-1.13.0）；时间与费用相关的数字均为官方口径，可能随版本调整。

第 0 步：拿到 API Key

Jev 目前是早期访问状态。在 TypeSafe 控制台注册并创建 API Key。所有请求用标准 Bearer 头认证：

curl https://api.typesafe.ai/v1/models \
  -H "Authorization: Bearer $TYPESAFE_API_KEY"

GET /v1/models 返回你的账号可用的模型名列表。Key 只存在你自己的环境变量里——本站教程不要求也不应该把 Key 贴给任何第三方工具。

第 1 步：发出第一个 Choice 请求

端点是 POST /v1/systemone，请求体三件套：state（要判断的内容）、model（模型名）、questions（问题字典）。下面是官方文档里的鞋店工单例子：

curl https://api.typesafe.ai/v1/systemone \
  -H "Authorization: Bearer $TYPESAFE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "jev-latest",
    "state": "My running shoes arrived in the wrong size. Can I swap them for a size 10?",
    "questions": {
      "department": {
        "type": "choice",
        "instructions": "Which team should handle this?",
        "criteria": {
          "returns": "Exchanges, refunds, wrong or damaged items",
          "shipping": "Delivery status, delays, lost packages",
          "billing": "Charges, invoices, payment problems"
        }
      }
    }
  }'

department 这个 id 是你自己起的，模型看不到它；答案按同样的 id 归位：

{
  "model": "jev-latest",
  "answers": {
    "department": {
      "type": "choice",
      "choice": "returns",
      "confidence": 1.0,
      "probabilities": { "shipping": 0.0, "returns": 1.0, "billing": 0.0 }
    }
  },
  "usage": { "input_tokens": 330, "output_tokens": 34 }
}

重点看三个东西：

• probabilities 是全部选项的分布（和为 1），不只是被选中的那个；
• confidence 由分布形状计算：概率越摊薄越低。它是你设阈值的依据，不是准确率；
• usage.input_tokens 直接决定费用——官方价格 jev-1.13.0 为输入 $0.042/百万 token、输出不计费。

第 2 步：用 Python SDK 写同一段逻辑

官方 SDK 提供带类型的问题构造器（pip install 走 pypi.typesafe.ai 的 Python SDK）：

from typesafe_sdk import Choice, TypeSafeClient

with TypeSafeClient() as client:
    response = client.system_one(
        state="My running shoes arrived in the wrong size. Can I swap them for a size 10?",
        questions={
            "department": Choice(
                instructions="Which team should handle this?",
                criteria={
                    "returns": "Exchanges, refunds, wrong or damaged items",
                    "shipping": "Delivery status, delays, lost packages",
                    "billing": "Charges, invoices, payment problems",
                },
            ),
        },
    )

print(response.answers["department"].choice)      # returns
print(response.answers["department"].confidence)  # 1.0

JavaScript SDK 同样提供类型化的 Choice / Score 构造器，字段语义与 HTTP API 一致。Score 问题的写法（数组即量表，顺序即档位）见决策原语详解。

第 3 步：把中文内容直接放进 state

state 接受自然语言文本（字符串、JSON 对象或文本数组）。中文可以直发，但官方对非英语能力的表述非常明确：英语是主训练语言、准确率最好；包括中日韩在内的其他语言「被处理但不均等」，要求你用自己的内容先测再用。

最小验证方法：

1. 写 30–50 条你自己业务里的真实样本（客服消息、工单、待分类文本）；
2. 人工标注期望类别（这就是你的黄金集）；
3. 全部跑一遍，记录 choice 命中率与 confidence 分布；
4. 把低置信度样本单独看一遍——它们是「该转人工」的部分，不一定是错误。

客服场景的完整契约与阈值流程在客服分流实战；更抽象的选型背景见Jev vs LLM。

第 4 步：版本别名与限流，两个必须懂的运维细节

版本别名：jev-latest 指向最新稳定版（当前即 jev-1.13.0），SDK 默认用它。但别名会随新版本发布悄悄移动——官方建议：如果你已经针对某个版本调好了置信度阈值，就钉死版本号（如 jev-1.13.0），按自己的节奏迁移新版本。响应里的 model 字段永远回报实际作答的版本 ID，把它记进日志。

限流与重试：官方当前口径为 250,000 tokens/s、1,200 requests/min，且动态调整（早期访问期随时可能变化），超限返回 429。官方客户端 SDK 默认带退避重试并尊重 retry-after 头；直接调 HTTP API 的话，自己实现 429 退避是必修课。高配额需要联系官方的销售方案。

常见坑

• 每次调用只问一个问题——官方明确建议并行问全：多问几个问题的边际延迟很小，代码忽略不需要的答案即可。
• 选项清单只给短名单——Choice 单问题最多 255 个选项，应该给完整清单并加 other 兜底，否则模型被迫硬选。
• 把 confidence 当准确率——低置信度的正确读法是「分布有歧义，走人工」，高置信度也只是「可以自动化」的必要条件。
• 中文效果直接照抄英文结论——先跑你的黄金集，再谈阈值。

跑通之后，下一步是设计一个完整的决策契约并校准阈值——到客服分流实战去；生态里值得参考的开源实现见项目导航。