DEV Community

Cover image for Wie man beliebige KI-Modelle in DeepSeek Harness ausführt?
Emre Demir
Emre Demir

Posted on Originally published at apidog.com

Wie man beliebige KI-Modelle in DeepSeek Harness ausführt?

DeepSeek Harness (dsh) wird mit eingebundenen DeepSeek-Modellen ausgeliefert, bindet Sie aber nicht daran. Modellanbieter sind Konfiguration: Sie verweisen einen Anbieterblock auf einen OpenAI-kompatiblen Endpunkt, hinterlegen eine Zugangsdaten-Referenz und führen Agenten-Sitzungen mit dem Modell aus, das hinter dieser URL liegt. Damit lassen sich lokale Ollama-Instanzen, Unternehmens-Gateways, Qwen über den DashScope-Kompatibilitätsmodus sowie Kataloganbieter wie Anthropic und OpenAI über dieselbe Schnittstelle nutzen.

Apidog noch heute ausprobieren

Dieser Leitfaden erklärt den Anbieterblock Schlüssel für Schlüssel und zeigt drei umsetzbare Setups: ein lokales Modell, einen gehosteten OpenAI-kompatiblen Endpunkt und die eingebauten Kataloganbieter. Alle Angaben stammen aus dem offiziellen Anbieter-Leitfaden auf dem Master-Branch, abgerufen am 20. August 2026. Beachten Sie: dsh ist eine Entwickler-Vorschau. Die README weist ausdrücklich auf abwärtsinkompatible Änderungen hin. Prüfen Sie die Dokumentation daher immer gegen Ihre installierte Version, bevor Sie produktiv deployen.

Wenn Sie den Harness noch nicht kennen, lesen Sie zuerst was DeepSeek Harness ist und wie es funktioniert. Hier geht es anschließend gezielt um die Anbieter-Infrastruktur.

Warum Modelle in einem Agenten-Harness wechseln?

Ein Agenten-Harness ist eine Schleife: Das Modell plant, ruft Tools auf, verarbeitet Ergebnisse und wiederholt den Ablauf. Der Harness steuert diese Schleife; das Modell ist austauschbar.

Typische Gründe für einen Modellwechsel:

  • Kosten: Agenten-Sitzungen verbrauchen schnell viele Token, weil Tool-Ergebnisse wieder in den Kontext gelangen. Sie können Routineaufgaben auf ein günstigeres Modell oder DeepSeek V4-Flash leiten und leistungsstärkere Modelle für komplexe Aufgaben reservieren.
  • Datenlokalität: Wenn Quellcode, Prompts oder Tool-Ausgaben das Netzwerk nicht verlassen dürfen, verwenden Sie ein Modell auf eigener Hardware. Der Harness und die Benutzeroberfläche bleiben gleich.
  • Lokale Entwicklung: Beim Erstellen von Plugins oder Testen von Agentenverhalten vermeiden lokale Modelle API-Kosten und Netzwerkabhängigkeiten. Für Verhaltens- und Integrationschecks genügt oft ein kleineres Modell.

Die Architektur von dsh folgt diesem Prinzip: Komponenten sind Plugins, einschließlich des Modelladapters. Anbieterrouten verwaltet das Plugin dsh-llm-pi-ai, das im Plugin-Konfigurationskatalog als Besitzer der Anbieterrouten dokumentiert ist. Konfiguriert wird das über YAML.

Der Anbieterblock, Schlüssel für Schlüssel

Benutzerdefinierte Anbieter liegen in $DSH_HOME/settings.yaml. Alternativ können Sie sie in der Weboberfläche unter Einstellungen → Modelle anlegen.

llm-pi-ai:
  providers:
    my-gateway:
      apiKeyEnv: GATEWAY_API_KEY
      api: openai-completions
      baseURL: https://gateway.example/v1
      models:
        - id: legacy-chat
        - id: vision-preview
          input: [text, image]
Enter fullscreen mode Exit fullscreen mode

