Jev 可用平台入口清单：官方 API、SDK、网关与 Agent skill

小猫跳舞 技术创作者 2026-09-21 76 阅读

先说结论

  • 官方侧有 4 个直接入口：官网/文档、控制台、HTTP API（POST https://api.typesafe.ai/v1/systemone，模型名 jev-latest）、/llms.txt 文档索引。
  • SDK 有 Python 和 JavaScript/TypeScript 两种官方客户端。我这次完整核对到的是 JavaScript SDK 的 Quickstart；Python 侧只确认到官方 SDK 索引里有 Python 页面，具体安装命令和问题对象写法我放在“这次没核实的”里。
  • 生态侧已经能通过 Vercel AI Gateway、Netlify AI Gateway、LiteLLM 三条路径使用 Jev。网关接入不等于 TypeSafe 官方 SLA，第三方平台的能力和性能口径要以各自公告为准。
  • 给编码 agent 的官方 skill 主要解决一个问题：Claude Code、Codex 这类工具在不了解 TypeSafe 规范时，容易把通用 LLM 的请求/响应写法硬套进去，甚至发明字段。装了 skill 后，agent 能按官方三种问题类型和模式来写集成代码。
  • 我的建议：已有 Vercel 或 Netlify 的项目优先走对应网关；后端自建服务用官方 API 或 SDK；已经在 LiteLLM 体系里就把 Jev 当分类器/路由器；要让 agent 写 TypeSafe 代码，先装 Agent skill，否则后续排查成本更高。

证据与过程

1. 官方侧四个入口：文档、控制台、API、llms.txt

官方 API 是最底层的接入方式。根据 官方 API Reference，评估端点写得很明确：

  • 端点：POST https://api.typesafe.ai/v1/systemone
  • 认证头：Authorization: Bearer <API_KEY>
  • 内容类型：application/json
  • 请求体顶层字段：state、model、questions
  • state 是必填，可以是字符串、对象或数组；model 是必填，官方写明使用 "jev-latest"；questions 是必填，是一个由你命名的 map，每个键下是一个 typed question。

官方 API Reference 给的示例请求如下：

