Como escrever prompt para tarefa repetitiva no DeepSeek V4.1 Flash e receber sempre o mesmo formato de saída

Prompt de tarefa repetitiva é fácil de aprovar e difícil de confiar

Ele acerta nas dez primeiras execuções, você olha, acha massa, sobe pra produção… e quebra lá na milésima, quando um campo some e o script que consome o JSON morre de madrugada

A DeepSeek lançou oficialmente o DeepSeek-V4.1-Flash em 10 de setembro de 2026, com melhorias em texto e agentes e entendimento visual multimodal nativo

É um MoE de 552 bilhões de parâmetros totais, com janela de contexto de 1 milhão de tokens

Traduzindo: modelo de uso industrial, daqueles que tu deixa rodando em lote em cima de milhares de itens

E é exatamente pra esse cenário que esse guia serve: você roda a MESMA tarefa muitas vezes e precisa que a saída caia sempre no mesmo formato, sem variação criativa 🙂

O que você precisa antes de escrever o prompt

Antes de sair escrevendo instrução, três decisões de infra que mudam o texto do prompt:

1. Endpoint e nome do modelo: as chamadas vão para https://api.deepseek.com/chat/completions e o campo model recebe deepseek-flash (o outro valor aceito é deepseek-v4-pro)

2. O aviso de roteamento: a partir de 14 de setembro de 2026, meio-dia de Pequim (04:00 UTC), todas as chamadas a deepseek-v4-pro passam a ser atendidas pelo V4.1 Flash e cobradas na tabela do V4.1 Flash

Formação Recomendada

Formação Claude Code

Domine Claude Code do absoluto zero até o avançado

• 116 aulas
• 4 projetos
• 9h 23min

Conhecer formação

Ou seja: mesmo quem não trocou o nome do modelo no código vai cair no Flash, então vale revisar o prompt antes disso

3. Cliente: dá pra usar o SDK da OpenAI, e isso importa por um motivo bem prático, o controle do modo raciocínio vai dentro de extra_body

Quem quer rodar local: os pesos estão publicados no Hugging Face, no repositório deepseek-ai/DeepSeek-V4.1-Flash, sob licença MIT

E tem uma decisão que precisa sair ANTES da primeira linha de prompt: raciocínio ligado ou desligado? Isso muda o padrão de max_tokens, e um padrão errado é metade dos JSONs truncados que você vai ver depois

Como escrever o prompt passo a passo para a saída sair sempre igual

1. Escreva UMA instrução curta no system

A regra vive em um lugar só

Quando você repete a mesma exigência no system, no user e de novo no fim da mensagem, cada repetição vira uma chance de conflito sutil de redação, e o modelo escolhe qual seguir

system = (
    "Voce classifica chamados de suporte. "
    "Responda apenas com um objeto json valido, sem nenhum texto fora do json."
)

O erro comum deste passo: escrever um system gigante com contexto de empresa, tom de voz e cinco parágrafos de regra

Instrução longa não é instrução forte, é instrução com mais superfície pra o modelo interpretar diferente entre uma execução e outra

2. Coloque a palavra json na mensagem

Não é estilo, é exigência: a documentação pede que a palavra "json" apareça no prompt de sistema ou no do usuário quando você usa o modo de saída JSON

Repare que o exemplo do passo anterior já cumpre isso

O erro comum deste passo: ligar o modo JSON no código e deixar o prompt falando só em "responda em formato estruturado"

Esse é o caminho mais curto pra requisição travada, e eu explico o porquê logo abaixo

3. Mostre um exemplo de entrada e o exemplo do formato de saída

A doc recomenda incluir um exemplo do formato JSON desejado, e na prática esse é o passo que mais estabiliza tarefa repetitiva

EXEMPLO = """
Entrada:
"Nao consigo logar desde ontem, ja troquei a senha duas vezes"

Saida json:
{"categoria": "acesso", "gravidade": "alta", "resumo": "usuario sem login apos troca de senha"}
"""

Mostrar vale mais que descrever, é a mesma lógica de quando você precisa descrever uma tela sem design pronto: exemplo concreto elimina a ambiguidade que a frase bonita não elimina

O erro comum deste passo: dar três exemplos com formatos ligeiramente diferentes entre si

Um exemplo consistente vale mais que três divergentes

4. Feche o formato no código, não só no texto

Prompt pedindo JSON é torcida, response_format é contrato

from openai import OpenAI

# a chamada bate em https://api.deepseek.com/chat/completions
client = OpenAI(api_key="SUA_CHAVE", base_url="https://api.deepseek.com")

resp = client.chat.completions.create(
    model="deepseek-flash",
    messages=[
        {"role": "system", "content": system + EXEMPLO},
        {"role": "user", "content": texto_do_chamado},
    ],
    response_format={"type": "json_object"},
)