Bedeutung der Schlüssel

  • my-gateway

    Die Anbieter-ID. Verwenden Sie einen stabilen Namen, da dieser als technischer Bezeichner dient. Der sichtbare Name in der Benutzeroberfläche wird separat gesetzt.

  • apiKeyEnv

    Name der Umgebungsvariable mit dem API-Schlüssel. Die YAML-Datei enthält nur die Referenz, nicht das Geheimnis selbst.

  • api

    Das verwendete Protokoll. Für OpenAI-kompatible Endpunkte ist der dokumentierte Wert:

  api: openai-completions
Enter fullscreen mode Exit fullscreen mode

  • baseURL

    Die Basis-URL des Endpunkts, an den dsh Anfragen sendet.

  • models

    Liste der Modell-IDs, die über diesen Anbieter verfügbar sind. Jede id muss exakt dem Modellnamen entsprechen, den der Endpunkt in der Anfrage erwartet.

  • input

    Definiert die Eingabemodalitäten eines Modells. Benutzerdefinierte Modelle sind standardmäßig textbasiert. Für Vision-Modelle deklarieren Sie Bilder explizit:

  input: [text, image]
Enter fullscreen mode Exit fullscreen mode

Alternativ können Sie defaultInput auf Anbieter- bzw. Routenebene setzen. Ein input direkt am Modell überschreibt diesen Standard.

  • compat Kompatibilitätsschalter für Endpunkte, die leicht vom OpenAI-Standard abweichen: 
  compat:
    supportsDeveloperRole: false
    maxTokensField: max_tokens
Enter fullscreen mode Exit fullscreen mode
  • supportsDeveloperRole: false: für Backends, die die Rolle developer ablehnen.
  • maxTokensField: max_tokens: für Backends, die den älteren Feldnamen für das Token-Limit erwarten.

compat kann auf Routenebene oder für einzelne Modelle gesetzt werden.

Wenn Sie einen benutzerdefinierten Anbieter über die Weboberfläche hinzufügen, kann „Verfügbare Modelle abrufen“ den OpenAI-kompatiblen Endpunkt GET /models abfragen. Implementiert Ihr Endpoint diese Route, müssen Sie Modell-IDs nicht manuell eintragen.

Wo der API-Schlüssel gespeichert wird

Geheimnisse speichert dsh nur schreibend in:

$DSH_HOME/.credentials.yaml
Enter fullscreen mode Exit fullscreen mode

Nach dem Speichern über die Benutzeroberfläche erhalten Sie nur einen redigierten Deskriptor zurück. Der Klartextwert wird nicht erneut angezeigt.

settings.yaml enthält ausschließlich Referenzen wie apiKeyEnv oder Zugangsdaten-Deskriptoren. Dadurch können Sie die Konfiguration teilen oder versionieren, ohne API-Schlüssel offenzulegen. Außerdem lassen sich Schlüssel rotieren, ohne den Anbieterblock anzupassen.

Anleitung 1: Ein lokales Modell über Ollama ausführen

Ollama stellt laut seinem OpenAI-Kompatibilitätshandbuch eine OpenAI-kompatible API unter folgender URL bereit:

http://localhost:11434/v1
Enter fullscreen mode Exit fullscreen mode

Da dsh mit openai-completions gegen eine beliebige Basis-URL arbeitet, können Sie Ollama so einbinden:

llm-pi-ai:
  providers:
    ollama-local:
      apiKeyEnv: OLLAMA_API_KEY
      api: openai-completions
      baseURL: http://localhost:11434/v1
      models:
        - id: gpt-oss:20b
        - id: qwen3
Enter fullscreen mode Exit fullscreen mode

Lokales Setup prüfen

  1. Starten Sie Ollama.
  2. Laden Sie die benötigten Modelle: 
   ollama pull gpt-oss:20b
Enter fullscreen mode Exit fullscreen mode
  1. Prüfen Sie die verfügbaren Modellnamen: 
   ollama list
Enter fullscreen mode Exit fullscreen mode

  1. Übernehmen Sie die Namen inklusive Tags exakt als id in die dsh-Konfiguration.

  2. Setzen Sie einen Dummy-Wert für die erwartete Umgebungsvariable:

   export OLLAMA_API_KEY=ollama
