ㅤ	大模型	Jev
输出	一段文字	你事先定义好的答案（选项 / 分数 / 是-否）
典型延迟 ⚠️	秒级	70–500 毫秒
计费 ⚠️	输入 + 输出 token	只算输入，输出不收费
上下文 ⚠️	通常 100K+	32K，纯文本输入（不收图片/音频/视频）

名字来自经济学家杰文斯和「杰文斯悖论」；TypeSafe 管它叫 System One 模型（卡尼曼意义上的快思考）。

它擅长：路由、分类、分诊、要不要拦下来。 它不擅长：写东西、解释理由、任何需要生成文本的活儿。

二、30 秒上手

原生端点：

API key 在 console.typesafe.ai 拿。模型 ID 用 jev-latest（或锁版本 jev-1.13、jev-1.13.0）。

以下为电商客服收到信息的场景，请求只有三个字段：

返回（✅ 官方 schema）：

一个请求里三类问题可以混用，而且是并行求值的 —— 所以多问几个问题几乎不增加延迟。这是它和「串行调大模型」最大的体感差别。

✅ 官方错误码

状态	含义	处理
`401`	key 缺失或无效	检查 `Authorization` 头
`422`	请求体校验失败	响应体会点名是哪个字段
`429`	限流	指数退避后重试
`529`	服务过载	稍后重试

官方说 429/529 用指数退避，官方 SDK 默认自带重试。

三、三类问题（核心）

所有问题共享同一个 state，各自独立求值。

类型	问什么	返回
`noul`	这句话成立吗	一个 0–1 的概率（就是答案本身）
`choice`	几个选项里选一个	选中的 key + 每个选项的概率 + confidence
`score`	在一条有序刻度上落在哪	分数（可能是小数）+ legend + 概率 + confidence

noul —— 是/否

criteria 可选，但强烈建议给，用 true / false 两个描述把边界钉死：

⚠️ noul 不返回 confidence —— 因为对二元问题来说，概率本身就是置信度。

✅ 另外：instructions 不只接受字符串，也可以是对象或数组 —— 把问题放一个字段、被引用的数据放别的字段，在问题里用反引号按名字指过去（比如 `sources`）。state 比较长时这个写法更清爽。

choice —— 多选一

criteria 是 选项key → 描述 的映射，最多 255 个选项。返回的 probabilities 里，被选中的那个一定是最大值。

✅ 每个选项的值可以是字符串、对象、数组，也可以是 null（不需要额外说明时就用 null，比如纯枚举那一项）。

务必留一个兜底选项（other / unclear）—— 模型选不出你没给的选项。如果不留，遇到都不沾边的内容它会硬选一个。

score —— 有序刻度

criteria 是有序数组，从低到高，最少 2 档、最多 10 档（✅ 官方明确写了上限 10）。

返回的 score 是概率加权平均，从 0 开始编号，所以可能是小数（上例 1.3 表示介于「不满」和「非常生气」之间）。legend 把档位编号映射回描述。

⚠️ 想要「程度」就用 score，别用 noul。noul 返回 0.5 是「是/否各占一半」，不是「中等」。

四、概率 ≠ 置信度（最容易搞混的地方）

choice 和 score 会同时返回两个不同的数：

ㅤ	含义
`probabilities[选项]`	模型认为这个答案对的可能性
`confidence`	概率分布有多集中（0 = 摊平，1 = 全压一个）

两者会背离。两个都要看：

选中项概率高、confidence 也高 → 放心自动化

选中项概率高、但 confidence 低 → 说明几个选项咬得很紧，值得人工扫一眼

选中项概率低 → 无论 confidence 如何，都该进复核

Vercel 的示例是双阈值同时卡：

五、怎么写好问题

这部分比 API 本身更决定成败。

1. 一个问题只问一件事。 Jev 的最佳区间是「一个有经验的人几秒钟能答完的问题」。别问「给这个 PR 打分」，拆成三个 score（测试覆盖、文档、描述清晰度），自己在代码里加权。

2. 描述，不要贴标签。 "有阻塞且无绕过方案" 比 "高" 给模型的信息多得多。criteria 里可以放示例短语。

3. state 只放这次判断需要的字段。 输入 token 是唯一计费维度，塞无关内容既贵又干扰。

4. 问「state 说了什么」，不要问「你会得出什么结论」。 前者是事实判断，后者要它替你做推理 —— 那不是它的活。

5. 分类 ≠ 授权。 Jev 能识别「客户在要求退款」或「这条命令看起来危险」，但该不该批准取决于它看不到的规则（账号状态、政策、权限）。把它当成流水线上的一个检查点，别当成最终裁决。

六、什么时候该用 / 不该用

该用：

循环里的高频小判断 —— 路由、分类、分诊、校验、状态判断

你已经在用大模型做这些，但嫌贵 / 慢

需要拿概率去卡阈值决定「自动处理还是转人工」的场景

不该用：

任何要生成文本的地方

需要它解释「为什么这么判断」的地方 —— 它不解释

强监管、要可审计的领域（金融 / 医疗 / 法律）—— 只给结论不给理由，很难过合规

需要多模态输入的场景

一个典型搭配：贵的前沿大模型做规划（系统二），高频廉价的判断交给 Jev（系统一）。

七、接入方式

途径	地址 / 包	备注
原生	`https://api.typesafe.ai/v1/systemone`	key 在 console.typesafe.ai
TypeScript SDK	`@typesafe-ai/sdk` → `client.systemOne({...})`	ㅤ
Python SDK	`typesafe-sdk` → `client.system_one(...)`	✅ 要求 Python ≥ 3.10
OpenRouter	base URL 换成 `https://openrouter.ai/api`	模型名加前缀 `typesafe/jev-1.13`；`jev-latest` 映射成 `~typesafe/jev-latest`
Vercel AI Gateway	`typesafe-ai/jev`，走 `experimental_evaluate`	需 AI SDK 7.0.105+；支持逐请求 ZDR
LangChain	`langchain-typesafe` → `TypeSafeClassifier`	是个 Runnable，可 invoke/batch/组合；带 LangSmith trace
Pydantic AI	provider `typesafe:jev-latest`	类型化输出
Postgres	社区扩展 `jev`	`jev()` / `jev_prob()` / `jev_choice()` / `jev_score()`

SDK 都会读环境变量 TYPESAFE_API_KEY 和 TYPESAFE_BASE_URL，所以换网关只要改 base URL。

注意：LangChain 的 agent middleware（ModelRouterMiddleware 做模型路由、AutoModeMiddleware 做工具风险拦截）目前标着 experimental，API 可能随时变。另外工具拦截只是拒绝危险调用，不等于请求批准，需要人工审批时还得再叠一层。