¿Cómo integrar DeepSeek Harness con API de múltiples modelos? Configuración y lógica de uso de los 4 protocolos de pasarelas como APIYI

¿Cómo integrar DeepSeek Harness con API de múltiples modelos? Configuración y lógica de uso de los 4 protocolos de pasarelas como APIYI

Resumen: DeepSeek Harness puede conectarse a gateways como APIYI mediante la «API de modelo personalizado». Para cada protocolo, el desarrollador configura un proveedor independiente, introduce el ID de modelo que el gateway realmente admite y, si la tarea lo requiere, integra además herramientas de búsqueda en línea.

DeepSeek Harness permite añadir gateways de API de terceros como proveedores de modelos personalizados. Hay cuatro protocolos disponibles: OpenAI Chat Completions, OpenAI Responses, Anthropic Messages y Gemini API. Por eso, una instancia de Harness puede invocar modelos de distintos fabricantes al mismo tiempo a través de gateways unificados como APIYI (apiyi.com). Que la integración funcione depende de cuatro puntos: que el protocolo y la Base URL coincidan, que el ID del modelo se corresponda con el que admite el gateway, que los parámetros de inferencia y salida sean compatibles y que las herramientas de búsqueda en línea se planifiquen por separado.

En las secciones siguientes se explica primero cómo Harness adapta los modelos y qué papel ocupa el gateway dentro de ese mecanismo. Después, se recorre la interfaz de configuración paso a paso para completar una configuración de proveedor personalizado y se incluye una plantilla de archivo de configuración para APIYI. A continuación, se repasan los problemas de compatibilidad y los códigos de error más frecuentes cuando el endpoint conecta pero las invocaciones fallan. Luego se distinguen dos rutas de acceso a internet: la búsqueda integrada en el servidor de DeepSeek y las herramientas Search / Fetch independientes de APIYI. Por último, se proponen ideas de diseño por capas y de despliegue para agentes multimodelo.

deepseek-harness-multi-model-api-gateway-config-es-image-0

Table of Contents

Para saber: terminología de integración multimodelo de DeepSeek Harness

Término Explicación
Harness Marco de ejecución de los agentes; se encarga de la integración de modelos, las llamadas a herramientas, el contexto, las sesiones y el bucle de ejecución de tareas
API Gateway Puerta de enlace que centraliza el reenvío y la gestión de solicitudes a las API de varios modelos, ofreciendo un único punto de entrada
Base URL Dirección base de las solicitudes a la API; según el protocolo, el prefijo de ruta de la dirección cambia
Provider Proveedor de servicios de modelos configurado en Harness, que corresponde a un conjunto de dirección, protocolo y clave
Model ID Identificador del modelo especificado en la solicitud; debe coincidir con el nombre que realmente ofrece la puerta de enlace
Chat Completions Interfaz de finalización de chat al estilo OpenAI, el protocolo más habitual en las puertas de enlace compatibles
Responses API Interfaz de respuestas estructuradas de OpenAI, orientada a llamadas a herramientas e interacción multiturno
Anthropic Messages Interfaz de mensajes al estilo Anthropic, protocolo nativo de los modelos de la familia Claude
Reasoning Effort Parámetro del nivel de razonamiento del modelo, como off, low, medium, high o max
Tool Calling Capacidad del modelo o del agente para decidir invocar herramientas externas y usar sus resultados en el razonamiento posterior
Search / Fetch Search se encarga de la búsqueda web y devuelve una lista de resultados; Fetch se encarga de recuperar el cuerpo de una página web concreta
API Key Credencial de autenticación que determina a qué modelos e interfaces puede acceder una solicitud

1 Por qué DeepSeek Harness encaja bien en la integración multimodelo mediante API

1.1 El mecanismo de proveedores de modelos de DeepSeek Harness

DeepSeek Harness se publicó como código abierto el 13 de agosto de 2026 en versión de vista previa para desarrolladores, bajo licencia MIT, y su arquitectura central se resume en una idea: «Everything is a Plugin». Los adaptadores de modelos, las herramientas, las Skills, el almacenamiento y la gestión de sesiones son plugins sustituibles, así que la conexión de modelos pasa a ser un elemento de configuración abierto en lugar de un vínculo al fabricante incrustado en el producto.

