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 且沿用其預設重試策略，就無需額外處理。