Pra contrato mais rígido, dá pra ir além do JSON básico e usar saída estruturada com JSON Schema, no response_format do tipo json_schema, que leva os campos name e schema

    response_format={
        "type": "json_schema",
        "name": "chamado",
        "schema": {
            "type": "object",
            "properties": {
                "categoria": {"type": "string"},
                "gravidade": {"type": "string"},
                "resumo": {"type": "string"},
            },
        },
    },

O erro comum deste passo: achar que ligar o response_format dispensa a instrução de JSON no texto

Não dispensa, os dois andam juntos

5. Dimensione o max_tokens pro JSON não truncar

O max_tokens aceita de 1 até 384K (393216)

Se você não define, o padrão depende do modo:

A própria documentação do modo JSON recomenda definir max_tokens de forma razoável justamente pra saída não ser cortada no meio

O erro comum deste passo: calcular o limite pelo exemplo pequeno que você testou

Dimensiona pelo item mais gordo do lote, não pelo mais magro

6. Baixe a temperature

O temperature tem padrão 1.0 e aceita valores entre 0 e 2

Valores mais baixos deixam a saída mais focada e determinística, que é exatamente o que tarefa repetitiva quer

    temperature=0,

O erro comum deste passo: deixar o padrão porque "o prompt já está bom"

Prompt bom com temperature alta ainda te dá variação de redação em campo de texto livre, e variação de redação é ruído no consumo automático

7. Decida o raciocínio de forma explícita

O modo raciocínio é controlado pelo parâmetro thinking, passado dentro de extra_body no SDK da OpenAI

    extra_body={"thinking": {"type": "disabled"}},

Ou {"thinking": {"type": "enabled"}} quando a tarefa pede mais cabeça

Tem também o reasoning_effort, que aceita none, low, high e max: o none desliga o modo raciocínio e os demais ligam

E atenção nisso: o padrão é modo raciocínio LIGADO com esforço high

No modo raciocínio, a cadeia de pensamento volta no campo reasoning_content, no mesmo nível de content

O erro comum deste passo: ler a resposta inteira e tentar dar parse em tudo

O JSON está em content, o raciocínio está em reasoning_content, e misturar os dois é bug garantido

8. Tarefa que aciona função? Vai de modo estrito de tool calls

No modo estrito de tool calls, a saída obedece ao JSON Schema da função

Pra isso o schema precisa listar todas as propriedades em required e trazer additionalProperties como false

schema_da_funcao = {
    "type": "object",
    "properties": {
        "categoria": {"type": "string"},
        "gravidade": {"type": "string"},
        "resumo": {"type": "string"},
    },
    "required": ["categoria", "gravidade", "resumo"],
    "additionalProperties": False,
}

O erro comum deste passo: marcar como required só os campos "importantes" e deixar o resto opcional

Campo opcional em tarefa que roda mil vezes é campo que um dia não vem

Quando a resposta foge do padrão: 4 falhas comuns e como corrigir

Falha 1: a requisição trava cuspindo espaço em branco sem parar

Sintoma: a chamada não retorna, e a saída é um fluxo interminável de espaços em branco até bater o limite de tokens

Causa: o JSON Output foi ligado sem instrução de JSON na mensagem, e a documentação avisa exatamente sobre isso

Solução: colocar a palavra "json" no prompt de sistema ou do usuário, com o exemplo do formato desejado

Prevenção: um teste automático que falha se a string "json" não estiver no prompt montado, antes de subir o lote

Falha 2: content vazio

Sintoma: a resposta chega, mas o content vem vazio

Causa: a documentação avisa que a API pode ocasionalmente devolver content vazio nesse modo

Solução: tratar isso como caso esperado no código chamador, com retry

Prevenção: nunca assumir que a resposta é sempre parseável, mesmo com tudo configurado certo

Falha 3: JSON cortado no meio

Sintoma: o parser estoura porque a string acaba na metade de um campo

Causa: max_tokens curto demais pro tamanho real da saída

Solução: subir o limite (a faixa vai até 393216) e conferir qual padrão está valendo pro seu modo

Prevenção: logar o tamanho da saída de cada execução e olhar o topo da distribuição, não a média

Falha 4: campo extra ou campo faltando entre execuções

Sintoma: roda 200 vezes, e três respostas vêm com um campo a mais ou a menos

Causa: formato aberto demais, o json_object garante JSON válido, não garante o SEU JSON

Solução: migrar de json_object pra json_schema, ou pro modo estrito de tool calls quando a tarefa aciona função

Prevenção: validar a saída contra o schema ANTES de gravar em qualquer lugar

