API-Referenz

Vollständige HTTP-API-Referenz für den Evaluierungs-Endpunkt von TypeSafe.

Evaluiere einen state gegen eine Map typisierter questions und erhalte strukturierte answers zurück, eine pro Frage. Für eine geführte Einführung beginne mit den Primitiven.

Evaluierungs-Endpunkt

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

Anfrage-Body

Die oberste Form jeder Anfrage. Jeder Eintrag in der questions-Map ist eine typisierte Frage, die du benennst.

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

Fragetypen

Ein Question ist einer von drei Typen, festgelegt durch sein type-Feld. Alle drei teilen type und instructions; jeder fügt sein eigenes criteria hinzu.

Die Eigenschaft instructions kann eine Zeichenkette, ein Objekt oder ein Array sein. Du kannst eine lange Frage mit zusätzlichem Kontext oder Daten, auf die sie sich beziehen muss, in ein strukturiertes Objekt aufteilen. Lege die Frage in ein Feld und die Daten in die anderen und verweise auf die Datenfelder mit ihrem Namen in Backticks, genauso wie du eine Frage auf einen verschachtelten state-Wert richtest:

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

Siehe Struktur in den Fragen verwenden, um mehr zu erfahren.

Noul

Eine Ja/Nein-Frage. Gibt die Wahrscheinlichkeit zurück, dass die Antwort ja ist.

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

Wählt eine Option aus einer Menge, die du definierst. Gibt die gewählte Option und die vollständige Wahrscheinlichkeitsverteilung zurück.

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

Bewertet den Zustand entlang einer Rubrik, die du definierst. Gibt einen wahrscheinlichkeitsgewichteten Wert über deine Stufen zurück.

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

Antwort-Body

Eine Antwort pro Frage, zurückgegeben unter denselben ids, die du angegeben hast.

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

Antworttypen

Jede Antwort trägt ein type, das zu ihrer Frage passt. Choice- und Score-Antworten tragen außerdem eine confidence zwischen 0 und 1, abgeleitet aus der Wahrscheinlichkeitsverteilung der Antwort. Siehe Konfidenz.

Noul-Antwort

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

Choice-Antwort

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

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

Fehler

Fehler verwenden Standard-HTTP-Statuscodes mit einem JSON-Body, der beschreibt, was schiefgelaufen ist.

Umgang mit Ratenlimits

Wenn du eine 429 Too Many Requests- oder 529 Overloaded-Antwort erhältst, versuche die Anfrage mit exponentiellem Backoff erneut, statt sofort erneut zu versuchen. Unsere Client-SDKs erledigen das automatisch, sodass kein zusätzlicher Aufwand nötig ist, wenn du eines unserer SDKs mit seiner Standard-Retry-Richtlinie verwendest.