Pi-Agent-Integration mit DeepSeek

DeepSeek bietet eine OpenAI-kompatible API, sodass Sie die vorhandene OpenAI-Adapterschicht von Pi wiederverwenden können, ohne einen separaten Adapter für DeepSeek zu entwickeln.

Die Kernarbeit für die Integration besteht nur aus zwei Dingen: den Provider und die Modellparameter in models.json deklarieren und den API-Schlüssel über Umgebungsvariablen bereitstellen.

Die Gesamtarchitektur ist im folgenden Diagramm dargestellt:

Pi 接入 DeepSeek 架构图

Die sogenannte "OpenAI-kompatible API" bedeutet, dass das HTTP-Schnittstellenprotokoll des Providers mit OpenAI konsistent ist. Solange das Protokoll kompatibel ist, kann jedes Tool, das OpenAI unterstützt, es direkt aufrufen; DeepSeek gehört zu dieser Kategorie.


Pi installieren

Pi hängt von der Node.js-Laufzeitumgebung ab. Bitte stellen Sie vor der Installation sicher, dass Node.js bereit ist.

Node.js installieren

Laden Sie den Installer für Ihr System von der offiziellen Node.js-Website herunter und installieren Sie ihn mit den Standardoptionen.

Pi CLI installieren

Im Terminal global über npm installieren:

npm install -g --ignore-scripts @earendil-works/pi-coding-agent

Linux- und macOS-Benutzer können auch das offizielle Installationsskript verwenden, um mit einem einzigen Befehl zu installieren:

curl -fsSL https://pi.dev/install.sh | sh

Installation überprüfen

Führen Sie den folgenden Befehl aus. Wenn die Versionsnummer normal ausgegeben wird, war die Installation erfolgreich:

pi --version

Ausgabe ähnelt:

0.83.0

DeepSeek-Anbieter konfigurieren

Pi definiert benutzerdefinierte Modell-Provider über models.json. Dieser Abschnitt integriert DeepSeek als OpenAI-kompatible API.

Pfad der Konfigurationsdatei

Verschiedene Betriebssysteme haben unterschiedliche Konfigurationspfade. Bitte folgen Sie dem für Ihr System:

BetriebssystemPfad der Konfigurationsdatei
Linux / macOS~/.pi/agent/models.json
Windows%USERPROFILE%\.pi\agent\models.json

models.json schreiben

Folgenden Inhalt in die Konfigurationsdatei schreiben:

{
  "providers": {
    "deepseek": {
      "baseUrl": "https://api.deepseek.com",
      "api": "openai-completions",
      "apiKey": "$DEEPSEEK_API_KEY",
      "models": [
        {
          "id": "deepseek-v4-pro",
          "name": "DeepSeek V4 Pro",
          "contextWindow": 1000000,
          "maxTokens": 384000,
          "input": ["text"],
          "reasoning": true,
          "cost": {
            "input": 1.74,
            "output": 3.48,
            "cacheRead": 0.145,
            "cacheWrite": 0
          },
          "compat": {
            "requiresReasoningContentOnAssistantMessages": true,
            "thinkingFormat": "deepseek",
            "reasoningEffortMap": {
              "minimal": "high",
              "low": "high",
              "medium": "high",
              "high": "high",
              "xhigh": "max"
            }
          }
        },
        {
          "id": "deepseek-v4-flash",
          "name": "DeepSeek V4 Flash",
          "contextWindow": 1000000,
          "maxTokens": 384000,
          "input": ["text"],
          "reasoning": true,
          "cost": {
            "input": 0.14,
            "output": 0.28,
            "cacheRead": 0.028,
            "cacheWrite": 0
          },
          "compat": {
            "requiresReasoningContentOnAssistantMessages": true,
            "thinkingFormat": "deepseek",
            "reasoningEffortMap": {
              "minimal": "high",
              "low": "high",
              "medium": "high",
              "high": "high",
              "xhigh": "max"
            }
          }
        }
      ]
    }
  }
}

