Jev 从入门到项目指引

Jev 产品概述

1. Jev 从入门到项目指引

1.1. Jev是什么

一句话：读自然语言，但不生成文字，只回「有类型的判断」+ 校准过的概率。

Jev 与大模型对比

和普通大模型的区别不在「更聪明」，而在输出形态：

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

⚠️ 延迟、计费、上下文这三行不在官方 API 参考里（官方页只给了 usage 的 token 计数示例）。

要用在预算里，先自己实测或问 TypeSafe 确认。

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

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

1.2. 秒上手

30 秒上手教程

原生端点：

POST https://api.typesafe.ai/v1/systemone
Authorization: Bearer $TYPESAFE_API_KEY

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

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

{
  "model": "jev-latest",
  "state": "帮帮我，我的付款已经失败三天了，客服一直没人回！",
  "questions": {
    "is_urgent":  { "type": "noul",   "instructions": "这段话表达了紧急吗？" },
    "department": {
      "type": "choice",
      "instructions": "该由哪个团队处理？",
      "criteria": {
        "billing":   "付款、开票、退款",
        "technical": "Bug、故障、集成",
        "sales":     "报价、升级、开新户"
      }
    },
    "frustration": {
      "type": "score",
      "instructions": "客户有多沮丧？",
      "criteria": ["平静", "不满", "非常生气"]
    }
  }
}

返回（✅ 官方 schema）：

{
  "model": "jev-1.13.0",
  "answers": {
    "is_urgent":   { "type": "noul", "noul": 0.96 },
    "department":  { "type": "choice", "choice": "billing", "confidence": 0.91,
                     "probabilities": { "billing": 0.98, "technical": 0.01, 
                     "sales": 0.01 }
    },
    "frustration": { "type": "score", "score": 1.3, "confidence": 0.78,
                     "legend": { "0": "平静", "1": "不满", "2": "非常生气" },
                     "probabilities": { "0": 0.12, "1": 0.46, "2": 0.42 } }
    },
  "usage": { "input_tokens": 214, "output_tokens": 0 }
}

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

✅ 官方错误码

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

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

1.3. 三类问题（核心）

三类问题类型说明

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

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

noul —— 是/否

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

{ "type": "noul", "instructions": "这是不是一个退款请求？",
  "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 是「是/否各占一半」，不是「中等」。

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

概率与置信度对比

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

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

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

  • 选中项概率高、confidence 也高 → 放心自动化
  • 选中项概率高、但 confidence 低 → 说明几个选项咬得很紧，值得人工扫一眼
  • 选中项概率低 → 无论 confidence 如何，都该进复核

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

const selected = department.probabilities?.[department.choice] ?? 0;
if (departmentConfidence < 0.6 || selected < 0.7) return { action: 'human-review' };

1.5. 怎么写好问题

问题写作指南

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

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

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

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

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

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

1.6. 什么时候该用 / 不该用

适用场景判断

该用：

  • 循环里的高频小判断 —— 路由、分类、分诊、校验、状态判断
  • 你已经在用大模型做这些，但嫌贵 / 慢
  • 需要拿概率去卡阈值决定「自动处理还是转人工」的场景

不该用：

  • 任何要生成文本的地方
  • 需要它解释「为什么这么判断」的地方 —— 它不解释
  • 强监管、要可审计的领域（金融 / 医疗 / 法律）—— 只给结论不给理由，很难过合规
  • 需要多模态输入的场景

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

1.7. 接入方式

接入方式对比

途径 地址 / 包 备注
原生 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 可能随时变。另外工具拦截只是拒绝危险调用，不等于请求批准，需要人工审批时还得再叠一层。

1.8. 常见坑

常见坑与避坑指南

  • 概率是四舍五入到两位小数的，choice 的各选项加起来可能只有 0.99。不要自己重新归一化，SDK 校验时已经处理了。
  • noul 的 0.5 是「不确定」，不是「中等」。要程度用 score。
  • 阈值要按动作定，不是按模型定。只读操作 0.7 也许够，破坏性操作得到 0.9 以上，且下面还得留确认步骤。
  • 校准 ≠ 单次正确。概率说的是「这类判断在大量样本上的命中率」，不保证这一次对。要拿你自己标注的数据跑一遍再定阈值。
  • 高 confidence 不等于正确答案 —— 它只说明分布集中。
  • API 升级会改默认模型：jev-latest 随时指向新版本；要可复现就锁 jev-1.13 这种具体版本。响应里的 model 字段回显的是实际作答的版本。

1.9. 速查表

速查表

端点    POST /v1/systemone
必填    model · state · questions
state   字符串 / JSON 对象 / JSON 数组，≤32K token，纯文本
问题    noul(是-否) · choice(多选一) · score(有序刻度)
并行    同一请求内所有问题并行求值，多问几乎不加延迟
计费    只算 input token
返回    model · answers · usage
坑      probability ≠ confidence；noul 无 confidence；别重新归一化

相关站点

1.10. 注册账号

官网地址： https://typesafe.ai/ 目前采用的是申请制，右上角 填了邮箱申请后，再填下个人相关信息，有个人链接 如推特链接、官网都可以加号上 可以提高通过率，审核通过后，邮箱点击登录账号即可！

注册页面截图

申请api key ：https://console.typesafe.ai/keys 密钥只显示一次，泄露可重新创建

1.11. 上手实战

上手实战示例

单条信息判断大可不必用Jev, 还是要大量判断请求的时候派上用场！

1.技术可选传统脚本 api 对接方式，可以看上面详解

2.非技术背景 直接vibe coding模式 直接把提示词发给agent

Install the TypeSafe skill. If you're in Claude Code, run `claude plugin marketplace add typesafe-ai/skills`, then `claude plugin install typesafe@typesafe-ai`. If you're in another agent, run `npx skills add typesafe-ai/skills --skill typesafe-ai` and select your agent. Use one installation method. You can read the skill directly at https://github.com/typesafe-ai/skills/blob/main/skills/typesafe-ai/SKILL.md (raw: https://raw.githubusercontent.com/typesafe-ai/skills/main/skills/typesafe-ai/SKILL.md). Then use the TypeSafe skill when working on this project.

3.使用开源项目，开源项目列表

购买飞机票：

https://github.com/browser-use/jev-ultrafast

用Jev的决策替换压缩摘要:

https://github.com/tamaratran/fast-jev-compaction

与官方无关的开源Jev

https://github.com/TheoLeeCJ/SemIf

加密货币自动交易工具

https://github.com/jarrodwatts/jev-trader

附录：

Jev 迭代很快，动手前先对一遍当前文档。 ⚠️ 来源标注：正文中标 ✅ 的来自官方文档；标 ⚠️ 的来自三方平台文档（AI/ML API、Vercel、LangChain、OpenRouter），官方页面上没有的，用之前建议再核一次。