Enter fullscreen mode Exit fullscreen mode

Ollama benötigt lokal keinen API-Schlüssel und ignoriert diesen Wert. Das dsh-Schema erwartet jedoch eine Zugangsdaten-Referenz.

Die dsh-Dokumentation enthält kein explizites Ollama-Beispiel. Dieses Setup kombiniert daher das dokumentierte dsh-Schema für benutzerdefinierte Anbieter mit Ollamas dokumentierter OpenAI-kompatibler API. Testen Sie die Konfiguration mit Ihrer dsh-Version, bevor Sie sie intern standardisieren.

Endpoint vor dsh testen

Prüfen Sie den Endpoint zuerst direkt:

GET http://localhost:11434/v1/models
Enter fullscreen mode Exit fullscreen mode

Rufen Sie ihn beispielsweise in Apidog auf. Wenn die Modellliste zurückkommt, stimmen Basis-URL und Serverstatus. Dann sollte auch „Verfügbare Modelle abrufen“ in dsh funktionieren.

Eine vollständige lokale Einrichtung finden Sie auch in wie man GPT-OSS mit Ollama ausführt. Das gleiche Muster gilt für andere Open-Weight-Modelle, sofern Ihre Hardware ausreicht.

Kleine lokale Modelle eignen sich gut für Plugin-Entwicklung und Integrationschecks. Bei langen Kontexten, Tool-Aufrufen und komplexer Planung sind sie oft weniger zuverlässig als die Modelle, für die der Harness optimiert wurde.

Anleitung 2: Einen gehosteten OpenAI-kompatiblen Endpoint nutzen

Für gehostete Modelle sollten Sie nur Anbieter verwenden, die ihre OpenAI-Kompatibilität explizit dokumentieren.

Alibaba Cloud Model Studio (DashScope) dokumentiert auf seiner OpenAI-Kompatibilitätsseite einen Endpoint für Qwen-Modelle:

https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1
Enter fullscreen mode Exit fullscreen mode

Die Authentifizierung erfolgt über DASHSCOPE_API_KEY.

llm-pi-ai:
  providers:
    qwen-dashscope:
      apiKeyEnv: DASHSCOPE_API_KEY
      api: openai-completions
      baseURL: https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1
      models:
        - id: qwen3-max
Enter fullscreen mode Exit fullscreen mode

Konfigurationsschritte

  1. Ersetzen Sie {WorkspaceId} durch Ihre Workspace-Domain aus der Model-Studio-Konsole.
  2. Setzen Sie den API-Schlüssel in der Laufzeitumgebung von dsh: 
   export DASHSCOPE_API_KEY=Ihr_API_Schlüssel
Enter fullscreen mode Exit fullscreen mode
  1. Prüfen Sie aktuelle Modell-IDs in der Dokumentation Ihres Anbieters.
  2. Testen Sie den Endpoint außerhalb von dsh mit GET {baseURL}/models.
  3. Fügen Sie den Anbieter in dsh hinzu und wählen Sie anschließend ein Modell für neue Sitzungen.

Eine Zusammenfassung der Premium-Stufe finden Sie im Qwen 3.8 API-Leitfaden.

Das gleiche Schema funktioniert für andere dokumentiert OpenAI-kompatible Anbieter, etwa Moonshots Kimi API, OpenRouter, vLLM-Deployments oder interne Unternehmens-Gateways. In der Regel ändern sich nur diese Werte:

apiKeyEnv: PROVIDER_API_KEY
baseURL: https://provider.example/v1
models:
  - id: provider-model-id
Enter fullscreen mode Exit fullscreen mode

Wenn Sie bereits Open-Source-Modelle in Codex konfiguriert haben, ist das Prinzip vertraut: Der dsh-Anbieterblock erfüllt eine ähnliche Funktion wie die model_providers-Konfiguration in Codex.

Besonderheiten bei gehosteten Endpoints

Backend lehnt Rollen oder Token-Felder ab

Setzen Sie zuerst den passenden Kompatibilitätsschalter:

compat:
  supportsDeveloperRole: false
Enter fullscreen mode Exit fullscreen mode

Oder:

compat:
  maxTokensField: max_tokens
Enter fullscreen mode Exit fullscreen mode

Ältere OpenAI-kompatible Implementierungen unterstützen häufig die Rolle developer oder neuere Token-Feldnamen nicht.

Vision-Modell erhält keine Bilder

Deklarieren Sie die Modalität explizit:

models:
  - id: vision-model
    input: [text, image]
Enter fullscreen mode Exit fullscreen mode

Ohne diese Angabe behandelt dsh benutzerdefinierte Modelle als Textmodelle.

Anleitung 3: Eingebaute Kataloganbieter verwenden

Für die großen Cloud-Anbieter brauchen Sie keinen benutzerdefinierten YAML-Block. dsh liefert Kataloganbieter für:

  • DeepSeek
  • Anthropic
  • OpenAI

Bei diesen Anbietern besteht die Einrichtung hauptsächlich darin, die Zugangsdaten zu hinterlegen.

Weitere Katalogeinträge verwenden eigene Authentifizierungsverfahren:

  • Bedrock: AWS-Zugangsdaten
  • Vertex: ADC-Projekt
  • Azure: API-Version
  • Codex: OAuth

Kataloganbieter sind der schnellste Weg, wenn Sie Claude, GPT oder DeepSeek ohne eigenes Gateway im Harness verwenden möchten. Benutzerdefinierte Anbieter sind dagegen sinnvoll für lokale Laufzeitumgebungen, regionale Anbieter, API-Gateways und OpenAI-kompatible Aggregatoren.

Details zum DeepSeek-API-Start finden Sie unter api-docs.deepseek.com.

Modellauswahl und Sitzungsbindung

Das Hinzufügen eines Anbieters macht dessen Modelle verfügbar. Wenn Sie unter Einstellungen → Modelle ein Modell auswählen, wird es zum Standard für neue Sitzungen.

Dabei gelten zwei wichtige Regeln:

  1. Bestehende Sitzungen behalten ihr ursprüngliches Modell.

    Ein Wechsel des Standardmodells beeinflusst laufende oder historische Sitzungen nicht.

  2. Das Löschen des Standardanbieters blockiert den Komponisten.

    Wenn der Anbieter gelöscht wird, der das aktuelle Standardmodell bereitstellt, müssen Sie zuerst ein neues Modell auswählen. dsh rät nicht stillschweigend.

Diese Bindung verbessert die Reproduzierbarkeit: Ein Sitzungsprotokoll repräsentiert ein Modell statt eines unbemerkten Modellwechsels während des Laufs. Das ist besonders relevant beim Vergleich verschiedener Harnesses, etwa in DeepSeek Harness vs. Claude Code.

Fehlerbehebung

baseURL ist falsch oder nicht erreichbar

Das ist der häufigste Fehler. Prüfen Sie:

  • Endet die URL auf dem erwarteten Pfad?
    • Meist /v1 für OpenAI-kompatible Endpunkte
    • /compatible-mode/v1 für DashScope
  • Liefert GET {baseURL}/models außerhalb von dsh eine Antwort?
  • Verwenden Sie denselben Authentifizierungsheader wie dsh?

Beispiel:

Authorization: Bearer $KEY
Enter fullscreen mode Exit fullscreen mode

Mit Apidog können Sie die Anfrage direkt senden und Statuscode sowie Response-Body prüfen, statt nur einen gekapselten Harness-Fehler zu sehen.

Für Offline-Entwicklung oder instabile Anbieter können Sie /models- und /chat/completions-Antworten in Apidog mocken und baseURL vorübergehend auf diesen Mock setzen.

Umgebungsvariable fehlt oder ist leer

apiKeyEnv benennt nur eine Variable; sie erzeugt sie nicht. Fehlt die Variable in der Umgebung, in der dsh tatsächlich läuft, werden Anfragen ohne gültige Authentifizierung gesendet und erhalten typischerweise einen 401-Fehler.

