# Modelos Custo Beneficio

> Seleciona até 5 candidatos OpenRouter para Model Engineering Eval com inteligência Artificial Analysis >35 via OpenRouter Benchmarks, reasoning controlável, throughput hard >=60 t/s e latência p50 <2min/p99 <3min.

- Skill: `cadugevaerd/modelos-custo-beneficio` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add cadugevaerd/modelos-custo-beneficio`
- Raw SKILL.md: https://api.skillmd.com/api/skills/cadugevaerd/modelos-custo-beneficio/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: cadugevaerd (https://skillmd.com/u/cadugevaerd)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/cadugevaerd/modelos-custo-beneficio

---


# Modelos custo-benefício — candidatos para Eval

Use para encontrar candidatos OpenRouter conforme requisitos técnicos. Esta skill **não escolhe modelo de produção** e não executa o runner: devolve até cinco candidatos e o contrato obrigatório para a suíte de Eval do repositório.

## Contrato de descoberta

Todo candidato deve cumprir simultaneamente:

1. versão mais recente da família (heurística `created` do OpenRouter);
2. não gratuito;
3. reasoning controlável via `reasoning.supported_efforts` ou `reasoning.supports_max_tokens`;
4. endpoint com `throughput_last_30m.p75 >= 60 t/s`; na ausência de `p75`, `p50`/`median`/`avg` é fallback. Dado ausente reprova;
5. endpoint com `latency_last_30m.p50 < 120_000ms` (2 min) e `latency_last_30m.p99 < 180_000ms` (3 min). Ambos são gates hard obrigatórios; dado ausente, inválido ou no limite reprova;
6. inputs, structured outputs, contexto e teto de custo solicitados;
7. suporte a `tools`, pois o gate de Tool Calls é obrigatório inclusive para runtime textual.
8. índice de inteligência estritamente maior que `35` por padrão, vindo de `GET /api/v1/benchmarks?source=artificial-analysis&task_type=intelligence`; usa match exato antes de fallback restrito a sufixo de data. Índices ausentes, inválidos, não finitos ou ambíguos reprovam.

O benchmark de inteligência é um filtro hard aplicado **antes** de `--candidate-limit`; não há associação fuzzy por nome e não há fallback para uma fonte que não possa ser verificada.

## Roteamento

| Necessidade de runtime | Flag | Slug emitido |
|---|---|---|
| Runtime exige Tool Calls | `--tool-calls` | `<modelo>:exacto` |
| Runtime apenas textual | `--no-tool-calls` | `<modelo>:nitro` |

`--no-tool-calls` define o slug de runtime; ele **não** dispensa o gate obrigatório de Tool Calls, que deve testar o mesmo modelo com `:exacto`.

## Entrada

`eval_language` é obrigatório e deve representar o idioma nativo da aplicação, por exemplo `pt-BR`. Aceite texto livre convertido para flags ou `--requirements-json`.

| Requisito | Flag | Observação |
|---|---|---|
| idioma nativo | `--eval-language` | obrigatório; exemplo `pt-BR` |
| throughput | `--min-throughput` | piso fixo de 60 t/s |
| input | `--input` | `text,image`, por exemplo |
| runtime com Tools | `--tool-calls` | emite `:exacto` |
| runtime texto | `--no-tool-calls` | emite `:nitro`; mantém gate Tools |
| structured output | `--structured-outputs` | exige `structured_outputs` |
| contexto | `--min-context` | janela mínima |
| custo | `--max-cost-per-1m` | teto ponderado |
| inteligência | `--min-intelligence` | índice OpenRouter/Artificial Analysis estritamente maior; padrão `35` |
| candidatos | `--limit` | 2–5; padrão 5 |

## Procedimento obrigatório

1. Defina `OPENROUTER_API_KEY` no ambiente antes de executar. A skill não acessa vaults, 1Password nem imprime a credencial:

   ```bash
   python scripts/openrouter_model_recommender.py \
     --eval-language pt-BR --limit 5 --min-throughput 60 --min-intelligence 35 \
     --input text,image --tool-calls --structured-outputs --min-context 128000
   ```

2. Se houver menos de dois candidatos, pare; não relaxe requisitos nem invente candidatos.

3. **Pré-flight da suíte:** procure casos executáveis para os quatro gates abaixo. Se algum não existir, crie-o no framework de Eval já adotado pelo repositório antes de testar candidatos. Sem cobertura nos quatro, **pare: nenhum modelo pode ser aprovado**.

   | Gate obrigatório | Critério mínimo |
   |---|---|
   | Idioma nativo (`eval_language`) | prompts, entradas, respostas esperadas e critérios no idioma real da aplicação; não substitua o corpus por tradução automática. |
   | Markdown | respostas com a estrutura exigida (títulos/listas/tabelas/fences aplicáveis) e validação determinística de sintaxe, inclusive fences não fechados. |
   | Tool Calls | chamada controlada do mesmo modelo via `:exacto`; valide escolha da ferramenta, schema e argumentos, resultado e recuperação/abstenção para ferramenta inválida/indisponível. |
   | Antialucinação | casos grounded e sem resposta; afirmações devem vir da evidência; sem evidência, deve declarar incerteza, pedir contexto ou recusar. Reprove fatos, citações, resultados de tool ou detalhes inventados. |
   | Ganho vs. mercado | compare cada candidato no mesmo corpus contra ≥3 baselines atuais, com IDs/versões/providers pinados e de provedores distintos; inclua o modelo de produção atual, se houver. Registre `Δ pass_rate` global e por gate (pontos percentuais), custo, latência e throughput. |

4. Execute cada candidato com `reasoning.initial` válido (`xhigh`, `high`, `medium`, `low` ou `minimal`; para `max_tokens`, use o mapa local equivalente). `None`, vazio ou valor fora desse enum não é esforço válido e desqualifica a combinação. Uma combinação `modelo + variante + reasoning` só passa se **cada gate** e a taxa global atingirem `pass_rate >= 95%`, ou o limiar explicitamente configurado pela suíte. Gate ausente ou falho desqualifica o candidato.

   **Prioridade de execução:** dispare em paralelo todas as combinações independentes de `modelo + variante + reasoning` (candidatos e baselines) para economizar tempo. Cada worker usa o mesmo snapshot de corpus/prompts/tools e grava resultado imutável separado. Limite a concorrência por provider conforme rate limits, orçamento e capacidade do runner; retries seguem a mesma política para todos. Só agregue métricas e decida principal/fallback após todos os jobs terminarem; não paralelize etapas dependentes nem compartilhe arquivos mutáveis.

5. Reduza o reasoning por sobrevivente: `xhigh → high → medium → low → minimal`, ignorando níveis não suportados. Ao falhar, retenha o menor nível anterior aprovado.

6. Somente com pelo menos dois modelos distintos aprovados nos quatro gates, o Eval escolhe `principal` e `fallback`: menor custo total observado → menor latência → maior throughput. Aplique runtime manualmente.

7. Revalide em até 30 dias, e quando mudarem idioma, contrato Markdown, ferramentas, corpus/grounding, modelo, provider, preço, reasoning ou suíte.

## Saída

Entregue apenas:

- até cinco candidatos com endpoint, reasoning inicial, throughput e índice de inteligência;
- metadados da fonte do benchmark (`source`, `task_type`, `as_of`, `version`) e diagnósticos no JSON;
- o guia de Eval acima.

Não anuncie vencedor antes dos quatro gates aprovados e não altere runtime.