¿Cómo ejecutar cualquier modelo en DeepSeek Harness?

DeepSeek Harness (dsh) incluye los propios modelos de DeepSeek integrados, pero no estás limitado a ellos. El harness trata a los proveedores de modelos como configuración: apunta un bloque de proveedor a cualquier endpoint compatible con OpenAI, entrégale una referencia de credencial, y tus sesiones de agente se ejecutarán en el modelo que se encuentre detrás de esa URL. Una instancia local de Ollama, una puerta de enlace de la empresa, Qwen a través del modo compatible de DashScope, o los grandes proveedores de catálogo como Anthropic y OpenAI, todos se conectan al mismo bloque.

Esta guía recorre ese bloque clave por clave, luego construye tres recetas funcionales: un modelo local, un endpoint alojado compatible con OpenAI y los proveedores de catálogo integrados. Todo lo que se cita aquí proviene de la guía oficial de proveedores en la rama master, obtenida el 20 de agosto de 2026. Una advertencia de antemano: dsh es una vista previa para desarrolladores, y el README advierte en mayúsculas que habrá cambios que romperán la compatibilidad. Revisa la documentación con tu versión instalada antes de copiar cualquier cosa en producción.

Si eres nuevo en el harness, comienza con qué es DeepSeek Harness y cómo funciona, luego vuelve aquí para la configuración del proveedor.

Por qué intercambiar modelos en un harness de agente

Un harness de agente es un bucle: el modelo planifica, llama a herramientas, lee resultados y repite. El harness es dueño del bucle; el modelo es un ingrediente. Tres razones por las que cambiarías el ingrediente:

Costo. Las sesiones de agente queman tokens rápidamente porque cada resultado de herramienta se realimenta al contexto. Dirigir sesiones rutinarias a un modelo más barato, o a DeepSeek V4-Flash en lugar de V4-Pro, cambia tu factura sin cambiar tu flujo de trabajo. Puedes mantener un modelo frontera costoso configurado para las sesiones que lo necesiten.

Localidad de los datos. Algunas bases de código no pueden salir del edificio. Un bloque de proveedor que apunta a un modelo ejecutándose en tu propio hardware significa que los prompts, el contenido de los archivos y las salidas de las herramientas nunca cruzan la red. El mismo harness, la misma interfaz de usuario, cero egreso.

Desarrollo local. Cuando estás construyendo plugins o probando el comportamiento del agente, no quieres que cada iteración cueste créditos de API o dependa de tu red. Un pequeño modelo local responde lo suficientemente rápido como para probar el bucle, y vuelves a usar el modelo real cuando el comportamiento importa.

El diseño se deriva de la arquitectura de dsh: todo en el harness es un plugin, y el adaptador de modelo es una de las piezas reemplazables. Las rutas del proveedor son propiedad del plugin dsh-llm-pi-ai, que está documentado en el catálogo de configuración de plugins del repositorio como que contiene "rutas de proveedor que posee esta instancia". Esa es la maquinaria. La superficie para el usuario es un bloque YAML.

El bloque de proveedor, clave por clave

Los proveedores personalizados residen en $DSH_HOME/settings.yaml, y también puedes crearlos desde la interfaz de usuario web en Configuración → Modelos. Aquí está el ejemplo directamente de la documentación oficial:

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]

Qué hace cada clave:

