发布日期：2026-09-24 | 适用版本：jev-1.13.0

Jev 是 TypeSafe 推出的旗舰模型，也是该公司所称的第一个「System One 模型」，它不生成文章，而是接收一段状态和若干带类型的问题，返回代码可以直接判断的数字与选项。本文按真实操作顺序拆解上手全过程：在控制台 console.typesafe.ai/keys 领取密钥、把密钥写进环境变量、用官方 curl 示例发出第一个请求、读懂返回里的 noul、choice、score 三种答案和 confidence 字段，再进一步用 Python SDK 或 MCP 服务把它接到编程智能体里。文中同时给出官方公布的关键参数：单次请求上下文 6.4 万 token、其中状态加最长问题不超过 3.2 万、限速为每秒 25 万 token 与每分钟 1200 次请求、只按输入 token 计费而输出免费，以及官方自己列出的九类失效场景，包括不会数数、不会比日期、英文之外语言准确率偏低这些新手最容易踩的坑。

Jev 是什么：一句话定义

Jev 是 TypeSafe 的旗舰模型，也是其定义的首个 System One 模型，它把自然语言和应用状态转成带校准概率的类型化答案，供代码直接使用，而不是生成给人阅读的文本。

官方文档对设计动机的表述很直白：大语言模型「被设计用来产出供人阅读的文本」，当消费方是代码而不是人的时候，这件事就变得别扭。你问一个模型「这个工单急不急」，它回一段「看起来比较紧急」，程序拿到这句话既不能比较，也分不清模型是有把握还是在猜。

Jev 的做法是把问题本身变成结构。你声明问题类型和可选答案，它返回每个答案的概率，格式固定。代码拿到的是可以和阈值比较的数字。

需要先说清它不做什么：Jev 不生成文本。官方在缺陷清单里把「生成」直接列为第九类失效场景，对应建议是「用生成式模型」。所以它不是 ChatGPT 的替代品，而是判断环节的替代品。

第一步：注册并领取 API Key

打开 console.typesafe.ai/keys 登录后创建密钥，这是官方文档中获取密钥的唯一入口。

官方快速上手页对这一步的描述只有一行：「从 dashboard 获取你的 API key」。注册流程本身文档没有单独说明，控制台登录页会引导完成。

拿到密钥后不要直接写进代码。官方所有示例都从环境变量 TYPESAFE_API_KEY 读取，Python SDK 也默认读这个变量，所以先把它导出：

export TYPESAFE_API_KEY="你的密钥"

想长期生效就写进 shell 配置文件，zsh 用户追加到 ~/.zshrc，bash 用户追加到 ~/.bashrc，然后重开终端或 source 一次。

验证密钥是否可用，最轻的办法是调模型列表接口，它不消耗判断额度：

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

返回里会列出账号可用的模型名。如果返回 401，说明密钥没读到或写错了，先 echo $TYPESAFE_API_KEY 确认变量有值。

第二步：不写代码先在 Playground 试一次

强烈建议在写任何代码之前，先去 console.typesafe.ai/playground 手动跑一遍，这是官方快速上手推荐的第一条路径，能让你在五分钟内理解三种问题类型的差别。

官方给的样例状态是一条客服消息：

Hi, I've been trying to connect my Stripe account for 3 days and the integration keeps failing. I'm losing sales. Please help ASAP.

把它粘进 state，然后加一个 noul 问题：

{
  "urgency": {
    "type": "noul",
    "instructions": "Does this message express urgency?"
  }
}

跑完你会看到一个 0 到 1 之间的数字。这就是 Jev 的全部输出形态：不是「这条消息比较紧急」，而是 0.95。

Playground 支持在一次调用里混合三种问题类型并同时看到全部结果，这一点非常值得在动手写代码前体验一遍，因为它直接决定了后面你会怎么组织请求。

第三步：用 curl 跑通第一个 API 请求

