Интеграция Pi Agent с DeepSeek

DeepSeek предоставляет API, совместимый с OpenAI, поэтому вы можете повторно использовать существующий слой адаптера OpenAI в Pi, не разрабатывая отдельный адаптер для DeepSeek.

Основная работа по интеграции — это всего две вещи: объявить провайдера и параметры модели в models.json и передать API-ключ через переменные окружения.

Общая архитектура показана на следующей схеме:

Pi 接入 DeepSeek 架构图

Так называемый «OpenAI-совместимый API» означает, что протокол HTTP-интерфейса провайдера соответствует OpenAI. Пока протокол совместим, любой инструмент, поддерживающий OpenAI, может вызывать его напрямую; DeepSeek относится к этой категории.

Установите Pi

Pi зависит от среды выполнения Node.js. Перед установкой убедитесь, что Node.js готов.

Установите Node.js

Скачайте установщик для вашей системы с официального сайта Node.js и установите его с параметрами по умолчанию.

Установите Pi CLI

Установите глобально через npm в терминале:

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

Пользователи Linux и macOS также могут использовать официальный скрипт установки, чтобы установить одной командой:

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

Проверка установки

Выполните следующую команду. Если номер версии выводится нормально, установка прошла успешно:

pi --version

Вывод, похожий на:

0.83.0

Настройка провайдера DeepSeek

Pi определяет пользовательских провайдеров моделей через models.json. В этом разделе DeepSeek интегрируется как OpenAI-совместимый API.

Путь к файлу конфигурации

В разных операционных системах пути конфигурации различаются. Используйте тот, который соответствует вашей системе:

Операционная система	Путь к файлу конфигурации
Linux / macOS	~/.pi/agent/models.json
Windows	%USERPROFILE%\.pi\agent\models.json

Запишите models.json

Запишите следующее содержимое в файл конфигурации:

{
  "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"
            }
          }
        }
      ]
    }
  }
}

Пояснение элементов конфигурации

Ниже по порядку поясняются основные поля, используемые в models.json:

Поле	Type	Обязательно?	Описание	Значение по умолчанию
baseUrl	string	Обязательный	Совместимая с OpenAI конечная точка API для DeepSeek	https://api.deepseek.com
api	string	Обязательный	Протокол интеграции; объявляет об использовании протокола, совместимого с OpenAI Completions	openai-completions
apiKey	string	Обязательный	Считывает ключ из переменной окружения с тем же именем; не нужно записывать ключ в открытом виде в файле конфигурации	$DEEPSEEK_API_KEY
contextWindow	число	Обязательный	Размер контекстного окна (tokens)	1000000
maxTokens	число	Обязательный	Максимальная длина вывода на запрос (tokens)	384000
рассуждение	логическое значение	Optional	Объявляет, что модель поддерживает возможность цепочки рассуждений (reasoning)	истина
стоимость	объект	Optional	Записывает удельные цены для входных/выходных данных/попаданий в кэш, используются интерфейсом Pi для оценки затрат	—
requiresReasoning ContentOnAssistantMessages	логическое значение	Рекомендуется	В многоходовых диалогах сообщения ассистента должны сохранять поле reasoning_content; иначе могут возникнуть проблемы совместимости	истина
thinkingFormat	string	Рекомендуется	Разбирает и отображает процесс рассуждения в соответствии со специфическим форматом содержимого мышления DeepSeek	deepseek
reasoningEffortMap	объект	Рекомендуется	Сопоставляет уровни усилий рассуждения Pi с уровнями, фактически поддерживаемыми DeepSeek	—

reasoningEffortMap сопоставляет пять уровней рассуждения Pi (minimal / low / medium / high / xhigh) с уровнями, поддерживаемыми DeepSeek. За исключением xhigh, отображаемого в max, все остальные сводятся к high.

Выбор модели

В конфигурации объявлены две модели DeepSeek. Основные различия следующие:

Модель	Контекстное окно	Максимальный вывод	Цена за единицу ввода	Цена за единицу вывода	Цена за единицу при попадании в кэш	Применимые сценарии
deepseek-v4-pro	1,000,000	384,000	1.74	3.48	0.145	Более сильные способности к рассуждению, подходит для сложных задач
deepseek-v4-flash	1,000,000	384,000	0.14	0.28	0.028	Более быстрый отклик, более низкая стоимость

