Un servicio de modelo compatible con API tiene una tarea poco glamurosa pero crítica: convertir varios formatos de solicitud públicos en el prompt exacto esperado por un modelo, y luego transformar los tokens generados de vuelta en la forma de respuesta esperada por el cliente. deepseek-recipe encapsula esa capa de traducción para DeepSeek V4 y V4.1.

No ejecuta el modelo. No abre un puerto HTTP, ejecuta herramientas, busca en la web ni almacena conversaciones. Mantener visible ese límite ahorrará tiempo en este tutorial: el resultado es un prompt renderizado que un backend de inferencia podría consumir, no una respuesta del modelo.

Instalación del binding de Python

El paquete oficial requiere Python 3.10 o superior:

Instala el paquete oficial mediante pip:

python3 -m pip install deepseek-recipe

Para un proyecto reproducible, instálalo dentro de un entorno virtual y fija la versión después de la primera ejecución verificada. El repositorio se publicó recientemente en septiembre de 2026 y su API podría seguir evolucionando. Registra tanto la versión del paquete Python como la codificación V4/V4.1 seleccionada por tu aplicación.

El paquete está respaldado por una familia de crates de Rust. Los usuarios de Python no necesitan reescribir su servicio en Rust; el binding expone los tipos de conversión y codificación requeridos para una integración normal.

Generar una conversación V4.1 mínima

Crea un script pequeño basado en el ejemplo oficial:

from deepseek_recipe import (
    ChatCompletionRequest,
    ConversionOptions,
    DeepseekV41Encoding,
)

request = ChatCompletionRequest({
    "model": "deepseek-flash",
    "messages": [
        {"role": "system", "content": "Answer with one short paragraph."},
        {"role": "user", "content": "Explain sparse attention to a Python developer."},
    ],
    "temperature": 0.2,
})

converted = request.convert(ConversionOptions())
encoding = DeepseekV41Encoding()
rendered = encoding.render_conversation(converted.conversation)

print(rendered.prompt)

Hay dos etapas deliberadas. request.convert(...) mapea la carga útil de Chat Completions en la representación de Conversación compartida de la biblioteca. render_conversation(...) aplica la codificación del prompt V4.1. Mantenerlos separados permite que un servicio API normalice diferentes protocolos externos antes de comprometerse con un diseño de tokens específico del modelo.

La cadena del modelo en la solicitud es parte de la carga útil orientada al cliente; el objeto de codificación seleccionado controla cómo se genera la conversación normalizada. No infieras que cualquier nombre de modelo arbitrario descarga o selecciona pesos automáticamente. Tu servicio circundante debe validar el modelo solicitado y enrutar el prompt a un backend apropiado.

Try DeepSeek on MidassAI

Inspeccionar antes de conectar la inferencia

Imprime el prompt solo en un fixture de desarrollo local, nunca en logs de producción que contengan datos de usuario. Confirma que los mensajes de sistema y usuario estén representados en el orden previsto. Añade ejemplos Unicode, contenido vacío y multilínea. Si tu servicio soporta imágenes o herramientas, crea fixtures separados para cada uno en lugar de asumir que el caso solo de texto prueba la compatibilidad.

Este es también el punto adecuado para pruebas de referencia (golden tests). Almacena un pequeño conjunto de cargas útiles de entrada no sensibles y expectativas estructurales aprobadas. La salida codificada exacta puede cambiar legítimamente entre versiones del paquete, así que decide si una actualización de versión debe actualizar las instantáneas o fallar hasta ser revisada.

Como mínimo, prueba:

un mensaje de sistema y uno de usuario;
una conversación multiturno con una respuesta del asistente;
el modo de pensamiento y cada valor de esfuerzo de razonamiento soportado que expongas;
temperature, top_p y límites de tokens de salida en sus bordes permitidos;
una herramienta de función de cliente con argumentos;
roles malformados, tipos de contenido y opciones no soportadas.

El último grupo importa porque la compatibilidad del protocolo también es compatibilidad de rechazo. Un servicio que descarta silenciosamente un campo no soportado es más difícil de depurar que uno que devuelve un error preciso.

Conocer qué puede traducir la biblioteca

