Integración de Pi Agent con DeepSeek

DeepSeek ofrece una interfaz compatible con OpenAI, por lo que se puede reutilizar la capa de adaptación OpenAI existente de Pi, sin necesidad de desarrollar un adaptador específico para DeepSeek.

El trabajo principal de la integración solo consta de dos partes: declarar el proveedor y los parámetros del modelo en models.json, y proporcionar la API Key mediante variables de entorno.

La arquitectura general se muestra en la siguiente figura:

Pi 接入 DeepSeek 架构图

La llamada "interfaz compatible con OpenAI" significa que el protocolo de interfaz HTTP del proveedor es consistente con OpenAI. Siempre que el protocolo sea compatible, cualquier herramienta que soporte OpenAI puede llamarlo directamente, y DeepSeek pertenece a esta categoría.

Instalar Pi

Pi depende del entorno de ejecución Node.js. Antes de la instalación, asegúrate de que Node.js esté listo.

Instalar Node.js

Descarga el paquete de instalación correspondiente a tu sistema desde el sitio web oficial de Node.js e instálalo con las opciones predeterminadas.

Instalar Pi CLI

Instalación global a través de npm en la terminal:

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

Los usuarios de Linux y macOS también pueden usar el script de instalación oficial para una instalación con un solo clic:

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

Verificar la instalación

Ejecuta el siguiente comando. Si se imprime correctamente el número de versión, la instalación fue exitosa:

pi --version

La salida es similar a:

0.83.0

Configurar el proveedor DeepSeek

Pi define proveedores de modelos personalizados mediante models.json. En esta sección se integra DeepSeek a través de una interfaz compatible con OpenAI.

Ruta del archivo de configuración

La ruta de configuración varía según el sistema operativo. Consulta la correspondiente a tu sistema:

Sistema operativo	Ruta del archivo de configuración
Linux / macOS	~/.pi/agent/models.json
Windows	%USERPROFILE%\.pi\agent\models.json

Escribir models.json

Escribe el siguiente contenido en el archivo de configuración:

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

Explicación de los elementos de configuración

A continuación, se explican uno por uno los campos principales utilizados en models.json:

Campo	Tipo	¿Obligatorio?	Descripción	Valor predeterminado
baseUrl	string	Obligatorio	Dirección de la interfaz compatible con OpenAI de DeepSeek	https://api.deepseek.com
api	string	Obligatorio	Protocolo de conexión; declara el uso del protocolo compatible con OpenAI Completions	openai-completions
apiKey	string	Obligatorio	Lee la clave desde una variable de entorno del mismo nombre, sin necesidad de escribir la Key en texto plano en el archivo de configuración.	$DEEPSEEK_API_KEY
contextWindow	number	Obligatorio	Tamaño de la ventana de contexto (tokens)	1000000
maxTokens	number	Obligatorio	Longitud máxima de salida por solicitud (tokens)	384000
reasoning	boolean	Opcional	Declara que el modelo admite capacidad de cadena de pensamiento (razonamiento)	true
cost	object	Opcional	Registra los precios unitarios de entrada/salida/aciertos de caché, para que la interfaz de Pi estime los costos.	—
requiresReasoning ContentOnAssistantMessages	boolean	Recomendado	En conversaciones de múltiples turnos, el mensaje assistant debe conservar el campo reasoning_content; de lo contrario, pueden surgir problemas de compatibilidad.	true
thinkingFormat	string	Recomendado	Analiza y muestra el proceso de razonamiento según el formato de contenido de pensamiento específico de DeepSeek.	deepseek
reasoningEffortMap	object	Recomendado	Mapea los niveles de intensidad de razonamiento de Pi a los niveles realmente compatibles con DeepSeek.	—

reasoningEffortMap asigna los cinco niveles de razonamiento de Pi (minimal / low / medium / high / xhigh) a los niveles compatibles con DeepSeek. Excepto que xhigh se asigna a max, el resto se reduce a high.

Selección de modelos

La configuración declara dos modelos DeepSeek. Sus principales diferencias son las siguientes:

