Curso
Trabalhando com DeepSeek em Python
3 h
1.3K
Trabalhando com o DeepSeek em Python
Saiba como criar aplicativos usando os modelos R1 e V3 do DeepSeek.
O que é o DeepSeek V4.1 Flash?
A DeepSeek oferece o V4.1 Flash pela API sob o ID de modelo deepseek-flash. Ele aceita entrada de imagem, suporta modos com e sem raciocínio, tem janela de contexto de 1M de tokens e pode retornar até 384K tokens via Chat Completions e Responses API.
Nosso panorama do DeepSeek V4.1 Flash cobre o lançamento, a arquitetura e os benchmarks.
Como o DeepSeek V4.1 Flash funciona?
A DeepSeek descreve o V4.1 Flash como um backbone MoE de 552B parâmetros, enquanto o Hugging Face reporta 763B parâmetros para o checkpoint publicado. A diferença é majoritariamente a memória condicional Engram de 196B parâmetros, além do codificador e projetor de visão — componentes presentes no checkpoint, mas fora do backbone MoE.
Seu design Encoder-Decoder Causal reutiliza estados do encoder em cache, com 8B parâmetros ativos por token durante a entrada e 16B durante a saída.
O que há de novo no DeepSeek V4.1 Flash?
O V4.1 Flash é o primeiro modelo da nova família de arquitetura V4.1, com compreensão de imagens nativa. Embeddings visuais e de texto são treinados juntos desde o início do pré-treinamento, em vez de adicionados depois como no experimental V4-Flash-Vision-Exp.
A Responses API é anterior ao V4.1 Flash; a DeepSeek adicionou suporte nativo durante o rollout do V4. Os nomes de modelo aposentados deepseek-v4-flash e deepseek-v4-flash-vision-exp agora apontam para o V4.1 Flash.
Quanto custa o DeepSeek V4.1 Flash?
A precificação da DeepSeek varia por horário de pico, com valores fora de pico a 50% do pico. Quando rodei o agente, entrada em cache custava US$ 0,003 por milhão de tokens fora de pico e US$ 0,006 no pico; entrada sem cache custava US$ 0,15 fora de pico e US$ 0,30 no pico; saída custava US$ 0,60 fora de pico e US$ 1,20 no pico, por sua página de preços.
Os horários de pico vão de 01:00 a 04:00 e de 06:00 a 10:00 UTC, de segunda a sexta, exceto feriados públicos chineses. Todos os demais horários são fora de pico, e feriados públicos na China são inteiramente fora de pico.
O que vamos construir: o agente visual de reparo do Launch Metrics
Nimbus Analytics Launch Metrics é um dashboard Flask para visitantes totais, cadastros, taxa de conversão, receita e cadastros diários. Coloquei três bugs em três arquivos e não contei ao agente quais eram. O código e o dashboard com erros estão neste repositório no GitHub.
Dashboard com erro ao lado do design de referência. Imagem do autor.
Os três bugs exigem evidências diferentes. Um aparece no screenshot, outro afeta o comportamento do navegador e um falha no pytest. O agente não recebe uma lista de bugs.
Antes de passar isso ao agente, eu defino o que significa "corrigido": a suíte de pytest precisa passar e um screenshot novo deve corresponder visualmente a uma imagem de referência. A opinião do modelo sozinha não basta, então o runner checa as duas formas de evidência.
Como funciona o loop de reparo
O loop alterna entre uma requisição ao modelo e a execução local das ferramentas. O V4.1 Flash retorna raciocínio, uma mensagem ou chamadas de ferramentas; o Python executa as ferramentas pedidas e adiciona os resultados ao histórico. O loop para quando o modelo responde sem nova chamada de ferramenta ou atinge o limite de quatorze turnos.
Loop de reparo conectando modelo, ferramentas e navegador. Imagem do autor.
Como configurar a API do DeepSeek V4.1 Flash
Você vai precisar do Python 3.10 ou superior e de uma chave da API da DeepSeek com crédito. A API da DeepSeek segue o formato de requisição da OpenAI, então este projeto usa o pacote openai em Python com base_url apontando para a DeepSeek.
Crie um ambiente virtual e instale o que o projeto precisa.
python3 -m venv .venv
source .venv/bin/activate
pip install openai flask playwright pytest python-dotenv requests streamlit
playwright install chromiumTestei com openai 3.14.1, flask 3.1.3 e playwright 1.63.0. Salve a chave em um arquivo .env na raiz do projeto como DEEPSEEK_API_KEY=sk-... e carregue com python-dotenv. Se sua chave já funciona com a Responses API, pule o próximo bloco; caso contrário, a requisição valida a chave e a 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)Se imprimir uma saudação curta, a chave e a base URL estão ok.
Passo 1: mostre ao modelo como é o "corrigido"
A primeira entrada do agente contém um screenshot de referência, uma tarefa curta e a URL ao vivo. Esta é a única imagem enviada em uma mensagem do usuário. Todos os outros screenshots vêm de uma ferramenta.
O runner envia a imagem de referência como data URL base64 em toda requisição. A DeepSeek recomenda a Files API quando a imagem é reutilizada. Um file_id evita reenviar os mesmos bytes toda vez.
Conseguir uma reação inicial antes de permitir mudanças
Na imagem anexada, perguntei o que o modelo checaria primeiro, mas sem ferramentas disponíveis. Isso me permitiu ver o plano antes que ele pudesse editar algo. A resposta propôs listar os arquivos do projeto, rastrear variáveis CSS e fazer um screenshot; usei reasoning: {"effort": "high"}, o nível padrão de raciocínio da DeepSeek.
Passo 2: dê ao agente ferramentas que ele possa usar
O agente recebe quatro function tools e uma ferramenta customizada.
-
list_fileseread_fileinspecionam o projeto, ambas restritas adashboard/etests/. -
run_testsexecuta o pytest. -
capture_dashboard_screenshotabre o Chromium em modo headless via Playwright.
A ferramenta customizada é apply_patch, declarada como {"type": "custom", "name": "apply_patch"} e aceita "por compatibilidade com o Codex". Qualquer outro nome de ferramenta custom retorna erro 400, enquanto tipos nativos como web search e computer use são ignorados silenciosamente.
Argumentos de função chegam como texto JSON e são validados antes da execução em Python. apply_patch chega como entrada de ferramenta custom, então o código lida separadamente e valida o patch antes de escrever arquivos. Erros de ferramenta são retornados ao modelo em vez de parar o loop.
Enviando screenshots do Playwright como saída de ferramenta
Quando capture_dashboard_screenshot roda, o resultado não é salvo em disco. O Python retorna como uma parte input_image dentro de function_call_output. A DeepSeek então lê o screenshot como imagem, não 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}"}],
})O agente pode corrigir o CSS, tirar outro screenshot e checar se os números ficaram legíveis.
Passo 3: construa o loop do agente e gerencie o histórico por conta própria
O histórico vive em uma lista Python porque a API não suporta previous_response_id ou conversas no servidor. O modo de raciocínio também exige cada item de reasoning dos turnos anteriores de ferramentas.
Importante: se a saída da ferramenta for inserida entre duas chamadas do mesmo turno, a próxima requisição retorna erro 400. Anexe cada item de response.output na ordem, depois rode as ferramentas e anexe seus resultados.
O runner limita o agente a quatorze turnos e aos diretórios dashboard/ e tests/. Não oferece acesso ao shell, valida argumentos de ferramentas e usa pytest para verificação.
O DeepSeek V4.1 Flash suporta saída estruturada?
Sim. Pela Responses API, o DeepSeek V4.1 Flash aceita um JSON Schema via text.format. O response_format do Chat Completions suporta modo JSON, mas não schemas. Depois que o loop termina, a requisição final registra bugs, correções, resultados dos testes, resultados dos screenshots e o método de verificação.
O projeto também inclui um app em Streamlit no app_streamlit.py. O mesmo agente roda como gerador com stream=True, então a página exibe o texto de raciocínio e as chamadas de ferramentas em tempo real. A barra lateral ajusta o esforço de raciocínio e o detalhamento da imagem.
A interface do Streamlit transmite a execução do agente. Vídeo do autor.
Passo 4: rode o agente visual de correção de bugs
A execução parecia concluída após um patch, mas a página ao vivo discordou.
Encontrando e corrigindo os bugs
O agente usou os dois primeiros turnos para observar antes de mexer em algo: o primeiro listou os arquivos e tirou um screenshot de base; o segundo leu app.py, index.html, style.css e o arquivo de testes.
No terceiro turno, rodou o pytest; no quarto, aplicou um patch que corrigiu a fórmula de conversão, alterou a cor da métrica e alinhou a busca no JavaScript com o ID do canvas.
- conversion_rate = data["conversions"] / data["signups"] * 100
+ conversion_rate = data["conversions"] / data["total_visitors"] * 100Rodando os testes no quinto turno, todos os cinco passaram. Foi aqui que a execução deixou de ser "redonda". Cada novo screenshot ainda mostrava 15% de conversão e um gráfico em branco.
Descobrindo obsolescência do processo e corrigindo
O agente confirmou que os arquivos em disco continham as correções, refez o screenshot e investigou se o servidor estava carregando os Python e templates atualizados. Dois checks temporários de frescor também não apareceram na página ao vivo.
No décimo quarto turno, o loop atingiu o limite e identificou a causa: run_tests valida o código em disco, enquanto o screenshot reflete um processo em execução com estado obsoleto. O Flask foi iniciado com debug=False, então não havia reloader para carregar o módulo Python alterado, e o auto-reload de template não estava ativado.
A mudança no CSS apareceu, enquanto o valor vindo do Python e o gráfico do template permaneceram desatualizados. O pytest importou app.py do disco, então testes verdes não garantiam uma página fresca.
Depois que reiniciei o Flask, o dashboard bateu com a imagem de referência. Faltava uma ferramenta restart_server, não outro patch de código.
Reiniciar torna visíveis as mudanças do patch no dashboard. Imagem do autor.
O agente corrigiu o dashboard?
Sim, o agente corrigiu o dashboard em disco. Ele alterou apenas os três arquivos com falhas, e o pytest saiu de quatro falhas para cinco testes passando. A página ao vivo exibiu todas as correções após reiniciar o Flask.
Passo 5: meça uso, cache e custo
Como o agente reenvia seu histórico, requisições posteriores repetem boa parte da entrada dos turnos anteriores. A DeepSeek compara esse prefixo repetido com seu cache automático. O cache opera em regime de melhor esforço, então estes números valem apenas para esta execução.
Ao longo de quatorze turnos de reparo e da requisição final do relatório em JSON, a API reportou 156.724 tokens de entrada, incluindo 137.088 em cache — 87% de acerto. A saída somou 11.497 tokens, com 9.362 de raciocínio. A execução ocorreu fora do horário de pico, então os quinze pedidos custaram cerca de US$ 0,0103.
A saída de raciocínio é a maior categoria de custo. Imagem do autor.
Um codebase maior, mais screenshots ou menos acertos de cache mudariam tanto a contagem de tokens quanto o custo.
Limitações da API do DeepSeek V4.1 Flash
Três limites da API importam antes de levar este runner além do demo.
-
Respostas em segundo plano não são suportadas; turnos longos bloqueiam até terminar.
-
parallel_tool_callsemax_tool_callssão ignorados; chamadas paralelas de ferramentas permanecem ativadas. -
Truncamento automático não é suportado; requisições que excedem o limite de contexto retornam erro 400.
Checklist de deployment do agente DeepSeek V4.1 Flash
Antes de usar este padrão em produção, coloque os controles no código da aplicação em vez de apenas nas instruções do modelo.
- Faça cumprir limites de turnos e de custo, e alerte quando forem atingidos
- Restrinja acesso a arquivos e valide cada argumento de ferramenta
- Inclua ferramentas para reiniciar e checar o serviço, garantindo verificação com o código atual
- Registre uso de tokens, chamadas de ferramentas, resultados dos testes e status final
Quando usar apply_patch vs. funções simples?
Use apply_patch quando uma única mudança precisar atualizar vários arquivos, como aqui. Rode os testes depois do patch, porque uma chamada ruim pode afetar vários arquivos.
Use read_file e write_file quando cada edição exigir uma checagem ou aprovação separada. Leva mais turnos, mas um erro afeta apenas um arquivo por vez.
Considerações finais
O loop de reparo visual corrigiu os três bugs em um único patch, mas a execução não foi um sucesso "limpo". O pytest passou enquanto o Flask ainda servia o Python e o template antigos, então o agente não conseguiu confirmar a página final até eu reiniciar o servidor.
Eu adicionaria uma ferramenta restart_server e uma comparação de pixels antes de testar um app maior. Manteria o limite de turnos e o escopo de arquivos e trataria pytest e comparação de screenshot como verificações separadas. Passar em uma nunca deve substituir passar na outra.