En la capa de modelos, Harness permite añadir varios proveedores e ir cambiando de modelo dentro de una misma sesión. Cada proveedor admite configurar API Key, Base URL, nombre del modelo, protocolo de API, longitud del contexto, máximo de tokens de salida, capacidad de entrada de imágenes y nivel de razonamiento. Tanto los sitios proxy como las pasarelas internas de empresa y los servicios de modelos autoalojados pueden conectarse como proveedores independientes.

Conviene tener en cuenta que Harness sigue en fase de vista previa para desarrolladores y que el equipo oficial advierte de posibles cambios incompatibles en versiones futuras. Antes de usarlo en producción, se recomienda fijar la versión y hacer copia de seguridad de la configuración.

1.2 El papel de la pasarela API dentro de DeepSeek Harness

Para Harness, una pasarela es simplemente un Provider. Cuatro campos determinan el destino de una petición: la Base URL apunta a la dirección de la pasarela, el protocolo define el formato de la petición y de la respuesta, la API Key acredita la identidad de quien llama y el Model ID indica a la pasarela a qué modelo debe reenviar la petición.

Poniendo el caso de APIYI apiyi.com: la plataforma ofrece con una sola API Key modelos de OpenAI, Claude, Gemini, DeepSeek y otros, y expone tres puntos de entrada de protocolo: compatible con OpenAI, nativo de Anthropic y Gemini. En Harness basta crear el proveedor correspondiente según el protocolo, y cambiar de modelo se reduce a modificar el Model ID, sin necesidad de abrir una cuenta y mantener una clave por cada fabricante.

deepseek-harness-multi-model-api-gateway-config-es-image-1


2 Configurar un proveedor de modelos personalizado en DeepSeek Harness desde cero

2.1 Abrir la interfaz de configuración de modelos de DeepSeek Harness

La forma más rápida de iniciar Harness en local es con el comando oficial de npm, aunque antes necesitas tener Node.js instalado:

npx @deepseek-ai/dsh web
# Abre por defecto la interfaz web local: http://127.0.0.1:3080

Una vez dentro de la interfaz, haz clic en Configuración → Modelos → Añadir proveedor de modelos → API de modelo personalizado y verás el formulario de configuración del proveedor. La versión de escritorio oficial ofrece instaladores para macOS Apple Silicon y Windows de 64 bits; la ruta de configuración es la misma.

2.2 Completar la información del proveedor DeepSeek Harness

Campo de configuración Función Qué tener en cuenta al rellenar
Provider ID Identificador único del proveedor Debe ir en minúsculas y no se puede renombrar después de crearlo, por ejemplo apiyi
Nombre para mostrar Nombre que aparece en el menú de modelos Puede ser algo como «APIYI compatible con OpenAI»
Protocolo de API Formato de las peticiones y respuestas Debe corresponder al Base URL, ver 2.3
Base URL Dirección del servicio de API Ojo con el prefijo de versión, ver 2.4
API Key Credencial de autenticación Se guarda en el archivo de credenciales; la interfaz solo muestra una vista parcial enmascarada
Model ID Nombre real del modelo que se invoca Debe coincidir exactamente con la lista de modelos del gateway
Context Window / Max Output Tokens Longitud del contexto y de la salida máxima Rellénelos según las especificaciones reales del modelo
Input Type Entrada de texto o de imágenes Marque la opción de imágenes solo para modelos visuales
Reasoning Effort Nivel de razonamiento y mapeo de parámetros Añada únicamente los niveles que el modelo realmente admite

El Provider ID no se puede renombrar porque la configuración de los modelos, el historial de conversaciones y las referencias a credenciales apuntan todos a ese ID. Si necesitas cambiarlo, primero crea un proveedor nuevo y luego elimina el antiguo.

El botón «Obtener modelos disponibles» del formulario intenta leer la lista de modelos desde el gateway. Si el gateway no ofrece una lista de modelos estándar, o si el formato devuelto no entra dentro de lo que Harness reconoce, basta con añadir el Model ID manualmente: el resultado es el mismo.

2.3 Elegir el protocolo de API de DeepSeek Harness

La API de modelos personalizados de Harness admite cuatro protocolos: OpenAI Chat Completions, OpenAI Responses, Anthropic Messages y Gemini API. Un proveedor solo puede vincularse a un protocolo; si una misma pasarela expone entradas para los tres protocolos, será necesario crear tres proveedores.