• my-gateway es el ID del proveedor. Es un identificador permanente, así que elige un nombre con el que puedas vivir; el nombre de visualización que se muestra en la interfaz de usuario se configura por separado.
• apiKeyEnv nombra la variable de entorno que contiene tu clave API. El archivo de configuración nunca contiene el secreto en sí, solo esta referencia. Más abajo se detalla dónde reside la clave real.
• api declara el protocolo de comunicación. openai-completions es el valor documentado para los endpoints compatibles con OpenAI, lo que hace que la promesa de "cualquier modelo" funcione: la mayoría de las puertas de enlace, los tiempos de ejecución locales y los proveedores alojados hablan este protocolo.
• baseURL es la raíz del endpoint al que el harness envía las solicitudes.
• models enumera los IDs de los modelos disponibles a través de este proveedor. Cada entrada necesita al menos un id, que debe coincidir con lo que el endpoint espera en el cuerpo de la solicitud.
• input declara las modalidades por modelo. Los modelos personalizados por defecto solo admiten texto, por lo que un modelo de visión debe declarar explícitamente input: [text, image] o los archivos adjuntos de imagen no le llegarán. También existe un defaultInput a nivel de ruta que establece un valor predeterminado para cada modelo en el proveedor; un input a nivel de modelo lo anula.
• compat contiene interruptores de compatibilidad para endpoints que se desvían del comportamiento estándar de OpenAI. La documentación menciona dos: supportsDeveloperRole: false para backends que rechazan el rol developer, y maxTokensField: max_tokens para backends que desean el nombre de campo más antiguo para el límite de salida. Compat se puede configurar a nivel de ruta o por modelo.

Una comodidad que vale la pena conocer: cuando añades un proveedor personalizado a través de la interfaz de usuario web, una opción "Obtener modelos disponibles" consulta la ruta GET /models compatible con OpenAI del endpoint y rellena la lista de modelos por ti. Si tu endpoint implementa esa ruta, te saltas la escritura manual.

Dónde reside la clave API real

Los secretos se almacenan solo para escritura en $DSH_HOME/.credentials.yaml. Después de guardar una clave a través de la interfaz de usuario, dsh solo devuelve un descriptor redactado; el valor literal nunca se muestra de nuevo. settings.yaml contiene referencias (nombres de apiKeyEnv, descriptores de credenciales), nunca las claves en sí. Esa división significa que puedes confirmar o compartir un archivo de configuración sin filtrar nada, y rotar una clave sin tocar la configuración del proveedor.

Receta 1: ejecutar un modelo local a través de Ollama

Ollama expone una API compatible con OpenAI en http://localhost:11434/v1, lo cual Ollama documenta en su propia guía de compatibilidad con OpenAI. Dado que dsh habla openai-completions a cualquier URL base, la combinación es sencilla.

[VERIFICAR: la documentación de dsh no muestra un ejemplo específico de Ollama; esta receta aplica el esquema de proveedor personalizado documentado al endpoint compatible con OpenAI documentado de Ollama. Prueba en tu instalación antes de publicar internamente.]

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

Notas sobre este:

• Ollama no requiere una clave API localmente, pero el esquema espera una referencia de credencial, así que establece un valor ficticio: export OLLAMA_API_KEY=ollama. Ollama ignora lo que sea que envíes.
• El id del modelo debe coincidir con la etiqueta que sirve Ollama. Ejecuta ollama list y copia los nombres exactamente, incluyendo la etiqueta.
• Primero descarga el modelo (ollama pull gpt-oss:20b) y confirma que el servidor responde antes de conectarlo a dsh. Cubrimos la configuración local completa en cómo ejecutar GPT-OSS usando Ollama, y el mismo patrón funciona para otros modelos de código abierto como Kimi K3 si tu hardware lo permite.

Una rápida verificación de cordura te ahorra una sesión de agente confusa: accede a http://localhost:11434/v1/models en Apidog antes de tocar la configuración de dsh. Si esa solicitud devuelve tu lista de modelos, la URL base es correcta, el servidor está activo y "Obtener modelos disponibles" en la interfaz de usuario de dsh también funcionará. Si no es así, ninguna cantidad de configuración del harness lo solucionará.

Gestión de expectativas: los harnesses de agentes se apoyan mucho en la llamada a herramientas y en contextos largos. Los modelos locales pequeños manejan el bucle para las pruebas, pero planificarán peor y omitirán llamadas a herramientas con más frecuencia que los modelos frontera en los que se construyó el harness. Esto está bien para el desarrollo de plugins; es frustrante para el trabajo real.

Receta 2: un endpoint alojado compatible con OpenAI (Qwen a través de DashScope)