接口地址是 POST https://api.typesafe.ai/v1/systemone，认证方式为 Authorization: Bearer <API_KEY>，请求体必须是 JSON。

下面这段是官方快速上手页原样给出的单问题示例，可以直接粘进终端执行：

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

请求体只有三个字段，全部必填：

state 是被评估的材料，可以是纯文本字符串，也可以是 JSON 对象或文本数组，用来传聊天记录、应用状态这类结构化数据。

model 指定用哪个模型，官方推荐填别名 jev-latest。

questions 是一个映射，键名由你自己定，答案会以同样的键返回。一个容易忽略的细节是官方明确说明键名「不会发送给底层模型，也不参与推理」，所以键名只服务于你的代码可读性，把判断依据写进 instructions 才有用。

第四步：读懂返回的三种答案

这是整个上手过程中最关键的一步，也是最容易半懂不懂的一步。把三种问题一次发出去，就能一次看清全部返回形态。

官方的三问题请求体是这样的：

{
  "state": "Hi, I've been trying to connect my Stripe account for 3 days and the integration keeps failing. I'm losing sales. Please help ASAP.",
  "model": "jev-latest",
  "questions": {
    "department": {
      "type": "choice",
      "instructions": "Which team should handle this",
      "criteria": {
        "billing": "Payment or subscription issues",
        "technical": "Bugs or integration problems",
        "sales": "Pricing or account questions"
      }
    },
    "frustration": {
      "type": "score",
      "instructions": "How frustrated the customer appears",
      "criteria": [
        "Calm, just stating facts",
        "Frustrated but civil",
        "Very angry, strong language"
      ]
    },
    "is_urgent": {
      "type": "noul",
      "instructions": "The message conveys urgency or time-sensitivity"
    }
  }
}

对应返回：

{
  "model": "jev-1.13.0",
  "answers": {
    "department": {
      "type": "choice",
      "choice": "technical",
      "confidence": 0.78,
      "probabilities": {
        "technical": 0.85,
        "sales": 0.0,
        "billing": 0.15
      }
    },
    "frustration": {
      "type": "score",
      "score": 1.0,
      "confidence": 1.0,
      "legend": {
        "0": "Calm, just stating facts",
        "1": "Frustrated but civil",
        "2": "Very angry, strong language"
      },
      "probabilities": {
        "0": 0.0,
        "1": 1.0,
        "2": 0.0
      }
    },
    "is_urgent": {
      "type": "noul",
      "noul": 1.0
    }
  },
  "usage": {
    "input_tokens": 392,
    "output_tokens": 65
  }
}

三种类型的区别和约束如下：

类型

用途

criteria 要求

返回字段

noul

判断一句陈述是否成立

可选，可用 true / false 键说明两种答案含义

noul，0 到 1 的概率

choice

从给定选项里选一个

必填，键为选项名，值可为 null

choice、probabilities、confidence

score

按有序档位打分

必填，数组，按顺序描述每档

score、legend、probabilities、confidence

两个硬限制要记住：choice 最多 255 个选项，score 至少两档、最多接受 10 档。

confidence 只出现在 choice 和 score 的答案里，noul 没有这个字段。它由概率分布推导而来，取值 0 到 1。文档给出的 choice 置信度算法是把最高概率 p 和选项数 n 代入 (n * p - 1) / (n - 1)，也就是说概率完全平均时置信度为 0，某一项概率为 1 时置信度为 1。

score 值是概率加权的期望，可能落在两档之间。这里有个新手陷阱：官方明确要求不要用档位之间的插值去反推精确数值，score 的档位在数值标定上很弱，它只适合判断是否越过某个阈值。

第五步：换成 Python SDK 写进项目

SDK 要求 Python 3.10 及以上，客户端默认从环境变量读密钥并默认调用 jev-latest，所以装完不需要额外配置。

pip install typesafe-sdk

或者用 uv：

uv add typesafe-sdk

官方同步调用示例，和上面那段 curl 做的是同一件事：