La elección del protocolo va de la mano con la familia del modelo. Para GPT, DeepSeek y la mayoría de los modelos nacionales, lo más seguro es usar OpenAI Chat Completions; en la serie Claude se puede optar por Anthropic Messages para conservar las características nativas; y la serie Gemini utiliza Gemini API. El protocolo Responses resulta adecuado para escenarios que requieren respuestas estructuradas y llamadas a herramientas, siempre que tanto la pasarela como el modelo de destino soporten esa interfaz.

2.4 Configurar una instancia de DeepSeek Harness con APIYI

La correspondencia oficial entre protocolos y Base URL que ofrece APIYI es la siguiente:

Protocolo Base URL de APIYI Modelos compatibles Plataformas disponibles
Compatible con OpenAI (Chat Completions) https://api.apiyi.com/v1 GPT, DeepSeek, etc. APIYI apiyi.com, API oficial de cada fabricante
Anthropic nativo https://api.apiyi.com Serie Claude APIYI, Anthropic oficial
Gemini https://api.apiyi.com/v1beta Serie Gemini APIYI, Google oficial

El protocolo Anthropic utiliza el dominio raíz, y el adaptador añade por su cuenta las rutas posteriores. Si se escribe un /v1 adicional después del dominio raíz, pueden producirse rutas duplicadas y devolver un 404. Para la integración del protocolo Responses, conviene consultar la documentación de la API Responses de APIYI antes de rellenar los datos.

Además de la configuración desde la interfaz, Harness también permite editar manualmente el archivo de configuración, ubicado en $DSH_HOME/profiles/web/cordis.patch.yml. A continuación se muestra una plantilla de proveedor compatible con OpenAI de APIYI, elaborada según la estructura de configuración oficial:

- id: llm-pi-ai
  config:
    providers:
      apiyi:
        apiKeyEnv: APIYI_API_KEY          # Lee la clave desde la variable de entorno
        api: openai-completions           # Protocolo OpenAI Chat Completions
        baseURL: https://api.apiyi.com/v1 # Punto de entrada compatible con OpenAI de APIYI
        models:
          - id: MODEL_ID_FROM_APIYI       # Sustituir por el ID de modelo realmente disponible en la cuenta

Los pasos de uso son los siguientes:

  1. Definir la variable de entorno APIYI_API_KEY;
  2. Sustituir MODEL_ID_FROM_APIYI por el nombre del modelo realmente disponible en la consola de APIYI;
  3. Guardar la configuración y seleccionar en el selector de modelos de Harness el proveedor apiyi y el modelo correspondiente;
  4. Iniciar una conversación sencilla para confirmar que la interfaz funciona correctamente.

Esta plantilla muestra la estructura de configuración oficial; los nombres de modelo deben ajustarse a la lista de los que realmente se pueden invocar desde la propia cuenta. Los cambios en la configuración de modelos suelen surtir efecto en la siguiente solicitud, sin necesidad de reiniciar la interfaz web. La configuración desde la interfaz resulta adecuada para añadir modelos y modificar claves en el día a día; el archivo de configuración lo es para ajustar parámetros avanzados como la compatibilidad, el modo de razonamiento, los tiempos de espera y los reintentos.

Antes de integrar Harness, se recomienda verificar por separado la Key y el Model ID con un script, de modo que los dos problemas —»la pasarela funciona» y «la configuración de Harness es correcta»— se investiguen de forma independiente:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["APIYI_API_KEY"],
    base_url="https://api.apiyi.com/v1"  # Punto de entrada compatible con OpenAI de APIYI apiyi.com
)

resp = client.chat.completions.create(
    model="MODEL_ID_FROM_APIYI",  # Debe coincidir con el Model ID introducido en Harness
    messages=[{"role": "user", "content": "用一句话介绍你自己"}],
    max_tokens=100
)
print(resp.choices[0].message.content)

🚀 Consejo para empezar rápido: los nuevos usuarios pueden registrarse en APIYI apiyi.com y obtener crédito de prueba gratuito; primero conviene confirmar con el script anterior que el ID de modelo está disponible y después escribirlo en la configuración de Harness. Así el tiempo total de resolución de problemas se reduce bastante.


