Jev API 教程：第一次请求与错误排查

1. 获取密钥并仅保存在服务端

在 TypeSafe Console 创建 API Key，并保存到 TYPESAFE_API_KEY 环境变量。不要把密钥写进浏览器 JavaScript、公开仓库、截图或交给模型判断的 state。

export TYPESAFE_API_KEY="your-api-key"

2. 发送最小但完整的请求

请求需要 model、作为证据的 state，以及带名称的 questions。先用一个边界清晰的 Choice，这样输入契约和返回结果都容易核对。

#!/bin/sh
set -eu

# Diagnostic direct-API example. Run it only from a trusted server-side shell.
# It makes one request and leaves retry policy to the calling application.
if [ -z "${TYPESAFE_API_KEY:-}" ]; then
  printf '%s\n' 'TYPESAFE_API_KEY is required; keep it server-side and do not print it.' >&2
  exit 2
fi

curl --fail-with-body --silent --show-error --include \
  --connect-timeout 5 \
  --max-time 20 \
  --request POST https://api.typesafe.ai/v1/systemone \
  --header "Authorization: Bearer $TYPESAFE_API_KEY" \
  --header 'Content-Type: application/json' \
  --write-out '\nHTTP %{http_code}\n' \
  --data-binary @- <<'JSON'
{
  "model": "jev-latest",
  "state": {
    "message": "Checkout returns HTTP 500 after payment."
  },
  "questions": {
    "route": {
      "type": "choice",
      "instructions": "Which team should handle this request?",
      "criteria": {
        "billing": "Charges, invoices, or subscriptions",
        "technical": "Bugs, APIs, or integrations",
        "human": "Ambiguous or sensitive cases"
      }
    }
  }
}
JSON

需要 curl 7.76+。脚本只发一次请求，不会把 401/422 或不确定答案藏在自动重试后面；诊断输出会保留错误正文、HTTP 状态和响应头。向支持人员提供 x-typesafe-request-id 时，先删除业务 state；绝不要复制 Authorization 请求头或 API Key。

下载受测试的 API quickstart 脚本 ↓

3. 读取类型化响应

答案位于你提供的问题 ID 下。Choice 返回胜出选项、每个选项的概率和 confidence；Score 返回有序量表上的位置；Noul 返回 P(true)，没有单独的 confidence 字段。

{
  "model": "jev-1.13.0",
  "answers": {
    "route": {
      "type": "choice",
      "choice": "technical",
      "confidence": 0.78,
      "probabilities": {
        "technical": 0.85,
        "billing": 0.10,
        "human": 0.05
      }
    }
  }
}

4. 把答案接入安全决策路径

进入业务分支前先校验响应结构与选项键。副作用继续由普通代码控制，高风险动作采用更严格的阈值，并区分网络失败与“模型给出了有效但不确定的结果”。

const REVIEW_THRESHOLD = 0.75; // Illustrative, not calibrated.
const allowed = new Set(['billing', 'technical', 'human']);
const route = response.answers?.route;
const valid = route && allowed.has(route.choice)
  && Number.isFinite(route.confidence)
  && route.confidence >= 0 && route.confidence <= 1;
console.log(!valid || route.choice === 'human' || route.confidence < REVIEW_THRESHOLD
  ? 'Human review required'
  : 'Suggested team: ' + route.choice);
// Suggestions only; no side effects.

5. 增加问题但不要隐藏策略

针对同一 state 的多个问题可以一次发送，并且彼此独立评估。把复合判断拆成小问题，再用可见、可版本化的业务规则在代码中组合答案。

6. 按故障层排查

先看 HTTP 状态，再检查脱敏后的错误正文与 x-typesafe-request-id 响应头。鉴权和请求结构错误需要修复，不能靠重试解决；限流、过载、服务故障与网络超时可以有限重试。低置信度的 2xx 响应是有效但不确定的结果，不是传输故障。