Cómo Ejecutar DeepSeek-V4 Localmente: Guía de Configuración Pro y Flash

Alrededor de 9 min

Cómo Ejecutar DeepSeek-V4 Localmente: Guía de Configuración Pro y Flash

DeepSeek-V4 es uno de los lanzamientos de modelos de pesos abiertos más ambiciosos de DeepSeek hasta ahora. La familia incluye DeepSeek-V4-Pro, un modelo Mixture-of-Experts (MoE) de 1.6T parámetros con 49B parámetros activados, y DeepSeek-V4-Flash, un modelo MoE más pequeño de 284B parámetros con 13B parámetros activados. Ambos modelos soportan una longitud de contexto de hasta un millón de tokens.

Esa combinación suena emocionante, pero también plantea una pregunta práctica: ¿realmente puedes ejecutar DeepSeek-V4 localmente?

La respuesta es sí, pero con una advertencia importante. DeepSeek-V4 no es un modelo para laptops. Incluso la versión Flash requiere un despliegue serio con múltiples GPUs. Esta guía recorre el camino de configuración local usando los repositorios oficiales de DeepSeek en Hugging Face, explica el hardware que debes planificar y muestra cómo usar correctamente los archivos oficiales de inferencia y codificación.

Páginas de referencia del modelo:

DeepSeek-V4-Pro vs DeepSeek-V4-Flash

Antes de descargar cualquier cosa, elige la variante correcta del modelo.

Modelo	Parámetros Totales	Parámetros Activados	Longitud de Contexto	Precisión	Mejor Para
DeepSeek-V4-Flash	284B	13B	1M	FP4 + FP8 mixto	Experimentos locales rápidos, servicio de bajo costo, asistentes de codificación, pruebas de contexto largo
DeepSeek-V4-Pro	1.6T	49B	1M	FP4 + FP8 mixto	Calidad máxima, laboratorios de investigación, grandes clústeres de GPU, tareas serias de razonamiento y agentes

El detalle más importante es que DeepSeek-V4 usa una arquitectura de Mixture-of-Experts (MoE). Solo una parte del modelo se activa para cada token, lo que reduce el costo computacional. Sin embargo, aún necesitas almacenar y cargar los pesos del modelo. Eso significa que los requisitos de memoria GPU y almacenamiento siguen siendo muy altos.

Para la mayoría de los desarrolladores, DeepSeek-V4-Flash es el punto de partida realista. DeepSeek-V4-Pro es mejor tratarlo como un despliegue a escala de clúster.

¿Qué Hace Diferente a DeepSeek-V4?

Según la tarjeta del modelo de DeepSeek, la serie V4 introduce varias mejoras importantes:

Arquitectura de Atención Híbrida: DeepSeek combina Compressed Sparse Attention (CSA) y Heavily Compressed Attention (HCA) para mejorar la eficiencia en contextos largos. En el escenario de un millón de tokens, se reporta que DeepSeek-V4-Pro usa mucho menos caché KV que DeepSeek-V3.2.
Conexiones Hiper-Constrainadas en el Manifold (mHC): Esto mejora la estabilidad en redes muy profundas mientras preserva la capacidad del modelo.
Optimizador Muon: DeepSeek usa Muon durante el entrenamiento para mejor convergencia y estabilidad.
Contexto Largo: Tanto Pro como Flash soportan hasta 1M tokens, recomendando DeepSeek al menos 384K de contexto para el modo Think Max.
Múltiples Modos de Razonamiento: DeepSeek-V4 soporta los estilos Non-think, Think High y Think Max.

Para el despliegue local, los dos cambios prácticos más importantes son la precisión mixta FP4/FP8 y el formato personalizado de codificación de chat.

Requisitos de Hardware

DeepSeek-V4 no está diseñado para GPUs de consumo como la RTX 4090, a menos que solo experimentes con cuantizaciones comunitarias muy modificadas en el futuro. Para los pesos oficiales, planifica alrededor de GPUs de servidor.

Planificación Práctica de Hardware

Caso de Uso	Hardware Sugerido	Notas
Despliegue de prueba DeepSeek-V4-Flash	4-8 GPUs NVIDIA de alta memoria	GPUs clase H100/H200/A100 son el objetivo práctico
Servicio de producción DeepSeek-V4-Flash	8+ GPUs de alta memoria	Más GPUs ayudan en rendimiento y cargas de contexto largo
Despliegue de investigación DeepSeek-V4-Pro	Gran clúster multi-nodo de GPUs	Trátalo como infraestructura de clúster, no como modelo para estación de trabajo única
Think Max con contexto largo	Memoria GPU extra y presupuesto para caché KV	DeepSeek recomienda al menos 384K de contexto para Think Max