3 La interfaz de DeepSeek Harness conecta, pero ¿por qué la invocación del modelo sigue fallando?

La documentación oficial de Harness lo deja claro: aunque la dirección de la API y la clave API sean correctas, la pasarela puede seguir rechazando la solicitud. El motivo es que las distintas interfaces compatibles tienen requisitos diferentes en cuanto a los roles de los mensajes, la longitud de salida y los parámetros de razonamiento. Los tres parámetros compat que se describen a continuación sirven para resolver este tipo de problemas y conviene habilitarlos según los errores que devuelva realmente la interfaz.

3.1 Compatibilidad con el rol Developer

La nueva especificación de OpenAI introdujo role: developer, pero algunas pasarelas compatibles solo reconocen system. Si te encuentras con casos en los que «todas las solicitudes fallan» o «solo fallan los modelos de razonamiento», puedes desactivar el rol developer:

compat:
  supportsDeveloperRole: false

Al activar esta opción, el adaptador ajusta la forma en que se gestionan los roles en las solicitudes, de modo que estas se ajusten al formato que la pasarela puede aceptar.

3.2 Compatibilidad del parámetro de salida máxima

La nueva interfaz de OpenAI usa max_completion_tokens para indicar la salida máxima, mientras que algunas pasarelas solo aceptan el tradicional max_tokens. Ambos significan lo mismo, pero si el nombre del campo no coincide, la validación de parámetros falla. La configuración correspondiente es:

compat:
  maxTokensField: max_tokens

3.3 Compatibilidad con el modo de razonamiento de DeepSeek

Algunos modelos DeepSeek tienen el razonamiento activado por defecto. Cuando en Harness se pone el nivel de razonamiento en off, algunos protocolos compatibles simplemente omiten los parámetros de razonamiento, y el modelo sigue pensando según su comportamiento por defecto, lo que hace que «off» no se pueda apagar de verdad. Por eso, oficialmente se ofrece un formato de pensamiento específico para DeepSeek:

compat:
  thinkingFormat: deepseek

Una vez activado, al desactivar el razonamiento el adaptador envía explícitamente {"thinking": {"type": "disabled"}}, y al activarlo envía {"thinking": {"type": "enabled"}}. El ejemplo oficial está pensado para el modelo DeepSeek V4 detrás de una pasarela compatible con OpenAI. En una pasarela multimodelo, este parámetro se puede configurar solo para el modelo DeepSeek, mientras que GPT, Claude y otros modelos mantienen el valor por defecto.

En cuanto al nivel de razonamiento, Harness permite mapear los valores off, low, medium, high, max de la interfaz a los valores que la API realmente acepta. Incluir en la configuración solo los niveles que el modelo realmente soporta evita errores en las peticiones cuando el usuario selecciona un nivel no válido. A continuación, un ejemplo completo que combina los tres parámetros de compatibilidad:

- id: llm-pi-ai
  config:
    providers:
      apiyi:
        apiKeyEnv: APIYI_API_KEY
        api: openai-completions
        baseURL: https://api.apiyi.com/v1
        compat:
          supportsDeveloperRole: false
          maxTokensField: max_tokens
        models:
          - id: MODEL_ID_FROM_APIYI

3.4 Solución rápida de errores comunes de DeepSeek Harness

Error o síntoma Posible causa Cómo resolverlo
MISSING_CREDENTIAL Clave no configurada Revisa la API Key y el nombre de la variable de entorno
UNKNOWN_MODEL ID del modelo no registrado Agrega el ID de modelo correcto dentro del proveedor
HTTP 401 Clave inválida o permisos insuficientes Verifica el contenido de la clave y el grupo al que pertenece
HTTP 404 Ruta del Base URL incorrecta Confirma el protocolo y el prefijo de versión (/v1, dominio raíz, /v1beta)
Lista de modelos vacía La pasarela no soporta la interfaz estándar de listado de modelos Agrega el ID del modelo manualmente
Todas las solicitudes fallan Conflicto de roles o formato de parámetros Revisa los parámetros de compatibilidad compat
Solo fallan los modelos de razonamiento El rol Developer no es compatible Configura supportsDeveloperRole: false
off no logra desactivar el pensamiento El modelo activa el pensamiento por defecto Configura thinkingFormat: deepseek
La interfaz de búsqueda devuelve 503 El grupo del token no tiene permisos de herramientas Cambia a un token del grupo default o svip
El chat funciona pero la conexión a internet no La herramienta de búsqueda no está integrada o el protocolo no es compatible Revisa las capacidades de la herramienta y la configuración del cliente

