JEV怎么使用？官网入口是什么？

先说结论

• 官网入口是 typesafe.ai，但实际开发入口建议直接落到 docs.typesafe.ai；AI 编码工具可以先读 docs.typesafe.ai/llms.txt。
• 最短上手路径按官方 Quick start 是：Playground 试 → 控制台拿 key → cURL 打通 → SDK 落地。
• 核心 API 事实：POST https://api.typesafe.ai/v1/systemone，model 用 "jev-latest"。
• Jev 是 TypeSafe 的 System One 模型，不是普通聊天补全模型；请求要提供 state 和 questions，答案按你给的问题 id 原样返回。
• 生态入口要分清：Netlify、LiteLLM 的公告是平台方/集成方一手信息，不是 TypeSafe 官方文档；Vercel AI Gateway 本次未能核实到可引链接。

官方入口：按三个用途收好

我建议只记三个“根”，其余都能从文档索引展开：

• 产品官网：typesafe.ai
• 文档总入口：docs.typesafe.ai
• 给 AI 编码工具的文档索引：docs.typesafe.ai/llms.txt

官方 llms.txt 自己也写明：

Fetch the complete documentation index at: https://docs.typesafe.ai/llms.txt Use this file to discover all available pages before exploring further.

下面是与“最短上手”直接相关的入口清单：

入口	链接	用途
官网	typesafe.ai	产品首页
官方文档	docs.typesafe.ai	文档首页
llms.txt	docs.typesafe.ai/llms.txt	给 agent／人枚举文档页
Playground	console.typesafe.ai/playground	不写代码先试
API keys	console.typesafe.ai/keys	拿 key
API Reference	docs.typesafe.ai/api	HTTP 字段与请求/响应
SDK 总览	docs.typesafe.ai/sdk	Python/JS SDK 入口
Python SDK	docs.typesafe.ai/sdk/python.md	Python 安装与用法
JavaScript SDK	docs.typesafe.ai/sdk/javascript.md	JS/TS 安装与用法
Agent skill	docs.typesafe.ai/agent-skill	给 coding agent 装技能

这些链接来自 TypeSafe 官方文档、控制台或 SDK 页面，属于一手来源；我按工程使用习惯把它分成“产品入口、文档入口、控制台入口”，这是本文的整理方式，不是官方目录规定。

最短上手：从零到第一次调用

官方 Quick start 的定位很清楚：

Prefer to just dive in? Here’s everything you need to get started immediately.

第一步：Playground 先试

打开 Playground，把任意文本作为 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.

然后加一个 Noul 问题，比如：Does this message express urgency?。接着可以再混加 Choice、Score，一次请求看多个结果。这是官方 Quick start 的试法。

第二步：控制台拿 key

到 API keys 拿 TYPESAFE_API_KEY。

第三步：cURL 打通

用 HTTP API 先确认网络、鉴权和字段都可通。这里我按官方 API Reference 的示例整理一个最小可复跑命令：

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

这里的 state、model、questions 都是官方 API Reference 写明必填的字段。model 用 "jev-latest"，API Reference 原文是：

Use “jev-latest”, TypeSafe’s flagship model.

注意不要把请求体写成聊天 messages，因为 Jev 不是聊天补全接口。

第四步：SDK 落地

官方 SDK 页面写明，客户端 SDK 会返回类型化问题和答案，并带默认重试策略。Python 可这样安装：

pip install typesafe-sdk

官方 Quick start 给的 Python 示例如下，我按原文保留字段形状，不加额外参数：

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)  # "technical"
print(response.answers["frustration"].score)  # 1.0
print(response.answers["is_urgent"].noul)     # 1.0

从这个官方示例可以看到：Score 的 criteria 是数组，从低到高描述；Choice 的 criteria 是选项到描述的 map；Noul 这里只有 instructions。三类答案分别读 .choice、.score、.noul。

API 形状：别在这几个字段上出错

官方 API Reference 给出的评估端点如下：

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