Requisitos de Almacenamiento

Planifica un almacenamiento local grande antes de comenzar la descarga:

Usa almacenamiento NVMe SSD siempre que sea posible.
Reserva espacio extra para pesos convertidos.
Evita descargar directamente en un disco del sistema pequeño.
Espera que el modelo Pro requiera mucho más almacenamiento que Flash.

Una estructura segura es:

/data/models/deepseek-v4-flash-hf      # archivos originales de Hugging Face
/data/models/deepseek-v4-flash-infer   # pesos convertidos para inferencia
/data/cache/huggingface                # caché de HF

Si alquilas un servidor GPU en la nube, elige una instancia con NVMe local o adjunta un volumen grande de alto rendimiento. Para planificación tipo VPS, puedes comparar servidores GPU o de alta memoria con proveedores como LightNode, pero asegúrate de que la instancia tenga realmente la memoria GPU requerida para esta clase de modelo.

Requisitos de Software

Necesitas un entorno Linux con drivers NVIDIA recientes y CUDA.

Línea base recomendada:

Componente	Recomendación
SO	Ubuntu 22.04 o superior
Python	3.10+
Driver GPU	Driver reciente de centro de datos NVIDIA
CUDA	CUDA 12.x preferido
PyTorch	Build con soporte CUDA
Git LFS	Requerido para archivos del modelo
Hugging Face CLI	Requerido para descargas confiables

Instala las herramientas básicas:

sudo apt update
sudo apt install -y git git-lfs python3 python3-venv python3-pip

git lfs install
pip install -U huggingface_hub

Si usas un entorno virtual de Python:

python3 -m venv dsv4-env
source dsv4-env/bin/activate
pip install -U pip wheel setuptools
pip install -U huggingface_hub torch transformers safetensors

Paso 1: Descargar DeepSeek-V4-Flash

Para la mayoría de usuarios, comienza con Flash:

mkdir -p /data/models
cd /data/models

huggingface-cli download deepseek-ai/DeepSeek-V4-Flash \
  --local-dir DeepSeek-V4-Flash \
  --local-dir-use-symlinks False

Si quieres el modelo Pro en su lugar:

huggingface-cli download deepseek-ai/DeepSeek-V4-Pro \
  --local-dir DeepSeek-V4-Pro \
  --local-dir-use-symlinks False

Si la descarga se interrumpe, simplemente ejecuta el mismo comando otra vez. Hugging Face reanudará la descarga.

Paso 2: Inspeccionar la Estructura Oficial del Repositorio

Después de descargar, revisa la carpeta del modelo:

cd /data/models/DeepSeek-V4-Flash
ls

La tarjeta del modelo apunta a dos carpetas importantes:

inference/ - código oficial local de inferencia, incluyendo scripts de conversión de pesos y generación
encoding/ - utilidades para codificación de prompts y análisis de salida para DeepSeek-V4

Esto importa porque DeepSeek-V4 no incluye una plantilla de chat normal en formato Jinja. No debes asumir que cualquier wrapper genérico compatible con OpenAI formateará los prompts correctamente desde el inicio.

Paso 3: Convertir los Pesos para la Inferencia Oficial

El README oficial de inferencia usa un paso de conversión antes de ejecutar la generación.

Desde el repositorio del modelo:

cd /data/models/DeepSeek-V4-Flash/inference

export HF_CKPT_PATH=/data/models/DeepSeek-V4-Flash
export SAVE_PATH=/data/models/DeepSeek-V4-Flash-infer
export EXPERTS=256
export MP=4
export CONFIG=config.json

python convert.py \
  --hf-ckpt-path ${HF_CKPT_PATH} \
  --save-path ${SAVE_PATH} \
  --n-experts ${EXPERTS} \
  --model-parallel ${MP}

Notas sobre parámetros:

Variable	Significado
`HF_CKPT_PATH`	Ruta a los archivos originales del modelo en Hugging Face
`SAVE_PATH`	Ruta de salida para los pesos convertidos para inferencia
`EXPERTS=256`	Número de expertos usados por la conversión de inferencia DeepSeek-V4
`MP=4`	Tamaño de paralelismo de modelo; usualmente iguala al número de GPUs usadas en la ejecución
`CONFIG`	Archivo de configuración del modelo usado por el script de generación

Si usas más GPUs, ajusta MP en consecuencia. Por ejemplo, en un nodo de 8 GPUs:

export MP=8

Opción de Expertos FP8

El README oficial de inferencia indica que si quieres usar expertos FP8 en lugar de FP4, elimina esta línea de config.json:

"expert_dtype": "fp4"

Luego pasa --expert-dtype fp8 durante la conversión:

