参考API 参考

将一个 state 与一张由带类型的 questions 组成的映射表进行对照评估，并返回结构化的 answers，每个问题对应一个答案。如需循序渐进的介绍，请从原语开始。

评估端点

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

请求体

每个请求的顶层结构。questions 映射表中的每个条目都是一个由你命名的带类型问题。

statestring | object | array

要评估的内容。文本使用纯字符串；聊天记录、数据记录或应用的当前状态等内容则使用结构化数据（对象/数组）。格式与最佳实践请参见状态。

modelstring

处理请求的模型。请使用 "jev-latest"，即 TypeSafe 的旗舰模型。可用模型与别名请参见模型。

questionsmap<string, Question>

一张由带类型的问题对象组成的映射表。每个键由你选择；答案会以相同的键返回。

json
{
  "state": "Help! My payouts have been failing for 3 days.",
  "model": "jev-latest",
  "questions": {
    "is_urgent": {
      "type": "noul",
      "instructions": "Does this convey urgency?"
    }
  }
}

问题类型

Question 是三种类型之一，由其 type 字段设定。三者共享 type 和 instructions；每种类型再添加自己的 criteria。

instructions 属性可以是字符串、对象或数组。对于带有额外上下文或需要引用数据的长问题，你可以把它拆成一个结构化对象：把问题放在一个字段里，把数据放在其他字段里，然后在问题中用反引号按名称引用这些数据字段，就像把问题指向嵌套的 state 值一样：

json
"instructions": {
  "potential_duplicate": {
    "name": "John Smith",
    "location": "Oakland, California",
    "last_employer": "Google"
  },
  "question": "Is the resume for the same person as `potential_duplicate`?"
}

更多信息请参阅在问题中使用结构。

Noul

一个是/否问题。返回答案为“是”的概率。

type"noul"
instructionsstring | object | array

要评估的是/否问题。对象可以把问题放在一个字段里，把它引用的数据放在其他字段里；参见在问题中使用结构。

criteriaobject

可选的描述，说明“是”与“否”分别代表什么。

json
{
  "state": "Help! My payouts have been failing for 3 days.",
  "model": "jev-latest",
  "questions": {
    "is_urgent": {
      "type": "noul",
      "instructions": "Does this convey urgency?",
      "criteria": {
        "true": "Explicitly time-sensitive",
        "false": "No urgency expressed"
      }
    }
  }
}

Choice

从你定义的一组选项中挑选一个。返回选中的选项以及完整的概率分布。

type"choice"
instructionsstring | object | array

模型要做的决定。对象可以把问题放在一个字段里，把它引用的数据放在其他字段里；参见结构化的 instructions 与 criteria。

criteriamap<string, string | object | array | null>

选项到评分标准描述的映射表；当某个选项无需额外说明时使用 null。每个 Choice 最多可有 255 个选项。

json
{
  "state": "Help! My payouts have been failing for 3 days.",
  "model": "jev-latest",
  "questions": {
    "department": {
      "type": "choice",
      "instructions": "Which team should handle this?",
      "criteria": {
        "billing": "Payments, invoicing, refunds",
        "technical": "Bugs, outages, integrations",
        "sales": "Pricing, upgrades, new accounts"
      }
    }
  }
}

Score

按照你定义的评分标准对状态进行评级。返回跨各等级的概率加权值。

type"score"
instructionsstring | object | array

模型要评级的内容。对象可以把问题放在一个字段里，把它引用的数据放在其他字段里；参见在问题中使用结构。

criteriaarray<string | object | array>

一个有序的等级描述数组。Score 应至少包含两个等级；API 最多接受 10 个。

json
{
  "state": "Help! My payouts have been failing for 3 days.",
  "model": "jev-latest",
  "questions": {
    "frustration": {
      "type": "score",
      "instructions": "How frustrated is the customer?",
      "criteria": ["Calm", "Frustrated", "Very angry"]
    }
  }
}

响应体

每个问题对应一个答案，以你提供的相同 id 返回。

modelstring

执行评估的模型。

answersmap<string, Answer>

每个问题对应一个答案，以你在 questions 中使用的相同 id 作为键。

usageobject

本次请求的 token 用量。

json
{
  "model": "jev-1.13.0",
  "answers": {
    "is_urgent": {
      "type": "noul",
      "noul": 0.95
    }
  },
  "usage": { "input_tokens": 296, "output_tokens": 20 }
}

答案类型

每个答案都带有一个与其问题相匹配的 type。Choice 和 Score 的答案还带有一个介于 0 到 1 之间的 confidence，由答案的概率分布推导而来。参见置信度。

Noul 答案

type"noul"
noulnumber

是/否答案，取值范围从 0（否）到 1（是）。

json
{
  "model": "jev-1.13.0",
  "answers": {
    "is_urgent": {
      "type": "noul",
      "noul": 0.95
    }
  },
  "usage": { "input_tokens": 307, "output_tokens": 20 }
}

Choice 答案

type"choice"
choicestring

概率最高的选项。

probabilitiesmap<string, number>

每个选项映射到其概率（总和为 1 的浮点数）。

confidencenumber

模型的确定程度，由概率推导而来。

json
{
  "model": "jev-1.13.0",
  "answers": {
    "department": {
      "type": "choice",
      "choice": "billing",
      "probabilities": { "billing": 0.88, "technical": 0.12, "sales": 0.0 },
      "confidence": 0.81
    }
  },
  "usage": { "input_tokens": 318, "output_tokens": 34 }
}

Score 答案

type"score"
scorenumber

跨各等级的概率加权答案；可能落在两个等级之间。

legendmap<string, string>

每个等级编号映射回其描述。

probabilitiesmap<string, number>

每个等级（字符串键）映射到其概率（总和为 1 的浮点数）。

confidencenumber

模型的确定程度，由概率推导而来。

json
{
  "model": "jev-1.13.0",
  "answers": {
    "frustration": {
      "type": "score",
      "score": 1.05,
      "legend": { "0": "Calm", "1": "Frustrated", "2": "Very angry" },
      "probabilities": { "0": 0.0, "1": 0.95, "2": 0.05 },
      "confidence": 0.92
    }
  },
  "usage": { "input_tokens": 304, "output_tokens": 18 }
}

错误

错误使用标准 HTTP 状态码，并附带描述问题所在的 JSON 响应体。

状态码含义
401 UnauthorizedAPI 密钥缺失或无效。请检查 Authorization 头。
422 Unprocessable Entity请求体未通过校验——例如缺少必填字段或问题格式错误。响应体会指出出问题的字段。
429 Too Many Requests你已超出速率限制。请稍作退避后重试。
529 OverloadedTypeSafe 暂时过载。请稍后重试。

处理速率限制

当收到 429 Too Many Requests 或 529 Overloaded 响应时，请使用指数退避来重试请求，而不是立即重试。我们的客户端 SDK 会自动处理这种情况，因此只要你使用我们的某个 SDK 及其默认重试策略，就无需额外处理。