Curso
Trabajar con DeepSeek en Python
3 h
1.3K
Trabajar con DeepSeek en Python
Aprende a crear aplicaciones utilizando los modelos R1 y V3 de DeepSeek.
¿Qué es DeepSeek V4.1 Flash?
DeepSeek ofrece V4.1 Flash a través de la API bajo el ID de modelo deepseek-flash. Acepta entrada de imágenes, admite modos con y sin razonamiento, tiene una ventana de contexto de 1M de tokens y puede devolver hasta 384K tokens mediante Chat Completions y la Responses API.
Nuestro resumen de DeepSeek V4.1 Flash cubre el lanzamiento, la arquitectura y los benchmarks.
¿Cómo funciona DeepSeek V4.1 Flash?
DeepSeek describe V4.1 Flash como una espina dorsal MoE de 552B parámetros, mientras que Hugging Face informa de 763B parámetros para el checkpoint publicado. La diferencia se debe sobre todo a la memoria condicional Engram de 196B parámetros, más el codificador y proyector de visión: todos incluidos en el checkpoint pero fuera de la espina dorsal MoE.
Su diseño Causal Encoder-Decoder reutiliza estados cacheados del encoder, con 8B parámetros activos por token durante la entrada y 16B durante la salida.
¿Qué hay de nuevo en DeepSeek V4.1 Flash?
V4.1 Flash es el primer modelo de la nueva familia V4.1, con comprensión visual integrada de forma nativa. Las incrustaciones visuales y de texto se entrenan conjuntamente desde el inicio del preentrenamiento, en lugar de añadirse después como en el experimental V4-Flash-Vision-Exp.
La Responses API es anterior a V4.1 Flash; DeepSeek añadió compatibilidad nativa durante el despliegue de V4. Los nombres retirados deepseek-v4-flash y deepseek-v4-flash-vision-exp ahora redirigen a V4.1 Flash.
¿Cuánto cuesta DeepSeek V4.1 Flash?
El precio de DeepSeek varía entre horas punta y valle, con tarifas valle al 50% de las de punta. Cuando ejecuté el agente, la entrada cacheada costaba 0,003 $ por millón de tokens en valle y 0,006 $ en punta; la entrada sin caché, 0,15 $ en valle y 0,30 $ en punta; y la salida, 0,60 $ en valle y 1,20 $ en punta, según la página de precios de DeepSeek.
Las horas punta son de 01:00 a 04:00 y de 06:00 a 10:00 UTC, de lunes a viernes, excluyendo festivos nacionales en China. El resto de horas son valle, y los festivos nacionales chinos son valle completos.
Qué vamos a construir: el agente de reparación visual Launch Metrics
Nimbus Analytics Launch Metrics es un dashboard en Flask para visitantes totales, registros, tasa de conversión, ingresos y registros diarios. Coloqué tres bugs en tres archivos y no le dije al agente cuáles eran. El código y el dashboard roto están en este repositorio de GitHub.
Dashboard roto junto al diseño de referencia. Imagen del autor.
Los tres bugs requieren evidencias distintas. Uno se ve en la captura, otro afecta al comportamiento del navegador y otro falla en pytest. El agente no recibe ninguna lista de bugs.
Antes de pasárselo al agente, defino qué significa "arreglado": la batería de pytest debe pasar y una captura nueva debe coincidir visualmente con una imagen de referencia. La opinión del modelo no basta, así que el runner comprueba ambas evidencias.
Cómo funciona el bucle de reparación
El bucle alterna entre una solicitud al modelo y la ejecución local de herramientas. V4.1 Flash devuelve razonamiento, un mensaje o llamadas a herramientas; Python ejecuta las herramientas solicitadas y añade los resultados al historial. El bucle se detiene cuando el modelo responde sin otra llamada a herramienta o llega al límite de catorce turnos.
Bucle de reparación conectando modelo, herramientas y navegador. Imagen del autor.
Cómo configurar la API de DeepSeek V4.1 Flash
Necesitarás Python 3.10 o superior y una clave de la API de DeepSeek con saldo. La API de DeepSeek sigue el formato de solicitudes de OpenAI, así que este proyecto usa el paquete openai de Python con base_url apuntando a DeepSeek.
Crea un entorno virtual e instala lo que necesita el proyecto.
python3 -m venv .venv
source .venv/bin/activate
pip install openai flask playwright pytest python-dotenv requests streamlit
playwright install chromiumLo probé con openai 3.14.1, flask 3.1.3 y playwright 1.63.0. Guarda la clave en un archivo .env en la raíz del proyecto como DEEPSEEK_API_KEY=sk-... y cárgala con python-dotenv. Si tu clave ya funciona con la Responses API, sáltate el siguiente bloque de código; si no, la solicitud comprueba la clave y la base URL.
from openai import OpenAI
import os
from dotenv import load_dotenv
load_dotenv()
client = OpenAI(api_key=os.environ["DEEPSEEK_API_KEY"], base_url="https://api.deepseek.com")
response = client.responses.create(model="deepseek-flash", input="Say hi in five words.")
print(response.output_text)Si imprime un saludo breve, la clave y la base URL funcionan.
Paso 1: muestra al modelo cómo se ve "arreglado"
La primera entrada del agente incluye una captura de referencia, una tarea breve y la URL en vivo. Es la única imagen enviada en un mensaje del usuario. Todas las capturas posteriores llegan desde una herramienta.
El runner envía la imagen de referencia como una URL de datos base64 en cada solicitud. DeepSeek recomienda la Files API cuando se reutiliza una imagen. Un file_id evita reenviar los mismos datos cada vez.
Obtener una reacción inicial antes de permitir cambios
En la imagen adjunta, pedí qué comprobaría primero el modelo, pero no tenía herramientas. Esto me permitió revisar su plan antes de que pudiera editar nada. La respuesta propuso listar los archivos del proyecto, trazar variables CSS y tomar una captura; usé reasoning: {"effort": "high"}, el nivel de razonamiento predeterminado de DeepSeek.
Paso 2: dale al agente herramientas útiles
El agente recibe cuatro function tools y una herramienta personalizada.
-
list_filesyread_fileinspeccionan el proyecto, ambas restringidas adashboard/ytests/. -
run_testsejecuta pytest. -
capture_dashboard_screenshotlanza Chromium en modo headless mediante Playwright.
La herramienta personalizada es apply_patch, declarada como {"type": "custom", "name": "apply_patch"} y aceptada "por compatibilidad con Codex". Cualquier otro nombre de herramienta personalizada devuelve un error 400, mientras que los tipos integrados como búsqueda web y uso del ordenador se ignoran en silencio.
Los argumentos de función llegan como texto JSON y se validan antes de que Python los ejecute. apply_patch llega como entrada de una herramienta personalizada, así que el código lo gestiona aparte y valida el parche antes de escribir archivos. Los errores de herramientas se devuelven al modelo en lugar de detener el bucle.
Enviar de vuelta capturas de Playwright como salida de herramienta
Cuando capture_dashboard_screenshot se ejecuta, su resultado no se guarda en disco. Python lo devuelve como una parte input_image dentro de function_call_output. DeepSeek lee entonces la captura como imagen y no como texto.
history.append({
"type": "function_call_output",
"call_id": item.call_id,
"output": [{"type": "input_image", "image_url": f"data:image/png;base64,{png_b64}"}],
})El agente puede parchear el CSS, tomar otra captura y comprobar si los números se leen bien.
Paso 3: construye el bucle del agente y gestiona tú el historial
El historial vive en una lista de Python porque la API no admite previous_response_id ni conversaciones del lado del servidor. El modo de razonamiento también requiere cada elemento de razonamiento de turnos de herramienta anteriores.
Importante: si insertas la salida de herramientas entre dos llamadas del mismo turno, la siguiente solicitud devuelve un error 400. Añade cada elemento de response.output en orden, luego ejecuta las herramientas y añade sus resultados.
El runner limita el agente a catorce turnos y a los directorios dashboard/ y tests/. No ofrece acceso a shell, valida los argumentos de herramientas y usa pytest para la verificación.
¿DeepSeek V4.1 Flash admite salida estructurada?
Sí. A través de la Responses API, DeepSeek V4.1 Flash acepta un JSON Schema mediante text.format. Chat Completions response_format admite modo JSON pero no esquemas. Tras detenerse el bucle, la solicitud final registra los bugs, arreglos, resultados de tests, resultados de capturas y el método de verificación.
El proyecto también incluye una app en Streamlit en app_streamlit.py. El mismo agente se ejecuta como generador con stream=True, así que la página muestra el texto de razonamiento y las llamadas a herramientas en tiempo real. La barra lateral cambia el esfuerzo de razonamiento y el detalle de imagen.
La UI de Streamlit muestra la ejecución del agente en streaming. Vídeo del autor.
Paso 4: ejecuta el agente de reparación visual
La ejecución parecía terminada tras un parche, pero la página en vivo no estaba de acuerdo.
Encontrar y arreglar los bugs
El agente usó sus dos primeros turnos para observar antes de tocar nada: el primer turno listó los archivos y tomó una captura de referencia; el segundo leyó app.py, index.html, style.css y el archivo de tests.
En el turno tres ejecutó pytest y en el cuatro aplicó un único parche que corrigió la fórmula de conversión, cambió el color de la métrica y alineó la búsqueda en JavaScript con el ID del canvas.
- conversion_rate = data["conversions"] / data["signups"] * 100
+ conversion_rate = data["conversions"] / data["total_visitors"] * 100Al ejecutar las pruebas en el turno cinco, las cinco pasaron. Aquí fue donde la ejecución dejó de ser limpia. Cada nueva captura seguía mostrando un 15% de conversión y un gráfico en blanco.
Detectar el estado obsoleto del sistema y solucionarlo
El agente confirmó que los archivos en disco contenían los arreglos, repitió la captura y comprobó si el servidor cargaba los Python y plantillas modificados. Dos comprobaciones temporales de frescura tampoco aparecieron en la página en vivo.
En el turno catorce, el bucle alcanzó su presupuesto e identificó la causa: run_tests verifica el código en disco, mientras que la captura comprueba un proceso en ejecución con estado obsoleto. Flask se inició con debug=False, así que no había reloader que cargara el módulo de Python actualizado, y la auto-recarga de plantillas no estaba habilitada.
El cambio de CSS sí apareció, mientras que el valor derivado de Python y el gráfico basado en plantilla se mantuvieron obsoletos. Pytest importó app.py desde disco, de modo que tests en verde no garantizaban una página fresca.
Tras reiniciar Flask, el dashboard coincidió con la imagen de referencia. La pieza que faltaba era una herramienta restart_server, no otro parche de código.
Reiniciar hace visibles los cambios parcheados del dashboard. Imagen del autor.
¿El agente arregló el dashboard?
Sí, el agente arregló el dashboard en disco. Solo modificó los tres archivos defectuosos y pytest pasó de cuatro fallos a cinco tests correctos. La página en vivo mostró todos los arreglos tras reiniciar Flask.
Paso 5: mide uso, caché y coste
Como el agente reenvía su historial, las solicitudes posteriores repiten gran parte de la entrada de turnos anteriores. DeepSeek compara ese prefijo repetido con su caché automática. La caché funciona bajo mejor esfuerzo, así que estas cifras aplican solo a esta ejecución.
A lo largo de catorce turnos de reparación y la solicitud final del informe JSON, la API reportó 156.724 tokens de entrada, incluidos 137.088 cacheados, un 87% de acierto. La salida sumó 11.497 tokens, con 9.362 de razonamiento. La ejecución fue en horas valle, así que las quince solicitudes costaron en total unos 0,0103 $.
El razonamiento es la mayor categoría de coste. Imagen del autor.
Un código más grande, más capturas o menos aciertos de caché cambiarían tanto el número de tokens como el coste.
Limitaciones de la API DeepSeek V4.1 Flash que debes conocer
Tres límites de la API importan antes de que este runner crezca más allá de la demo.
-
No hay respuestas en segundo plano, así que los turnos largos bloquean hasta terminar.
-
parallel_tool_callsymax_tool_callsse ignoran; las llamadas paralelas a herramientas permanecen habilitadas. -
No hay truncado automático: las solicitudes que superen el límite de contexto devuelven un error 400.
Checklist de despliegue para un agente DeepSeek V4.1 Flash
Antes de usar este patrón en producción, mueve los controles al código de la aplicación en lugar de a las instrucciones del modelo.
- Impón límites de turnos y costes, y avisa cuando se alcancen
- Restringe el acceso a archivos y valida cada argumento de herramienta
- Incluye herramientas para reiniciar y comprobar el servicio, para verificar con el código actual
- Registra uso de tokens, llamadas a herramientas, resultados de tests y estado final
¿Cuándo usar apply_patch frente a funciones simples?
Usa apply_patch cuando un único cambio deba actualizar varios archivos, como aquí. Ejecuta tests después del parche, porque una sola llamada errónea puede dañar varios archivos.
Usa read_file y write_file cuando cada edición necesite una comprobación o aprobación por separado. Llevan más turnos, pero un mal cambio afecta a un solo archivo cada vez.
Reflexiones finales
El bucle de reparación visual arregló los tres bugs en un solo parche, pero la ejecución no fue un éxito impecable. Pytest pasó mientras Flask seguía sirviendo el Python y la plantilla antiguos, así que el agente no pudo confirmar la página final hasta que reinicié el servidor.
Añadiría una herramienta restart_server y una comparación por píxeles antes de probar una app más grande. Mantendría la restricción de directorios y el límite de turnos, y trataría pytest y la comparación de capturas como comprobaciones separadas. Aprobar una nunca debería sustituir a aprobar la otra.