Processamento em lote

O processamento em lote roda o agente Hermes sobre centenas ou milhares de prompts em paralelo, gerando dados de trajetória estruturados. O uso principal é gerar dados de treino — produzindo trajetórias no formato ShareGPT, com estatísticas de uso de ferramenta, que servem para fine-tuning ou avaliação.

Visão geral

O executor de lote (batch_runner.py) processa um conjunto de prompts em JSONL, passando cada um por uma sessão completa de agente, com acesso a ferramentas. Cada prompt ganha um ambiente isolado. A saída são trajetórias estruturadas, com o histórico completo da conversa, estatísticas das chamadas de ferramenta e métricas de cobertura de raciocínio.

Começando

# Execução básica
python batch_runner.py \
    --dataset_file=data/prompts.jsonl \
    --batch_size=10 \
    --run_name=meu_primeiro_run \
    --model=anthropic/claude-sonnet-4.6 \
    --num_workers=4

# Retomar uma execução interrompida
python batch_runner.py \
    --dataset_file=data/prompts.jsonl \
    --batch_size=10 \
    --run_name=meu_primeiro_run \
    --resume

# Listar as distribuições de conjuntos de ferramenta
python batch_runner.py --list_distributions

Custo previsível em escala

Execuções em lote sobem muitas sessões simultâneas, cada uma chamando o modelo e as ferramentas. Uma assinatura do Nous Portal junta o acesso ao modelo com busca na web, geração de imagem, síntese de voz e navegadores na nuvem numa conta só — útil quando você quer custo estável por trajetória, sem equilibrar limites de requisição entre cinco fornecedores. Configure com hermes setup --portal e aponte o --model para um modelo da Nous.

Formato do conjunto de dados

A entrada é um arquivo JSONL (um objeto JSON por linha). Cada entrada precisa de um campo prompt:

{"prompt": "Escreva uma função em Python que ache a maior substring palíndroma"}
{"prompt": "Crie um endpoint REST de autenticação de usuário com Flask"}
{"prompt": "Depure este erro: TypeError: cannot unpack non-iterable NoneType object"}

As entradas também aceitam:

• image ou docker_image: a imagem de container do sandbox daquele prompt (funciona nos backends Docker, Modal e Singularity)
• cwd: troca o diretório de trabalho da sessão de terminal daquela tarefa

Opções

Parâmetro	Padrão	Descrição
--dataset_file	(obrigatório)	Caminho do JSONL
--batch_size	(obrigatório)	Prompts por lote
--run_name	(obrigatório)	Nome da execução (usado no diretório de saída e no checkpoint)
--distribution	"default"	Distribuição de conjuntos de ferramenta a sortear
--model	claude-sonnet-4.6	Modelo
--base_url	https://openrouter.ai/api/v1	URL base da API
--api_key	(variável de ambiente)	Chave do modelo
--max_turns	10	Máximo de iterações com ferramenta por prompt
--num_workers	4	Processos em paralelo
--resume	false	Retoma do checkpoint
--verbose	false	Log detalhado
--max_samples	todos	Processa só as primeiras N entradas
--max_tokens	padrão do modelo	Máximo de tokens por resposta

Roteamento de provedores (OpenRouter)

Parâmetro	Descrição
--providers_allowed	Provedores permitidos, separados por vírgula ("anthropic,openai")
--providers_ignored	Provedores a ignorar ("together,deepinfra")
--providers_order	Ordem de preferência
--provider_sort	Ordena por "price", "throughput" ou "latency"

Controle de raciocínio

Parâmetro	Descrição
--reasoning_effort	Esforço: none, minimal, low, medium, high, xhigh, max, ultra
--reasoning_disabled	Desliga por completo os tokens de raciocínio

Opções avançadas

Parâmetro	Descrição
--ephemeral_system_prompt	Prompt de sistema usado na execução, mas NÃO salvo nas trajetórias
--log_prefix_chars	Caracteres mostrados nas prévias de log (padrão: 100)
--prefill_messages_file	Arquivo JSON com mensagens de preenchimento, para condicionamento com poucos exemplos

Distribuições de conjuntos de ferramenta

Cada prompt recebe um conjunto de ferramentas sorteado de uma distribuição. Isso faz os dados de treino cobrirem combinações diversas. Use --list_distributions para ver as disponíveis.

Na implementação atual, as distribuições atribuem uma probabilidade a cada conjunto de ferramentas individualmente. O sorteador decide cada conjunto de forma independente e então garante que pelo menos um fique ativo. Isso é diferente de uma tabela de combinações prontas, escrita à mão.

Formato de saída

Tudo vai para data/<run_name>/:

data/meu_run/
├── trajectories.jsonl    # saída final combinada (todos os lotes juntos)
├── batch_0.jsonl         # resultado de cada lote
├── batch_1.jsonl
├── ...
├── checkpoint.json       # checkpoint de retomada
└── statistics.json       # estatísticas agregadas de uso de ferramenta

Formato da trajetória

Cada linha do trajectories.jsonl é um objeto JSON:

{
  "prompt_index": 42,
  "conversations": [
    {"from": "human", "value": "Write a function..."},
    {"from": "gpt", "value": "I'll create that function...",
     "tool_calls": [...]},
    {"from": "tool", "value": "..."},
    {"from": "gpt", "value": "Here's the completed function..."}
  ],
  "metadata": {
    "batch_num": 2,
    "timestamp": "2026-01-15T10:30:00",
    "model": "anthropic/claude-sonnet-4.6"
  },
  "completed": true,
  "partial": false,
  "api_calls": 3,
  "toolsets_used": ["terminal", "file"],
  "tool_stats": {
    "terminal": {"count": 2, "success": 2, "failure": 0},
    "read_file": {"count": 1, "success": 1, "failure": 0}
  },
  "tool_error_counts": {
    "terminal": 0,
    "read_file": 0
  }
}

O campo conversations usa um formato parecido com o ShareGPT, com from e value. As estatísticas de ferramenta são normalizadas para incluir todas as ferramentas possíveis, com zero como padrão — garantindo esquema consistente entre entradas, para compatibilidade com conjuntos do Hugging Face.

Checkpoints

O executor tem checkpoints robustos, para tolerar falha:

• Arquivo de checkpoint: salvo depois de cada lote, registrando quais índices terminaram
• Retomada por conteúdo: com --resume, o executor varre os arquivos de lote existentes e casa os prompts concluídos pelo texto de verdade (não só pelo índice), o que permite recuperação mesmo se a ordem do conjunto mudar
• Prompts que falharam: só os concluídos com sucesso são marcados como prontos — os que falharam são tentados de novo na retomada
• Junção dos lotes: ao terminar, todos os arquivos de lote (inclusive de execuções anteriores) são unidos num trajectories.jsonl

Como a retomada funciona

1. Varre todos os batch_*.jsonl atrás de prompts concluídos, casando por conteúdo
2. Filtra o conjunto, tirando os já concluídos
3. Reagrupa o que sobrou em lotes
4. Processa só o que falta
5. Junta todos os arquivos de lote, antigos e novos, na saída final

Filtragem de qualidade

O executor aplica filtros automáticos:

• Filtro de ausência de raciocínio: amostras em que nenhum turno do assistente tem raciocínio (sem <REASONING_SCRATCHPAD> nem tokens nativos de pensamento) são descartadas
• Filtro de entrada corrompida: entradas com nome de ferramenta alucinado (fora da lista válida) são filtradas na junção final
• Estatística de raciocínio: registra a porcentagem de turnos com e sem raciocínio na execução inteira

Estatísticas

No fim, o executor imprime:

• Uso de ferramenta: contagem de chamadas e taxa de sucesso e falha por ferramenta
• Cobertura de raciocínio: porcentagem de turnos do assistente com raciocínio
• Amostras descartadas: quantas foram filtradas por falta de raciocínio
• Duração: tempo total

As estatísticas também vão para o statistics.json, para análise por programa.

Para que serve

Gerar dados de treino

Produzir trajetórias diversas de uso de ferramenta, para fine-tuning:

python batch_runner.py \
    --dataset_file=data/prompts_codigo.jsonl \
    --batch_size=20 \
    --run_name=codigo_v1 \
    --model=anthropic/claude-sonnet-4.6 \
    --num_workers=8 \
    --distribution=default \
    --max_turns=15

Avaliar modelos

Medir o quanto um modelo usa bem as ferramentas, num conjunto padronizado:

python batch_runner.py \
    --dataset_file=data/avaliacao.jsonl \
    --batch_size=10 \
    --run_name=avaliacao_gpt4 \
    --model=openai/gpt-4o \
    --num_workers=4 \
    --max_turns=10

Imagem de container por prompt

Em avaliações que exigem ambientes específicos, cada prompt pode ter a própria imagem:

{"prompt": "Instale o numpy e calcule os autovalores de uma matriz 3x3", "image": "python:3.11-slim"}
{"prompt": "Compile este programa em Rust e rode", "image": "rust:1.75"}
{"prompt": "Monte um servidor Express em Node.js", "image": "node:20-alpine", "cwd": "/app"}

O executor confere se as imagens Docker estão acessíveis antes de rodar cada prompt.