from typesafe_sdk import Choice, Noul, Score, TypeSafeClient

client = TypeSafeClient()

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

response = client.system_one(
    state=ticket,
    questions={
        "department": Choice(
            instructions="Which team should handle this",
            criteria={
                "billing": "Payment or subscription issues",
                "technical": "Bugs or integration problems",
                "sales": "Pricing or account questions",
            },
        ),
        "frustration": Score(
            instructions="How frustrated the customer appears",
            criteria=[
                "Calm, just stating facts",
                "Frustrated but civil",
                "Very angry, strong language",
            ],
        ),
        "is_urgent": Noul(
            instructions="The message conveys urgency or time-sensitivity",
        ),
    },
)

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

SDK 默认开启带退避的重试，并在响应携带 retry-after 头时遵守它。直接调 HTTP 接口就得自己实现这套逻辑。

第六步：接到编程智能体里

如果你的目标是让 Claude Code 或 Codex 这类智能体在写代码时用上 Jev，有两条路，选一条就够，同时装会出现重复副本。

第一条是装 MCP 服务，社区项目 typesafe-mcp 提供一个叫 evaluate 的静态二进制，无需 Node 或 Python 运行时：

curl -fsSL https://raw.githubusercontent.com/itsmostafa/typesafe-mcp/main/install.sh | sh

然后一条命令完成注册，它会自动找到本机的 Claude Code、Claude Desktop 和 Codex 并逐个写入配置：

TYPESAFE_API_KEY=你的密钥 evaluate setup mcp

后续升级用 evaluate update 原地替换。如果用的是 pi，命令换成 evaluate setup pi。

第二条是装官方 Agent Skill，它不提供工具调用，而是把 API 用法、三种问题类型和架构模式的完整上下文喂给智能体。Claude Code 用两条命令：

claude plugin marketplace add typesafe-ai/skills
claude plugin install typesafe@typesafe-ai

其他智能体用一条命令，会提示你选择目标智能体，默认装到当前项目，加 -g 装到全局：

npx skills add typesafe-ai/skills --skill typesafe-ai

装完之后在提示词里点名「use the TypeSafe skill」即可，任何智能体都认这种写法。官方推荐的第一条提示词不是让它写功能，而是让它先扫项目找机会：

Using the TypeSafe skill, explore the project and find opportunities for using
intelligent judgement to stand in for complex parsing or other fragile code.

关键参数速查

这些数字直接决定你的请求能不能跑通，官方模型页公布如下：

项

jev-1.13.0

计费方式

只按输入 token 计费，输出 token 免费

价格

每十亿输入 token 为 42 美元，折合每百万约 0.042 美元

限速

每秒 25 万 token，每分钟 1200 次请求

上下文

单请求 6.4 万 token；状态加最长的那一个问题不超过 3.2 万

输入形态

仅文本，可为字符串、JSON 对象或文本数组，不支持图像、音频、视频

典型延迟

通常在半秒以内

上下文这条容易误解，需要拆开看：6.4 万的预算覆盖状态加上所有问题的总和，3.2 万的预算只针对状态加上单个最长的问题。因为 Jev 把状态读入一次后并行评估所有问题，所以多问几个问题延迟增长很小，但总预算是共享的。

限速有一条重要提醒：官方称正在承接非常大的需求量，上述限速可能随时调整而不另行通知，更高限额需走定制或企业方案。所以别把当前数字写死进重试逻辑。

另外别名会移动。jev-latest 和 jev-preview 当前都指向 jev-1.13.0，新版本发布时别名会跟着走，答案可能在你没改代码的情况下变化。如果你已经针对某个版本调过置信度阈值，就把版本号写死，自己决定何时升级。响应里的 model 字段会报告实际应答的版本 ID，建议记日志。

新手最容易踩的六个坑

官方维护了一份 jev-1.13 缺陷清单，最后审阅日期为 2026 年 9 月 17 日，列出九类失效场景。挑出对新手杀伤力最大的几条：

