Cómo usar la API DeepSeek-V3.1: un tutorial práctico para desarrolladores

DeepSeek-V3.1 es el último modelo de razonamiento híbrido de DeepSeek, compatible con un modo de chat rápido "sin pensamiento" y un modo más deliberado "pensamiento/razonamiento". Ofrece contexto extenso (hasta 128K), resultados estructurados y llamadas a funciones. Se puede acceder a él directamente a través de la API de DeepSeek compatible con OpenAI, un endpoint compatible con Anthropic o CometAPI. A continuación, se explica el modelo, los puntos de referencia y el coste, las funciones avanzadas (llamadas a funciones, resultados JSON, modo de razonamiento) y se ofrecen ejemplos de código completos: llamadas REST directas a DeepSeek (curl/Node/Python), uso del cliente Anthropic y llamadas a través de CometAPI.

¿Qué es DeepSeek-V3.1 y qué novedades hay en esta versión?

DeepSeek-V3.1 es la versión más reciente de la familia DeepSeek V3: una línea de modelos de lenguaje grande, de alta capacidad y con una combinación de expertos que ofrece un diseño de inferencia híbrido con dos “modos” operativos: uno rápido charla sin pensar modo y un pensador / razonador Modo que permite exponer rastros de estilo de cadena de pensamiento para tareas de razonamiento más complejas y el uso de agentes/herramientas. Esta versión enfatiza una latencia de pensamiento más rápida, capacidades mejoradas de herramientas/agentes y un manejo de contexto más extenso para flujos de trabajo a escala de documentos.

Conclusiones prácticas clave:

• Dos modos de funcionamiento: deepseek-chat para el rendimiento y el costo, deepseek-reasoner (un modelo de razonamiento) cuando desea rastros de cadenas de pensamiento o una mayor fidelidad de razonamiento.
• Manejo de agente/herramienta mejorado y mejoras de tokenizador/contexto para documentos largos.
• Longitud del contexto: hasta ~128K tokens (permite documentos largos, bases de código, registros).

Avance de referencia

DeepSeek-V3.1 demostró mejoras significativas en desafíos de programación reales. En la evaluación verificada de SWE-bench, que mide la frecuencia con la que el modelo corrige problemas de GitHub para garantizar la aprobación de las pruebas unitarias, la versión 3.1 alcanzó una tasa de éxito del 66 %, en comparación con el 45 % de la versión 3-0324 y la versión R1. En la versión multilingüe, la versión 3.1 resolvió el 54.5 % de los problemas, casi el doble de la tasa de éxito aproximada del 30 % de las otras versiones. En la evaluación de Terminal-Bench, que prueba si el modelo puede completar tareas correctamente en un entorno Linux real, DeepSeek-V3.1 logró el 31 % de las tareas, en comparación con el 13 % y el 6 % de las otras versiones, respectivamente. Estas mejoras demuestran que DeepSeek-V3.1 es más fiable al ejecutar código y operar en entornos de herramientas reales.

Los puntos de referencia de recuperación de información también favorecen a DeepSeek-V3.1 en navegación, búsqueda y respuesta a preguntas. En la evaluación BrowseComp, que requiere navegar y extraer respuestas de una página web, V3.1 respondió correctamente al 30% de las preguntas, en comparación con el 9% de R1. En la versión china, DeepSeek-V3.1 logró una precisión del 49%, en comparación con el 36% de R1. En el Hard Language Exam (HLE), V3.1 superó ligeramente a R1, logrando una precisión del 30% al 25%, respectivamente. En tareas de búsqueda profunda como xbench-DeepSearch, que requieren sintetizar información en diferentes fuentes, V3.1 obtuvo una puntuación del 71% frente al 1% de R55. DeepSeek-V3.1 también demostró una pequeña pero constante ventaja en puntos de referencia como (razonamiento estructurado), SimpleQA (respuesta a preguntas fácticas) y Seal0 (respuesta a preguntas específicas del dominio). En general, V3.1 superó significativamente a R1 en recuperación de información y respuesta a preguntas ligeras.

