JEV注册、使用、部署、安装教程

卷心菜技术创作者 2026-09-25 15 阅读

先说结论

JEV/Jev 是 TypeSafe 的托管 API，请求打到 POST https://api.typesafe.ai/v1/systemone；官方公开文档中没讲自托管/私有化部署，所以“安装 Jev”实际是安装 SDK 或写调用代码。
注册就是到官方控制台拿 key：官方 Quick start 给的入口是控制台的 API Keys 页（地址是 console.typesafe.ai/keys，需要登录后访问，所以直接抓取会返回 403，属正常现象），拿到的 key 放环境变量 TYPESAFE_API_KEY。
Python 侧 pip install typesafe-sdk；JavaScript/TypeScript 侧 npm install @typesafe-ai/sdk，Node.js ≥20。官方 SDK 默认用 jev-latest。
最小调用只有三种问题：choice、score、noul。字段形状不能混：choice 返回 choice/probabilities/confidence；score 返回 score/legend/probabilities/confidence，其 criteria 是有序数组（从低到高）；noul 只返回一个 0~1 的 noul 值，没有 confidence，也没有 probabilities。
上线要盯限流：官方 Models 页写 250,000 tokens/s、1,200 req/min，超了返回 429；官方 SDK 默认带 backoff 重试。日志、密钥管理和低置信兜底是工程侧清单。

证据与过程

先纠正：Jev 是托管 API，没有公开自托管方案

很多“部署教程”写法容易误导，好像要拉模型、装推理服务、开端口。实际上 TypeSafe 文档的入口是从 Playground、API key、cURL 开始的。官方 Quick start 里的调用方式是：

POST https://api.typesafe.ai/v1/systemone
Authorization: Bearer
Content-Type: application/json

它要你带 Bearer $TYPESAFE_API_KEY，这是典型托管 API 形态。官方 API reference 的定位也很清楚：

Evaluate a state against a map of typed questions and get back structured answers, one per question.

也就是说，Jev 是一个评价端点：你把 state 和一组问题发过去，它返回结构化回答。官方 Client SDKs 页的写法也没有任何“本地拉起服务”的步骤，而是：

Install a TypeSafe client SDK and use typed questions and answers in your application.

所以本文的判断是：能装的是 SDK，能“部署”的是你自己的调用代码、函数或网关接入。官方公开文档中没出现自托管/私有部署章节；这一点属于文档范围判断，而不是官方明确否认。为了稳妥，如果你确实需要私有化，应该联系 TypeSafe 官方确认。

注册与拿 key

注册拿 key 的入口在官方 Quick start 里直接给出，就是控制台的 API Keys 页（console.typesafe.ai/keys，需登录；非登录抓取会返回 403）。拿到 key 后，Quick start 示例使用环境变量：

curl -X POST https://api.typesafe.ai/v1/systemone 
  -H "Authorization: Bearer $TYPESAFE_API_KEY" 
  -H "Content-Type: application/json" 
  -d @- <<'EOF'
{
  "state": "Help! My payouts have been failing for 3 days.",
  "model": "jev-latest",
  "questions": {
    "is_urgent": {
      "type": "noul",
      "instructions": "Does this convey urgency?"
    }
  }
}
EOF

这里有两件事值得强调：一是 key 放环境变量，不要硬编码进仓库；二是官方 Quick start 已把 model 写成 jev-latest。官方 Models 页也确认，jev-latest 是客户端 SDK 默认值。

安装：只有两条 SDK 路线

Python：官方 Quick start 提供：

pip install typesafe-sdk

也可以：

uv add typesafe-sdk

官方示例中，SDK 会从环境变量读取 TYPESAFE_API_KEY，并且默认调用 jev-latest。

JavaScript/TypeScript：官方 JavaScript SDK 明确要求 Node.js 20 或更高：

Install the SDK (Node.js 20 or newer): npm install @typesafe-ai/sdk

导入方式为：

import { choice, TypeSafeClient } from "@typesafe-ai/sdk";

因此“安装 Jev”不是安装模型本体，而是安装这两个官方 SDK 之一。JS 包名照官方 JavaScript SDK 页面写为 @typesafe-ai/sdk，不要写成别的。

一次最小调用

下面用 Python 展示一次请求同时带 choice、score、noul。字段按官方 Quick start 和 API Reference 的写法来，并且按本次审稿要求不写错返回字段。

import os
from typesafe_sdk import Choice, Noul, Score, TypeSafeClient

client = TypeSafeClient()  # 读取 TYPESAFE_API_KEY，默认 jev-latest

state = "用户说支付失败已经 3 天，还没解决，很生气。"

response = client.system_one(
    state=state,
    questions={
        "route": Choice(
            instructions="这个工单应该分给哪个团队？",
            criteria={
                "billing": "支付、退款、账单问题",
                "technical": "支付集成或系统故障",
                "sales": "选购、升级、账号问题",
            },
        ),
        # score 的 criteria 是有序数组：从低到高
        "frustration": Score(
            instructions="用户情绪有多强烈？",
            criteria=["平静", "有些不满", "非常生气"],
        ),
        "is_urgent": Noul(
            instructions="用户是否表达出时间紧迫？",
        ),
    },
)

# choice 答案：choice、probabilities、confidence
print(response.answers["route"].choice)
print(response.answers["route"].probabilities)
print(response.answers["route"].confidence)

