TS TypeSafe 文档中文版
原文 ↗

API 参考

TypeSafe 评估端点的完整 HTTP API 参考。

用一个带类型的 questions 映射来评估 state，并取回结构化的 answers，每个问题对应一个答案。如需引导式介绍，请从 原语 开始。

评估端点

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

请求体

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

state string | object | array 必填

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

model string 必填

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

questions map<string, Question> 必填

带类型的 Question 对象组成的映射。每个键由你选择；答案会在相同的键下返回。

映射项
‹question id› Question

由你选择的一个键。与之匹配的 Answer 会在同一个 id 下返回。该键不会被发送给底层模型，也不用于推理。

示例请求
{
  "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 &#x22;noul&#x22; 必填
instructions string | object | array 必填

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

criteria object

对“是”和“否”分别意味着什么的可选描述。

属性
true string | object | array

“是”（取值接近 1）意味着什么。

false string | object | array

“否”（取值接近 0）意味着什么。

示例请求
{
  "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 &#x22;choice&#x22; 必填
instructions string | object | array 必填

模型应该判定什么。对象可以把问题放在一个字段中，把它引用的数据放在其他字段中；参见 结构化的 instructions 和 criteria。

criteria map<string, string | object | array | null> 必填

选项到评分标准描述的映射；当某个选项不需要额外细节时使用 null。每个 Choice 最多可以有 255 个选项。

映射项
‹option› string | object | array | null

由你选择的一个键。对该选项的描述。

示例请求
{
  "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 &#x22;score&#x22; 必填
instructions string | object | array 必填

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

criteria array<string | object | array> 必填

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

示例请求
{
  "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 下返回。

model string

执行本次评估的模型。

answers map<string, Answer>

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

映射项
‹question id› Answer

你在 questions 中选择的同一个 id。

usage object

该请求的 token 用量。

属性
input_tokens integer
output_tokens integer
示例响应
{
  "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 &#x22;noul&#x22;
noul number

0（否）到 1（是）之间的是/否答案。

示例响应
{
  "model": "jev-1.13.0",
  "answers": {
    "is_urgent": {
      "type": "noul",
      "noul": 0.95
    }
  },
  "usage": { "input_tokens": 307, "output_tokens": 20 }
}

Choice 答案

type &#x22;choice&#x22;
choice string

概率最高的选项。

probabilities map<string, number>

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

映射项
‹option› number

你在 criteria 中定义的一个选项。

confidence number

模型的确定程度，由概率推导得出。

示例响应
{
  "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 &#x22;score&#x22;
score number

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

legend map<string, string>

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

probabilities map<string, number>

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

映射项
‹level› number

等级索引，以与 legend 匹配的字符串键表示。

confidence number

模型的确定程度，由概率推导得出。

示例响应
{
  "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 Unauthorized 缺少 API 密钥或密钥无效。请检查 Authorization 请求头。
422 Unprocessable Entity 请求体未通过校验——例如缺少必填字段，或问题格式错误。响应体会详细说明有问题的字段。
429 Too Many Requests 你已超出速率限制。请退避，稍等片刻后重试。
529 Overloaded TypeSafe 暂时过载。请稍等片刻后重试。

处理速率限制

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