Execute o CrucibleForge em seus próprios modelos: Guia de instalação

Ir para: CrucibleForge no GitHub

O CrucibleForge é a ferramenta de código aberto responsável por gerar todas as pontuações no MakoBench. É gratuito (licença MIT-0, sem restrições) e você pode executá-lo com seus próprios modelos, em sua própria máquina. Esta página explica como instalá-lo e realizar uma primeira execução. Todos os comandos abaixo foram executados num clone recente do repositório público; o resultado dessas execuções está reproduzido aqui. Não possui GPU ou não tem tempo? Peça para nós executarmos seu modelo em nosso equipamento.

O que você precisa antes de começar?

• Python 3.12 ou versão mais recente com uv, ou Docker. O uv baixará o Python para você.
• Um modelo para testar por trás de um endpoint /chat/completions compatível com a OpenAI.
• Um avaliador, que pode ser qualquer modelo capaz de seguir instruções, seja local ou hospedado. O código é avaliado ao ser executado, mas o Chat precisa de um avaliador.
• No Linux, bubblewrap (bwrap). O código escrito pelo modelo é executado dentro dele. No Windows e macOS não há bubblewrap; você deve usar --allow-unsandboxed ou a imagem do Docker, onde o container funciona como sandbox.

Como se instala?

Esta é a forma nativa no Linux. O Docker é o caminho mais simples caso você prefira não instalar ferramentas do Python. O README contém blocos de código prontos para copiar e colar em Windows, Linux e macOS; o Docker Desktop ou Compose é utilizado como método 1 em todos os casos. Para esta página, não utilizamos o método do Docker.

git clone https://github.com/LaserLloyd/CrucibleForge.git
cd CrucibleForge
uv sync --python 3.13
uv run crucibleforge --version
crucibleforge 4.0.1

Trata-se da versão 4.0.1, a versão pública atual no momento da redação deste texto. Agora, crie seu arquivo de configuração:

uv run crucibleforge config --init
wrote models.yaml - edit providers/models, then `crucibleforge status`

O arquivo de exemplo lista provedores como LM Studio, Ollama, llama.cpp ou qualquer servidor local, DeepSeek, OpenRouter, OpenAI e Open WebUI; além disso, há quatro modelos de exemplo. Nada será executado até que você ative um deles.

Como conectar seu modelo?

models.yaml precisa de um provedor, um modelo e um juiz.

1. Provedor. Onde o modelo é servido. Qualquer servidor que atenda ao protocolo /chat/completions funciona com type: openai. Exemplos locais do README: http://localhost:11434/v1 para o Ollama, http://localhost:1234/v1 para o LM Studio, http://localhost:8000/v1 para o vLLM. Uma API hospedada requer api_key_env: NAME_OF_ENV_VAR. A chave em si nunca deve ser inserida no arquivo.
2. Modelo. Um registro contendo um name, o provider, o model_id conhecido pelo servidor e um context_length.
3. Juiz. É informado a cada execução, na forma de --judge provider:model_id.

Para ver o que um servidor oferece, basta perguntar a ele. Este é um provedor hospedado cuja chave está definida no ambiente:

uv run crucibleforge models discover deepseek
  * deepseek-flash
  * deepseek-v4-pro

2 models on deepseek (* = in registry)

O asterisco indica que o modelo já está registrado. O arquivo de exemplo vem com o deepseek-flash habilitado; portanto, não foi necessário fazer nenhuma edição para a nossa execução. Para seu próprio modelo, adicione um registro assim:

models:
  - name: my-model
    provider: ollama
    model_id: qwen3:8b
    context_length: 32768

Como verificar a configuração?

export DEEPSEEK_API_KEY=...       # only for a hosted provider or judge
uv run crucibleforge status

Sem a chave definida, a saída de status para o provedor hospedado fica assim (apenas as linhas relevantes foram mantidas):

suite revision: 4.0.1+e3d1c6fb
providers:
  ollama         openai      http://localhost:11434/v1       DOWN conc=8
  deepseek       openai      https://api.deepseek.com/v1     UP   conc=8 key: $DEEPSEEK_API_KEY (NOT SET)
    reachable, but it wants an API key: set $DEEPSEEK_API_KEY (HTTP 401)
registry (models):
  [enabled ] deepseek-flash   deepseek   deepseek-flash    $0.14/0.28 per 1M
cases: 393 total (235 hard)
smoke subset: 37 cases
benchmark (bench): 33 cases

DOWN significa que nada respondeu nesse endereço; isso é esperado para servidores locais que não estavam em execução. UP com 401 indica que o host está acessível, mas exige uma chave. A quantidade de casos é importante: o conjunto completo possui 393 casos, e o sistema utiliza 33 deles.

Quanto custa uma execução antes de ela começar?

Adicione --plan a qualquer execução; assim, nada será executado. O sistema exibe o que seria executado e uma estimativa do tempo necessário:

uv run crucibleforge all --models deepseek-flash --judge deepseek:deepseek-v4-flash --plan
  T1 - every model: 29 rows (29 cases) + 4 perf probes
  one round - hosted API (nothing loaded): 29 rows, 8 requests at once
  estimate: generation 18.5 min; judge 16.0 min ... -> ~34 min
(plan only - no model, provider or judge was called; times are estimates)

Essa é a execução completa em um modelo hospedado: cerca de 34 minutos, segundo a própria estimativa da ferramenta. Trata-se apenas de uma estimativa, não de uma medição real. Para um modelo local, o README indica aproximadamente 25 a 30 minutos em uma máquina com GPU rápida.

