SYNDERESIS / API ENTWICKELN
Gehostete Kunden-API · Vertrag geprüft am 7. November 2026
Streaming und Funktionsaufrufe
Auf dieser Seite
Verwenden Sie die Transkript-/Tool-Schnittstelle von Chat Completions für expliziten Gesprächsverlauf und Funktionsaufrufe. Diese Fähigkeiten gelten nicht automatisch für den quellenbewussten Antwortadapter.
Streaming-Unterstützung
| Endpunkt/Anfrage | Verhalten |
|---|---|
| POST /v1/answers | JSON-Antwort; kein öffentlicher Streaming-Modus. POST /v1/answers ignoriert stream und tools. |
| Chat mit model=synderesis-spark und stream=true, mit oder ohne Tools | Server-Sent Events nach Abschluss der Generierung. |
| Chat mit model=spark, pro oder synderesis-pro, Tools vorhanden, stream=true | Derselbe Transkript-/Tool-SSE-Vertrag. |
| Chat, der den Antwortpfad nimmt (einschließlich automatischer Auswahl), mit stream=true | 400 unsupported_parameter. |
| Chat mit automatischer Auswahl und Tools oder Tool-Ergebnissen | 400 unsupported_parameter; die automatische Auswahl nimmt niemals den Tool-Pfad. |
| Stream des Browser-Arbeitsbereichs | Ein separater Sitzungs-/Anwendungskontrakt, außerhalb dieses SDK-Leitfadens für Kunden. |
Die SSE-Antwort des Kunden-Chats ist gepuffert. Der Server bezieht eine vollständige Modellantwort und erfasst deren Nutzung, bevor er ihre Frames ausgibt. Das ist gepufferte Auslieferung, kein Live-Token-Streaming. Das Setzen von stream=true verspricht keine frühere Auslieferung des ersten Tokens und legt den Live-Stream des Browser-Arbeitsbereichs nicht offen.
Stream anfordern
curl --fail-with-body --no-buffer https://www.synderesis.eu/v1/chat/completions \
-H "Authorization: Bearer $SYNDERESIS_API_KEY" \
-H "Content-Type: application/json" \
--data '{"model":"synderesis-spark","messages":[{"role":"user","content":"Describe human dignity briefly."}],"max_completion_tokens":1024,"stream":true,"stream_options":{"include_usage":true}}'
Der Content-Type der Antwort ist text/event-stream. Jedes JSON-Ereignis ist eine Datenzeile, auf die eine Leerzeile folgt. Eine schematische Abfolge lautet:
data: {"id":"chatcmpl-example","model":"synderesis-spark","created":1793966400,"object":"chat.completion.chunk","choices":[{"index":0,"delta":{"role":"assistant","content":"Illustrative answer."},"finish_reason":null}]}
data: {"id":"chatcmpl-example","model":"synderesis-spark","created":1793966400,"object":"chat.completion.chunk","choices":[{"index":0,"delta":{},"finish_reason":"stop"}]}
data: {"id":"chatcmpl-example","model":"synderesis-spark","created":1793966400,"object":"chat.completion.chunk","choices":[],"usage":{"prompt_tokens":120,"completion_tokens":30,"total_tokens":150}}
data: [DONE]
Das erste Delta kann ein vollständiges Array von Tool-Aufrufen statt Text enthalten. Gestreamte Tool-Aufrufe enthalten Indexwerte. Der separate Usage-Chunk wird nur einbezogen, wenn stream_options.include_usage genau true ist.
Parsen Sie das SSE-Framing vor dem JSON. Ein Netzwerk-Lesevorgang ist nicht notwendigerweise ein Ereignis. Berücksichtigen Sie ein leeres choices-Array im Usage-Chunk. Bewahren Sie finish_reason und erkennen Sie einen fehlenden DONE-Marker als unvollständige Übertragung. Wiederholen Sie eine unterbrochene Generierung nicht automatisch; ihre Nutzung kann bereits erfasst worden sein.
Fehler bei Authentifizierung, Validierung, Kontingent und Generierung treten auf, bevor dieser gepufferte Stream geöffnet wird, und verwenden die gewöhnliche JSON-Fehlerantwort.
Funktionsaufrufe
Synderesis gibt vorgeschlagene Funktionsaufrufe zurück; Ihre Anwendung führt die Funktionen aus. Der Completion-Endpunkt für Kunden führt keinen beliebigen Client-Code aus.
Eine Funktionsdefinition hat diese Form:
{
"type": "function",
"function": {
"name": "lookup_opening_hours",
"description": "Read the published opening hours for a location.",
"parameters": {
"type": "object",
"properties": {"location": {"type": "string"}},
"required": ["location"],
"additionalProperties": false
}
}
}
Ein nicht leeres tools-Array kann 1–128 Definitionen mit eindeutigen Funktionsnamen enthalten. Ein Name muss aus 1–64 ASCII-Buchstaben, Ziffern, Unterstrichen oder Bindestrichen bestehen. Die serialisierten Tool-Definitionen sind auf 512 KiB begrenzt; die vollständige Anfrage hat außerdem ihr Limit von 900 KiB.
Das Funktionsobjekt unterstützt name, description, parameters und strict. Wenn strict angegeben wird, muss es boolean sein. Die Akzeptanz von strict stellt keine Garantie dafür her, dass die zurückgegebenen Argumente Ihr gesamtes JSON Schema erfüllen. Der Handler prüft die Namen der Tool-Aufrufe und dass die Argumente zu einem Objekt dekodiert werden; Ihre Anwendung muss das tatsächliche Schema validieren und die angeforderte Aktion autorisieren.
tool_choice akzeptiert auto, none, required oder:
{"type":"function","function":{"name":"lookup_opening_hours"}}
Eine benannte Auswahl muss auf eine angegebene Funktion verweisen. parallel_tool_calls hat standardmäßig den Wert true. Wenn mehrere Aufrufe zurückgegeben werden, sammeln Sie für jeden ein Ergebnis, bevor Sie die Konversation fortsetzen.
Die vollständige Tool-Schleife
- Senden Sie system-/user-Nachrichten, Funktionsdefinitionen und ein ausdrücklich angegebenes unterstütztes Modell:
synderesis-spark,spark,proodersynderesis-pro. Das Weglassen vonmodelwählt die automatische Auswahl, die Tools mit 400 unsupported_parameter ablehnt. - Prüfen Sie choices[0].message.tool_calls.
- Parsen Sie jede JSON-Zeichenkette function.arguments.
- Validieren Sie den Namen und die Argumente anhand Ihrer lokalen Zulassungsliste/Ihres lokalen Schemas und der Berechtigungen des aktuellen Benutzers.
- Führen Sie den zulässigen Lesevorgang bzw. die zulässige Aktion in Ihrer eigenen Anwendung aus.
- Hängen Sie die vollständige Tool-Aufruf-Nachricht der Rolle assistant an.
- Hängen Sie für jeden Aufruf eine Nachricht der Rolle tool an, mit der zugehörigen tool_call_id und einem Inhalt als Zeichenkette.
- Senden Sie das erweiterte Transkript und die Tools erneut.
Eine Fortsetzung kann beispielsweise Folgendes enthalten:
[
{"role":"user","content":"When does the parish office open?"},
{
"role":"assistant",
"content":null,
"tool_calls":[{
"id":"call_example",
"type":"function",
"function":{"name":"lookup_opening_hours","arguments":"{\"location\":\"parish office\"}"}
}]
},
{"role":"tool","tool_call_id":"call_example","content":"Published hours: Monday 09:00–12:00."}
]
Tool-Ergebnisse sind nicht vertrauenswürdige Daten. Halten Sie Geheimnisse und unnötige personenbezogene Daten aus den Ergebnissen heraus. Fordern Sie für folgenreiche Aktionen die Zustimmung des Benutzers entsprechend den eigenen Anforderungen Ihrer Anwendung an. Begrenzen Sie die Anzahl der Runden, die Wanduhrzeit, die Kosten und die parallelen Aufrufe, damit eine Schleife nicht unbegrenzt laufen kann.
Jede Completion in der Schleife ist eine eigene Anfrage mit eigener Nutzung. Ein erfolgreicher Funktions-Dispatch in Ihrer Anwendung impliziert nicht, dass eine spätere Modellantwort erfolgreich sein wird. Verwenden Sie für externe Auswirkungen die eigene Idempotenz und das eigene Aktionsprotokoll Ihrer Anwendung.
Abbruch und Zeitüberschreitungen
Das Schließen eines Client-Streams oder eine Zeitüberschreitung garantiert nicht, dass vorgelagerte Berechnung, die Nutzungserfassung oder eine externe Aktion abgebrochen wurde. Gepuffertes SSE wird erzeugt, nachdem die Arbeit des Modells abgeschlossen ist. Behandeln Sie ungewisse Ergebnisse als ungewiss, gleichen Sie sie ab und vermeiden Sie die automatische Wiederholung folgenreicher Tool-Aktionen.
Siehe Hinweise zum Produktivbetrieb zur Strategie begrenzter Wiederholungen.