El alcance actual cubre Messages, Chat Completions y solicitudes estilo Responses, incluyendo streaming y respuestas completas. La representación compartida soporta texto, imágenes, pensamiento y llamadas a herramientas del cliente. El análisis de salida cubre contenido de pensamiento, llamadas a herramientas, objetos JSON y secuencias de parada.

Para solicitudes Responses, se soportan los namespaces de herramientas y la herramienta personalizada apply_patch. Eso no significa que la biblioteca aplique parches. Representa y analiza la llamada a la herramienta; una aplicación host aún decide si la herramienta existe, solicita permiso, la ejecuta y devuelve su resultado al modelo.

El preprocesamiento de imágenes V4.1 está disponible a través del componente de imagen y OpenCV. Las imágenes pueden llegar como datos base64 o URLs externas. Un servicio de producción debe establecer límites de tamaño, comprobaciones de tipo de medio, tiempos de espera de descarga y restricciones de red antes de entregar contenido remoto al código de preprocesamiento.

Gestionar campos no compatibles explícitamente

A partir de la versión verificada, logprobs y top_logprobs no son compatibles. Tampoco lo son el contenido de documentos, audio o video, recuperación de archivos por file_id, múltiples completaciones mediante n > 1, o contenido de pensamiento cifrado.

Las expectativas de salida estructurada necesitan cuidado. La biblioteca puede analizar salida de objetos JSON, pero no enforce JSON Schema, expresiones regulares ni definiciones estrictas de herramientas. Si tu API anuncia esas garantías, la validación debe ocurrir en otro lugar. Un objeto JSON analizado aún puede violar el esquema del llamador.

El almacenamiento de conversaciones también está fuera del paquete. previous_response_id no recupera contexto anterior. Tu servicio HTTP debe resolver el estado de conversación almacenado y pasar los mensajes resultantes a la conversión, o rechazar el campo claramente.

Las herramientas de servidor como web_search no son soportadas porque la capa de recipe no ejecuta herramientas. Si un cliente envía tal solicitud, no la conviertas en una llamada de función de cliente sin documentar la diferencia semántica.

Integrarlo en un servicio API sin difuminar responsabilidades

Un pipeline de servicio limpio tiene cuatro límites:

Autenticación, límites de tasa, límites de tamaño de cuerpo y validación de API pública.
Normalización deepseek-recipe y codificación V4/V4.1.
Un backend de inferencia que consume tokens y produce tokens generados.
Análisis de recipe, orquestación de herramientas propiedad de la aplicación y streaming HTTP.

Mantén métricas alrededor de cada límite. El tiempo de conversión de solicitud, el tiempo hasta el primer token generado, el tiempo de espera de herramienta y el tiempo de serialización de respuesta responden diferentes preguntas operativas. Combinarlos en un número de latencia único hace que las regresiones sean difíciles de localizar.

No pases prompts renderizados a través de logs o sistemas de trazabilidad por defecto. Registra metadatos seguros como conteo de mensajes, tipos de contenido, versión de codificación, conteo de tokens y errores de conversión. Si el registro de carga útil muestreada es inevitable, hazlo opt-in, anonimizado, con control de acceso y de corta duración.

Cuándo este tutorial no es la ruta adecuada

Usa deepseek-recipe cuando estés construyendo o adaptando un servicio de inferencia y necesites conversión de protocolo específica de DeepSeek. Si solo quieres llamar a un endpoint existente compatible con DeepSeek, usa el SDK del cliente de ese servicio o su API HTTP. Añadir un codificador de prompts a un cliente de aplicación duplica el comportamiento del servidor y puede hacer que las actualizaciones sean más difíciles.

El paquete es más valioso precisamente porque no es un servidor todo en uno. Ofrece a los equipos de infraestructura una capa de conversión compartida y testeable mientras deja el despliegue, programación, seguridad y herramientas bajo su control. Una primera integración exitosa termina con un prompt verificado y una lista de campos no soportados, no con una afirmación de que toda la pila de servicio está completa.

Fuente verificada: repositorio oficial de deepseek-recipe, accedido el 14 de septiembre de 2026.

Convertir Solicitudes API para DeepSeek V4.1 con Python