CH 06 · Configurar modelo y nivel de razonamiento

Extensión~4.000 palabrasTiempo~15 minRequisitoCH 03 ya en marchaNivelReproducible

Objetivo del capítulo

Deja bien configuradas las dos perillas "qué modelo" y "cuánto pensar": primero entiende las tres cosas que necesita una llamada a un modelo (API Key / Base URL / Model ID), luego lee el archivo de configuración, cambia el modelo predeterminado, ajusta el nivel de razonamiento y, por último, aprende a conectar modelos de terceros.

Primero entiende tres conceptos: API Key / Base URL / Model ID

Sin importar qué herramienta uses para llamar a un modelo grande, una petición lleva tres cosas — API Key (quién eres), Base URL (a dónde ir), Model ID (qué modelo usar):

Vamos uno por uno:

• API Key: una cadena con prefijo sk-, tu "documento de identidad" en una plataforma de modelos. La petición la lleva para que la plataforma sepa quién eres y a qué cuenta facturar. Es una contraseña — no la filtres, no la commitees a un repo Git. Nota al margen: el prefijo sk- es un formato común en el ecosistema compatible con OpenAI; DeepSeek y muchas plataformas nacionales y pasarelas propias siguen este formato.
• Base URL: la "dirección" del modelo, es decir, el endpoint del servicio API. Todas las peticiones van a esta dirección.
• Model ID: el nombre del modelo, especifica exactamente cuál usar. Si la petición dice deepseek-v4-flash-vision-exp, usas la versión con visión; deepseek-v4-pro es el flagship.

Estos tres valores vienen todos de la propia plataforma de modelos, no los inventa dsh. Toma DeepSeek como ejemplo, cómo obtenerlos:

1. API Key: abre la Plataforma Abierta DeepSeek, regístrate e inicia sesión, ve a Consola → API Keys → Crear API key, nómbrala y pulsa crear, inmediatamente cópiala y guárdala — la clave se muestra completa solo en el momento de la creación, después la página solo muestra un descriptor redactado.
2. Base URL: los documentos oficiales de DeepSeek indican claramente que el endpoint compatible con OpenAI es https://api.deepseek.com (el endpoint compatible con Anthropic es https://api.deepseek.com/anthropic).
3. Model ID: encuéntralo en la lista de modelos en los documentos oficiales de la API; son los mismos que viste en el selector de modelos (deepseek-v4-pro / deepseek-v4-flash / deepseek-v4-flash-vision-exp).

Cuando conectes modelos de terceros más adelante, verás que son las mismas tres cosas — solo que con valores distintos.

Dónde está el archivo de configuración: $DSH_HOME/settings.yaml

La configuración global de dsh es un único archivo: C:\Users\<tu-usuario>\.dsh\settings.yaml. En mi máquina se ve así:

ui-onboarding:
  welcomeNoticeVersion: 2026-08-13.1
agent-default-model:
  provider: deepseek-official
  model: deepseek-v4-flash-vision-exp
  reasoningEffort: high

Este archivo es el punto de llegada de los cambios de modelo y nivel de razonamiento que hagas en la Web UI — cualquier cambio que hagas en la UI acaba escribiéndose aquí. Cada uno de los tres campos gestiona una cosa:

Campo	Rol	Mi valor
provider	Por qué provider enrutar	deepseek-official (DeepSeek oficial)
model	Modelo predeterminado para sesiones nuevas	deepseek-v4-flash-vision-exp
reasoningEffort	Nivel de razonamiento predeterminado	high

Cómo elegir entre los tres modelos

El adaptador oficial de DeepSeek publica tres modelos por defecto, cada uno con una ventana de contexto de 1M tokens:

Model ID	Posicionamiento
deepseek-v4-pro	Flagship, tareas complejas y críticas en calidad, más capaz pero más caro
deepseek-v4-flash	Rápido, económico, para tareas diarias
deepseek-v4-flash-vision-exp	Versión con visión: puede leer imágenes, ver capturas; al nivel de flash en texto puro

Un detalle: el Model ID se pasa tal cual al protocolo, así que cuando el equipo oficial publique modelos nuevos, no necesitas volver a registrarte — solo rellena el nuevo ID en la configuración.

Nivel de razonamiento: off / low / high / max

El nivel de razonamiento decide cuánto "piensa" el modelo antes de actuar. El modelo oficial de DeepSeek tiene cuatro niveles. En la Web UI, pulsa el botón de modelo a la derecha del cuadro de entrada para ver y cambiar entre estos cuatro niveles (prueba local, High es el predeterminado marcado):

Nivel	Comportamiento
off	Deshabilita el pensamiento (thinking: disabled), más rápido y más barato
low	Pensamiento ligero
high (predeterminado)	Razonamiento profundo, adecuado para tareas de Agent
max	Máxima intensidad de pensamiento, solo para el trabajo más difícil

El valor predeterminado oficial es high. El nivel afecta directamente al tiempo y al costo: un nivel con pensamiento habilitado es algo más lento y más caro, pero más fiable en tareas complejas; off no piensa, así que un Q&A simple vuelve al instante. Elegir un nivel sigue un principio — cuanto más difícil la tarea, más alto el nivel.

Cómo cambiar: Web UI o editar el archivo

Las dos formas acaban en settings.yaml:

• Web UI: Ajustes → Modelos. Guarda claves, ve modelos configurados, añade providers. El modelo elegido en el selector de modelo se convierte en el predeterminado para sesiones nuevas; las sesiones que ya han enviado peticiones mantendrán el modelo que estaban usando cuando empezaron, y no cambiarán con el valor predeterminado.

