Cómo implementar deepseek-v3.1 localmente a través de ollama: La guía más oriental

DeepSeek-V3.1 es un modelo de lenguaje MoE híbrido "pensante/no pensante" (671 B en total, ≈37 B activados por token) que puede ejecutarse localmente si se utilizan el proveedor, la cuantificación y las herramientas adecuadas. A continuación, explico qué es DeepSeek-V3.1, los requisitos de hardware y software, tutoriales paso a paso para su ejecución local (ejemplos de Ollama + llama.cpp) y cómo... Implementar y utilizar el modo de pensamiento (la <think>/</think> Plantilla de chat) con ejemplos de código que puedes copiar y pegar.

¿Qué es DeepSeek-V3.1?

DeepSeek-V3.1 es la versión 3.1 de la familia MoE (Mezcla de Expertos) de DeepSeek. Fue diseñado como un modelo de inferencia híbrido que admite dos plantillas/modos conversacionales: Ideas y No pensar — desde el mismo punto de control modificando la plantilla de chat. La arquitectura del modelo se basa en el diseño de DeepSeek-V3 MoE (671 37 millones de parámetros totales; aproximadamente XNUMX XNUMX millones de parámetros activados por token para la inferencia) e incorpora mejoras posteriores al entrenamiento para el uso de herramientas, las habilidades de los agentes y el manejo de contextos extensos.

Características destacadas

Híbrido Pensamiento / No pensamiento modos (alternados mediante la tokenización de la plantilla de chat).
Arquitectura MoE: gran cantidad total de parámetros, pero parámetros activados limitados por token (permite eficiencia).
Mejoras posteriores al entrenamiento para llamadas de herramientas y flujos de trabajo de agentes (formato de llamada de herramientas y plantillas de agentes documentados en los activos del modelo).

¿Qué necesito para ejecutar DeepSeek-V3.1 localmente?

Corriendo el ser completados DeepSeek-V3.1 (puntos de control sin procesar) es un recurso pesado: el almacenamiento de puntos de control y entrenamiento, así como la orquestación de inferencias, no son triviales. Sin embargo, existen vías prácticas:

Ferretería

**Inferencia completamente distribuida (investigación/clúster)**Varias GPU de alta memoria (clase A100/H800) o un clúster de GPU con servicio paralelo de modelos (típico para puntos de control de más de 600 B). Úselo solo si ejecuta clústeres de investigación en producción.
Opciones locales prácticas: utilizar el parámetro activado Perspectiva (≈37 B activada) o una compilación GGUF cuantificada/dinámica de 1 bit. Las cuantificaciones de la comunidad (dinámica de 1 bit/GGUF) reducen significativamente los requisitos de disco y RAM; por ejemplo, las publicaciones de la comunidad informan sobre la compresión de un punto de control de 720 GB a ~170 GB de GGUF para una variante cuantificada. Esto hace viable la inferencia de GPU local de un solo servidor para ordenadores/servidores con recursos suficientes.

En pocas palabras: Espere un flujo de trabajo de modelo grande (decenas a cientos de GB de disco para artefactos cuantificados); para VRAM de GPU, utilice variantes cuantificadas y apunte a ≥24–48 GB de VRAM para un rendimiento razonable; de lo contrario, utilice CPU+swap con compensaciones de rendimiento.

Software y herramientas

Python 3.10+ (para herramientas de transformación/tokenización y scripts personalizados).

transformers (para funciones de tokenizador y auxiliar): la tarjeta modelo muestra ejemplos de uso transformers.AutoTokenizer.

Uno o más tiempos de ejecución de inferencia local:

Ollama (fácil: ollama pull / ollama run Integración; algunas compilaciones de DeepSeek en Ollama requieren versiones preliminares (consulte la nota sobre el modelo/ollama). Ollama se ha convertido en un ejecutor local estándar para los modelos comunitarios.
llama.cpp / ggml pilas o llama-server para archivos cuantificados GGUF: excelente para la ejecución directa de GGUF.
Inferencia de generación de texto / Triton / Pilas FlashAttention para inferencia de GPU de mayor rendimiento (configuraciones avanzadas).

Disco: gran espacio libre para archivos de modelo (decenas → cientos de GB dependiendo de la cuantificación).

Artefactos del modelo (qué archivo obtener)

Tensores de seguridad oficiales / variantes BF16 / FP8 / GGUF: Hugging Face aloja artefactos del modelo V3.1 y múltiples cuantificaciones. Si necesita un archivo GGUF/cuantizado para llama.cpp, busque una versión de cuantificación de la comunidad (o un script de conversión de safetensors → GGUF) — la tarjeta del modelo enumera las variantes cuantificadas.

¿Cómo preparo el modelo para la inferencia local?

A continuación se presentan los pasos de preparación recomendados organizados de simple a avanzado.

Paso 1: Elija un tiempo de ejecución (recomendado)

Prueba para principiantes/rápida: Ollama: configuración mínima: descargar, ejecutar el modelo, llamar a la API. Nota: Algunas compilaciones de DeepSeek-V3.1 incluyen Ollama v0.11.7 como requisito para funciones específicas.
Control avanzado/de bajo nivel: llama.cpp + Cuantización GGUF (si está disponible). Esto le brinda control directo de inferencia e integración con llama-server.

Paso 2 — Descargar el modelo

Si utilizas Ollama:

# install ollama (see https://ollama.com/docs)

# Pull the model (this downloads the model to your machine)
ollama pull deepseek-ai/DeepSeek-V3.1
# or a specific tag: ollama pull deepseek-ai/DeepSeek-V3.1:quant-q4_0

(De Ollama run se extraerá automáticamente si no está presente; pull (Le permite controlar el tiempo).

Si usas Hugging Face + llama.cpp:

# Example: download via huggingface-cli or hf_transfer

pip install huggingface_hub
hf_hub_download(repo_id="deepseek-ai/DeepSeek-V3.1", filename="DeepSeek-V3.1.gguf")
# or use a community quant file (gguf) referenced on the Hugging Face model page

Hugging Face enumera artefactos del modelo, plantillas y cuantificaciones en la tarjeta del modelo.

Paso 3: Convertir/cuantizar (opcional)

Si solo encuentra tensores seguros o artefactos BF16 pero necesita GGUF para llama.cpp, utilice los scripts de conversión en llama.cpp (o herramientas de la comunidad) para convertir → cuantificar. Existen herramientas de la comunidad para la cuantificación dinámica de 1 bit que conservan la precisión a la vez que reducen el tamaño; consulte las publicaciones de la comunidad que informan hasta ~170 GB.

¿Cómo ejecuto DeepSeek-V3.1 localmente? (Tutoriales prácticos)

Te lo mostraré Ollama (fácil, recomendado) y llama.cpp (GGUF) ejemplos más un breve ejemplo de Python que utiliza los ayudantes del tokenizador de tarjetas modelo.

A — Corriendo con Ollama (inicio rápido)

Instalar Ollama (siga las instrucciones oficiales).
Extraiga y ejecute el modelo:

# pull model to disk (optional; run will pull automatically)

ollama pull deepseek-ai/DeepSeek-V3.1

# start an interactive session (runs model and exposes local API)

ollama run deepseek-ai/DeepSeek-V3.1

Realice una solicitud HTTP al servidor Ollama local:

# curl usage example (local Ollama server usually listens on port 11434)

curl -sS -X POST 'http://localhost:11434/api/generate' \
  -H 'Content-Type: application/json' \
  -d '{
    "model":"deepseek-ai/DeepSeek-V3.1",
    "prompt":"Explain the difference between thinking and non-thinking mode in DeepSeek.",
    "max_tokens":256
  }'

Los patrones CLI y API de Ollama están diseñados para ser simples: ollama run Se extraerá si es necesario y se iniciará un servidor de modelos. Consulta la documentación de Ollama y las páginas de modelos para obtener sugerencias de memoria y nombres/etiquetas exactos de los modelos.

B — Ejecución de un GGUF cuantificado mediante llama.cpp

Build llama.cpp con CUDA (opcional) o CPU:

git clone https://github.com/ggerganov/llama.cpp
cd llama.cpp
# for CUDA:

make clean && make LLAMA_CUBLAS=1
# or CPU only:

make

Coloque el archivo del modelo GGUF en una ruta y ejecute:

./main -m /path/to/DeepSeek-V3.1.q4_K_M.gguf \
  -p "Explain how to enable thinking mode." \
  --temp 0.2 --n_predict 512

Para uso del servidor, llama-server (proyecto comunitario) puede exponer un punto final HTTP:

llama-server -m /path/to/DeepSeek-V3.1.q4_K_M.gguf
# then POST to the server like:

curl -X POST "http://localhost:8080/api/v1/generate" -d '{"prompt":"Hello","max_tokens":200}'

Utilice cuantificaciones GGUF de la comunidad (dinámica q4/q8/1 bit) para adaptarse a los presupuestos de GPU/CPU; llama.cpp repo proporciona herramientas de conversión y orientación.

C — Ejemplo de Python que utiliza el tokenizador + plantilla de chat

La tarjeta modelo Hugging Face proporciona una tokenizer.apply_chat_template ayudante y muestra cómo codificar una conversación con thinking=TrueA continuación se muestra un ejemplo mínimo de Python adaptado de la tarjeta modelo:

from transformers import AutoTokenizer

tokenizer = AutoTokenizer.from_pretrained("deepseek-ai/DeepSeek-V3.1")

messages = [
    {"role": "system", "content": "You are a helpful assistant"},
    {"role": "user", "content": "Who are you?"},
    {"role": "assistant", "content": "<think>Hmm</think>I am DeepSeek"},
    {"role": "user", "content": "1+1=?"}
]

# apply thinking chat template

s = tokenizer.apply_chat_template(messages, tokenize=False, thinking=True, add_generation_prompt=True)
print(s)  # the template includes the special <think> token placement

Luego, puede introducir el mensaje tokenizado en su entorno de ejecución de inferencia (Ollama/llama.cpp/TGI) según su pila.

¿Cómo funciona el Modo Pensamiento y cómo lo implemento localmente?

Usos de DeepSeek-V3.1 plantillas de chat que contienen una ficha de pensamiento especial (por ejemplo, <think> y </think>). La plantilla determina si el modelo está en modo de pensamiento o de no pensamiento:

No pensar lugares de plantilla </think> en el prefijo del asistente, que indica al modelo que produzca respuestas directas (el formato de llamada de herramienta se admite en modo sin pensamiento).
Ideas lugares de plantilla <think> En el prefijo del asistente, que hace que el modelo genere señales intermedias internas de cadena de pensamiento (el modelo está entrenado para usar esa secuencia de tokens para razonar internamente y producir respuestas de varios pasos de mayor calidad). La tarjeta del modelo "Cara Abrazándose" documenta estos tokens exactos y... tokenizer.apply_chat_template(..., thinking=True) API.

Alternancia programática (ejemplos)

A — Con el tokenizador (Python):

# thinking=True or thinking=False changes how the prompt is formatted

prompt_thinking = tokenizer.apply_chat_template(messages, thinking=True, add_generation_prompt=True)
prompt_non_thinking = tokenizer.apply_chat_template(messages, thinking=False, add_generation_prompt=True)

Alimentación prompt_thinking a su tiempo de ejecución de inferencia para obtener el comportamiento de pensamiento.

B — Con mensaje sin procesar (llama.cpp / manual):

recuadro <think> antes de que el asistente gire cuando usted le indique:

<｜begin_of_sentence｜>You are a helpful assistant<｜User｜>How to optimize this code?<｜Assistant｜><think>

(El diseño exacto de las fichas se encuentra en la tarjeta modelo; debes respetar el espaciado y los marcadores especiales si usas la plantilla original).

C — Con Ollama (alternar interfaz de usuario):
La demo web oficial de DeepSeek y las notas de la versión mencionan un botón "DeepThink" para cambiar de modo en la interfaz alojada. Localmente, Ollama o tu aplicación deberían replicar este comportamiento cambiando la plantilla de chat (es decir, modificando el mensaje que envías al entorno de ejecución entre los dos formularios tokenizados). Si ejecutas DeepSeek mediante Ollama, puedes implementar esto en tu aplicación manteniendo dos plantillas de mensajes (pensamiento vs. no pensamiento) y alternando entre ellas mediante la API de Ollama.

¿Cómo implemento el modo de pensamiento como agente (llamadas a herramientas, agentes de código)?

Documentos de DeepSeek-V3.1 llamada de herramienta y agente Plantillas en los recursos del modelo. El modelo espera que las herramientas se presenten en un formato JSON/instrucción específico y admite el encadenamiento de múltiples llamadas a herramientas en un solo turno si se siguen exactamente los tokens de contenedor descritos en la tarjeta del modelo.

Ejemplo: envoltura de llamada a herramienta simple (pseudo)

El modelo especifica un bloque descriptor de herramientas y un estricto tool_calls_begin / tool_call_begin Formato. Un ejemplo mínimo (conceptual):

## Tools

You have access to the following tools:

### web_search

Description: Query the web
Parameters: {"q": "string"}

<｜begin_of_sentence｜>{system prompt}

## Tools

...tool descriptions...

<｜User｜>Find the population of Tokyo<｜Assistant｜></think>
<｜tool_calls_begin｜><｜tool_call_begin｜>web_search<｜tool_sep｜>{"q":"population of Tokyo 2025"}<｜tool_call_end｜><｜tool_calls_end｜>

La salida de la herramienta debe luego ser devuelta al modelo en el siguiente turno siguiendo el formato prescrito del modelo (ver assets/search_tool_trajectory.html En la página del modelo para el flujo exacto). La implementación de agentes requiere orquestación programática: llamar a la herramienta → capturar el resultado → inyectar el resultado en el contexto del chat exactamente como lo indica la plantilla → volver a llamar al modelo.

Consejos prácticos, solución de problemas y notas de seguridad (¿A qué debo prestar atención?)

Las plantillas de token son estrictas. Utilice el modelo tokenizer.apply_chat_template o reproducir exactamente <think>/</think> Tokens como se muestra. El espaciado incorrecto o la falta de marcadores cambiarán el comportamiento del modelo.
El formato de la herramienta debe ser JSON válido. El modelo analizará los argumentos de la herramienta como JSON; un JSON no válido interrumpirá las llamadas de la herramienta.
Compensaciones en la cuantificación. Las cuantificaciones dinámicas/agresivas de 1 bit reducen el almacenamiento y la RAM, pero pueden alterar ligeramente la fidelidad numérica. Realice pruebas en sus cargas de trabajo. Existen cuantificaciones de la comunidad que reducen el 80 % del uso del disco (informe de ejemplo: 720 GB → ~170 GB), pero valide siempre con las indicaciones.
Compatibilidad con Ollama. Algunas variantes de DeepSeek indican que Ollama v0.11.7 es necesario para las funciones previas al lanzamiento: consulte la página del modelo de Ollama y actualice según corresponda.

Ejemplo de principio a fin: ejecutar DeepSeek-V3.1 localmente con el modo de pensamiento (mini tutorial)

Instalar Ollama y extraer el modelo:

# install ollama per docs, then:

ollama pull deepseek-ai/DeepSeek-V3.1
ollama run deepseek-ai/DeepSeek-V3.1 &

Utilice el tokenizador de Python para componer una propuesta de reflexión:

from transformers import AutoTokenizer
tokenizer = AutoTokenizer.from_pretrained("deepseek-ai/DeepSeek-V3.1")

msgs = [
  {"role":"system","content":"You are a helpful assistant."},
  {"role":"user","content":"Plan a multi-step strategy to prototype a mobile app in 2 weeks."}
]
prompt = tokenizer.apply_chat_template(msgs, thinking=True, add_generation_prompt=True)

import requests
resp = requests.post("http://localhost:11434/api/generate", json={
    "model": "deepseek-ai/DeepSeek-V3.1",
    "prompt": prompt,
    "max_tokens": 400
})
print(resp.json())

Si el modelo devuelve una llamada de herramienta en el formato toolcall, analiza el JSON y ejecuta la herramienta, luego inyecta los resultados en el siguiente mensaje según las plantillas de la tarjeta del modelo.

¿Cómo debería elegir su ruta de implementación?

Si quieres la ruta más rápida para experimentar: use Ollama Y los ejemplos de la tarjeta del modelo "Cara Abrazadora". Ollama oculta muchos detalles de infraestructura y proporciona una API HTTP local.
Si necesita un menor costo / mayor portabilidad: utilizar una comunidad GGUF cuantificado artefacto y correr con llama.cpp or llama-serverLa cuantificación ahorra disco y memoria, pero prueba la precisión para su carga de trabajo.
Si está creando agentes o herramientas: Siga las instrucciones de la tarjeta modelo llamada de herramienta y agente plantillas exactamente; orquestar las salidas de la herramienta en el contexto del modelo.

Primeros Pasos

CometAPI es una plataforma API unificada que integra más de 500 modelos de IA de proveedores líderes, como la serie GPT de OpenAI, Gemini de Google, Claude de Anthropic, Midjourney, Suno y más, en una única interfaz intuitiva para desarrolladores. Al ofrecer autenticación, formato de solicitudes y gestión de respuestas consistentes, CometAPI simplifica drásticamente la integración de las capacidades de IA en sus aplicaciones. Ya sea que esté desarrollando chatbots, generadores de imágenes, compositores musicales o canales de análisis basados en datos, CometAPI le permite iterar más rápido, controlar costos y mantenerse independiente del proveedor, todo mientras aprovecha los últimos avances del ecosistema de IA.

Los desarrolladores pueden acceder Búsqueda profunda V3.1 A través de CometAPI, las últimas versiones de los modelos listadas corresponden a la fecha de publicación del artículo. Para comenzar, explore las capacidades del modelo en Playground y consultar el Guía de API Para obtener instrucciones detalladas, consulte la sección "Antes de acceder, asegúrese de haber iniciado sesión en CometAPI y de haber obtenido la clave API". CometAPI Ofrecemos un precio muy inferior al oficial para ayudarte a integrarte.

Conclusión

DeepSeek-V3.1 ofrece una filosofía práctica de inferencia híbrida (un punto de control + comportamiento basado en plantillas) que facilita la experimentación con razonamiento en cadena de pensamiento y el uso de herramientas de agente, siempre que se respeten las plantillas de chat y los requisitos de las herramientas. Utilice la tarjeta de modelo Hugging Face y las notas de la versión de DeepSeek como primera opción; seleccione un entorno de ejecución local (Ollama para simplificar, llama.cpp para el control) y probar compilaciones cuantificadas para implementaciones locales prácticas.