DeepSeek Harness LLM Adapter : Connecter n'importe quel modèle
Les fournisseurs de modèles ne se limitent pas à DeepSeek. Si vous souhaitez connecter dsh à votre propre point de terminaison de modèle, vous devez écrire un adaptateur LLM.
Dans cette section, nous aborderons la classe abstraite LlmAdapter, la méthode stream(), l'enregistrement des routes et la configuration cordis.yml.
Qu'est-ce qu'un adaptateur LLM ?
Un adaptateur LLM est une classe qui hérite de LlmAdapter et implémente la méthode stream().
Il convertit les requêtes indépendantes du fournisseur du Harness en appels API pour un fournisseur spécifique.
Il convertit ensuite la réponse en chunks Harness, à savoir StreamChunk.
Par conséquent, agent-loop consomme une interface unifiée et ne se soucie pas du fournisseur dont l'API se trouve derrière.
En haut se trouve agent-loop, qui consomme un service de génération en streaming indépendant du fournisseur.
Au milieu se trouve le registre ctx.llm, qui maintient le contrat abstrait de LlmAdapter.
En bas se trouvent les adaptateurs individuels, chacun se connectant à un format d’API différent.
Utilisé lors de l’enregistrementctx.llm.registerAdapter(['my-provider'], adapter)Lier la route.
Implémentation minimale
La documentation officielle donne un squelette minimal ; nous le suivons et ajoutons des commentaires.
stream() est le cœur, retournant un générateur asynchrone AsyncIterable.
Les commentaires en trois étapes marquent le flux standard : conversion du format de message, appel de l’API de streaming et conversion de la réponse en StreamChunk.
Exemple
import type { Context } from '@deepseek-ai/cordis'
import Schema from '@deepseek-ai/schemastery'
import { LlmAdapter, type GenerateOptions, type StreamChunk } from '@deepseek-ai/dsh-llm'
// Adaptateur : hérite de la classe abstraite et implémente stream().
class MyAdapter extends LlmAdapter {
private apiKey: string
constructor(apiKey: string) {
super()
this.apiKey = apiKey
}
// stream() renvoie un générateur asynchrone, produisant StreamChunk pièce par pièce
async *stream(options: GenerateOptions): AsyncIterable<StreamChunk> {
// 1. Convertir options.messages au format du fournisseur.
// 2. Appeler l'API de streaming.
// 3. Convertir la réponse en valeurs StreamChunk.
}
}
// Configuration du plugin : apiKey et providers sont tous deux requis.
export interface Config {
apiKey: string
providers: string[]
}
// Schéma Schemastery du même nom, valider la configuration au chargement
export const Config: Schema<Config> = Schema.objet({
apiKey: Schema.string().required(),
providers: Schema.array(Schema.string()).required(),
})
export const name = 'my-llm-adapter'
// Déclarer la dépendance au service llm pour garantir que ctx.llm est prêt.
export const inject = ['llm']
export function apply(ctx: Context, config: Config) {
const adapter = new MyAdapter(config.apiKey)
// Lier la liste des routes de fournisseurs à cet adaptateur
ctx.llm.registerAdapter(config.providers, adapter)
}
apiKey provient de la configuration du plugin, ce qui évite de coder en dur le secret dans le code.
Le tableau providers déclare quelles routes de fournisseur cet adaptateur prend en charge.
Dans apply, d'abord new MyAdapter(config.apiKey), puis registerAdapter termine l'enregistrement.
inject: ['llm'] garantit que apply n'est exécuté qu'après que le service ctx.llm est prêt.
stream() renvoie un générateur asynchrone qui utilise yield pour émettre des tronçons un par un.
Le prochain article expliquera en détail le protocole de découpage StreamChunk.
GenerateOptions : ce que l'adaptateur reçoit
stream() reçoit les GenerateOptions exportés par le dépôt.
Il inclut le modèle, l'effort de raisonnement, l'historique de conversation, le prompt système, le schéma d'outil, les paramètres de génération, les séquences d'arrêt et le signal d'abandon.
Les champs complets sont régis par les types TypeScript exportés par @deepseek-ai/dsh-llm.
| Fields | Description |
|---|---|
| fournisseur | Sélectionner un adaptateur enregistré |
| model | Les ID de modèle appartenant à l'adaptateur n'ont pas besoin d'être enregistrés au démarrage. |
| messages | Historique des conversations |
| prompt système | Prompt système |
| tools | schéma d’outil |
| raisonnement | L’ID d’effort de raisonnement pris en charge par l’adaptateur (facultatif). |
| signal | Signal d’abandon, utilisé par l’annulation et la libération des ressources pour arrêter complètement. |
L’adaptateur doit mapper les champs pris en charge vers l’API spécifique.
Si un champ ne peut pas être pris en charge, il doit lever une LlmError avec un code stable, et ne doit pas l’ignorer silencieusement.
Les champs non pris en charge doivent lever des erreurs explicites plutôt que d’être ignorés silencieusement ; sinon, le modèle recevra des résultats incomplets.
Enregistrer l’adaptateur
Dans apply, appelez ctx.llm.registerAdapter pour terminer l’enregistrement de la route.
Exemple
ctx.llm.registerAdapter(['my-provider'], adapter)
Le premier paramètre est la liste des routes de fournisseur gérées par l’adaptateur.
GenerateOptions.provider sélectionne un adaptateur enregistré.
GenerateOptions.model transmet l'ID de modèle détenu par l'adaptateur, qui n'a pas besoin d'être enregistré au démarrage du cycle de vie.
Si l'adaptateur peut exposer les options de modèle au sélecteur, il peut redéfinir listModels().
Lorsque vous devez renvoyer l'identité exacte du fournisseur et du modèle, vous pouvez redéfinir resolveModel(provider, model, signal?).
resolveModel renvoie, en une seule requête, le fournisseur exact, l'identité du modèle, ainsi que les métadonnées facultatives de contexte et de raisonnement.
Les métadonnées de raisonnement décrivent les efforts de raisonnement facultatifs du modèle : des ID opaques ordonnés, des noms d'affichage et des valeurs de configuration par défaut facultatives.
Préservez la liste facultative faisant autorité fournie par l'adaptateur, y compris la valeur off renvoyée par l'API de capacité en amont ; ne promeuvez pas ces valeurs en énumérations du cœur.
Les requêtes asynchrones doivent répondre au signal facultatif afin que l'annulation et la libération des ressources s'arrêtent complètement.
Le service valide le résultat agrégé : un effort de raisonnement explicitement spécifié mais non pris en charge sera rejeté avant l'appel à stream().
Omettre le raisonnement indique que le modèle n'a pas de capacité d'effort de raisonnement facultative.
Utilisation dans cordis.yml
Chargez le plugin adaptateur avec agent-loop, et faites en sorte qu'agent-loop utilise le nouveau fournisseur et le nouveau modèle.
Exemple
# Charger le plugin d'adaptateur ; apiKey est lu à partir des variables d'environnement.
- id: my-llm
name: './src/my-llm-adapter.ts'
config:
apiKey: !!js process.env.MY_API_KEY
providers:
- my-provider
# Configurer agent-loop pour utiliser le fournisseur et le modèle du nouvel adaptateur
- id: agent-loop
name: '@deepseek-ai/dsh-agent-loop'
config:
agents:
- id: main
provider: my-provider
model: my-model-v1
La config.apiKey du plugin my-llm est lue depuis la variable d'environnement MY_API_KEY et n'est pas écrite sur le disque.
Le tableau providers enregistre la route my-provider vers MyAdapter.
Configurez le fournisseur et le modèle dans agents.main de agent-loop, et les requêtes générées atteindront le nouvel adaptateur.
Référence pratique
Le dépôt contient deux implémentations existantes complètes pour comparaison.
llm-deepseek s'adapte à l'API DeepSeek, en utilisant le format compatible OpenAI.
llm-pi-ai s'adapte à Pi AI, qui utilise un format d'API différent.
Comparer ces deux adaptateurs montre comment le même contrat de harness est implémenté au-dessus de différents SDK de fournisseurs.
Lire d'abord llm-deepseek puis llm-pi-ai permet de voir le plus facilement l'idée de couture « contrat inchangé, implémentations variables ».
Résumé et auto-test
Résumé en une phrase : adaptateur LLM = hériter de LlmAdapter + implémenter stream() + enregistrement de route registerAdapter + configuration cordis.yml.
Question d'auto-évaluation 1 : Quel est le type de retour de stream() ?
Question d'auto-évaluation 2 : Que représente le premier paramètre de registerAdapter ?
Question d'auto-évaluation 3 : Quelles options de configuration agent-loop utilise-t-il pour sélectionner un nouvel adaptateur ?
autres extensions