Цены за единицу указаны в долларах США за миллион токенов.

Получение и установка API-ключа

Сначала получите API-ключ на открытой платформе DeepSeek:https://platform.deepseek.com/api_keys。

Для Linux / macOS экспортируйте переменную окружения в терминале:

export DEEPSEEK_API_KEY="你的 DeepSeek API Key"

Для Windows (PowerShell) задайте её следующим образом:

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

Рекомендуется прописать команду export в конфигурацию оболочки (например, ~/.bashrc, ~/.zshrc или профиль PowerShell), чтобы не задавать её заново при каждом открытии нового терминала.

Пожалуйста, замените "your DeepSeek API Key" в примере на ваш настоящий ключ. API-ключ — это конфиденциальная информация; храните его в безопасности и никогда не коммитьте в репозиторий.

Запуск и тестирование

После настройки вы можете запустить Pi и переключиться на модель DeepSeek.

Запуск Pi

Перейдите в каталог проекта:

cd ~/example-test/

Напрямую выполните команду pi:

pi

Переключение на модель DeepSeek

После входа в интерактивный интерфейс переключитесь, выполнив следующие шаги:

Введите/modelОткройте селектор модели.
Выберите провайдера deepseek, затем выберите DeepSeek-V4-Pro или DeepSeek-V4-Flash.
Затем запросите текущую модель.

После переключения вы можете сразу начать писать код в этом минималистичном терминальном фреймворке.

Предлагаемые шаги тестирования

Проверьте, завершена ли интеграция и пригодна ли она для использования, пройдя по приведённому ниже контрольному списку:

Пункт тестирования	Способ выполнения	Ожидаемый результат
Аутентификация и подключение	Отправьте предложение, например: «Здравствуйте, пожалуйста, расскажите о примерной обучающей платформе»	Получите обычный ответ без ошибок аутентификации 401 / 403, подтверждающий, что apiKey и baseUrl настроены правильно
Способность к рассуждению	Задайте вопрос, требующий многошагового рассуждения, например попросите сначала проанализировать, а затем предложить решение	Выведите видимый процесс мышления, указывающий на то, что thinkingFormat и reasoning активны
Многоходовые вызовы инструментов	Заставьте Pi непрерывно вызывать инструменты для чтения файлов, выполнения команд, изменения кода и проверки результатов	Многоходовой диалог остаётся стабильным без ошибок, вызванных отсутствием reasoning_content
Переключение Reasoning Effort	В /model переключитесь с medium на xhigh	Поведение соответствует сопоставлению reasoningEffortMap; xhigh соответствует значению max DeepSeek
Расчёт стоимости	После выполнения нескольких реальных задач проверьте статистику стоимости	Статистика интерфейса совпадает с ценами за единицу, заданными в поле cost

Среди них "Многоходовые вызовы инструментов" — ключевой сценарий для проверки того, правильно ли настроена конфигурация requiresReasoningContentOnAssistantMessages.

Общие советы по устранению неполадок

Если при интеграции возникнут проблемы, воспользуйтесь следующим контрольным списком, чтобы быстро их локализовать.

DeepSeek не отображается в селекторе моделей

Проверьте, правильный ли путь к models.json. Пути для Windows и Linux / macOS различаются.

Также убедитесь, что в формате JSON нет синтаксических ошибок, таких как висячие запятые или незакрытые кавычки.

Ошибка аутентификации

Убедитесь, что переменная окружения DEEPSEEK_API_KEY задана правильно.

Примечание: сеанс терминала, в котором вы запускаете команду pi, должен быть тем же сеансом, в котором вы задали переменную окружения.

Многоходовые вызовы инструментов сообщают об ошибках

Сначала проверьте, полностью ли настроены requiresReasoningContentOnAssistantMessages и thinkingFormat, как описано выше.

Нужны дополнительные возможности настройки

Вы можете обратиться кофициальной документации Pi по моделям, чтобы узнать о более полных параметрах конфигурации.

Другие расширения

Избранное в справочнике