Como é uma execução de teste do tipo “smoke run”?

O sinalizador --smoke executa um pequeno conjunto de testes, do início ao fim: geração de respostas, avaliação e geração do relatório. É a maneira mais rápida de verificar se sua configuração está funcionando corretamente. Utilizamos o DeepSeek Flash tanto como modelo quanto como avaliador; essa é a combinação indicada no guia de início rápido do README. A execução foi feita fora dos horários de pico do DeepSeek.

uv run crucibleforge all --smoke --models deepseek-flash --judge deepseek:deepseek-v4-flash --yes
... profile bench: 4 cases, thinking cap 24576, judge deepseek:deepseek-v4-flash
... link check passed: deepseek reachable, data channel OK
... run: models=['deepseek-flash'] cases=4 smoke=True fresh=False
... [deepseek-flash] RD1-marisol r1 done (15 rows)
... judging done: 1 rows, 0 unparsable judge verdicts, 0 empty generations, 0 errored
run summary:
  deepseek-flash: 15 rows, load 0.0s (deepseek), $0.0229
timing: generation 1.2 min, judge 14 s, report 8 s, total 1.6 min
wrote results/report.md, results/failures.md, results/report.html

A execução durou 1,6 minutos e custou $0,0229. Os 15 casos testados incluem um cenário de role-play e também testes de desempenho. Há duas observações importantes a serem feitas:

• A API do avaliador rejeitou uma solicitação de saída estruturada; por isso, o CrucibleForge recorreu ao formato JSON de texto livre para essa sessão. Mesmo assim, as pontuações foram geradas.
• O avaliador não conseguiu passar na verificação de calibração para textos com conteúdo adulto. O CrucibleForge então avaliou apenas os demais casos, deixando os textos com conteúdo adulto pendentes para um avaliador capaz de lidar com eles. O README informa que a maioria dos avaliadores hospedados se comporta dessa forma. Essas pontuações permanecem visíveis no painel, mas nunca são somadas ao total geral.

Como interpretar o resultado?

Abra results/report.html num navegador, ou leia results/report.md. Nossa execução de teste imprimiu uma única linha:

| Model          | Overall | Class | Coding | Chat        | tok/s | Suite | Notes                                          |
| deepseek-flash | -       | -     | -      | 2.5 +/- 0.1 | 159.7 | 4.0.1 | partial (4/33 cases); judged by deepseek-v4-flash |

O valor de 2,5 referente ao Chat não é uma pontuação do modelo. Trata-se do único caso de role-play que foi executado, dentro da parte do Chat à qual esse caso pertence. A linha indica parcial (4/33 casos); um modelo parcial não possui pontuação geral, nem classificação, nem ranking. Essa também é a regra no quadro principal de resultados. Execute o conjunto completo de testes para obter um valor total real (Código mais Chat, 20 no total). Para saber o significado de cada coluna, leia Como o MakoBench funciona e O que o MakoBench testa.

A velocidade (tok/s) serve apenas para comparar modelos executados no mesmo hardware. A velocidade de um modelo hospedado depende do seu provedor e do grau de utilização dele.

Como executar o benchmark completo?

uv run crucibleforge all --models my-model --judge my-provider:my-judge --yes

Adicione --fresh para arquivar primeiro o registro de execução anterior do modelo. Os resultados são salvos em results/, ao lado de models.yaml: o relatório de pontuações, as falhas, o relatório HTML e um registro de cada prompt e resposta. A interface web é iniciada com um único comando (uv run crucibleforge gui) e, por padrão, escuta apenas no loopback.

Algumas coisas que você precisa saber antes

• Os testes de codificação executam código escrito pelo modelo. Use o bubblewrap no Linux ou a imagem do Docker em outros sistemas. O parâmetro --allow-unsandboxed permite que esse código seja executado como você, com acesso aos seus arquivos.
• As execuções hospedadas têm custo. Execute primeiro --plan e o teste básico.
• O conjunto de testes inclui casos de ficção adulta que ficam separados dos demais e nunca são incluídos no total geral. O README contém uma nota sobre esse conteúdo.
• O avaliador influencia as pontuações do Chat. No quadro de resultados do MakoBench, o avaliador é a Gemma 4 31B (versão “heretic” sem censura, Q8) rodando em nosso próprio hardware com GPU. Suas pontuações no Chat só coincidirão com as do quadro se você usar o mesmo avaliador; já os testes de código são avaliados pela execução real, portanto funcionam independentemente.
• As pontuações são comparadas dentro de uma mesma versão do conjunto de testes. Esta página refere-se à versão 4.0 do conjunto; consulte o que mudou na Versão 4.0.

Tudo foi verificado corretamente?

Quase. Também executamos uv run crucibleforge cases verify, que recalcula as respostas corretas offline. Essa execução verificou 393 casos e apontou um com problema: um caso do banco de códigos cuja solução de referência ultrapassou o tempo limite em um teste de sinal. Essa execução compartilhou nossa máquina com outras tarefas; portanto, não podemos afirmar se se trata de uma falha real ou apenas de um problema de desempenho do sistema. Ainda não relatamos isso aos desenvolvedores. Se você encontrar o mesmo caso, não está sozinho.

Quer que executemos isso para você?

Relacionado: Como o MakoBench funciona, Suite 4.0: o que mudou e o quadro.