En términos de eficiencia de razonamiento, los resultados del uso de tokens demuestran su eficacia. En AIME 2025 (un examen de matemáticas difícil), V3.1-Think logró una precisión comparable o ligeramente superior a R1 (88.4 % frente a 87.5 %), pero utilizó aproximadamente un 30 % menos de tokens. En GPQA Diamond (un examen de posgrado multidominio), los dos modelos fueron casi iguales (80.1 % frente a 81.0 %), pero V3.1 utilizó casi la mitad de tokens que R1. En la prueba de referencia LiveCodeBench, que evalúa el razonamiento del código, V3.1 no solo fue más preciso (74.8 % frente a 73.3 %), sino también más conciso. Esto demuestra que V3.1-Think puede proporcionar un razonamiento detallado evitando la verbosidad.

En general, la versión 3.1 representa un salto generacional significativo en comparación con la versión 3-0324. En comparación con la versión 1, la versión 3.1 logró una mayor precisión en casi todos los puntos de referencia y fue más eficaz en tareas de razonamiento complejas. El único punto de referencia en el que la versión 1 igualó las expectativas fue GPQA, pero a un coste casi el doble.

¿Cómo obtengo una clave API y configuro una cuenta de desarrollo?

Paso 1: Regístrese y cree una cuenta

1. Visita el portal para desarrolladores de DeepSeek (documentación/consola de DeepSeek). Crea una cuenta con tu correo electrónico o proveedor de SSO.
2. Complete cualquier verificación de identidad o configuración de facturación requerida por el portal.

Paso 2: crea una clave API

1. En el panel de control, vaya a Claves de la API → Crear clave. Nombra tu clave (por ejemplo, dev-local-01).
2. Copie la clave y guárdela en un administrador de secretos seguro (consulte las mejores prácticas de producción a continuación).

Consejo: Algunas puertas de enlace y enrutadores de terceros (por ejemplo, CometAPI) le permiten usar una única clave de puerta de enlace para acceder a los modelos de DeepSeek a través de ellos, lo que resulta útil para la redundancia de múltiples proveedores (consulte la API de DeepSeek V3.1 sección).

¿Cómo configuro mi entorno de desarrollo (Linux/macOS/Windows)?

Esta es una configuración simple y reproducible para Python y Node.js que funciona para DeepSeek (puntos finales compatibles con OpenAI), CometAPI y Anthropic.

Requisitos previos

• Python 3.10+ (recomendado), pip, virtualenv.
• Node.js 18+ y npm/yarn.
• curl (para pruebas rápidas).

Entorno de Python (paso a paso)

1. Crear un directorio de proyecto:

mkdir deepseek-demo && cd deepseek-demo
python -m venv .venv
source .venv/bin/activate   # macOS / Linux

# .venv\Scripts\activate    # Windows PowerShell

2. Instalar paquetes mínimos:

pip install --upgrade pip
pip install requests
# Optional: install an OpenAI-compatible client if you prefer one:

pip install openai

3. Guarde su clave API en variables de entorno (nunca la confirme):

export DEEPSEEK_KEY="sk_live_xxx"
export CometAPI_KEY="or_xxx"
export ANTHROPIC_KEY="anthropic_xxx"

(Uso de Windows PowerShell $env:DEEPSEEK_KEY = "…")

Entorno de nodo (paso a paso)

1. Inicializar:

mkdir deepseek-node && cd deepseek-node
npm init -y
npm install node-fetch dotenv

2. Créar un .env archivo:

DEEPSEEK_KEY=sk_live_xxx
CometAPI_KEY=or_xxx
ANTHROPIC_KEY=anthropic_xxx

¿Cómo llamo directamente a DeepSeek-V3.1? — Ejemplos de código paso a paso

La API de DeepSeek es compatible con OpenAI. A continuación se muestran copiar pegar ejemplos: curl, Python (solicitudes y estilo SDK de openai) y Node.

Paso 1: Ejemplo de rizo simple

curl https://api.deepseek.com/v1/chat/completions \
  -H "Authorization: Bearer $DEEPSEEK_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-chat-v3.1",
    "messages": [
      {"role":"system","content":"You are a concise engineering assistant."},
      {"role":"user","content":"Give a 5-step secure deployment checklist for a Django app."}
    ],
    "max_tokens": 400,
    "temperature": 0.0,
    "reasoning_enabled": true
  }'

