DeepSeek Harness Protocole StreamChunk et gestion des erreurs
Quel type de données le stream() de l'adaptateur produit-il réellement ?
La réponse est StreamChunk, un protocole de découpage strictement ordonné.
Cela couvre les séquences de chunks, les règles clés et la gestion des erreurs de transmission.
Protocole StreamChunk
StreamChunk est le protocole de streaming entre le Harness et l'adaptateur.
Un bloc de contenu commence par block-start, utilise delta pour une transmission incrémentielle au milieu, et se termine par block-end.
Le texte et les appels d'outils sont deux types différents de blocs de contenu, chacun passant par start / delta / end.
Lorsque tous les chunks arrivent à leur terme, envoyez d'abord usage pour rapporter l'utilisation des tokens, puis envoyez finish pour déclarer la raison de fin.
Le diagramme ci-dessus, de haut en bas, montre une séquence complète de chunks.
D'abord un bloc de texte : block-start → text-delta × 2 → block-end.
Puis un bloc d'appel d'outil : block-start → tool-call-delta → block-end.
Enfin, l'utilisation et la fin.
Un motif de fin stop indique un achèvement normal, tandis que tool-calls indique une demande d'exécution d'outils.
Séquence complète des fragments
La documentation officielle fournit exampleChunks, qui produit tous les chunks d'une seule génération dans l'ordre.
text-delta peut être divisé en plusieurs chunks, concaténés de manière incrémentielle pour former le texte complet.
L'argumentsDelta de tool-call-delta est le delta incrémentiel du texte JSON brut.
Exemple
import { CallId, type StreamChunk } from '@deepseek-ai/dsh-llm'
async function* exampleChunks(): AsyncIterable<StreamChunk> {
// 1. Commencez chaque bloc de contenu avec block-start.
// Démarrer un bloc de texte, l'index est 0
yield { type: 'block-start', index: 0, blockType: 'text' }
// 2. Diffuser le texte via text-delta.
// Delta de texte, peut être divisé en plusieurs fragments
yield { type: 'text-delta', index: 0, text: 'example' }
yield { type: 'text-delta', index: 0, text: ' tutoriel' }
// 3. Terminer chaque bloc de contenu par block-end et le bloc complet.
// Terminer par un bloc complet, l'index correspond à block-start
yield {
type: 'block-end',
index: 0,
block: { type: 'text', text: 'exemple de tutoriel' },
}
// 4. Bloc d'appel d'outil.
// Démarrer un bloc d'appel d'outil, l'index est 1
yield { type: 'block-start', index: 1, blockType: 'tool-call' }
// Nom de l'outil et delta d'argument, id généré par la fabrique CallId
yield {
type: 'tool-call-delta',
index: 1,
id: CallId('call-123'),
name: 'bash',
argumentsDelta: '{"command":"echo example"}',
}
// Terminer par un bloc complet, arguments est un texte JSON assemblé
yield {
type: 'block-end',
index: 1,
block: {
type: 'tool-call',
id: CallId('call-123'),
name: 'bash',
arguments: '{"command":"echo example"}',
},
}
// 5. Utilisation des jetons.
// Signaler l'utilisation des jetons, doit être avant finish.
yield { type: 'usage', usage: { inputTokens: 100, outputTokens: 50 } }
// 6. Raison de fin.
// Dernier chunk, déclarez la raison de fin.
yield { type: 'finish', reason: { kind: 'stop' } }
// Alternativement, { kind: 'tool-calls' } demande l'exécution d'outils.
}
CallId est une fonction de fabrique intégrée au protocole, utilisée pour générer des identifiants d'appel d'outil.
argumentsDelta peut être entièrement généré dans un seul chunk, ou généré de manière incrémentielle sur plusieurs chunks.
Règles clés
Le protocole comporte cinq règles strictes ; en violer une seule fera échouer l'analyse du consommateur.
| Règles | Description |
|---|---|
| block-start et block-end sont appariés. | Chaque block-start doit avoir un block-end correspondant. |
| L'index s'incrémente à partir de 0. | Utilisé pour identifier l'ordre des blocs de contenu. |
| argumentsDelta est le delta JSON brut. | Peut être entièrement généré en un seul chunk, ou généré sur plusieurs chunks |
| finish doit être le dernier chunk | Aucun autre shard n'est autorisé après cela. |
| usage doit venir avant finish. | Indiquer d'abord l'utilisation des tokens, puis déclarer la fin |
text-delta et tool-call-delta doivent tous deux porter l'index de leur bloc propriétaire, et les blocs de contenu ne doivent pas être entrelacés les uns avec les autres.
Gestion des erreurs : exprimer les échecs avec LlmError
L'adaptateur doit lever les échecs de transmission et de protocole via LlmError avec un code stable.
La boucle d'agent conserve l'erreur et son code pour les diagnostics et la gestion des politiques.
Ne comptez pas sur la conversion automatique d'une Error simple.
Un code stable permet à la couche supérieure de faire correspondre précisément les types d'erreur au lieu d'analyser les chaînes d'erreur.
Chaque requête HTTP d'un fournisseur doit également fusionner attributionHeaders().
Transmettez également options.signal à fetch pour que l'annulation et la libération des ressources aboutissent à un arrêt complet.
Exemple
import {
attributionHeaders,
LlmAdapter,
LlmError,
type GenerateOptions,
type StreamChunk,
} from '@deepseek-ai/dsh-llm'
class HttpAdapter extends LlmAdapter {
// Le constructeur injecte l'adresse du point de terminaison
constructor(private readonly endpoint: string) {
super()
}
async *stream(options: GenerateOptions): AsyncIterable<StreamChunk> {
// Lancer la requête HTTP, fusionner les en-têtes d'attribution, transmettre le signal d'abandon.
const response = await fetch(this.endpoint, {
method: 'POST',
headers: {
'content-type': 'application/json',
...attributionHeaders(),
},
body: JSON.stringify({ model: options.model, messages: options.messages }),
// Lorsque l'appelant demande une annulation, fetch abandonnera immédiatement
...options.signal ? { signal: options.signal } : {},
})
if (!response.ok) {
// Utiliser LlmError avec un code stable pour exprimer un échec de transport
throw new LlmError(`Provider API error: ${response.status}`, 'PROVIDER_HTTP_ERROR')
}
// Un véritable adaptateur analyse la réponse et émet la séquence complète de chunks.
// L’adaptateur réel analyse ici le corps de la réponse, produisant la séquence complète de chunks.
yield { type: 'finish', reason: { kind: 'stop' } }
}
}
attributionHeaders() fusionne les informations d’attribution dans les en-têtes de la requête.
Lorsque options.signal existe, transmettez-le comme signal à fetch, et arrêtez-vous immédiatement lorsque la requête est annulée.
Lorsque response.ok est false, levez LlmError avec le code PROVIDER_HTTP_ERROR.
Le squelette ne produit qu’un finish ; un véritable adaptateur analyserait le corps de la réponse ici.
Le premier argument de LlmError est le message, et le second argument est le code stable.
La couche supérieure prend des décisions de politique en fonction du code ; donc une fois qu’un code est publié, ne le modifiez pas.
Champs qui ne peuvent pas être ignorés silencieusement.
Si GenerateOptions contient des champs que l’adaptateur ne peut pas prendre en charge, levez également LlmError ; ne les ignorez pas silencieusement.
Les métadonnées de raisonnement incluent un ID opaque ordonné, un nom d'affichage et des valeurs par défaut de configuration optionnelles.
Veuillez conserver la liste facultative faisant autorité fournie par l'adaptateur, y compris les valeurs off renvoyées par son API de capacités amont.
N'élevez pas l'intensité de raisonnement optionnelle au rang d'énumération principale, sinon l'adaptateur perdra la flexibilité amont.
Le service validera le résultat agrégé et rejettera les intensités de raisonnement explicitement spécifiées mais non prises en charge avant d'appeler stream().
Omettre le raisonnement signifie que le modèle ne dispose d'aucune capacité d'intensité de raisonnement optionnelle.
Résumé et auto-test
Résumé en une phrase : le protocole StreamChunk utilise des blocs appariés pour décrire le contenu, se conclut par usage et finish ; en cas d'échec, il s'exprime avec LlmError portant un code stable.
Question d'auto-évaluation 1 : Quel est l'ensemble minimal de chunks dont un bloc de texte a besoin ?
Question d'auto-évaluation 2 : Quel est l'ordre entre usage et finish ?
Question d'auto-évaluation 3 : Lorsqu'une requête échoue, pourquoi utiliser LlmError avec un code plutôt qu'une Error simple ?
autres extensions