• Edita el archivo directamente: cambia los tres campos en agent-default-model, o añade una sección llm-deepseek: para sobrescribir más campos (se usa más adelante al configurar un provider personalizado).

Regla de efectividad: los cambios surten efecto en la siguiente petición, no hace falta reiniciar el servicio.

Configurar modelos de terceros

Lo que acabamos de cubrir es la configuración oficial de DeepSeek. Aquí es exactamente donde dsh muestra una característica distintiva: conecta cualquier modelo, no se queda atado al suyo. El adaptador oficial simplemente viene por defecto con DeepSeek; puedes conectar completamente Anthropic, OpenAI, cualquier pasarela compatible con OpenAI, incluso modelos locales. Por el contrario, productos como Codex están limitados a un conjunto fijo de modelos; para cambiar de provider hay que esperar a que el equipo oficial lo abra. En dsh hay dos formas de conectar un tercero.

Método uno: añadir un Provider (usar directorio existente)

La página Ajustes → Modelos tiene una entrada Añadir Provider, donde encuentras un lote de "directorios" oficiales — elige Anthropic, OpenAI u otro directorio existente; el endpoint y el protocolo ya están configurados. Tras añadir, sigue el formulario de tres pasos:

1. Elige el provider: pulsa el desplegable "Provider" y elige el provider que quieras conectar (p. ej. minimax-cn).
2. Rellena la API key: pega la Key de esa plataforma en el cuadro "API Key" — visualización enmascarada, solo escritura.
3. Obtén modelos disponibles: pulsa "Obtener modelos disponibles" para traer su directorio de modelos, y luego puedes elegir su Model ID de la lista.

Tras guardar, los modelos del provider aparecen en el selector de modelo para uso normal.

Método dos: añadir un Provider personalizado (tu propia pasarela / modelo local)

Si dsh no trae preinstalada la plataforma que usas, usa Añadir Provider personalizado. Lo que hay que rellenar son exactamente las tres del inicio de este capítulo más una más:

Campo	Qué es	Ejemplo
Provider ID	Un ID único para este provider (minúsculas, permanente una vez fijado)	my-gateway
Dirección API	El Base URL, la dirección del servicio del modelo	https://tu-direccion-de-pasarela
Protocolo API	En qué formato hablar (compatible con OpenAI / Anthropic, etc.)	openai-completions
Key	La API Key, la credencial de autenticación	sk-...
Model	Rellena al menos un Model ID	deepseek-v4-flash

Tras guardar, este provider personalizado aparece en la lista de modelos para uso normal. Algunas notas:

• El Provider ID es permanente una vez fijado, no lo cambies a la ligera; configuraciones posteriores lo referencian.
• Para modelos locales / pasarelas propias, apunta la dirección API a tu propio servicio y rellena la clave del servicio local en el campo de clave (o deja un placeholder según sus requisitos).
• Si tu modelo personalizado es un modelo de visión (recibe imágenes), con rellenar el Model ID no basta — el requisito oficial es declarar adicionalmente que admite entrada de imagen. En settings.yaml, añade una línea input: [text, image] a ese provider, si no las imágenes serán rechazadas como entrada no válida.

Claves y credenciales

Detrás de la tarjeta de Key que rellenaste (CH 03) hay dos mecanismos:

• La clave es de solo escritura: tras guardar en Ajustes → Modelos, la página solo muestra un descriptor redactado, el texto plano solo va a parar a C:\Users\<tu-usuario>\.dsh\.credentials.yaml, y settings.yaml solo guarda una referencia a la credencial, nunca el texto plano.
• Orden de resolución: en el momento de la petición, primero se consulta el almacén de credenciales, luego la variable de entorno (predeterminada DEEPSEEK_API_KEY) se usa como fallback. Si ninguna la tiene, obtienes MISSING_CREDENTIAL.

Hoja de referencia rápida de resolución de problemas

Solo hay un puñado de errores relacionados con la configuración; busca el tuyo:

Error	Significado	Solución
MISSING_CREDENTIAL	No hay clave configurada	Ve a la página de Modelos para guardar una clave, o configura la variable de entorno a la que se referencia
INVALID_CREDENTIAL	El formato de la clave es incorrecto	Comprueba la Key que rellenaste
UNKNOWN_MODEL	El modelo no existe o no está configurado	Elige un modelo configurado
UNSUPPORTED_REASONING_EFFORT	Nivel de razonamiento no soportado	Usa uno de off / low / high / max
Obtener modelos disponibles devuelve 401	La clave es incorrecta	Comprueba la clave; el descubrimiento de modelos llama al endpoint compatible con OpenAI GET /models

Lo que aprendiste en este capítulo

Apruebas si puedes completar los siguientes puntos:

• [ ] Explicas los tres conceptos API Key / Base URL / Model ID, y dónde obtenerlos (usando DeepSeek como ejemplo)
• [ ] Indicas la ubicación de settings.yaml y qué significan los tres campos de agent-default-model
• [ ] Indicas el posicionamiento de cada uno de los tres Model ID de DeepSeek
• [ ] Indicas los cuatro valores de nivel de razonamiento (off / low / high / max) y el predeterminado, y el principio para elegir uno
• [ ] Sabes que tras cambiar el modelo/nivel, surte efecto en la siguiente petición, no hace falta reiniciar
• [ ] Conoces las dos formas de conectar modelos de terceros: añadir un Provider (directorio existente, rellena su clave, usa su Model ID) vs añadir un Provider personalizado (Provider ID / dirección API / protocolo / clave / modelo)
• [ ] Sabes dónde se almacenan las claves y por qué settings no guarda texto plano
• [ ] Usas la tabla de resolución de problemas para localizar errores como MISSING_CREDENTIAL y UNKNOWN_MODEL