💡 Como ler este módulo
A camada de providers é o ponto em que DeerFlow vira agnóstico de LLM — ou não. Escolhas feitas aqui ecoam em custo de billing, latência percebida e qualidade de output. Leia os 5 primeiros tópicos antes de ir para o lab: o lab só faz sentido depois de você entender por que está comparando três modelos, não só como.
🔌 ChatOpenAI com base_url — OpenRouter, LiteLLM e gateways
O provider padrão do DeerFlow é uma camada fina em volta do langchain_openai.ChatOpenAI. Ele aceita um base_url arbitrário, o que significa que qualquer servidor OpenAI-compatible vira provider sem uma linha de código novo. É essa propriedade que transforma um harness single-vendor em um router multi-provider — sem reescrever nada.
🎯 Conceito Central
Qualquer endpoint que fale o contrato /v1/chat/completions da OpenAI pode ser apontado pelo DeerFlow via base_url. Isso inclui:
- •OpenRouter — catálogo de ~200 modelos com billing unificado, roteamento por preço ou disponibilidade
- •LiteLLM proxy — self-hosted, deduplica chamadas, aplica rate limit e guardrails por equipe
- •Gateways internos — Portkey, Helicone, Azure OpenAI, qualquer middle-layer com interface OpenAI
- •Ollama / LM Studio — inference local pessoal, útil para testes offline
Config típica em conf.yaml
BASIC_MODEL:
base_url: https://openrouter.ai/api/v1
model: anthropic/claude-sonnet-4.5
api_key: $OPENROUTER_API_KEY
extra_headers:
HTTP-Referer: https://automationsai.net
X-Title: DeerFlow
REASONING_MODEL:
base_url: http://litellm.internal:4000
model: gpt-5-high
api_key: $LITELLM_KEY💡 Dica prática
Não use OpenRouter direto em produção sem um proxy LiteLLM no meio. OpenRouter é excelente para descobrir modelos e consolidar billing, mas você ainda quer rate-limit por equipe, caching de completions idênticas e um único lugar para matar um provider quando ele pifar. LiteLLM cobre isso e aceita OpenRouter como backend — é a combinação padrão.
🆕 use_responses_api — o novo /v1/responses da OpenAI
A OpenAI introduziu /v1/responses como substituto modernizado de /v1/chat/completions. DeerFlow expõe isso via a flag use_responses_api: true no bloco do modelo. Não é cosmético: a Responses API muda como tools são declaradas, como streams emitem eventos, e como state persiste entre chamadas.
📊 Dados: diferenças práticas
- Tools — Responses API aceita built-in tools (web_search, file_search, code_interpreter) sem você implementar; Chat Completions não
- State — Responses API pode manter
previous_response_id, reduzindo tokens enviados em turnos subsequentes - Streaming — eventos tipados (response.created, response.output_text.delta, response.tool_call.delta) em vez de deltas opacos
- Reasoning — modelos o1/o3/gpt-5 expõem
reasoning.effortnativamente apenas na Responses API - Compatibilidade — só funciona em endpoint oficial da OpenAI ou gateways que implementam o contrato (Azure ainda não, em abril/2026)
✓ Quando ligar
- ✓Usando modelo reasoning (o3, gpt-5-high) direto da OpenAI
- ✓Quer built-in web_search sem acoplar Tavily/Serper
- ✓Precisa passar arquivos grandes e reutilizar state entre turnos
- ✓UI consome os eventos tipados para mostrar etapas
✗ Quando NÃO ligar
- ✗Provider é OpenRouter/LiteLLM (ainda não cobrem Responses API completa)
- ✗Modelo não-OpenAI (Claude, Gemini, Qwen) — não entende o formato
- ✗Middleware do DeerFlow faz mutação de
messages[]em Chat format - ✗Precisa previsibilidade de schema — Responses API ainda evolui
🖥️ vLLM local com VllmChatModel
vLLM é o servidor de inference open-source dominante para modelos open-weights. DeerFlow traz um VllmChatModel dedicado que fala vLLM diretamente, com suporte a reasoning de modelos como Qwen3-Thinking, DeepSeek-R1 e variantes Hermes. Não é só "ChatOpenAI apontando para localhost": o provider especializado entende tags de reasoning, continuations e streaming tool-calls em modelos que não seguem o formato OpenAI exatamente.
Suba o servidor vLLM
Container Docker ou binário local, uma GPU suficiente para o modelo escolhido
docker run --gpus all -p 8000:8000 \
vllm/vllm-openai:latest \
--model Qwen/Qwen3-32B-Instruct \
--enable-auto-tool-choice \
--tool-call-parser hermesDeclare o provider no conf.yaml
Use provider: vllm em vez de openai_compatible para ativar o parser específico
REASONING_MODEL:
provider: vllm
base_url: http://localhost:8000/v1
model: Qwen/Qwen3-32B-Instruct
reasoning_parser: hermesValide tool calling
Tool calling em modelos open-weights é historicamente frágil — teste antes de confiar
Rode uma skill simples que força tool call (ex.: data-analysis com CSV minúsculo). Se a skill não aciona a tool, o parser do vLLM está errado ou o modelo não foi fine-tuned para tool calling. Troque o tool-call-parser ou o modelo.
Meça throughput real
vLLM vende throughput, não latência — avalie com carga representativa
Um Qwen3-32B numa H100 dá ~60-80 tokens/s para 1 usuário e 400+ tokens/s agregados em 8 usuários paralelos. Latência por requisição única é pior que GPT-4o-mini via API; ganho real é escala e dados sensíveis.
🔑 Providers CLI-backed: Codex CLI e Claude Code OAuth
Dois providers especiais do DeerFlow conversam com CLIs já logadas em vez de API keys: Codex CLI (OpenAI) e Claude Code OAuth (Anthropic). Você reaproveita a assinatura que já paga e ganha acesso aos mesmos modelos de topo que o CLI usa — sem criar conta de API nova, sem cota diferente, sem billing separado.
🎯 Como funciona
O provider do DeerFlow abre um processo stdio do CLI correspondente e troca mensagens no protocolo que ele entende. Do ponto de vista da skill, é um LLM como outro qualquer; do ponto de vista do billing, é a sua assinatura pessoal do CLI rodando local.
- •Codex CLI — usa subscription ChatGPT Plus/Team/Enterprise, modelos gpt-5 via CLI oficial
- •Claude Code OAuth — usa subscription Claude Max/Team, modelos Opus/Sonnet 4.6 via claude CLI
- •Sem API key — o OAuth do CLI já fez o trabalho de autenticação
✓ Fazer
- ✓Usar em máquina pessoal de dev onde o CLI já está logado
- ✓Testar skills caras antes de pagar API key dedicada
- ✓Aproveitar rate limits generosos da subscription
- ✓Documentar claramente que está usando assinatura pessoal
✗ Evitar
- ✗Deploy em servidor compartilhado — vai logar com a conta de quem?
- ✗Produção multi-tenant — viola ToS das duas subscriptions
- ✗CI/CD — sessões expiram, OAuth não renova automaticamente
- ✗Volume >10k req/dia — você vai ser rate-limited e parar o agente
⚠️ Alerta legal
Os ToS da ChatGPT Plus/Claude Max não são explícitos sobre uso via harness; tecnicamente é "você usando o CLI". Na prática, se começar a parecer serviço pago revendido, você perde a conta. Use para dev/teste pessoal, nunca como substituto de API key em produto.
💰 Trade-off custo × latência × qualidade
"Qual modelo usar?" é a pergunta errada. A certa é: qual modelo usar para qual papel? Um harness com 5 skills pode justificar 3 providers diferentes — um rápido e barato para triagem, um reasoning forte para planejamento, um self-hosted para dados sensíveis. A decisão é por papel, não global.
📊 Benchmark informal (abril/2026, ordem de grandeza)
| Modelo | $/1M in | $/1M out | TTFT | Qualidade | Quando |
|---|---|---|---|---|---|
| gpt-5-high | $5 | $40 | ~4s | ★★★★★ | lead_agent, planning |
| claude-sonnet-4.5 | $3 | $15 | ~1.5s | ★★★★★ | skills longas, código |
| gpt-5-mini | $0.25 | $2 | ~0.8s | ★★★★ | triagem, title, resumo |
| gemini-2.5-flash | $0.15 | $0.60 | ~0.4s | ★★★ | sub-agents baratos |
| Qwen3-32B vLLM | ~$0.20* | ~$0.20* | ~2s | ★★★ | dados sensíveis |
* custo amortizado em H100 com 8 usuários paralelos; latência única é pior.
🎯 Regra de ouro
Antes de otimizar modelo, otimize o papel. Um lead_agent gpt-5-high custa 10× mais caro que um gpt-5-mini — mas se ele toma 1 decisão boa que evita 20 chamadas subsequentes erradas, sai barato. Use modelo caro onde decisão ruim gera cascata; use modelo barato onde só processa.
🧪 Lab: mesma tarefa em 3 modelos
Chega de tabela. Vamos rodar a mesma skill de deep-research em três providers diferentes, capturar traces e comparar custo real. Ordem dos eventos é: preparar dataset fixo, declarar 3 model profiles, rodar, exportar, preencher planilha. O objetivo não é decidir "qual ganha" — é ver com seus olhos que "qualidade" é relativa ao caso de uso.
Prepare 3 queries representativas
Uma fácil ("estado da arte em RAG em 2026, 1 parágrafo"), uma média ("comparativo entre vLLM, SGLang e TGI para servir Qwen3 em uma H100") e uma difícil ("análise crítica das limitações metodológicas do paper X, com citação de fonte"). Use as mesmas 3 em todos os runs.
Declare 3 profiles no conf.yaml
Exemplo: BASIC_MODEL_A = claude-sonnet-4.5 via OpenRouter, BASIC_MODEL_B = gpt-5 via Codex CLI, BASIC_MODEL_C = Qwen3-32B via vLLM local. Crie conf-a.yaml, conf-b.yaml, conf-c.yaml para trocar sem editar variável de ambiente entre runs.
Execute e capture traces
Rode a skill deep-research 3×3 = 9 vezes (3 queries × 3 providers). Use o modo trace do DeerFlow (--trace) para salvar JSON com tokens in/out, wall time, ferramentas chamadas e custo estimado.
Preencha a planilha de comparação
9 linhas × colunas: query, provider, tokens_in, tokens_out, wall_time, custo_$, qualidade_1a5. Qualidade é nota subjetiva sua lendo a resposta — seja duro. Calcule custo_por_resposta_útil = custo / qualidade.
Escreva a conclusão (3 parágrafos)
Um para cada query, dizendo qual provider venceu para ela. A conclusão raramente é "um único provider domina" — é "A venceu na fácil pelo custo, B na média pela qualidade, C na difícil porque só ele tinha os dados sensíveis ok". Guarde o documento — vai servir de referência para decisões futuras.
💡 Resultado esperado
A primeira vez que você roda este lab, quase sempre descobre que estava pagando caro demais por uma skill onde o modelo barato bastaria, ou que estava usando um modelo médio onde o caro rendia 3× mais valor. Um dos dois. Raramente "estava tudo ótimo".
📝 Resumo do Módulo
Próximo Módulo:
3.2 — 🛡️ Sandbox, file system e segurança
Agora que o DeerFlow tem LLMs para conversar, o que acontece quando ele executa código gerado no seu host?