Las primeras ocho filas se basan en la documentación oficial de configuración de Harness, mientras que los problemas relacionados con grupos provienen de la documentación oficial de APIYI. Te sugerimos seguir este orden de arriba hacia abajo: primero confirma las credenciales, luego el ID del modelo, después la ruta y, por último, la compatibilidad de parámetros.


4 Añadir capacidad de búsqueda en línea al Harness de DeepSeek

4.1 Distinguir entre búsqueda integrada del modelo y API de búsqueda independiente

Que una conversación normal se ejecute correctamente solo demuestra que la clave API funciona, que el ID del modelo es el correcto y que el protocolo de chat es básicamente compatible. La capacidad de conexión a internet requiere además que el modelo soporte la herramienta correspondiente, que la solicitud declare correctamente la herramienta, que el servicio API soporte ese protocolo de herramientas, que el Harness pueda procesar la respuesta de la herramienta, o que el desarrollador integre la búsqueda por separado en la capa de aplicación. Por eso, que el chat funcione y que la conexión a internet funcione son dos pasos de verificación independientes.

Dentro del ecosistema DeepSeek, la capacidad de conexión a internet tiene dos rutas técnicas:

deepseek-harness-multi-model-api-gateway-config-es-image-2

Dimensión Ruta A: herramientas del servidor integradas al modelo Ruta B: API independiente de Search / Fetch
Forma de invocación Declarar deepseek_web_search y deepseek_read_url en la solicitud de chat El programa solicita activamente /v1/tools/search y /v1/tools/fetch
Quién decide buscar El modelo decide por sí mismo La lógica de herramientas del desarrollador o del Agent
Ejecución de la herramienta El servidor de DeepSeek realiza la búsqueda y la concatenación de contexto El cliente procesa el resultado por su cuenta tras recibirlo
Alcance de modelos El anuncio oficial apunta explícitamente a deepseek-flash Es independiente del modelo, cualquier modelo puede reutilizar los resultados
Criterio de facturación Se cobra según el número real de términos de búsqueda, páginas web rastreadas, etc. Se cobra por número de solicitudes exitosas, sin consumir tokens del modelo
Canales disponibles actualmente API oficial de DeepSeek API oficial de DeepSeek, APIYI

4.2 Cómo funciona la búsqueda integrada del modelo

El 13 de noviembre de 2026, DeepSeek abrió varias capacidades de aplicación que respaldan la app, entre ellas la búsqueda web y la lectura de enlaces, que se ofrecen como herramientas del lado del servidor. Basta declararlas en la lista de herramientas de la solicitud:

[
  {"type": "deepseek_web_search", "name": "deepseek_web_search"},
  {"type": "deepseek_read_url", "name": "deepseek_read_url"}
]

Una vez declaradas, el modelo decide por sí mismo si necesita conectarse a internet y genera los términos de búsqueda; el servidor de DeepSeek ejecuta la búsqueda y devuelve una respuesta con citas de fuentes. Al activar el modo de pensamiento, la búsqueda pasa a un flujo de varios pasos: el modelo puede buscar varias palabras clave, abrir páginas web, buscar dentro de la página y verificar de forma cruzada. La documentación oficial indica que responde tras un máximo de aproximadamente 20 llamadas a herramientas. deepseek_read_url solo reconoce las URL del último mensaje del usuario y considera como máximo 10 enlaces distintos.

Los desarrolladores todavía deben gestionar los bloques de contenido devueltos, la información de citas, los eventos de streaming y el historial de varios turnos. Según el anuncio oficial, esta integración completa de herramientas a nivel de conversación corre a cargo de deepseek-flash (DeepSeek-V4.1-Flash). De acuerdo con la documentación de APIYI, el trabajo de compatibilidad para llamar a este tipo de búsqueda integrada a través de la pasarela desde clientes como Harness o Claude Code sigue en planificación para etapas posteriores; por ahora, para usar la ruta A, hay que conectarse directamente a la API oficial de DeepSeek.