Erläuterung der Konfigurationselemente

Im Folgenden werden die in models.json verwendeten Hauptfelder einzeln erläutert:

FeldTypeErforderlich?BeschreibungStandardwert
baseUrlstringErforderlichDer OpenAI-kompatible API-Endpunkt für DeepSeekhttps://api.deepseek.com
apistringErforderlichIntegrationsprotokoll; deklariert die Verwendung des OpenAI-Completions-kompatiblen Protokollsopenai-completions
apiKeystringErforderlichLiest den Schlüssel aus einer Umgebungsvariable mit demselben Namen; der Schlüssel muss nicht im Klartext in der Konfigurationsdatei geschrieben werden$DEEPSEEK_API_KEY
contextWindownumberErforderlichGröße des Kontextfensters (Tokens)1000000
maxTokensnumberErforderlichMaximale Ausgabelänge pro Anfrage (Tokens)384000
ReasoningbooleschOptionalGibt an, dass das Modell die Chain-of-Thought-(Reasoning-)Fähigkeit unterstütztwahr
KostenObjektOptionalSpeichert Einheitspreise für Input/Output/Cache-Treffer, die von der Pi-Schnittstelle zur Kostenschätzung verwendet werden—
requiresReasoning
ContentOnAssistantMessages
booleschEmpfohlenIn Multi-Turn-Konversationen müssen Assistant-Nachrichten das Feld reasoning_content beibehalten; andernfalls können Kompatibilitätsprobleme auftretenwahr
thinkingFormatstringEmpfohlenParst und zeigt den Reasoning-Prozess gemäß dem spezifischen Thinking-Content-Format von DeepSeek andeepseek
reasoningEffortMapObjektEmpfohlenBildet Pis Reasoning-Effort-Level auf die tatsächlich von DeepSeek unterstützten Level ab—

reasoningEffortMap bildet die fünf Reasoning-Level von Pi (minimal / low / medium / high / xhigh) auf die von DeepSeek unterstützten Level ab. Mit Ausnahme von xhigh, das auf max abgebildet wird, konvergieren alle anderen zu high.

Modellauswahl

Die Konfiguration deklariert zwei DeepSeek-Modelle. Die wichtigsten Unterschiede sind folgende:

ModellKontextfensterMaximale AusgabeEingabe-EinheitspreisAusgabe-EinheitspreisCache-Treffer-EinheitspreisGeeignete Szenarien
deepseek-v4-pro1,000,000384,0001.743.480.145Stärkere Argumentationsfähigkeit, geeignet für komplexe Aufgaben
deepseek-v4-flash1,000,000384,0000.140.280.028Schnellere Antwort, geringere Kosten

Die Einheitspreise sind in US-Dollar pro Million Token.

API-Schlüssel beziehen und festlegen

Beantragen Sie zunächst einen API-Schlüssel auf der DeepSeek Open Platform:https://platform.deepseek.com/api_keys。

Für Linux / macOS exportieren Sie die Umgebungsvariable im Terminal:

export DEEPSEEK_API_KEY="你的 DeepSeek API Key"

Für Windows (PowerShell) setzen Sie sie wie folgt:

$env:DEEPSEEK_API_KEY="你的 DeepSeek API Key"

Es wird empfohlen, den export-Befehl in die Shell-Konfiguration (wie ~/.bashrc, ~/.zshrc oder PowerShell-Profil) zu schreiben, um ihn nicht bei jedem Öffnen eines neuen Terminals erneut festlegen zu müssen.

Bitte ersetzen Sie "your DeepSeek API Key" im Beispiel durch Ihren echten Schlüssel. Der API Key ist eine vertrauliche Information; bitte bewahren Sie ihn sicher auf und committen Sie ihn niemals in ein Repository.


Ausführen und Testen

Sobald die Konfiguration abgeschlossen ist, können Sie Pi starten und zum DeepSeek-Modell wechseln.

