API 参考

API 参考

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

用一个类型化 questions 映射来评估 state，拿回结构化的 answers，每个问题一个。想跟着入门，请从原语开始。

评估端点

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

请求体

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

{
  "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 里嵌套的值一样：

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

详见在问题中使用结构化数据。

Noul

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

{
  "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

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

{
  "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

按你定义的量规给状态评分。返回一个在你各档位之间按概率加权的值。

{
  "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": "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 答案

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

Choice 答案

{
  "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 答案

{
  "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 响应体。

处理限流

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