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.

StreamChunk 分片序列图

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

// Dateipfad: Beispielcode, der eine vollständige Chunk-Sequenz demonstriert
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.

RegelnBeschreibung
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 seinNach 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

// Dateipfad: Beispielcode, ein HttpAdapter-Grundgerüst mit Fehlerbehandlung
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