Essa prevenção transversal é a mais importante das quatro, e é a mesma ideia de escrever um prompt que se verifica sozinho: a checagem não pode depender de você estar olhando a tela

Prompt fixo em escala: cache de contexto, horário e custo por milhão de tokens

Aqui a coisa fica interessante, porque repetição vira dinheiro

O Context Caching em disco vem ligado por padrão pra todos os usuários, sem necessidade de mudar código

Porém (e é um porém grande) o cache só é acionado quando o prefixo da requisição coincide integralmente com um prefixo já armazenado, contado a partir do token 0

A unidade de armazenamento é de 64 tokens, e conteúdo menor que isso não é cacheado

A consequência prática pra quem escreve prompt é direta: parte FIXA primeiro (instrução, exemplos, schema), parte variável no fim

Se você joga o dado do cliente no começo do system só porque ficou mais bonitinho de ler, o prefixo muda a cada chamada e o cache nunca bate

Pra conferir se está funcionando, é só olhar o usage da resposta:

print(resp.usage.prompt_cache_hit_tokens)
print(resp.usage.prompt_cache_miss_tokens)

Esses dois campos mostram quantos tokens de entrada bateram no cache e quantos não bateram

E o preço da nova série Flash, fora do horário de pico:

O horário de pico da API é 01:00 às 04:00 e 06:00 às 10:00 UTC, de segunda a sexta

Todas as demais horas são fora de pico

Juntando as duas coisas: prompt com prefixo estável + lote agendado fora dos horários de pico

O teste na prática: rotina de SEO a cada 3 horas e commit diário às 10h

Esse papo de formato fechado não é teoria de API, é o que separa uma rotina que se sustenta de uma que você precisa babysittar

No vídeo abaixo eu mostro isso em outro contexto, agendando prompts como tarefa recorrente

Minha defesa lá é simples: boa parte do trabalho de um projeto é rotineira (commit, revisão de segurança, checagem de performance), e é justamente essa parte que vale virar prompt agendado, pra não depender da memória do dev

Uma das rotinas que eu criei foi de revisão de SEO, rodando a cada 3 horas

O prompt já embutia o formato de saída: identificar os principais problemas, gerar um arquivo de auditoria e incluir níveis de gravidade

E isso é essencial em tarefa agendada por um motivo bobo e decisivo: eu não estou na frente da tela quando ela roda, então preciso do relatório salvo pra consultar depois

O resultado saiu como relatório em markdown, com os problemas classificados por gravidade, exatamente na estrutura que eu pedi: 7 problemas de gravidade média, 3 de baixa e 1 de alta

Olha esse número por um segundo

Se amanhã a saída vier com o campo de gravidade escrito diferente, ou com uma categoria nova que eu não previ, a contagem por gravidade some e qualquer consumo automático desse relatório quebra

Não é o texto que quebra, é o contrato

Uma coisa que eu achei mto massa na hora de montar: antes de executar, a ferramenta montou um plano de implementação da rotina, que eu revisei e confirmei, com os passos de criar o script de verificação, testar a rotina e só então deixar o agendamento rodando

Teve um segundo prompt repetitivo também, desses do dia a dia: verificar se há alterações no projeto, criar commit semântico descrevendo a alteração e enviar pro GitHub, todo dia às 10 da manhã

Eu separo os dois usos por horizonte de tempo: rotina de frequência curta, ligada ao desenvolvimento de um projeto específico, eu crio pelo chat mesmo; rotina perpétua, como o commit que não pode ser esquecido, eu cadastro como tarefa fixa

E tem um ponto cego clássico que isso cobre: projeto feito no vibe coding costuma ficar inseguro porque o prompt do dia a dia esquece esse ângulo

Uma rotina agendada de revisão resolve isso sem esforço extra, e por isso eu acho agendamento um recurso subestimado, ideias parecidas já rondavam antes de existir suporte nativo

Conclusão

Prompt de tarefa repetitiva é contrato, não conversa

O resumo do que segura o formato ao longo de milhares de execuções: uma instrução curta e única no system, a palavra json na mensagem, exemplo de entrada e de saída, response_format fechado, max_tokens dimensionado pelo pior caso, temperature baixa, raciocínio decidido de forma explícita e a parte fixa do prompt no começo pra o cache bater

Próximo passo bem concreto, pra hoje: pega a tarefa que tu mais repete, escreve a instrução única com exemplo de saída, liga o json_schema, roda 50 vezes com temperature baixa e MEDE quantas fugiram do formato

Se fugiu nenhuma em 50, aí sim tu sobe pra milhares

Se fugiu uma, tu já sabe onde ela vai te encontrar lá na frente… 😀

até o próximo post!