DeepSeek-Harness: StreamChunk-Protokoll und Fehlerbehandlung
Welche Art von Daten gibt stream() des Adapters tatsächlich aus?
Die Antwort ist StreamChunk, ein streng geordnetes Chunking-Protokoll.
Dies behandelt Chunk-Sequenzen, wichtigste Regeln und den Umgang mit Übertragungsfehlern.
StreamChunk-Protokoll
StreamChunk ist das Streaming-Protokoll zwischen dem Harness und dem Adapter.
Ein Inhaltsblock beginnt mit block-start, verwendet delta für die inkrementelle Übertragung in der Mitte und endet mit block-end.
Text und Tool-Aufrufe sind zwei verschiedene Arten von Inhaltsblöcken, die jeweils start / delta / end durchlaufen.
Wenn alle Chunks zu Ende gehen, senden Sie zuerst usage, um den Token-Verbrauch zu melden, und dann finish, um den Endgrund anzugeben.
Das obige Diagramm zeigt von oben nach unten eine vollständige Chunk-Sequenz.
Zuerst ein Textblock: block-start → text-delta × 2 → block-end.
Dann ein Tool-Aufruf-Block: block-start → tool-call-delta → block-end.
Abschließend: usage und finish.
Ein Finish-Grund von stop zeigt einen normalen Abschluss an, während tool-calls eine Anforderung zum Ausführen von Tools anzeigt.
Vollständige Shard-Sequenz
Die offizielle Dokumentation bietet exampleChunks, welches alle Chunks aus einer einzelnen Generierung in Reihenfolge erzeugt.
text-delta kann in mehrere Chunks aufgeteilt und inkrementell zum vollständigen Text zusammengesetzt werden.
Das argumentsDelta von tool-call-delta ist das inkrementelle Delta des rohen JSON-Texts.
Beispiel
import { CallId, type StreamChunk } from '@deepseek-ai/dsh-llm'
async function* exampleChunks(): AsyncIterable<StreamChunk> {
// 1. Beginne jeden Inhaltsblock mit block-start.
// Starte einen Textblock, Index ist 0
yield { type: 'block-start', index: 0, blockType: 'text' }
// 2. Text durch text-delta streamen.
// Text-Delta, kann in mehrere Fragmente aufgeteilt werden
yield { type: 'text-delta', index: 0, text: 'example' }
yield { type: 'text-delta', index: 0, text: ' tutorial' }
// 3. Beende jeden Inhaltsblock mit block-end und dem vollständigen Block.
// Ende mit einem vollständigen Block, Index stimmt mit block-start überein
yield {
type: 'block-end',
index: 0,
block: { type: 'text', text: 'Beispiel-Tutorial' },
}
// 4. Tool-Aufruf-Block.
// Starte einen Tool-Block, index ist 1
yield { type: 'block-start', index: 1, blockType: 'tool-call' }
// Tool-Name und Argument-Delta, id von CallId-Factory generiert
yield {
1⟧'tool-call-delta': 'tool-call-delta',
index: 1,
id: CallId('123'),
name: 'bash',
argumentsDelta: '{"command":"echo example"}',
}
// Beende mit einem vollständigen Block, arguments ist zusammengesetzter JSON-Text
yield {
type: 'block-end',
index: 1,
block: {
type: 'tool-call',
id: CallId('123'),
name: 'bash',
arguments: '{"command":"echo example"}',
},
}
// 5. Token-Nutzung.
// Token-Nutzung melden, muss vor finish erfolgen.
yield { type: 'usage', usage: { inputTokens: 100, outputTokens: 50 } }
// 6. Abschlussgrund.
// Letzter Chunk, Grund für die Beendigung angeben.
yield { type: 'finish', reason: { kind: 'stop' } }
// Alternativ fordert { kind: 'tool-calls' } die Ausführung eines Tools an.
}
CallId ist eine in das Protokoll integrierte Factory-Funktion, die zum Generieren von Tool-Call-IDs verwendet wird.
argumentsDelta kann vollständig in einem einzigen Chunk generiert werden oder inkrementell über mehrere Chunks hinweg generiert werden.
Wichtige Regeln
Das Protokoll hat fünf strikte Regeln; die Verletzung einer einzigen davon führt dazu, dass der Consumer beim Parsen fehlschlägt.
| Regeln | Beschreibung |
|---|---|
| block-start und block-end treten paarweise auf. | Jeder block-start muss ein entsprechendes block-end haben. |
| Der Index beginnt bei 0. | Wird verwendet, um die Reihenfolge der Inhaltsblöcke zu identifizieren. |
| argumentsDelta ist das rohe JSON-Delta. | Kann vollständig in einem Chunk generiert werden oder über mehrere Chunks hinweg generiert werden |
| finish muss der letzte Chunk sein | Nach diesem sind keine weiteren Shards erlaubt. |
| usage muss vor finish kommen. | Melde zuerst die Token-Nutzung und erkläre dann das Ende |
text-delta und tool-call-delta müssen den Index ihres zugehörigen Blocks tragen, und Inhaltsblöcke dürfen nicht miteinander verschachtelt werden.
Fehler: Fehler mit LlmError ausdrücken
Der Adapter sollte Übertragungs- und Protokollfehler über LlmError mit einem stabilen Code auslösen.
Die Agent-Loop behält den Fehler und seinen Code für Diagnose- und Richtlinienbehandlung bei.
Verlassen Sie sich nicht darauf, dass ein einfacher Error automatisch konvertiert wird.
Ein stabiler Code ermöglicht es der oberen Ebene, Fehlertypen präzise zuzuordnen, anstatt Fehlerstrings zu parsen.
Jede HTTP-Anfrage eines Providers muss außerdem attributionHeaders() zusammenführen.
Übergeben Sie außerdem options.signal an fetch, damit Abbruch und Ressourcenfreigabe vollständig zum Stillstand kommen.
Beispiel
import {
attributionHeaders,
LlmAdapter,
LlmError,
type GenerateOptions,
type StreamChunk,
} from '@deepseek-ai/dsh-llm'
class HttpAdapter extends LlmAdapter {
// Konstruktor injiziert Endpunktadresse
constructor(private readonly endpoint: string) {
super()
}
async *stream(options: GenerateOptions): AsyncIterable<StreamChunk> {
// HTTP-Anfrage initiieren, Attributions-Header zusammenführen, Abbruchsignal übergeben.
const response = await fetch(this.endpoint, {
method: 'POST',
headers: {
'content-type': 'application/json',
...attributionHeaders(),
},
body: JSON.stringify({ model: options.model, messages: options.messages }),
// Wenn der Aufrufer einen Abbruch anfordert, bricht fetch sofort ab
...options.signal ? { signal: options.signal } : {},
})
if (!response.ok) {
// LlmError mit einem stabilen Code verwenden, um Transportfehler auszudrücken
throw new LlmError(`Provider-API-Fehler: ${response.status}`, 'PROVIDER_HTTP_ERROR')
}
// Ein echter Adapter parst die Antwort und emittiert die vollständige Chunk-Sequenz.
// Der echte Adapter parst hier den Antwort-Body und erzeugt dabei die vollständige Chunk-Sequenz.
yield { type: 'finish', reason: { kind: 'stop' } }
}
}
attributionHeaders() führt Attributionsinformationen in die Request-Header ein.
Wenn options.signal existiert, übergib es als signal an fetch und stoppe sofort, wenn die Anfrage abgebrochen wird.
Wenn response.ok false ist, wirf LlmError mit dem Code PROVIDER_HTTP_ERROR.
Das Grundgerüst liefert nur ein finish; ein echter Adapter würde hier den Antwort-Body parsen.
Das erste Argument von LlmError ist die Nachricht, und das zweite Argument ist der stabile Code.
Die obere Schicht trifft anhand des Codes Richtlinienentscheidungen; sobald ein Code veröffentlicht wurde, ändere ihn nicht.
Felder, die nicht stillschweigend verworfen werden dürfen.
Wenn GenerateOptions Felder enthält, die der Adapter nicht unterstützen kann, wirf ebenfalls LlmError; verwerfe sie nicht stillschweigend.
Reasoning-Metadaten umfassen eine geordnete opake ID, einen Anzeigenamen und optionale Konfigurationsstandardwerte.
Bitte bewahren Sie die vom Adapter bereitgestellte maßgebliche optionale Liste, einschließlich der von seiner Upstream-Capability-API zurückgegebenen off-Werte, unverändert auf.
Stufen Sie die optionale Reasoning-Intensität nicht zu einem Core-Enum hoch, sonst verliert der Adapter die Upstream-Flexibilität.
Der Dienst wird das aggregierte Ergebnis validieren und explizit angegebene, aber nicht unterstützte Reasoning-Stärken zurückweisen, bevor stream() aufgerufen wird.
Das Weglassen von Reasoning bedeutet, dass das Modell keine optionale Reasoning-Intensitätsfähigkeit besitzt.
Zusammenfassung und Selbsttest
Zusammenfassung in einem Satz: Das StreamChunk-Protokoll verwendet paarweise Blöcke, um Inhalte zu beschreiben, und schließt mit usage und finish ab; bei einem Fehler drückt es dies mit LlmError aus, der einen stabilen Code trägt.
Selbsttestfrage 1: Was ist die minimale Menge an Chunks, die ein Textblock benötigt?
Selbsttestfrage 2: Wie ist die Reihenfolge von usage und finish?
Selbsttestfrage 3: Warum sollte man, wenn eine Anfrage fehlschlägt, LlmError mit einem Code statt eines einfachen Error verwenden?
Weitere Erweiterungen