Jev API 使用教程：TypeSafe 接入与首次请求

1. 准备访问权限和测试样例

进入 TypeSafe 官方控制台，确认账号已经获得访问权限，然后创建 API Key。在服务端将它保存为 TYPESAFE_API_KEY 环境变量。官方快速开始文档也提供 Playground，可以先在那里测试问题。

先选一个意思明确的短工单。把负责团队、紧急程度、退款意愿分成三个判断，分别查看结果，才能知道错误来自分类、评分还是问题定义。

• 下方示例使用 Node.js 18 及以上版本自带的 fetch。
• 密钥只能保存在服务端，不要放进 VITE_ 环境变量或网页脚本。
• 账号权限和计费由 TypeSafe 管理，本社区站无法代发 API Key。

2. 发起服务端 JavaScript 请求

下面的原创示例使用官方文档中的请求结构。保存为 quickstart.mjs，配置环境变量后在服务端运行。代码只打印判断和用量，不会执行退款或向客户发送消息。

接口与字段已于 2026 年 9 月 20 日核对官方文档。本次没有执行付费模型调用，因此不承诺示例会返回特定预测值或延迟。

// Run on your server with Node.js 18+; never expose this key in browser code.
const apiKey = process.env.TYPESAFE_API_KEY;
if (!apiKey) throw new Error('Set TYPESAFE_API_KEY first');

const response = await fetch('https://api.typesafe.ai/v1/systemone', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'jev-latest',
    state: 'My invoice lists the same purchase twice. Please refund the duplicate charge.',
    questions: {
      team: {
        type: 'choice',
        instructions: 'Which team should handle this request?',
        criteria: {
          billing: 'Charges, invoices, and refunds',
          technical: 'Bugs and integration problems',
          other: 'Requests outside the listed categories',
        },
      },
      urgency: {
        type: 'score',
        instructions: 'How time-sensitive is the request?',
        criteria: ['No stated deadline', 'A stated deadline', 'An immediate service outage'],
      },
      refund: {
        type: 'noul',
        instructions: 'Does the customer explicitly request a refund?',
      },
    },
  }),
});

if (!response.ok) {
  throw new Error(`TypeSafe request failed: HTTP ${response.status}`);
}
const { answers, usage } = await response.json();
console.log({
  team: answers.team.choice,
  confidence: answers.team.confidence,
  urgency: answers.urgency.score, // Three levels: 0 to 2, including fractions.
  refundProbability: answers.refund.noul,
  inputTokens: usage.input_tokens,
});
// Select automation thresholds on your own evaluation data before taking action.

3. 正确读取三种返回值

Score 从数组下标 0 开始计分，三个等级的范围就是 0 到 2，允许小数。即使等级描述写着“1 = 低”，也不会改变数组下标的编号方式。

Noul 没有单独的 confidence 字段。接近 0 表示更倾向于否，接近 1 表示更倾向于是。Choice 和 Score 的 confidence 是对概率分布的概括，不应直接当作最高选项的概率。

4. 先判断错误，再决定是否重试

不要把所有失败都放进无限重试循环。设置超时、重试次数上限和人工兜底。排查分流错误时，也不要顺手把密钥或完整客户信息写进日志。

5. 用自己的数据确定自动化阈值

测试集应包含普通工单、表达含糊的工单和不属于任何已知类别的工单。同时观察错分与转人工的比例。阈值应由错误成本决定，不能直接照搬演示里的某个小数。

保留测试时的模型版本。模型或评分规则更新后，重新跑同一批样例。格式正确不代表选项正确，模型置信度也不能替代应用本身的操作授权。

常见问题