请求顶层三件套是 state、model、questions。state 可以是 string/object/array，questions 是一个 map，key 由你命名，回答会按同一 key 返回。API Reference 也写明，问题 id 不会发给底层模型，也不参与推理。

三种问题类型返回形状，按本次写作工单约束列成表，方便审稿：

问题类型	criteria 形状	答案字段
choice	map：选项 → 描述	choice、probabilities、confidence
score	有序数组，从低到高	score、legend、probabilities、confidence
noul	可选 true/false 描述	noul（0~1）

其中 legend 字段按本次写作工单约束补入；choice/probabilities/confidence 与 score/probabilities/confidence 的返回语义可以在官方 Primitives 与 API 文档中核到。

特别强调：score 的 criteria 是有序数组。API Reference 原文写明：

An ordered array of level descriptions.

另外两个官方数据：Choice 最多 255 个选项；Score 至少 2 级、最多 10 级。API Reference 原文分别写明：

You can have a maximum of 255 options per Choice.

A Score should have at least two levels; the API accepts up to 10.

而 noul 按约束只返回一个 0~1 的 noul 值，没有 confidence，也没有 probabilities。写伪代码时不要自造 levels=、threshold= 这类参数；拿不准就回看官方 Primitives 或 Quick start 示例。这是本次写作工单给的字段约束，不是我从源码里猜的。

生态入口：平台方与集成方，不是 TypeSafe 官方文档

现在能看到两类可核实的生态入口，都必须标成“非 TypeSafe 官方文档”：

• Netlify AI Gateway：官方 changelog 发布 TypeSafe Jev 接入 AI Gateway，零配置在 Netlify Functions 里使用 @typesafe-ai/sdk。原文写道：

TypeSafe’s Jev model is now available through Netlify’s AI Gateway with zero configuration required.

其中提到的约 32,000 tokens、约 150,000 字符、70–500ms 等数据属于 Netlify 平台公告数据，不是 TypeSafe 官方文档数据。

• LiteLLM：官方博客文章 是 LiteLLM 集成方的一手发布，不是 TypeSafe 官方文档。标题为 TypeSafe Jev on LiteLLM，说明 LiteLLM 侧有接入动作。

Vercel AI Gateway 也常被列入生态入口，但这次我拿到的来源里没有 Vercel 公告链接，不能编 URL，我把它放进“这次没核实的”。

我的判断与落地清单

以下是我的建议，不是官方要求：

• 要把 Jev 当“决策模型”用，不要当聊天模型用。先确定 state 里放什么上下文，再确定 questions 里放哪几类问题。
• 给 coding agent 用时，优先读 llms.txt，再按需打开 Primitives、API Reference、Agent skill。因为 llms.txt 能枚举官方页面，适合避免“脑补某功能是否存在”。
• 接入顺序建议：Playground 验证问题设计 → cURL 验证 API → SDK 落进项目。不要一上来就封装一堆阈值；先用 noul 的 0~1 值或 confidence 观察分布。
• 遇到“某功能官方是否支持”，去 llms.txt 找页面再下结论。这是本文的关键建议，优先级高于集成方公告。

这次没核实的

• Vercel AI Gateway 接入 Jev 的官方公告链接：本次未能核实到可引用的 Vercel 一手链接。
• typesafe.ai 根域的首页文案、产品价格、控制台具体注册流程：本文没有展开核实，只把官方入口列出。
• Netlify changelog 中提到的 jev-1.13.0 当前别名、32k tokens、70–500ms 等数据：我没有在 TypeSafe 官方文档中二次核实，只能标为 Netlify 平台公告数据。
• Python/JavaScript SDK 的全部版本兼容与 retry 默认参数：SDK 页面只总览到“自动 retry”，更细的默认值我未逐条复读。

参考来源

• 官方文档索引 llms.txt
• 官方 Quick start
• 官方 API 参考
• 官方 Client SDKs
• Netlify changelog：TypeSafe Jev now available in AI Gateway
• LiteLLM 集成文章：TypeSafe Jev on LiteLLM