python convert.py \
  --hf-ckpt-path ${HF_CKPT_PATH} \
  --save-path ${SAVE_PATH} \
  --n-experts ${EXPERTS} \
  --model-parallel ${MP} \
  --expert-dtype fp8

Para la mayoría de usuarios, comienza primero con la configuración mixta por defecto FP4/FP8. Cambia la precisión solo después de tener una base funcional.

Paso 4: Iniciar un Chat Interactivo

Una vez que la conversión termine, ejecuta el script oficial de generación:

cd /data/models/DeepSeek-V4-Flash/inference

export MP=4
export SAVE_PATH=/data/models/DeepSeek-V4-Flash-infer
export CONFIG=config.json

torchrun --nproc-per-node ${MP} generate.py \
  --ckpt-path ${SAVE_PATH} \
  --config ${CONFIG} \
  --interactive

Para un archivo de entrada por lotes:

torchrun --nproc-per-node ${MP} generate.py \
  --ckpt-path ${SAVE_PATH} \
  --config ${CONFIG} \
  --input-file prompts.txt

Para una ejecución multinodo:

torchrun \
  --nnodes ${NODES} \
  --nproc-per-node $((MP / NODES)) \
  --node-rank $RANK \
  --master-addr $ADDR \
  generate.py \
  --ckpt-path ${SAVE_PATH} \
  --config ${CONFIG} \
  --input-file prompts.txt

Asegúrate de que cada nodo pueda acceder a la ruta del checkpoint convertido, o copia los archivos convertidos a la misma ruta en cada máquina.

Paso 5: Usar los Ajustes Correctos de Muestreo

DeepSeek recomienda los siguientes parámetros de muestreo para despliegue local:

temperature = 1.0
top_p = 1.0

Si tu script de generación expone estos como flags CLI, úsalos directamente. Si no, configúralos en el script o en la configuración donde se definen los parámetros de muestreo.

Para el modo Think Max, DeepSeek recomienda usar una ventana de contexto de al menos:

384K tokens

No comiences con una ventana de contexto enorme en tu primera prueba. Empieza pequeño, confirma que el modelo carga y genera correctamente, luego aumenta la longitud del contexto gradualmente mientras monitoreas la memoria GPU.

Paso 6: Entender la Codificación de Chat de DeepSeek-V4

DeepSeek-V4 no incluye una plantilla estándar de chat Jinja. En cambio, el repositorio provee una carpeta encoding/ con utilidades en Python.

El uso básico es así:

from encoding_dsv4 import encode_messages, parse_message_from_completion_text

messages = [
    {"role": "system", "content": "Eres un asistente útil."},
    {"role": "user", "content": "¿Cuánto es 2+2?"},
]

prompt = encode_messages(messages, thinking_mode="thinking")
print(prompt)

Para chat sin pensamiento, usa el modo chat:

prompt = encode_messages(messages, thinking_mode="chat")

Para modo thinking, el modelo usa delimitadores explícitos de razonamiento:

<think> ... </think>

El parser puede convertir el texto generado de vuelta a mensajes estructurados del asistente:

completion = "Aritmética simple.</think>2 + 2 = 4.<｜end▁of▁sentence｜>"
parsed = parse_message_from_completion_text(completion, thinking_mode="thinking")
print(parsed)

Esto es especialmente importante si quieres construir tu propio wrapper local de API alrededor de DeepSeek-V4.

Modos de Razonamiento Explicados

DeepSeek-V4 soporta tres estilos prácticos de razonamiento:

Modo	Comportamiento	Caso de Uso
Non-think	Respuestas rápidas y directas	Preguntas y respuestas simples, resúmenes, ayuda rutinaria de codificación
Think High	Respuestas razonadas con análisis deliberado	Depuración, planificación, matemáticas, decisiones de arquitectura
Think Max	Máximo esfuerzo de razonamiento	Tareas difíciles de codificación, flujos de trabajo agenticos, resolución de problemas a nivel de investigación

Para un servidor local, puede que quieras exponer estos como nombres de modelo separados, por ejemplo:

deepseek-v4-flash-chat
deepseek-v4-flash-thinking
deepseek-v4-flash-max

Internamente, cada ruta puede usar diferente codificación de prompt, límites de contexto y parámetros de generación.

¿Puedes Ejecutar DeepSeek-V4 con vLLM o SGLang?

Al lanzamiento, la ruta más segura es el código oficial de inferencia DeepSeek en el repositorio del modelo. Los frameworks genéricos de servicio pueden necesitar actualizaciones antes de soportar completamente la arquitectura de DeepSeek-V4, la precisión mixta, el comportamiento de contexto largo y la codificación personalizada.

Un enfoque práctico es:

Primero, ejecuta con éxito la ruta oficial inference/generate.py.
Confirma la calidad de salida y el formato del prompt con las utilidades oficiales encoding/.
Luego verifica si tu framework preferido ha añadido soporte explícito para DeepSeek-V4.
Solo migra a vLLM, SGLang, TensorRT-LLM u otro framework de servicio después de confirmar soporte.

Esto evita un modo común de fallo: el modelo carga, pero la calidad del chat es pobre porque la plantilla del prompt es incorrecta.

Construyendo un Wrapper Simple de API Local

Si quieres un endpoint local estilo OpenAI, puedes envolver la ruta oficial de generación con FastAPI. La implementación exacta depende de cómo integres generate.py, pero el flujo general es:

Recibir messages compatibles con OpenAI.
Convertirlos usando encoding_dsv4.encode_messages().
Enviar el prompt codificado al motor de inferencia DeepSeek-V4.
Parsear la salida usando parse_message_from_completion_text().
Devolver una respuesta JSON compatible con OpenAI.

Pseudo-código:

from encoding_dsv4 import encode_messages, parse_message_from_completion_text

messages = [
    {"role": "system", "content": "Eres un asistente útil."},
    {"role": "user", "content": "Explica el caché KV en términos simples."},
]

prompt = encode_messages(messages, thinking_mode="thinking")

# Envía el prompt a tu worker local de inferencia DeepSeek-V4
raw_completion = run_deepseek_v4(prompt)

assistant_message = parse_message_from_completion_text(
    raw_completion,
    thinking_mode="thinking",
)

print(assistant_message["content"])

Para producción, añade:

cola de solicitudes
salida en streaming
manejo de tiempos de espera
chequeos de salud de GPU
aplicación de límite máximo de contexto
logs estructurados
autenticación

Solución de Problemas

1. CUDA Out of Memory

Reduce la presión de memoria:

disminuye la longitud del contexto
reduce el tamaño del batch
aumenta el paralelismo tensor/modelo
usa más GPUs
comienza con DeepSeek-V4-Flash en lugar de Pro

El contexto largo suele ser lo primero que se reduce durante la depuración.

2. La Descarga Falla o Se Cuelga

Usa huggingface-cli download en lugar de descargas por navegador. Vuelve a ejecutar el mismo comando para reanudar.

También puedes configurar un directorio de caché dedicado:

export HF_HOME=/data/cache/huggingface
export HUGGINGFACE_HUB_CACHE=/data/cache/huggingface/hub

3. El Modelo Genera Salidas Extrañas en el Chat

Revisa el formato del prompt. DeepSeek-V4 no usa una plantilla estándar Jinja para chat. Usa la implementación oficial encoding/.

4. La Ejecución Multi-GPU Falla

Verifica que PyTorch detecte todas las GPUs:

python - <<'PY'
import torch
print(torch.cuda.device_count())
for i in range(torch.cuda.device_count()):
    print(i, torch.cuda.get_device_name(i))
PY

También revisa la red NCCL para ejecuciones multinodo:

export NCCL_DEBUG=INFO

5. Think Max Es Muy Lento

Think Max está diseñado para gastar más cómputo en razonamientos difíciles. Úsalo solo para tareas que justifiquen el costo. Para uso normal de asistente, Non-think o Think High suelen ser más prácticos.

Estrategia Recomendada de Despliegue

Si vas a desplegar DeepSeek-V4 localmente por primera vez, sigue esta secuencia:

Comienza con DeepSeek-V4-Flash.
Usa el código oficial de inferencia.
Usa primero un contexto pequeño de prueba.
Confirma que la codificación oficial funciona.
Aumenta la longitud del contexto gradualmente.
Añade un wrapper de API solo después de que la generación local sea estable.
Considera Pro solo cuando tengas recursos GPU a escala de clúster.

Reflexiones Finales

DeepSeek-V4 es poderoso, pero no es un modelo local casual. La versión Flash es el punto de entrada práctico, mientras que Pro pertenece a entornos serios multi-GPU o multinodo. La clave para una configuración exitosa es respetar el flujo oficial: descarga el repositorio de Hugging Face, convierte los pesos con las herramientas de inferencia provistas, ejecuta la generación con torchrun y usa las utilidades dedicadas de codificación DeepSeek-V4 en lugar de asumir una plantilla genérica de chat.

Si solo necesitas experimentar con prompts, el servicio de chat alojado de DeepSeek o las rutas API pueden ser más fáciles. Pero si necesitas privacidad de datos, control total, sin facturación por token o infraestructura personalizada, ejecutar DeepSeek-V4 localmente te da una base sólida para construir sistemas de IA privados con contexto largo.