{
  "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、type、instructions。官方文档还写明：instructions 可以是字符串、对象或数组；choice 的 criteria 是 map，最多 255 个选项；score 的 criteria 是数组，API 接受 2 到 10 个等级。以上都是官方 API Reference 里的内容，不是我的自行发挥。

官网和文档入口可以从 TypeSafe 文档首页 进入。官方文档站还在多个页面开头写了一句话：“Fetch the complete documentation index at: /llms.txt”。这个入口对应的完整 URL 是 https://docs.typesafe.ai/llms.txt。它的主要用途是给 AI 编码工具或爬虫读：工具可以先读 llms.txt 发现所有可用页面，再按需请求具体页面，而不是每次凭猜 URL。官方 API Reference 页面本身就写了这条提示，因此这属于官方提供的能力。

控制台入口比较特殊。官方文档站左侧导航有 “TypeSafe console” 的入口，可以进入 Playground 和 API Keys 管理。但这次我拿到的来源正文里没有单独给出 console 的 URL，所以我不在正文里编地址。需要控制台的读者可以从 TypeSafe 文档首页 找到 “TypeSafe console” 导航进入。要调用官方 API，至少需要准备一个 API Key。

2. SDK：Python 与 JavaScript 的官方差异点

官方 Client SDKs 索引 写明，官方 SDK 提供 typed questions and answers for the TypeSafe API，并且默认有重试策略：“handle retries automatically with their default retry policy”。这句话是官方说的。

JavaScript/TypeScript SDK 这一侧，官方 JavaScript SDK 页面 给出了完整 Quickstart。安装命令是：

npm install @typesafe-ai/sdk

官方写明需要 Node.js 20 或更新版本，并在环境变量中设置 TYPESAFE_API_KEY。初始化客户端和构造问题对象的官方示例是：

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

const client = new TypeSafeClient();
const response = await client.systemOne({
  state: { document: "I was charged twice. Please fix this ASAP." },
  questions: {
    category: choice("What is this ticket about?", {
      billing: null,
      technical: null,
      other: null,
    }),
  },
});

console.log(response.answers.category.choice);

这个官方示例里，初始化方式是 new TypeSafeClient()，问题对象用 choice(...) helper 构造，choices 的每个选项以 null 表示不需要额外判据。官方页面还写明，答案类型会从问题定义中推导出来，包内包含 ESM、CommonJS 和 TypeScript declarations。这些都是官方 JavaScript SDK 页面能查到的原文内容。

Python SDK 这一侧，官方 SDK 索引页里明确列了 Python SDK 页面，标题是 “Python Install the Python client SDK and make your first request.”。但这次来源正文没有包含 Python 页面的完整代码，所以 Python 的初始化方式、问题对象写法和 JavaScript 的逐字段差异，我没有可核查的原文。工单里提到的 pip install typesafe-sdk 我没有在抓取到的来源正文里看到，因此不在这里写成已核实事实。需要 Python 集成的读者，建议直接打开官方 SDK 索引页，进入 Python SDK 页查看 Quick start。我把这条放进“这次没核实的”。

3. 生态侧三条路径：Vercel、Netlify、LiteLLM

Vercel AI Gateway

Vercel changelog 宣布 Jev 在 AI Gateway 上可用。接入方式不是直接调 TypeSafe HTTP API，而是用 AI SDK 7 的实验性 evaluate API。Vercel 官方 changelog 写明，安装当前 AI SDK（AI SDK 7.0.105 起支持 evaluate API）：

pnpm add ai@latest

模型名写为 typesafe-ai/jev。Vercel 官方给的示例是：

import { experimental_evaluate as evaluate } from 'ai';

const result = await evaluate({
  model: 'typesafe-ai/jev',
  state: 'The support agent issued a full refund to the customer.',
  questions: {
    refunded: {
      type: 'boolean',
      instructions: 'Was a refund issued?',
    },
  },
  providerOptions: {
    gateway: { zeroDataRetention: true },
  },
});

console.log(result.answers.refunded);

Vercel changelog 还写到，Jev 在 Vercel AI Gateway 上支持 Zero Data Retention 和 No Training，并且评估调用会出现在日志、自定义报告、预算计数里。关于性能，Vercel changelog 里写的是 “TypeSafe reports Jev was up to 193.6x faster and 444.6x cheaper than LLMs on its workflow evaluations”——这是 Vercel 官方 changelog 转述 TypeSafe 的报告数据，不是 Vercel 自己测出来的数据，更不应该被当成对读者自己工作负载的保证。我在正文里把它标成“Vercel changelog 转述 TypeSafe 报告”。

Netlify AI Gateway

Netlify changelog 宣布 Jev 接入 Netlify AI Gateway，口径是“零配置”。也就是说，在 Netlify Functions 里安装 @typesafe-ai/sdk 后可以直接使用，不需要自己创建 TypeSafe API Key，也不需要配 base URL，AI Gateway 会自动处理凭证，用量计入 Netlify credits。这是 Netlify 官方 changelog 说出来的，属于平台官方公告。

Netlify 官方给的示例同样是 TypeSafeClient 和 choice helper：

import type { Config, Context } from "@netlify/functions";
import { choice, TypeSafeClient } from "@typesafe-ai/sdk";

export default async (req: Request, context: Context) => {
  const client = new TypeSafeClient();
  const { answers } = await client.systemOne({
    state: await req.json(),
    questions: {
      team: choice("Route this contact form submission", {
        sales: null,
        support: null,
        spam: null,
      }),
    },
  });

  return Response.json({
    team: answers.team.choice,
    requestId: context.requestId,
  });
};

export const config: Config = { path: "/api/route", method: "POST" };

Netlify 官方 changelog 还写到，每个请求中的所有 questions 会并行评估同一个 state。这个行为是 Netlify 官方描述的产品能力。另外，Netlify changelog 里给出的数字是：state 和 questions 共享大约 32,000 tokens 的预算，约等于 150,000 个英文字符；TypeSafe 报告端到端响应时间为 70–500ms。这里 32,000 tokens 和 150,000 字符是 Netlify 官方写出的能力参数，70–500ms 是 Netlify changelog 转引 TypeSafe 的报告，不属于我们自己的实测。

LiteLLM

LiteLLM 官方博客 的标题是 “JEV Classifier: 5.43x as Fast as Haiku, 96% Lower Cost”。这条路径更适合已经在用 LiteLLM 或 LiteLLM Auto Router 的团队：把 Jev 作为一个分类器/路由器组件，而不是直接让业务代码调 TypeSafe API。标题里的 5.43x 和 96% 是 LiteLLM 集成方口径，不是 TypeSafe 官方数据。它们只能说明 LiteLLM 在特定 Auto-Router 基准或对比场景里得出的结果，不能当作 Jev 在所有场景下的官方性能指标。这次来源只抓到博客标题列表，没有正文，所以具体配置字段、测试条件、和 Haiku 的对比方法，我都没法在这篇文章里展开。这条路径的可靠性需要读者自己去 LiteLLM 官方博客里核对正文。

4. 给编码 agent 的路径：官方 Agent skill

官方 Agent skill 页面 写明，这个 skill 是 “Drop-in skill for Claude Code, Codex, and other agent environments”。它解决的核心问题是：让编码 agent 了解 TypeSafe 的三种 question 类型、已有架构模式和最佳实践，而不是凭通用 LLM 的经验去写请求体和响应解析。

官方页面给了两种安装方式：

# 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

官方页面还说，也可以直接读 GitHub 上的 SKILL.md，路径是 https://github.com/typesafe-ai/skills/blob/main/skills/typesafe-ai/SKILL.md。这个是官方给出的 GitHub 地址。

Agent skill 页面里有几条官方建议对我很有用：

  • 把 questions 和 thresholds 常量放在单一代码文件里，方便人类 review；
  • 不要把 agent 的断言直接当真，鼓励 agent 先验证假设；
  • 如果 agent 开始发明不存在的请求或响应字段，通常是因为 skill 版本旧了，更新后重试。

这几条是官方页面 “Good vibe coding principles” 和 “Common issues” 里的内容，不是我的推论。尤其最后一条解释了很多集成问题的来源：不是模型不行，而是它没有拿到最新的 TypeSafe 规范。

5. 对照表

入口 在哪一层 适合谁 要准备什么 官方链接
官网/文档 认知入口 第一次了解 Jev 的人 无 TypeSafe 文档首页
控制台 交互入口 想快速试 Playground、创建 API Key 的人 账号，从文档站进入 “TypeSafe console” 从 文档首页 进入
官方 HTTP API 直接调用层 任何能发 HTTPS 请求的后端 API_KEY，模型名 jev-latest API Reference
/llms.txt 给 AI 编码工具读的文档索引 Claude Code、Codex 等 agent 工具能访问 URL llms.txt
Python SDK SDK 语言层 Python 后端 官方 Python SDK 页的安装命令 Client SDKs 索引
JavaScript/TS SDK SDK 语言层 Node.js 20+、前端、Netlify Functions npm install @typesafe-ai/sdk 和 TYPESAFE_API_KEY JavaScript SDK
Vercel AI Gateway 生态网关层 已用 Vercel + AI SDK 7 的项目 pnpm add ai@latest，模型名 typesafe-ai/jev Vercel changelog
Netlify AI Gateway 生态网关层 已用 Netlify Functions 的项目 @typesafe-ai/sdk，无需自建 Key Netlify changelog
LiteLLM Auto Router 生态路由层 已有 LiteLLM 或 Auto Router 的团队 LiteLLM 配置，Jev 作为分类器 LiteLLM 官方博客
Agent skill 编码 agent 辅助层 让 Claude Code / Codex 按官方规范写 TypeSafe 集成 安装 skill，或直接给 agent 读 SKILL.md Agent skill

6. 自己的判断与落地清单

我的判断是：不要一上来就直连官方 HTTP API。大多数团队的实际瓶颈不是“调不通”，而是“agent 或开发者不理解 Jev 的 question 语义”。如果你的项目已经跑在 Vercel 或 Netlify 上，走平台网关最省事，因为凭证管理和计费都落在现有平台里。如果团队已经用 LiteLLM 做网关或 Auto Router，把 Jev 作为分类器接入是低摩擦的做法，但要留意性能口径是集成方的，不是 TypeSafe 官方基准。如果既没有 Vercel/Netlify，也不想引入 LiteLLM，那么用官方 API 或官方 JavaScript SDK 是最稳的路径，至少行为有官方文档可查。

落地清单：

  1. 先确认集成位置：Vercel / Netlify / 自托管 / LiteLLM。
  2. 读 llms.txt 或官方文档索引，按你的场景找页面；如果走 Vercel，重点看 Vercel changelog；走 Netlify，重点看 Netlify changelog。
  3. 模型名不要写错：直连 API 用 jev-latest；Vercel 用 typesafe-ai/jev；Netlify SDK 默认 jev-latest；LiteLLM 按它的配置。
  4. 用 noul、choice、score 表达业务判断，而不是让模型输出自由文本再去解析。官方 API Reference 和 SDK 示例都体现了这一点。
  5. 如果让 agent 帮忙写 TypeSafe 集成，先装官方 Agent skill，并提醒它不要发明字段。项目里把 questions 和阈值常量集中到一个文件，方便人肉 review。

这次没核实的

  • Python SDK 的初始化代码、问题对象写法和 JavaScript 的逐字段差异：本次来源正文只包含 JavaScript SDK Quickstart，没有 Python SDK 页全文。工单里的 pip install typesafe-sdk 我没有在抓取到的来源正文里看到，需要读者自行到官方 Python SDK 页确认。
  • TypeSafe console 的独立 URL、Playground 与 API Keys 的页面路径：官方文档页只有导航入口，没有给出可点击的 console URL。
  • LiteLLM 博客正文里的配置字段、测试条件、和 Haiku 的具体对比方式：来源只给到博客标题列表，没有正文，无法核实。
  • Vercel AI SDK 7 的 experimental_evaluate API 是否会变动、参数是否稳定：本次无法核实。它既然标成 experimental，接入生产前需要跟踪 Vercel 后续公告。

参考来源

  1. TypeSafe AI API Reference（官方）
    https://docs.typesafe.ai/api
  2. TypeSafe AI Client SDKs 索引（官方）
    https://docs.typesafe.ai/sdk
  3. TypeSafe AI JavaScript SDK（官方）
    https://docs.typesafe.ai/sdk/javascript
  4. TypeSafe AI Agent skill（官方）
    https://docs.typesafe.ai/agent-skill
  5. Vercel changelog: TypeSafe AI’s Jev now available on AI Gateway（官方）
    https://vercel.com/changelog/typesafe-ai-jev-now-available-on-ai-gateway
  6. Netlify changelog: TypeSafe Jev now available in AI Gateway（官方）
    https://www.netlify.com/changelog/typesafe-jev-ai-gateway/
  7. LiteLLM blog: TypeSafe Jev on LiteLLM（官方）
    https://docs.litellm.ai/blog/typesafe_jev
  8. TypeSafe AI 文档首页（官方）
    https://docs.typesafe.ai/
  9. TypeSafe AI llms.txt（官方）
    https://docs.typesafe.ai/llms.txt
# AI# 知识

评论区

0 条评论

登录后可评论。

小猫跳舞 76 阅读