Prüfen Sie die Variable im selben Kontext, aus dem Sie dsh starten:

echo $GATEWAY_API_KEY
dsh web
Enter fullscreen mode Exit fullscreen mode

Ein Prozess, der über eine GUI oder einen Dienstmanager gestartet wird, übernimmt Ihr Shell-Profil möglicherweise nicht.

Eingabemodalität stimmt nicht

Wenn Bilder nicht beim Modell ankommen oder Anfragen mit Anhängen fehlschlagen, fehlt oft die explizite Vision-Deklaration:

models:
  - id: vision-model
    input: [text, image]
Enter fullscreen mode Exit fullscreen mode

Wenn alle Modelle eines Anbieters Bilder verarbeiten, können Sie stattdessen defaultInput auf Routenebene setzen.

Protokoll-Eigenheiten des Backends

Fehler zu nicht unterstützten Rollen oder Token-Parametern deuten auf fehlende Kompatibilitätseinstellungen hin:

compat:
  supportsDeveloperRole: false
  maxTokensField: max_tokens
Enter fullscreen mode Exit fullscreen mode

Das sind die zwei dokumentierten Schalter für diese Fälle.

„Gestern hat es noch funktioniert“

dsh ist eine Entwickler-Vorschau. Pinnen Sie die produktiv eingesetzte Version, lesen Sie Release Notes vor Upgrades und rechnen Sie mit Änderungen am Einstellungsschema.

Das deepseek-harness Repository ist die maßgebliche Quelle, nicht dieser oder irgendein anderer Blogbeitrag.

Modellanbieter sind außerdem nur eine Hälfte der Anpassung: Die andere Hälfte sind die Tools, die Ihr Agent aufrufen darf. Wie Sie API-Workflows direkt einbinden, zeigt Verwendung des Apidog CLI in DeepSeek Harness.

Häufig gestellte Fragen

Unterstützt DeepSeek Harness Ollama offiziell?

Die offizielle Anbieter-Dokumentation nennt Ollama nicht explizit. Sie unterstützt jedoch Endpunkte, die das Protokoll openai-completions sprechen. Ollama dokumentiert eine OpenAI-kompatible API unter:

http://localhost:11434/v1
Enter fullscreen mode Exit fullscreen mode

Das gezeigte Setup kombiniert diese beiden dokumentierten Teile. Testen Sie es mit Ihrer installierten dsh-Version, da sich das Schema zwischen Releases ändern kann.

Wo speichert dsh meine API-Schlüssel?

In:

$DSH_HOME/.credentials.yaml
Enter fullscreen mode Exit fullscreen mode

Die Speicherung erfolgt nur schreibend. Die Benutzeroberfläche zeigt nach dem Speichern einen redigierten Deskriptor. In settings.yaml stehen nur Referenzen wie apiKeyEnv, keine Klartext-Schlüssel.

Kann ich unterschiedliche Modelle für unterschiedliche Sitzungen verwenden?

Ja. Das ausgewählte Modell ist nur der Standard für neue Sitzungen. Bestehende Sitzungen behalten das Modell, mit dem sie gestartet wurden.

Sie können daher ein günstigeres Modell wie DeepSeek V4-Flash für Routineaufgaben verwenden und für schwierige Probleme auf ein leistungsstärkeres Modell wechseln, ohne frühere Sitzungen zu verändern.

Mein Endpoint liefert in dsh Fehler, aber dieselbe Anfrage funktioniert mit Curl. Was nun?

Vergleichen Sie die genauen Nutzlasten. Der Harness kann beispielsweise eine developer-Rolle oder ein neueres Token-Limit-Feld senden, das Ihr Backend nicht akzeptiert.

Versuchen Sie die dokumentierten Kompatibilitätsschalter:

compat:
  supportsDeveloperRole: false
  maxTokensField: max_tokens
Enter fullscreen mode Exit fullscreen mode

Wenn Sie die vom Harness formatierte Anfrage in einem API-Client nachstellen, sehen Sie schnell, bei welchem Feld das Backend scheitert.

Top comments (0)