4.3 Integración independiente de Search / Fetch de APIYI

APIYI lanzó el 21 de octubre de 2026 las interfaces de herramientas independientes DeepSeek Search & Fetch, correspondientes a deepseek-search y deepseek-fetch. Search devuelve resultados de búsqueda estructurados, y Fetch recupera una página web concreta y devuelve el cuerpo en Markdown. Las solicitudes no requieren pasar un ID de modelo ni consumen tokens del modelo, y se facturan por número de llamadas exitosas.

El siguiente ejemplo primero busca y después recupera la página web que ocupa el primer puesto:

import os
import requests

BASE = "https://api.apiyi.com/v1/tools"  # Interfaz de herramientas independientes de APIYI
headers = {"Authorization": f"Bearer {os.environ['APIYI_API_KEY']}"}

search = requests.post(
    f"{BASE}/search",
    headers=headers,
    json={"query": "DeepSeek Harness 插件", "count": 5},
    timeout=60,
)
search.raise_for_status()
results = search.json()["results"]

if results:
    url = results[0]["url"]
    fetch = requests.post(
        f"{BASE}/fetch",
        headers=headers,
        json={"url": url},
        timeout=60,
    )
    if fetch.ok:
        print(fetch.json()["content"])

Hay que prestar especial atención a los grupos de tokens: los grupos default y svip pueden llamar a estas dos interfaces, mientras que los tokens del grupo ClaudeCode no pueden hacerlo directamente, y la documentación registra casos en los que devolvió 503. Las pruebas internas de la documentación de APIYI muestran que Search devuelve 5 resultados en aproximadamente 1.8 segundos y que 20 solicitudes concurrentes devolvieron todas 200; cuando Fetch accede a una página inaccesible, devuelve un fallo y no se cobra. Estos datos provienen de las pruebas de la propia plataforma, y el rendimiento real depende de la red y del sitio de destino. En cuanto al precio, la documentación indica un precio interno de $0.90 por cada 1000 llamadas, y con la bonificación por recarga el pago efectivo resulta aún menor; consulta la consola para el dato exacto.

Para que el Agent de Harness utilice esta lógica de forma autónoma, es necesario encapsularla como un plugin de herramientas. Los plugins de Harness se escriben en TypeScript y registran herramientas a través del objeto de contexto ctx; cuando se desinstala el plugin, el framework elimina automáticamente las herramientas y los eventos registrados. Al encapsular, se recomienda registrar search y fetch como dos herramientas independientes, de modo que el modelo primero obtenga la lista de resultados y luego decida qué páginas recuperar.

💡 Consejo técnico: Search / Fetch independientes están desacoplados del modelo, por lo que un mismo conjunto de resultados de búsqueda puede entregarse a distintos modelos como GPT, Claude o DeepSeek para su procesamiento. Mediante APIYI apiyi.com puedes gestionar con una sola clave API tanto la invocación del modelo como la herramienta de búsqueda, lo que facilita comparar en Harness la calidad de las respuestas de distintos modelos basadas en la misma información.


5 Cómo diseñar un Agent multimodelo con DeepSeek Harness

5.1 Elegir distintos modelos según la tarea

El valor de conectar varios modelos está en asignar el modelo adecuado a cada tarea. Un Agent de programación puede usar un modelo que domine el código; las tareas de alta frecuencia como organizar documentación, resumir o reescribir encajan mejor con modelos de menor coste; y para analizar capturas de pantalla o entender gráficos hay que escoger sí o sí un modelo visual que admita entrada de imágenes, marcando la casilla de imagen en Input Type.

Tomemos como ejemplo los modelos oficiales de DeepSeek: DeepSeek-V4.1-Flash admite comprensión de imágenes y DeepSeek-V4-Pro no, y sus precios también difieren varias veces. Si en Harness los configuras como dos Model ID dentro de un mismo provider y vas cambiando según la tarea dentro de la sesión, consigues equilibrar resultados y coste.

5.2 Gestionar por capas la invocación de modelos de DeepSeek Harness y las capacidades de búsqueda

deepseek-harness-multi-model-api-gateway-config-es-image-3

