API 接入
TypeSafe AI 模型与 Jev AI API：生产环境集成指南
用 Jev AI 模型与 API 构建类型化决策：了解请求格式、TypeScript 运行时校验、概率阈值、故障处理与上线评估。
搜索 typesafe ai model、jev ai model 或 jev ai api，最终往往会碰到同一个工程问题：怎样把 AI 判断变成业务代码能够安全使用的值？Jev 面向边界明确的决策。你提供一段状态和类型化问题，它返回 Choice、Score 或 Noul 结果；应用再决定路由、排队或交给人工复核。响应校验、权限和最终动作仍由应用负责。
本文以客服工单分流为例，从问题设计、API 请求、响应校验、阈值策略，一直讲到生产上线。先厘清名称：TypeSafe AI 在官方发布文章中把 Jev 介绍为面向软件决策的 System One 模型。Jev AI 模型介绍页提供自己的产品说明和 API 体验；网站页脚明确称其独立运营，与 TypeSafe 没有隶属、运营或背书关系。选择凭证、端点和服务条款时，应区分模型概念、原厂服务与本站 API。
目录
- 什么是 TypeSafe AI 模型
- Jev AI 模型适合什么任务
- Jev AI API 的请求契约
- 构造客服工单分流请求
- 读取并校验响应
- 把概率转为业务策略
- 让 API 在生产环境稳定运行
- 上线前如何评估
- 常见错误与修正方法
- 常见问题
什么是 TypeSafe AI 模型？
这里的“类型安全”说的是模型接口：调用方在推断前定义允许的答案形状。TypeSafe 对 Jev 的描述是面向快速结构化决策的 System One 模型，而不是生成长段文字的聊天模型。输入由状态和问题组成，输出是带概率的类型化结果。但答案满足类型要求，并不代表业务判断一定正确；一个合法的 billing 值仍可能把工单分错团队。
普通聊天模型也能通过提示词或 JSON Schema 输出结构化数据，这适用于许多场景。工程上仍需区分三件事：模型能否按格式回答、答案是否正确、应用是否可以执行动作。Jev 的收窄接口让责任更清楚：模型处理模糊判断，API 搬运受约束的结果，应用执行运行时校验、阈值、权限和审计。
TypeScript 类型只能检查编译时的代码。网络响应进入服务端后仍是未知数据，因此“类型安全的 AI”应该是整个系统的属性，不能成为跳过运行时校验的理由。
Jev AI 模型适合什么任务？
当答案空间能预先定义时，Jev 适合路由到指定团队、给严重程度打分，或判断是否需要人工复核。它也可以和生成式 LLM 配合：Jev 判断请求该走哪条路径，LLM 负责写回复。模型输出再高的概率，也不应直接赋予其退款、删库或付款权限。
Jev 的公开文档列出三种问题类型：Choice 从预定义选项中选择，返回各选项概率和置信度；Score 基于有序等级给出概率加权分数、等级说明、分布和置信度；Noul 返回 0 到 1 的“是”概率，它没有另一个独立的置信度字段。多个问题可以共享同一段状态，在一次请求中得到答案。
Jev AI API 文档目前列出的状态输入包括文本、JSON 对象、文本数组；图片、音频和视频暂不支持。如果数据来自附件，应先通过独立、可校验的流程提取为文本。对于非英语数据，应在自己的标注样本上验证效果，不能直接假定与英语一致。
Jev AI API 的请求契约
本站文档给出的端点是 POST https://thejevai.com/v1/systemone。请求从服务端发出，包含 Bearer API Key 和 Content-Type: application/json。请求体必须有 model、state、questions 三个顶层字段；文档给出的模型别名是 jev-latest。问题 ID 由应用决定，响应会用相同 ID 对应答案。响应中的模型名可能是解析后的具体版本。
不同服务的端点和密钥不要混用。TypeSafe 原厂资料使用单独的 api.typesafe.ai 端点，下面示例则针对 thejevai.com。正式集成前，应重新核对文档中的模型别名、限制与条款。
| 问题类型 | 输入要求 | 输出重点 | 工单示例 |
|---|---|---|---|
| Choice | criteria 中列出具名选项 |
choice、概率、置信度 |
哪个团队先处理？ |
| Score | criteria 是从低到高的等级数组 |
加权 score、等级、概率、置信度 |
影响有多严重？ |
| Noul | 一个是/否问题，可加 true/false 说明 | noul，即“是”的概率 |
是否需要人工？ |
每个问题尽量只做一种判断。“分类、定优先级、决定是否退款”混合了三套策略。拆为 Choice、Score、Noul 后，结果才能逐项核对。文档允许 Choice 最多 255 个选项、Score 使用 2–10 个等级；实际场景宜从少量、容易解释的选项开始。
构造客服工单分流请求
假设客户写道：“我被重复扣费，而且三天无法收到款项。”我们需要判断负责团队、影响程度，以及是否必须人工介入。只放入判断所需的工单和政策事实，省略无关个人信息。如果预设团队不能覆盖所有情况，Choice 应有 none_of_the_above 出口，不要强迫模型选一个貌似合理但不合适的团队。
{
"model": "jev-latest",
"state": {
"ticket": "我被重复扣费，而且三天无法收到款项。",
"account_tier": "business",
"policy": "退款必须由有权限的审核员批准；服务故障报告需升级处理。"
},
"questions": {
"team": {
"type": "choice",
"instructions": "哪个获准团队应先调查？",
"criteria": {
"billing": "重复收费、发票、退款或收款",
"technical": "不涉及支付的产品故障或集成问题",
"account": "账户访问与身份问题",
"none_of_the_above": "没有明确匹配的获准团队"
}
},
"severity": {
"type": "score",
"instructions": "评估服务影响，而不是客户情绪。",
"criteria": ["无服务影响", "局部影响", "明显影响", "服务受阻"]
},
"needs_human": {
"type": "noul",
"instructions": "依据给定政策，退款或账户变更前是否需要人工审核？",
"criteria": {
"true": "退款或账户变更需要授权",
"false": "仅需要分类或排队"
}
}
}
}
这个示例的关键边界是：模型可以识别可能的团队和风险，却不能批准退款。确定性规则必须保证授权人批准前不会执行退款。needs_human 仅帮助界面和队列安排，不是权限凭证。
可以先在在线 Playground验证契约，再由后端发送同样的请求。测试时使用已脱敏的真实样本，覆盖模糊表述、信息缺失、无匹配分类和工单正文中试图改写政策的文字。工单始终是数据，不是系统指令。
读取并校验响应
文档中的响应有模型标识、以问题 ID 为键的 answers，以及 usage。Choice 答案包含选项、概率分布和置信度；Score 答案包含加权分数、等级、概率与置信度；Noul 答案只有 type 和 noul。下面的数据仅用于说明字段，不是对上述工单输出结果的承诺：
{
"model": "jev-1.13.0",
"answers": {
"team": {
"type": "choice",
"choice": "billing",
"probabilities": { "billing": 0.84, "technical": 0.12, "account": 0.02, "none_of_the_above": 0.02 },
"confidence": 0.76
},
"severity": {
"type": "score",
"score": 2.4,
"legend": { "0": "无服务影响", "1": "局部影响", "2": "明显影响", "3": "服务受阻" },
"probabilities": { "0": 0.01, "1": 0.09, "2": 0.39, "3": 0.51 },
"confidence": 0.57
},
"needs_human": { "type": "noul", "noul": 0.94 }
},
"usage": { "input_tokens": 318, "output_tokens": 52 }
}
team.choice 是候选路由；分布显示其他团队的概率，confidence 则是另一个由分布得到的信号。severity.score 是概率加权值，因此可以落在两个等级之间。needs_human.noul 表示“是”的概率；不要读取文档未承诺的 needs_human.confidence。
在服务端，应把解析后的 JSON 当作 unknown，逐项验证业务策略会使用的字段。下面仅展示 Choice 部分的紧凑 TypeScript 校验；requestBody 即上文的请求对象。Score 和 Noul 也须分别校验：
const teams = ["billing", "technical", "account", "none_of_the_above"] as const;
type Team = (typeof teams)[number];
function isRecord(value: unknown): value is Record<string, unknown> {
return typeof value === "object" && value !== null && !Array.isArray(value);
}
function isProbability(value: unknown): value is number {
return typeof value === "number" && Number.isFinite(value) && value >= 0 && value <= 1;
}
function readTeam(raw: unknown): { team: Team; probability: number; confidence: number } | null {
if (!isRecord(raw) || !isRecord(raw.answers)) return null;
const answer = raw.answers.team;
if (!isRecord(answer) || answer.type !== "choice") return null;
if (!teams.some((team) => team === answer.choice)) return null;
if (!isRecord(answer.probabilities) || !isProbability(answer.confidence)) return null;
const probabilities = answer.probabilities;
if (!teams.every((team) => isProbability(probabilities[team]))) return null;
const total = teams.reduce((sum, team) => sum + (probabilities[team] as number), 0);
if (Math.abs(total - 1) > 0.02) return null; // 容许 API 返回值的四舍五入误差
return {
team: answer.choice as Team,
probability: probabilities[answer.choice as Team] as number,
confidence: answer.confidence
};
}
const apiKey = process.env.JEV_API_KEY;
if (!apiKey) throw new Error("JEV_API_KEY is missing");
const response = await fetch("https://thejevai.com/v1/systemone", {
method: "POST",
headers: {
Authorization: `Bearer ${apiKey}`,
"Content-Type": "application/json"
},
body: JSON.stringify(requestBody),
signal: AbortSignal.timeout(5000)
});
if (!response.ok) throw new Error(`Jev request failed: ${response.status}`);
const raw: unknown = await response.json();
const teamDecision = readTeam(raw);
if (!teamDecision) throw new Error("Unexpected Jev team response");
JEV_API_KEY 应放在服务端密钥配置中，并在服务启动时检查是否存在，避免空值拼成无效令牌。日志不要记录完整密钥、未脱敏工单或响应。也可以用现有的 Schema 库表达同样规则；关键在于网络值的运行时校验，而非选用哪个库。
把概率转为业务策略
概率是信号，不是执行许可，也不是准确率保证。示例中的 team 对 billing 有较高概率，但其 confidence 与最高选项概率并不相同。生产规则应综合选项、分布、风险和误分代价。还应区分需要复核与服务不可用：超时不等于 Noul 给出了“否”。
对于低风险队列，可以先假设：最高选项概率达到 0.85 时自动分流，0.60–0.85 时进入待确认队列，更低或响应不合法时交给人工。这些数字只是说明策略结构，并非 Jev 默认值；应根据标注数据和错误代价确定。退款、付款、删除、账户修改等动作，无论概率多高，都必须通过原有权限与授权规则。
合法且信号强 + 已获准的低风险动作 → 自动处理
合法但不确定，或涉及敏感动作 → 人工复核
无效响应、超时、缺少密钥 → 安全回退
Choice 要看第一与第二选项是否接近；Score 要防止加权均值掩盖分散的概率；Noul 的中间值通常意味着不确定。把阈值按工作流配置，并与问题版本一同记录，避免在多个处理函数中散落数字。
让 API 在生产环境稳定运行
公开文档列出 401（密钥缺失或无效）、422（请求校验失败）、429（限流）、529（服务过载）。处理方式应不同：401 要修正配置；422 要修正请求契约；429 和 529 可采用有次数上限的指数退避与随机抖动。网络错误和超时必须有明确的回退路径。
为调用设置符合产品体验的截止时间。重试提高可用性，也会增加流量和等待时间；有上限的少量重试通常比无限循环更可控。让业务副作用留在重试的模型调用之外，避免再次请求时重复执行动作。客户端计时应包含网络与应用开销；文档中的 elapsed 是服务返回的额外耗时字段，usage 记录令牌使用情况。
监控超时、429/529、响应结构异常、问题级别分歧、人工复核比例和下游错误代价。审计记录中保存问题版本与模型标识，并按数据保留规则脱敏或散列敏感状态。安全边界也要清楚：浏览器请求你的后端，后端持有密钥；用户写入的工单不能改写系统策略，最终动作仍须经过普通权限与业务规则。
上线前如何评估？
先从真实工作流收集标注样本，包含常规、模糊、政策敏感、无匹配选项和各种目标语言的案例。请业务人员标出目标团队、严重程度与人工复核要求；同时记录标注者之间的分歧。如果人都难以一致，单一“标准答案”也可能高估模型问题。
在样本上运行同一请求契约，不要只看总准确率。Choice 要看团队之间的混淆和 none_of_the_above 比例；Score 要看严重程度低估的代价；Noul 要看本应人工复核却被判为无需复核的漏报。必要时按语言、客户群或政策版本拆分结果。
还要检查概率校准：按预测概率分组，把各组的实际成功比例与模型给出的概率比较。一个模型可以把案例排序得不错，却在你的领域过度自信。根据校准结果和错误代价确定自动化阈值，再用未参与调参的样本验证。TypeSafe 发布的速度与校准结果可以提供背景，但不能代替对本站端点和自有流量的测量。
上线采用递进方式：先只记录、不执行；再向人工分流员提供建议；最后只自动处理最安全的类别。定期审查异常，确有明确失败模式时再调整问题文字或选项，改阈值前重跑留出的评估集。比较完整工作流的延迟和成本，包含人工复核，而不是只看模型推断时间。
常见错误与修正方法
把类型正确当成判断正确。 Schema 校验只能拦住字段缺失或结构错误；团队是否选对，要单独评估。
用封闭选项描述开放世界。 真实情况可能没有匹配团队，增加明确的退出选项和人工路径。
把 Noul 当作布尔值。 它是“是”的概率，阈值由应用决定，硬性政策依然有效。
在浏览器代码中放密钥。 调用应放到后端，泄露后需轮换密钥。
对所有错误都重试。 401 与 422 应修正原因；暂时性的 429 和 529 才适合有上限的退避。
混用不同服务的地址和密钥。 使用 TypeSafe 原厂服务还是独立运营的 Jev AI API，须核对端点、凭证与条款。
没有回退路径。 API 不可用时进入安全队列或人工复核，也是应用可执行、可观测的结果。
若希望进一步理解 TypeScript 的运行时边界，可阅读站内 Jev TypeSafe 指南。
常见问题
Jev AI 模型是 LLM 吗？
TypeSafe 将 Jev 描述为 System One 决策模型，目标是返回受约束的结果与概率，而非开放式长文。需要写作或开放式推理时使用生成模型；答案空间明确时可考虑类型化决策接口。
“类型安全”是否意味着 Jev 不会判断错误？
不是。类型安全关心结果形状，合法的 Choice 仍可能选错团队。应校验响应、用代表性数据评估，并把业务策略放在模型之外。
能从浏览器直接调用 Jev AI API 吗？
密钥应留在服务端。浏览器先请求你的应用，后端筛选必要状态、调用 Jev、校验答案，再把界面所需的最小结果返回给前端。
第一项实践该做什么？
从一个低风险、可撤销的决策开始，例如工单分类。先定义答案空间和标注样本，在 Playground 查看分布，然后让 API 仅记录建议，不立即自动执行。第一阶段能稳定地把不确定案例送给人工，就已经具有实际价值。