Para un ejemplo alojado, elige un proveedor que documente su compatibilidad con OpenAI en lugar de uno que asumas que la tiene. Alibaba Cloud Model Studio (DashScope) lo hace: su página de compatibilidad con OpenAI documenta un endpoint /compatible-mode/v1 para los modelos Qwen, con dominios regionales y específicos del espacio de trabajo (para Singapur: https://{WorkspaceId}.ap-southeast-1.maas.aliyuncs.com/compatible-mode/v1) y autenticación a través de la variable de entorno DASHSCOPE_API_KEY.

Mapeado al esquema dsh:

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

Reemplaza {WorkspaceId} con tu dominio de espacio de trabajo real de la consola de Model Studio, y consulta la lista de modelos del proveedor para obtener los IDs actuales; mantenemos un resumen del nivel insignia en nuestra guía de API Qwen 3.8. El mismo patrón se extiende a cualquier proveedor con compatibilidad OpenAI documentada: la API Kimi de Moonshot, OpenRouter, un despliegue de vLLM o la puerta de enlace interna de tu empresa. Las únicas partes que cambian son baseURL, el nombre de la variable de entorno y los IDs de los modelos. Si has configurado modelos de código abierto en Codex, esto te resultará familiar; el bloque YAML de dsh desempeña el mismo papel que la configuración model_providers de Codex.

Dos especificidades de los endpoints alojados:

• Si el endpoint del proveedor rechaza las solicitudes con errores extraños sobre roles o campos de tokens, para eso existen los interruptores compat. Prueba primero supportsDeveloperRole: false; las implementaciones más antiguas compatibles con OpenAI son anteriores al rol developer.
• Los modelos de visión deben declarar input: [text, image] explícitamente, incluso si el modelo alojado soporta imágenes. dsh asume solo texto para modelos personalizados a menos que se le indique lo contrario.

Receta 3: los proveedores de catálogo integrados

No necesitas un bloque personalizado para las nubes principales. dsh incluye proveedores de catálogo para DeepSeek, Anthropic y OpenAI, donde la configuración es principalmente "pegar una clave API". Las entradas de catálogo especializadas tienen sus propios flujos de autenticación nativos: Bedrock usa credenciales de AWS, Vertex quiere un proyecto ADC, Azure necesita su api-version y Codex se autentica a través de OAuth.

Los proveedores de catálogo son el camino de menor fricción cuando simplemente quieres Claude o GPT detrás del harness, y son la forma en que la mayoría de la gente ejecutará DeepSeek V4-Pro, cuyo lanzamiento de API en agosto de 2026 llegó junto con el propio harness (detalles en api-docs.deepseek.com). Los proveedores personalizados son para todo lo que el catálogo no cubre: tiempos de ejecución locales, puertas de enlace, proveedores regionales y agregadores compatibles con OpenAI.

Selección del modelo y lo que las sesiones recuerdan

Agregar un proveedor hace que sus modelos estén disponibles; seleccionar un modelo en Configuración → Modelos lo convierte en el predeterminado para las nuevas sesiones. Dos comportamientos de la documentación que vale la pena internalizar:

1. Las sesiones existentes mantienen el modelo con el que se iniciaron. Las sesiones registran su modelo original, por lo que cambiar el predeterminado a mitad del proyecto no reescribe silenciosamente el historial ni cambia lo que usa una sesión en curso.
2. Si eliminas el proveedor que posee el valor predeterminado actual, el compositor bloquea la entrada hasta que elijas un nuevo modelo. El harness falla ruidosamente en lugar de adivinar.

Esa fijación de sesión es importante para la reproducibilidad: cuando comparas dsh con otros harnesses (hicimos exactamente eso en DeepSeek Harness vs Claude Code), puedes confiar en que la transcripción de una sesión refleja un solo modelo, no un cambio a mitad de ejecución.

Resolución de los fallos habituales

URL base incorrecta o inaccesible. El fallo más común es el menos exótico. Confirma que la URL termina donde el protocolo espera (normalmente /v1 para endpoints compatibles con OpenAI, /compatible-mode/v1 para DashScope) y que un simple GET {baseURL}/models se realiza correctamente fuera del harness. Este es el punto de control donde Descargar Apidog se amortiza en cinco minutos: envía la solicitud con el mismo encabezado (Authorization: Bearer $KEY) que enviará el harness, y lee el código de estado y el cuerpo reales en lugar de un error de harness envuelto. Si estás desarrollando sin conexión o el proveedor es inestable, simula las respuestas /models y /chat/completions del proveedor en Apidog y apunta baseURL al simulacro mientras construyes.

Variable de entorno ausente o vacía. apiKeyEnv nombra una variable; no la crea. Si la variable no está configurada en el entorno en el que realmente se ejecuta dsh, las solicitudes saldrán sin autenticar y devolverán 401. Recuerda que un proceso lanzado desde una interfaz gráfica de usuario o un gestor de servicios puede no heredar tu perfil de shell. Haz echo $GATEWAY_API_KEY en el mismo contexto que lanza dsh web, no solo en una terminal cualquiera.

Discrepancia en la modalidad de entrada. Adjuntas una imagen, y el modelo nunca la ve, o la solicitud arroja un error. Los modelos personalizados son solo de texto por defecto. Agrega input: [text, image] en la entrada del modelo, o establece defaultInput a nivel de ruta si cada modelo en el proveedor maneja imágenes.

Peculiaridades del protocolo. Los errores que mencionan un rol no soportado o un parámetro de token rechazado apuntan a los interruptores de compatibilidad: supportsDeveloperRole: false y maxTokensField: max_tokens son los dos documentados.

Todo funcionó ayer. Versión preliminar para desarrolladores. Fija la versión que despliegas, lee las notas de la versión antes de actualizar y espera que el esquema de configuración cambie. El repositorio deepseek-harness es la fuente de verdad, no cualquier entrada de blog, incluida esta.

Una nota de integración más: los proveedores de modelos son solo la mitad de la historia de personalización. La otra mitad son las herramientas que el agente puede llamar, y puedes conectar tus flujos de trabajo de API directamente; cubrimos eso en uso de Apidog CLI dentro de DeepSeek Harness.

Preguntas Frecuentes

¿DeepSeek Harness es compatible oficialmente con Ollama?

El documento oficial de proveedores no menciona a Ollama por su nombre. Lo que sí soporta es cualquier endpoint que hable el protocolo openai-completions, y Ollama documenta una API compatible con OpenAI en http://localhost:11434/v1. La receta anterior combina las dos mitades documentadas; pruébala en tu instalación, ya que dsh es una vista previa para desarrolladores y los esquemas pueden cambiar entre versiones.

¿Dónde guarda dsh mis claves API?

En $DSH_HOME/.credentials.yaml, solo para escritura. La interfaz de usuario muestra un descriptor redactado después de guardar, y settings.yaml solo contiene referencias como nombres de apiKeyEnv. Nunca terminas con una clave en texto plano dentro de la configuración de tu proveedor.

¿Puedo ejecutar diferentes modelos para diferentes sesiones?

Sí. Seleccionar un modelo solo establece el valor predeterminado para las nuevas sesiones; cada sesión existente conserva el modelo con el que comenzó. Así, puedes ejecutar un modelo económico como DeepSeek V4-Flash para sesiones rutinarias, cambiar el valor predeterminado a un modelo más pesado para un problema difícil, y tus sesiones anteriores permanecerán intactas.

Mi endpoint personalizado devuelve errores que la misma solicitud no produce en curl. ¿Ahora qué?

Compara las cargas útiles exactas. El harness puede enviar un rol developer o un campo de límite de token más nuevo que tu backend no acepte; las soluciones documentadas son supportsDeveloperRole: false y maxTokensField: max_tokens bajo compat. Reproducir la solicitud con formato de harness en un cliente API te muestra qué campo ahoga al backend.