它会字面理解你的提问。 官方原话是它回答你写下的问题，不是你想问的问题。范围词、否定、隐含条件都按字面读。判断方法很好用：当你看着一个错误答案、开始向自己解释「我其实是想问」的时候，那句解释就是你漏写的另一半指令。

它不会数数。 数单词里的字符、数某个词出现几次、数长列表里有几项都不可靠，官方说模型识别的是答案的形状而非逐个清点，误差随被数对象增大而增大。正确做法是在代码里循环，对每个候选问一个问题，然后自己加总。

它不会比日期。 Jev 把日期当文本读，不当有序量。问两个日期谁在前、相差多久、是否落在某个窗口内都不可靠，混合格式和相对表述会让情况更糟。官方建议拆开：抽取交给模型，因为那是判断；算术留在代码，因为那不是。

大而杂的状态会拉低准确率。 不要图省事把整个上下文塞进去，先过滤，只发问题真正需要的部分。

层层套娃的问题会掉准确率。 双重否定、属性的属性、需要多跳推理的问题都算这一类。

中文内容要先自测。 这一条对国内读者格外重要：官方明说英文是主要训练语言、也是当前准确率最好的语言，其他语言包括中日韩文字虽然支持但表现不同等，建议在自己的内容上测过再依赖它，并在路由时格外关注置信度。

报错怎么办

四个状态码覆盖了绝大多数情况：

401 是密钥缺失或无效，先检查 Authorization 头和环境变量。422 是校验失败，比如必填字段没给或问题写得不合法，响应体会指出具体是哪个字段。429 是超限速，稍等再试。529 是服务过载，稍后重试。

对 429 和 529，官方要求用指数退避而不是立即重试，客户端 SDK 在默认重试设置下会自动处理。

常见问题

Jev 会拿我的数据训练吗？

官方模型页写明 Jev 不使用客户请求和响应进行训练，也不用客户数据做微调或 LoRA 适配，所有账号共享同一份权重。企业客户可申请零数据保留。数据处理协议和隐私政策在其法务页面。

既然不能微调，怎么让它适配我的业务？

通过请求本身而不是权重。官方给的三条路径是：把专有内容和参考资料放进 state；把领域规则和边界情况写进每个问题的 instructions 和 criteria；把宽泛判断拆成原子问题，在代码里组合结果。官方强调这样做的好处是业务优先级变化时，你改的是代码里的一个系数，而不是重写提示词。

一次能评估多少条数据？

社区 MCP 项目的说明提到可以在 items 字段里传最多 500 条记录，对每条问同样的问题，其中一条失败其余仍会完成。不过官方 HTTP API 参考页当前只列出 state、model、questions 三个字段，未包含 items，两处文档存在差异，批量场景建议以官方 API 参考为准并实测确认。

置信度阈值该设多少？

没有标准答案，取决于你的业务对误判的容忍度。官方缺陷文档里的示例代码把 noul 阈值设为 0.5 并注明「阈值设多少由你决定，取决于你的用例」。可行的做法是高置信度自动放行、低置信度转人工复核，官方把这个模式称为置信度门控路由。

小结

Jev 的上手门槛比想象的低：领密钥、导环境变量、粘一段 curl，三步就能看到第一个概率返回。真正需要花时间的不是接入，而是学会把一个模糊判断拆成若干个字面清晰的原子问题，并且认清它不会数数、不会算日期、中文表现弱于英文这些边界。

本文所有接口地址、字段名、限制数值与缺陷描述均来自 TypeSafe 官方文档 docs.typesafe.ai 的 API 参考页、模型页与 jev-1.13 缺陷页，缺陷页最后审阅日期为 2026 年 9 月 17 日；MCP 相关命令来自社区项目 itsmostafa/typesafe-mcp 仓库说明。模型别名与限速均会随版本和容量调整而变化，接入前请以实时文档为准。

延伸阅读