Pi starten

In das Projektverzeichnis wechseln:

cd ~/example-test/

Führen Sie direkt den Befehl pi aus:

pi

Zum DeepSeek-Modell wechseln

Nachdem Sie die interaktive Oberfläche betreten haben, wechseln Sie, indem Sie den folgenden Schritten folgen:

  1. Geben Sie/modelein, um den Modellselektor zu öffnen.

  2. Wählen Sie den Anbieter deepseek aus und wählen Sie dann DeepSeek-V4-Pro oder DeepSeek-V4-Flash.

  3. Fragen Sie als Nächstes das aktuelle Modell ab.

Nach dem Wechsel können Sie direkt in diesem minimalistischen Terminal-Framework mit dem Programmieren beginnen.

Vorgeschlagene Testschritte

Überprüfen Sie, ob die Integration vollständig und nutzbar ist, indem Sie die folgende Checkliste durchgehen:

TestelementVorgehensweiseErwartetes Ergebnis
Authentifizierung und KonnektivitätSenden Sie einen Satz, zum Beispiel: "Hallo, bitte stellen Sie die Beispiel-Lernplattform vor"Empfangen Sie eine normale Antwort ohne 401-/403-Authentifizierungsfehler, die bestätigt, dass apiKey und baseUrl korrekt konfiguriert sind
Reasoning-FähigkeitStellen Sie eine Frage, die mehrstufiges Reasoning erfordert, z. B. indem Sie es bitten, zuerst zu analysieren und dann eine Lösung bereitzustellenEinen sichtbaren Denkprozess ausgeben, der anzeigt, dass thinkingFormat und reasoning wirksam sind
Mehrrunden-Tool-AufrufePi kontinuierlich Tools aufrufen lassen, um Dateien zu lesen, Befehle auszuführen, Code zu ändern und Ergebnisse zu überprüfenMehrturn-Konversation bleibt stabil, ohne Fehler durch fehlendes reasoning_content
Umschalten des Reasoning-AufwandsIn /model von medium zu xhigh wechselnVerhalten entspricht dem Mapping in reasoningEffortMap; xhigh entspricht DeepSeeks max
KostenberechnungNach Ausführung einiger realer Aufgaben die Kostenstatistik prüfenDie Statistiken der Oberfläche stimmen mit den im Feld cost festgelegten Stückpreisen überein

Unter diesen ist "Multi-turn Tool Calls" das Schlüsselszenario, um zu überprüfen, ob die Konfiguration requiresReasoningContentOnAssistantMessages korrekt ist.


Allgemeine Fehlerbehebung

Wenn bei der Integration Probleme auftreten, verwenden Sie die folgende Checkliste, um sie schnell zu lokalisieren.

DeepSeek wird im Modellselektor nicht angezeigt

Prüfen Sie, ob der Pfad zu models.json korrekt ist. Die Pfade für Windows und Linux / macOS sind unterschiedlich.

Bestätigen Sie außerdem, dass das JSON-Format keine Syntaxfehler enthält, wie z. B. nachgestellte Kommas oder nicht geschlossene Anführungszeichen.

Authentifizierung fehlgeschlagen

Bestätigen Sie, dass die Umgebungsvariable DEEPSEEK_API_KEY korrekt gesetzt wurde.

Hinweis: Die Terminal-Sitzung, in der Sie den Befehl pi ausführen, muss dieselbe Sitzung sein, in der Sie die Umgebungsvariable gesetzt haben.

Multi-Turn-Tool-Aufrufe melden Fehler

Prüfen Sie zunächst, ob requiresReasoningContentOnAssistantMessages und thinkingFormat wie oben beschrieben vollständig konfiguriert wurden.

Benötigen Sie weitere Anpassungsmöglichkeiten

Sie können sich auf dieoffizielle Pi-Modelldokumentationfür umfassendere Konfigurationsoptionen beziehen.

Weitere Erweiterungen