Modelo	Ventana de contexto	Salida máxima	Precio unitario de entrada	Precio unitario de salida	Precio unitario de aciertos de caché	Escenarios de uso
deepseek-v4-pro	1,000,000	384,000	1.74	3.48	0.145	Mayor capacidad de razonamiento, adecuado para tareas complejas
deepseek-v4-flash	1,000,000	384,000	0.14	0.28	0.028	Respuesta más rápida y menor costo

El precio unitario se expresa en dólares por cada millón de tokens.

Obtener y configurar la API Key

Primero solicita una API Key en la plataforma abierta de DeepSeek:https://platform.deepseek.com/api_keys。

En Linux / macOS, exporta la variable de entorno en la terminal:

export DEEPSEEK_API_KEY="你的 DeepSeek API Key"

En Windows (PowerShell), la forma de configurarlo es:

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

Se recomienda escribir el comando de exportación en la configuración del shell (por ejemplo, ~/.bashrc, ~/.zshrc o el perfil de PowerShell) para evitar tener que configurarlo cada vez que se abre una nueva terminal.

Reemplaza "tu API Key de DeepSeek" en el ejemplo con la clave real. La API Key es información sensible; guárdala de forma segura y nunca la subas a un repositorio de versiones.

Ejecución y pruebas

Una vez completada la configuración, puedes iniciar Pi y cambiar al modelo DeepSeek.

Iniciar Pi

Entra al directorio del proyecto:

cd ~/ejemplo-test/

Ejecuta directamente el comando pi:

pi

Cambiar al modelo DeepSeek

Al entrar en la interfaz interactiva, sigue estos pasos para cambiar:

Ingresa/modelAbre el selector de modelos.
Selecciona el proveedor deepseek y elige DeepSeek-V4-Pro o DeepSeek-V4-Flash.
A continuación, consulta el modelo actual.

Una vez completado el cambio, ya puedes empezar a programar directamente en este marco de terminal minimalista.

Pasos de prueba recomendados

Verifica uno por uno si la integración está completa y operativa según la siguiente lista:

Elemento de prueba	Método de operación	Resultado esperado
Autenticación y conectividad	Envía una frase, por ejemplo: "Hola, por favor presenta la plataforma de aprendizaje ejemplo".	Si se obtiene una respuesta normal sin errores de autenticación 401/403, significa que apiKey y baseUrl están configurados correctamente.
Capacidad de razonamiento	Haz una pregunta que requiera razonamiento de varios pasos, por ejemplo, pídele que primero analice y luego proponga una solución.	Si se muestra el proceso de pensamiento visible, indica que thinkingFormat y reasoning están activos.
Llamadas a herramientas de múltiples turnos	Haz que Pi llame herramientas consecutivamente para leer archivos, ejecutar comandos, modificar código y verificar resultados.	La conversación de múltiples turnos es estable y no se producen errores por la pérdida de reasoning_content.
Cambio de intensidad de razonamiento	En /model, cambia de medium a xhigh.	El comportamiento sigue el mapeo de reasoningEffortMap; xhigh corresponde a max en DeepSeek.
Cálculo de costos	Después de ejecutar varias tareas reales, revisa las estadísticas de gastos.	Las estadísticas de la interfaz coinciden con los precios unitarios configurados en el campo cost.

Entre ellos, "llamadas a herramientas de múltiples turnos" es el escenario clave para verificar si la configuración de requiresReasoningContentOnAssistantMessages es correcta.

Solución de problemas comunes

Si encuentras problemas durante la integración, puedes usar la siguiente lista para localizarlos rápidamente.

No se ve DeepSeek en el selector de modelos

Verifica que la ruta de models.json sea correcta; la ruta es diferente entre Windows y Linux/macOS.

También confirma que el formato JSON no tenga errores de sintaxis, como comas sobrantes o comillas sin cerrar.

Error de autenticación

Confirma que la variable de entorno DEEPSEEK_API_KEY esté configurada correctamente.

Nota: la sesión de terminal que ejecuta el comando pi debe ser la misma que configuró la variable de entorno.

Error en llamadas a herramientas de múltiples turnos

Primero verifica que requiresReasoningContentOnAssistantMessages y thinkingFormat estén completamente configurados como se indicó anteriormente.

Se necesita más capacidad de personalización

Puedes consultarla documentación oficial de modelos de Pipara conocer opciones de configuración más completas.

Otras extensiones

Favoritos de referencia