Notas: reasoning_enabled Activa o desactiva el modo Pensar (marca del proveedor). El nombre exacto de la marca puede variar según el proveedor; consulte la documentación del modelo.

Paso 2: Python (solicitudes) con telemetría simple

import os, requests, time, json

API_KEY = os.environ
URL = "https://api.deepseek.com/v1/chat/completions"

payload = {
  "model": "deepseek-chat-v3.1",
  "messages": [
    {"role": "system", "content": "You are a helpful coding assistant."},
    {"role": "user", "content": "Refactor this Flask function to be testable: ..."}
  ],
  "max_tokens": 600,
  "temperature": 0.1,
  "reasoning_enabled": True
}

start = time.time()
r = requests.post(URL, headers={
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}, json=payload, timeout=60)

elapsed = time.time() - start
print("Status:", r.status_code, "Elapsed:", elapsed)
data = r.json()
print(json.dumps(data, indent=2))

CometAPI: acceso completamente gratuito a DeepSeek V3.1

Para los desarrolladores que buscan acceso inmediato sin registro, CometAPI ofrece una alternativa atractiva a DeepSeek V3.1 (nombre del modelo: deepseek-v3-1-250821; deepseek-v3.1). Este servicio de puerta de enlace agrega múltiples modelos de IA a través de una API unificada, lo que proporciona acceso a DeepSeek y ofrece otras ventajas, como conmutación por error automática, análisis de uso y facturación simplificada entre proveedores.

Primero, crea una cuenta CometAPI en https://www.cometapi.com/El proceso completo solo toma dos minutos y solo requiere la verificación de la dirección de correo electrónico. Una vez iniciada la sesión, genere una nueva clave en la sección "Clave API". https://www.cometapi.com/ ofrece créditos gratuitos para nuevas cuentas y un 20% de descuento sobre el precio oficial de la API.

La implementación técnica requiere cambios mínimos en el código. Simplemente cambie el punto final de su API de una URL directa de DeepSeek a la puerta de enlace de CometAPI.

Nota: La API admite la transmisión (stream: true), max_tokens, temperatura, secuencias de detención y funciones de llamada de funciones similares a otras API compatibles con OpenAI.

¿Cómo puedo llamar a DeepSeek usando SDK antrópicos?

DeepSeek proporciona un punto final compatible con Anthropic para que pueda reutilizar los SDK de Anthropc o las herramientas de Claude Code apuntando el SDK a https://api.deepseek.com/anthropic y estableciendo el nombre del modelo en deepseek-chat (o deepseek-reasoner donde sea compatible).

Invocar el modelo DeepSeek a través de la API antrópica

Instale el SDK de Anthropic: pip install anthropic. Configure su entorno:

export ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic  
export ANTHROPIC_API_KEY=YOUR_DEEPSEEK_KEY

Crear un mensaje:

import anthropic
client = anthropic.Anthropic()
message = client.messages.create(
model="deepseek-chat",
max_tokens=1000,
system="You are a helpful assistant.",
messages=[
{
"role": "user",
"content": [
{
"type": "text",
"text": "Hi, how are you?"
}
]
}
]
)
print(message.content)

Utilice DeepSeek en Claude Code

Instalar: npm install -g @anthropic-ai/claude-code. Configura tu entorno:

export ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic
export ANTHROPIC_AUTH_TOKEN=${YOUR_API_KEY}
export ANTHROPIC_MODEL=deepseek-chat
export ANTHROPIC_SMALL_FAST_MODEL=deepseek-chat

Ingrese al directorio del proyecto y ejecute el código Claude:

cd my-project  
claude

Utilice DeepSeek en Claude Code a través de CometAPI

CometAPI es compatible con Claude Code. Tras la instalación, al configurar el entorno, simplemente reemplace la URL base por https://www.cometapi.com/console/ y la clave por la clave de CometAPI para usar el modelo DeepSeek de CometAPI en Claude Code.

# Navigate to your project folder cd your-project-folder 

# Set environment variables (replace sk-... with your actual token) 
export ANTHROPIC_AUTH_TOKEN=sk-... 
export ANTHROPIC_BASE_URL=https://www.cometapi.com/console/ 
# Start Claude Code 

claude

Notas:

• DeepSeek asigna nombres de modelos antrópicos no admitidos a deepseek-chat.
• La capa de compatibilidad antrópica admite system, messages, temperature, streaming, secuencias de parada y matrices de pensamiento.

¿Cuáles son las mejores prácticas de producción concretas (seguridad, costo, confiabilidad)?

A continuación se presentan patrones de producción recomendados que se aplican a DeepSeek o cualquier uso de LLM de gran volumen.

Secretos e identidad

• Almacene las claves API en un administrador secreto (no utilice .env en producción). Rote las claves periódicamente y cree claves por servicio con el mínimo privilegio.
• Utilice proyectos/cuentas separados para desarrollo/preparación/producción.

Límites de velocidad y reintentos

• Implementar retroceso exponencial En HTTP 429/5xx con fluctuación. Límite de reintentos (p. ej., 3 intentos).
• Utilice claves de idempotencia para solicitudes que puedan repetirse.

Ejemplo de Python: reintento con retroceso

import time, random, requests

def post_with_retries(url, headers, payload, attempts=3):
    for i in range(attempts):
        r = requests.post(url, json=payload, headers=headers, timeout=60)
        if r.status_code == 200:
            return r.json()
        if r.status_code in (429, 502, 503, 504):
            backoff = (2 ** i) + random.random()
            time.sleep(backoff)
            continue
        r.raise_for_status()
    raise RuntimeError("Retries exhausted")

Manejo de costos

• Limitar max_tokens y evitar solicitar accidentalmente salidas enormes.
• Respuestas del modelo de caché Cuando corresponda (especialmente para solicitudes repetidas). DeepSeek distingue explícitamente entre el éxito y el fracaso de la caché en el precio: el almacenamiento en caché ahorra dinero.
• Use deepseek-chat para pequeñas respuestas rutinarias; reserva deepseek-reasoner para los casos que realmente necesitan CoT (es más caro).

Observabilidad y registro

• Registra únicamente metadatos de solicitudes en texto plano (hashes de solicitud, recuento de tokens, latencias). Evita registrar datos completos de usuario o contenido sensible. Almacena los ID de solicitud/respuesta para la conciliación de soporte y facturación.
• Realice un seguimiento del uso del token por solicitud y exponga presupuestos/alertas sobre costos.

Controles de seguridad y alucinaciones

• Use Salidas de herramientas y validadores deterministas para cualquier cosa que sea crítica para la seguridad (financiera, legal, médica).
• Para salidas estructuradas, utilice response_format+Esquema JSON y valida las salidas antes de tomar acciones irreversibles.

Patrones de implementación

• Ejecute llamadas de modelo desde un proceso de trabajo dedicado para controlar la simultaneidad y las colas.
• Descargue trabajos pesados ​​a trabajadores asincrónicos (tareas de Celery, Fargate, trabajos de Cloud Run) y responda a los usuarios con indicadores de progreso.
• Para necesidades de latencia/rendimiento extremos, considere los SLA del proveedor y si debe auto hospedarlo o usar aceleradores del proveedor.

Nota de cierre

DeepSeek-V3.1 es un modelo híbrido pragmático, diseñado tanto para chat rápido como para tareas complejas de agencia. Su API compatible con OpenAI facilita la migración en muchos proyectos, mientras que las capas de compatibilidad con Anthropic y CometAPI lo hacen flexible para los ecosistemas existentes. Los benchmarks y los informes de la comunidad muestran prometedoras compensaciones entre coste y rendimiento; sin embargo, como con cualquier modelo nuevo, valídalo en tus cargas de trabajo reales (solicitudes, llamadas a funciones, comprobaciones de seguridad, latencia) antes de su implementación completa en producción.

En CometAPI, puede ejecutarlo de forma segura e interactuar con él a través de una API compatible con OpenAI o una interfaz fácil de usar. Area de juegos, sin límites de velocidad.

👉 Implemente DeepSeek-V3.1 en CometAPI ahora!

¿Por qué utilizar CometAPI?

• Multiplexación de proveedores:cambiar de proveedor sin reescribir el código.
• Facturación/métricas unificadas:Si enruta varios modelos a través de CometAPI, obtendrá una única superficie de integración.
• Metadatos del modelo:ver la longitud del contexto y los parámetros activos por variante del modelo.