La estructura recomendada se divide en tres capas. La capa de ejecución corre a cargo de Harness: bucle de tareas, compresión de contexto, carga de plugins y control de permisos. La capa de modelos la asume el gateway de API: conversión de protocolos, enrutado de modelos y facturación. La capa de herramientas la aportan interfaces independientes como Search / Fetch para obtener información externa. Las tres capas son sustituibles por separado: cambiar de modelo implica solo modificar el Model ID, cambiar de servicio de búsqueda implica solo cambiar el plugin de herramientas, y la lógica de ejecución queda intacta.

La separación por capas también aporta ventajas de seguridad. Una evaluación controlada del laboratorio Zhuque de Tencent sobre Harness mostró que contenidos no confiables —páginas web, archivos, Skills, etc.— pueden influir en el comportamiento del Agent mediante inyección indirecta de indicaciones. Al separar la capa de herramientas de la capa de ejecución, se puede añadir un filtro y una confirmación unificados antes de que los resultados de búsqueda entren en el contexto y antes de que se ejecuten herramientas sensibles.

5.3 Recomendaciones prácticas para desplegar DeepSeek Harness

  1. Configuración de modelos: un protocolo corresponde a un provider; el Provider ID en minúsculas y definido de una vez por todas; los model ID se copian siempre desde la consola del gateway.
  2. Gestión de claves: Harness guarda las claves en $DSH_HOME/.credentials.yaml; el archivo de configuración solo referencia variables de entorno, para evitar que una Key en texto plano acabe en configuraciones compartidas o en repositorios de código.
  3. Pruebas de compatibilidad: cada vez que integres un modelo nuevo, verifica en orden conversación normal, desactivar el pensamiento, salidas largas y entrada de imágenes; después, según el error, activa el parámetro compat.
  4. Invocación de herramientas: controla el número de plugins. La comunidad reporta que, tras instalar más de una decena de plugins, pueden aparecer desbordamientos de contexto y un aumento del consumo de tokens; mantener descripciones escuetas en las herramientas de búsqueda resulta más estable.
  5. Registro de costes: los tokens del modelo y las llamadas a herramientas se facturan por separado, así que conviene contabilizarlos por separado en el panel del gateway. La consola de APIYI apiyi.com permite consultar el uso por Key, lo que va bien para asignar Keys independientes a cada Agent y imputar costes.

Además, antes de actualizar Harness, haz copia de seguridad de la configuración bajo $DSH_HOME. La comunidad documentó un caso en el que, tras una actualización de versión, se perdieron configuraciones de plugins de terceros y la recuperación llevó varias horas.


Preguntas Frecuentes (FAQ)

P1: ¿DeepSeek Harness solo puede usar modelos DeepSeek?

Harness permite, mediante la API de modelos personalizados, conectarse a cualquier servicio compatible con uno de los cuatro protocolos, incluidos las familias OpenAI, Claude, Gemini, así como diversos gateways de API y servicios de modelos autoalojados. El modelo oficial de DeepSeek es solo una de las opciones.

P2: ¿Por qué crear varios proveedores para un mismo gateway?

Harness establece que un proveedor solo se vincula a un protocolo. APIYI ofrece simultáneamente tres entradas: compatible con OpenAI, Anthropic y Gemini. Si quieres invocar GPT, Claude y Gemini respectivamente con protocolos nativos, necesitas crear tres proveedores, con Base URL respectivamente `/v1`, el dominio raíz y `/v1beta`.

P3: ¿Cómo confirmo qué ID de modelo debo escribir?

Prueba primero la función «Obtener modelos disponibles»; si no pueden leerse, copia el nombre exacto de la lista de modelos en la consola de APIYI apiyi.com y añádelo manualmente. El ID del modelo distingue entre mayúsculas y minúsculas y sufijos de versión; cualquier diferencia activará UNKNOWN_MODEL o un error del gateway.

P4: Tras conectarse vía APIYI, ¿se puede usar deepseek_web_search directamente?

Actualmente APIYI ya admite las interfaces independientes Search / Fetch de DeepSeek; el trabajo de compatibilidad para invocar la búsqueda integrada del modelo a través de clientes como Harness sigue en planificación. En esta etapa se recomienda usar `/v1/tools/search` y `/v1/tools/fetch` de APIYI para encapsularlos como herramientas de Agent; cuando se necesite búsqueda integrada, conéctate directamente a la API oficial de DeepSeek.

