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
| Bedarf | API | Felder |
|---|---|---|
| Portable JSON-Objekt-Antworten | /v1/chat/completions | response_format: {"type": "json_object"} |
| OpenAI-kompatibler Funktionsaufruf | /v1/chat/completions | tools: [{ "type": "function", "function": ... }] |
| OpenAI Responses Tools | /v1/responses | Responses tools, tool_choice und text Felder |
| Claude-natives Tool-Use oder Thinking | /v1/messages | Anthropic Messages Tool-Schema |
| Gemini-Funktionsdeklarationen oder integrierte Tools | /v1beta/models/:model:generateContent | Gemini-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:
- Senden Sie Nachrichten zusammen mit Tool-Definitionen.
- Lesen Sie die Modellantwort auf
tool_calls,function_call, Anthropictool_useoder Gemini-Funktionsaufruf-Parts. - Führen Sie das Tool in Ihrem eigenen Backend aus.
- Hängen Sie das Tool-Ergebnis im selben API-Format an.
- 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
| Thema | Referenz |
|---|---|
| Multi-Format API | Multi-Format API |
| Chat Completion erstellen | Chat-Completion erstellen |
| Response erstellen | Response erstellen |
| Message erstellen | Nachricht erstellen |
| Gemini Content generieren | Generate Gemini Content |