Kernleitfäden

Strukturierte Ausgaben & Tool Calling

JSON zurückgeben oder ein Modell Funktionen in Ihrer Anwendung aufrufen lassen

Strukturierte Ausgaben fordern ein Modell dazu auf, JSON zu liefern. Tool Calling ermöglicht es dem Modell, eine Funktion anzufordern, die von Ihrer Anwendung ausgeführt wird. Die verfügbaren Felder hängen vom API-Format und dem Modell ab. Behalten Sie daher während der gesamten Konversation ein einheitliches Format bei und validieren Sie jeden vom Modell erzeugten Wert in Ihrer Anwendung.

Wählen Sie ein API-Format

BedarfAPIFelder
Portable JSON-Objekt-Antworten/v1/chat/completionsresponse_format: {"type": "json_object"}
OpenAI-kompatibler Funktionsaufruf/v1/chat/completionstools: [{ "type": "function", "function": ... }]
OpenAI Responses Tools/v1/responsesResponses tools, tool_choice und text Felder
Claude-natives Tool-Use oder Thinking/v1/messagesAnthropic Messages Tool-Schema
Gemini-Funktionsdeklarationen oder integrierte Tools/v1beta/models/:model:generateContentGemini-native tools und Content-Parts

Verwenden Sie integrierte Tools nur mit dem API-Format, das diese dokumentiert; TokenLab konvertiert diese Tools nicht zwischen verschiedenen Formaten.

JSON-Modus

Für ein JSON-Objekt, das über viele Chat-Modelle hinweg funktioniert, verwenden Sie den Chat Completions JSON-Modus:

{
  "model": "gpt-5.6-terra",
  "messages": [
    {
      "role": "user",
      "content": "Return a JSON object with city and weather."
    }
  ],
  "response_format": { "type": "json_object" }
}

Modelle, die den JSON-Modus unterstützen, führen json-mode in den capabilities unter GET /v1/models auf. Chat Completions akzeptiert text und json_object. json_schema und strict sind modell- und formatspezifisch; verwenden Sie diese nur, wenn das ausgewählte Modell deren Unterstützung dokumentiert.

Parsen und validieren Sie zurückgegebenes JSON immer auf Ihrem Server. Der JSON-Modus ersetzt nicht die Schema-Validierung auf Anwendungsebene.

Einen Tool-Aufruf abschließen

TokenLab gibt den Funktionsnamen und die Argumente zurück; Ihre Anwendung führt diese aus:

  1. Senden Sie Nachrichten zusammen mit Tool-Definitionen.
  2. Lesen Sie die Modellantwort auf tool_calls, function_call, Anthropic tool_use oder Gemini-Funktionsaufruf-Parts.
  3. Führen Sie das Tool in Ihrem eigenen Backend aus.
  4. Hängen Sie das Tool-Ergebnis im selben API-Format an.
  5. Setzen Sie die Konversation fort, bis das Modell eine endgültige Antwort liefert.

Behalten Sie dasselbe API-Format bei, bis der Tool-Aufruf und die endgültige Antwort abgeschlossen sind. Die vier Formate stellen den Tool-Status unterschiedlich dar.

Chat Completions Beispiel

curl https://api.tokenlab.sh/v1/chat/completions \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-terra",
    "messages": [
      {
        "role": "user",
        "content": "Extract name and email as JSON. If needed, look up the customer."
      }
    ],
    "response_format": { "type": "json_object" },
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "lookup_customer",
          "description": "Look up a customer by email",
          "parameters": {
            "type": "object",
            "properties": {
              "email": { "type": "string" }
            },
            "required": ["email"]
          }
        }
      }
    ]
  }'

Ein nützliches Schema schreiben

  • Halten Sie Schemas klein und explizit. Große, verschachtelte Schemas verbrauchen mehr Token und verringern die Zuverlässigkeit.
  • Bevorzugen Sie erforderliche Felder für Werte, ohne die Ihr Produkt nicht fortfahren kann.
  • Verwenden Sie Enums für geschlossene Mengen, von denen Ihre UI oder Ihr Backend abhängt.
  • Fügen Sie Beispiele in den Prompt ein, wenn das Modell Schwierigkeiten mit einer Struktur hat.
  • Wenn ein Feld nicht unterstützt wird, entfernen Sie es oder verwenden Sie ein API-Format, das es dokumentiert.

Vor der Ausführung eines Tools

  • Protokollieren Sie das API-Format, das Modell, die Tool-Namen und die Schema-Feldnamen.
  • Validieren Sie Tool-Argumente, bevor Sie Seiteneffekte ausführen.
  • Wenden Sie Ihre eigenen Berechtigungsprüfungen vor der Tool-Ausführung an.
  • Gestalten Sie die Tool-Ausführung idempotent, falls ein Client-Retry denselben Tool-Aufruf wiederholen könnte.
  • Protokollieren Sie keine Geheimnisse, die von Tools zurückgegeben werden, in für das Modell sichtbaren Nachrichten.

API-Referenz

ThemaReferenz
Multi-Format APIMulti-Format API
Chat Completion erstellenChat-Completion erstellen
Response erstellenResponse erstellen
Message erstellenNachricht erstellen
Gemini Content generierenGenerate Gemini Content

Auf dieser Seite