P5: La interfaz de búsqueda devuelve 503, pero el diálogo funciona perfectamente, ¿cuál es la causa?

La causa más común es la agrupación de tokens. Los tokens del grupo ClaudeCode no pueden llamar directamente a interfaces de herramientas independientes; basta cambiar a una Key de los grupos default o svip. Puedes crear por separado un token del grupo correspondiente para la herramienta de búsqueda en el panel de APIYI apiyi.com, gestionándolo por separado de la Key de invocación del modelo.

P6: ¿Qué limitaciones tiene la integración multimodelo de DeepSeek Harness?

Harness sigue siendo una versión preliminar para desarrolladores; la estructura de configuración puede cambiar según la versión. El grado de transferencia transparente de Responses, parámetros de razonamiento y protocolos de herramientas varía entre gateways, y debe verificarse modelo por modelo. Demasiados plugins aumentarán el contexto y el costo de Tokens, y la calidad de entrega de tareas complejas también depende de la configuración de plugins y la gestión del proceso de ejecución.


Resumen

El mecanismo de adaptación de modelos abiertos de DeepSeek Harness permite que un framework de Agent llame a modelos de múltiples proveedores a través de una pasarela unificada. A la hora de implementarlo, conviene tener en cuenta estos puntos:

  1. El protocolo define el proveedor: se crea un Provider por cada protocolo, y el prefijo de versión de la Base URL se corresponde estrictamente con el protocolo.
  2. El ID del modelo se copia de la pasarela: cópielo desde la consola y, si no puede leer la lista, añádalo manualmente.
  3. Los parámetros de compatibilidad se activan según el error: el rol developer, el campo max_tokens y el formato de pensamiento de DeepSeek cubren la mayoría de los problemas del tipo «conecta pero no funciona».
  4. La capacidad de búsqueda en internet se planifica aparte: la búsqueda integrada utiliza la API oficial de DeepSeek, mientras que Search / Fetch independientes pueden invocarse a través de la pasarela y encapsularse como herramientas.
  5. Capas y gobernanza: separe la capa de ejecución, la capa de modelos y la capa de herramientas, y gestione por separado las claves, las versiones y los costes.

Se recomienda empezar ejecutando un único modelo para completar el flujo «verificación del script → configuración de Harness → conversación sencilla» y, después, ir añadiendo más modelos y herramientas de búsqueda. Le sugerimos solicitar una cuota de prueba gratuita a través de APIYI apiyi.com y completar con una sola clave la verificación integral de varios modelos junto con Search / Fetch.


📚 Referencias

  1. Documentación de configuración de modelos de DeepSeek Harness: campos de proveedor personalizado y parámetros de compatibilidad compat
  2. Enlace: deepseek-harness.github.io/deepseek-harness/guide/providers
  3. Descripción: documentación oficial de supportsDeveloperRole, maxTokensField y thinkingFormat

  4. Repositorio GitHub de DeepSeek Harness: código fuente, Releases y forma de inicio

  5. Enlace: github.com/deepseek-ai/deepseek-harness
  6. Descripción: actualizaciones de versión y notas sobre la fase de vista previa para desarrolladores

  7. Documentación de las herramientas web de DeepSeek: deepseek_web_search y deepseek_read_url

  8. Enlace: api-docs.deepseek.com/zh-cn/guides/web_tools/
  9. Descripción: forma de declaración de la búsqueda integrada, limitaciones y criterios de facturación

  10. Guía de configuración de Base URL de APIYI: descripción de las tres rutas de protocolo

  11. Enlace: help.apiyi.com/apiyi-base-url-v1-claude-gemini-endpoint-config-guide.html
  12. Descripción: casos de uso de /v1, el dominio raíz y /v1beta

  13. Documentación de DeepSeek Search & Fetch de APIYI: interfaces de herramientas independientes y requisitos de agrupación

  14. Enlace: docs.apiyi.com/api-capabilities/deepseek-search-fetch/overview
  15. Descripción: parámetros de solicitud, agrupación de tokens y criterios de facturación

Autor: Equipo técnico de APIYI
Intercambio técnico: si encuentra problemas durante la configuración, puede contactarnos a través de la página de inicio de APIYI apiyi.com; para más información sobre interfaces, consulte el centro de documentación en docs.apiyi.com

Artículos relacionados

Publicaciones Similares