# score 答案：score、legend、probabilities、confidence
print(response.answers["frustration"].score)
print(response.answers["frustration"].legend)
print(response.answers["frustration"].probabilities)
print(response.answers["frustration"].confidence)

# noul 答案：只有 0~1 的 noul 值
print(response.answers["is_urgent"].noul)

官方 API Reference 对 score 的 criteria 原文是：

An ordered array of level descriptions.

工程上应从低到高排列，这样返回的 legend、score 和 probabilities 的顺序才可读、可解释。noul 只返回一个 noul 值，代码里不要尝试取它的 confidence 或 probabilities，否则会踩空。

“部署”到底指什么

实践中“部署 Jev”往往混用三个意思，要分开讲。

1）在自己的服务里集成调用。这是最常见的一种。你可以在 FastAPI、Flask、Next.js、Netlify Functions、云函数或普通后端里新建 TypeSafeClient，把业务状态作为 state 发过去，再用 choice/score/noul 结果做路由、打分或兜底。这种“部署”实际是部署你的调用代码。官方 Client SDKs 页说：

Our client SDKs provide typed questions and answers for the TypeSafe API and handle retries automatically with their default retry policy.

所以官方 SDK 默认带重试，服务里不用一开始就自己写重试循环。

2）走 AI Gateway。Netlify 官方 changelog 已经宣布接入 Jev，标题就是：

TypeSafe Jev now available in AI Gateway

该页的表述是：

Install @typesafe-ai/sdk and use it directly in your Netlify Functions — no API keys to create, no provider config, no base URLs to wire up.

来源链接见 Netlify changelog。这种情况下，你的 Netlify Function 通过网关访问 Jev，网关自动处理凭证，费用走 Netlify credits。这是“部署”的另一种含义：不是部署模型，而是把函数和网关接入一起部署。Vercel AI Gateway 等其它网关是否已接入，本文未获得官方来源，放到后面“这次没核实的”一节。

3）在编码 agent 里安装官方 skill。官方 Agent skill 页描述为：

Drop-in skill for Claude Code, Codex, and other agent environments.

Claude Code 安装命令：

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

其他 agent 可以用：

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

这也不是“部署模型”，而是把 TypeSafe API 的三种问题类型、架构模式、最佳实践导入编码 agent。如果你让 agent 写集成代码，先装 skill 可以在一定程度上减少 agent 编造请求或响应字段。

上线清单：限流、日志、低置信兜底

官方 Models 页给出 Jev 1.13 的限流数字，属于官方数据：

250,000 tokens per second
1,200 requests per minute
任一超限返回 429 Too Many Requests

原文是：

A request over either limit returns 429 Too Many Requests . Our client SDKs retry with backoff by default and honor the retry-after header when the response carries one.

这里要注意：官方 SDK 会自动重试，并且尊重 retry-after 响应头；如果你用 HTTP API 直接调用，需要自己实现 429 的 backoff。官方 Models 页还提示，限流数字是动态调整的：

Rate limits are adjusting dynamically.

所以我们不能把 250k/1,200 当死值，但可以作为容量规划参考。

日志方面，官方 Models 页说明 SDK 默认用 jev-latest，但响应里的 model 字段会报告实际版本 ID。工程上应至少记录 model，这样 alias 移动导致行为变化时可以追溯。至于 token 用量字段，本文没有从给定来源核到具体结构，放到未核实。

低置信度兜底是实践中的常用做法，不是官方推荐某个具体数字。官方 Agent skill 页反而提醒：

If all you care about is choosing the best option, you just need to choose the option with the highest confidence (rather than setting a confidence threshold).

因此本文的上线清单是：优先用最高置信选项做自动路由；如果业务必须有人工复核，只在特定问题或特定场景里设置阈值，阈值应集中放在一份常量文件里，便于评审和调整，不要散落各处。也不要照抄网络上的“通用阈值”。

自己的判断/清单

先分清 API 服务和 SDK：要装的是 typesafe-sdk 或 @typesafe-ai/sdk，不是 Jev 本体。
先用 Playground 验证问题设计，再用 key 写代码；Playground 可以帮你快速看 choice/score/noul 的行为。
对 score 的 criteria 必须当有序数组维护，从低到高；对 noul 不要期待 confidence 或 probabilities。
如果你的服务在 Netlify，先查 Netlify AI Gateway，它能省掉 key、provider 配置和 base URL；否则直接走官方 API 并管好 TYPESAFE_API_KEY。
限流规划按官方给的 250k tokens/s、1,200 req/min，但要把它当作动态值；依赖 SDK 重试，或自己实现 429 backoff。
日志至少记录 model；低置信度兜底用自己业务的阈值，代码中集中管理。

这次没核实的

官方是否提供私有化/自托管：官方公开文档未见自托管章节，但“没有”是文档范围判断，不是官方明确声明；企业定制需联系官方确认。
Python SDK 的精确最低版本范围：Quick start 片段显示 Python 3.10+，但建议使用前打开官方 Python SDK 再确认。
usage/token 字段：官方 Models 页写了价格按输入 token 计费、输出免费，但给定来源未展示响应里的 token 用量字段结构。
Vercel AI Gateway 或其他网关是否接入 Jev：未提供官方来源，未能核实。
中文/英文精度差距：官方 Models 页只说 English best、CJK handled but not equally well，没给可量化数字，需要在自己的业务数据上实测。

参考来源

# Agent # 教程

评论区

0 条评论

登录后可评论。