Como o CrucibleForge funciona: um benchmark aberto para LLMs, explicado

O CrucibleForge é um benchmark de código aberto para modelos de linguagem. Você aponta o modelo para ele, e o sistema executa um conjunto fixo de testes, avalia as respostas e gera um relatório. O MakoBench é nosso painel público; todos os números exibidos nele vêm desta ferramenta. Você pode usar a mesma ferramenta com seus próprios modelos. Ela é gratuita e licenciada sob MIT-0, portanto não há restrições para seu uso.

Os cinco blocos

Este é todo o sistema, no nível em que você precisa utilizá-lo. Cada bloco realiza uma tarefa e repassa seu resultado para o próximo.

1. Seus modelos. O CrucibleForge se comunica com qualquer modelo que siga o formato de chat da OpenAI. Isso inclui tanto servidores locais quanto APIs hospedadas por empresas.
2. Verificação de conformidade. Cada provedor possui requisitos ligeiramente diferentes. Antes de avaliar um modelo, sete chamadas simples comprovam que o sistema se comunica corretamente com ele: o ID do modelo é retornado, o raciocínio aparece onde esperado, uma informação persiste entre turnos, o ciclo completo de chamada de ferramentas funciona, as configurações do amostrador são aceitas, um prompt de codificação médio cabe no limite de tokens, e para provedores hospedados os documentos oficiais foram revisados nos últimos 120 dias. Uma falha nessa verificação impede a execução do modelo, pois uma pontuação baseada em requisições incorretas mediria o sistema, não o próprio modelo.
3. Executor de testes. Ele envia os casos de teste ao modelo, em paralelo conforme permitido pelo servidor, e registra cada prompt e resposta.
4. Avaliadores. Cada resposta é avaliada pelo método adequado. Veja a seção seguinte para mais detalhes.
5. Pontuações e saída final. As notas são agrupadas em Codificação, Chat e Total, cada uma com sua margem de tolerância; o sistema gera um relatório. Para nós, esse relatório alimenta o quadro MakoBench. Para você, ele resulta em um arquivo report.html que pode ser aberto no navegador.

Os testes, em termos simples

A pontuação total tem duas partes: dez pontos para cada uma, por um desempenho perfeito nos testes padrão. O total é a soma dessas duas partes, ou seja, 20 pontos no total. Pacotes bônus com questões mais difíceis são desbloqueados quando um modelo obtém 90% ou mais de acertos em uma das partes; essa é a única forma de ultrapassar os 10 pontos. Cada revisão dos testes tem um limite máximo; um novo pacote aumenta esse limite.

Código: o modelo consegue escrever e raciocinar sobre programas?

• Funções (5 pontos). Escreva uma função em Python a partir de uma descrição. Testes ocultos são executados em um ambiente isolado. A pontuação parcial corresponde à proporção de grupos de testes que foram aprovados.
• Previsão e correção de erros (2,5 pontos). Indique exatamente o que um pequeno programa imprime; depois, encontre e corrija um erro em um projeto simples. As respostas são comparadas exatamente ou verificadas pela execução da correção.
• Uso de ferramentas (2,5 pontos). Conversas pré-definidas nas quais o modelo deve utilizar as ferramentas corretamente; há armadilhas como uso de ferramenta errada ou argumentos inválidos.

Nada disso exige opinião subjetiva. O código é executado, e ele passa ou não nos testes.

Conversa: o modelo é um bom companheiro em uma história?

• Role-play profundo (3 pontos). Sessões longas e repletas de detalhes narrativos. O modelo se lembra de fatos mencionados anteriormente, aceita correções e mantém o ponto de vista do personagem?
• Conversa cotidiana (3 pontos). Um bate-papo comum que precisa permanecer consistente ao longo de várias rodadas.
• Personagens (2 pontos). Um único personagem com diversas vozes e hábitos distintos.
• Escrita criativa (2 pontos). Uma história escrita em conjunto, sob restrições específicas como extensão, tempo verbal e elementos que devem ou não aparecer na narrativa.

O teste de conversa avalia o desempenho do modelo em role-play e diálogos cotidianos. Ele não mede a capacidade de responder perguntas simples; portanto, considere-o como uma avaliação da habilidade do modelo em interagir dentro de uma história, e não como um indicador de quão bom ele é como assistente.

NSFW: separado intencionalmente

Alguns modelos são desenvolvidos para ficção adulta; algumas pessoas desejam exatamente isso, então existe um conjunto específico de testes para esse fim. Eles geram uma pontuação própria (pontuação NSFW), que nunca é somada à pontuação total. Todos os personagens nesses testes são adultos. Um número maior indica apenas que o modelo vai mais longe nesse tipo de conteúdo; se isso é útil ou não depende do seu objetivo.

Como funciona a avaliação da conversa

As respostas de conversa não podem ser executadas, então um modelo avaliador as analisa. Ele não atribui notas livres; cada caso traz uma lista de perguntas do tipo “sim/não”, como “o personagem manteve a primeira pessoa na narrativa?”. Para cada uma delas, o avaliador responde sim ou não e cita a linha que comprova sua resposta. Uma resposta “sim” cuja citação não consta na resposta do modelo é considerada “não”. Regras textuais, como contagem de palavras ou presença de frases proibidas, também são aplicadas paralelamente ao avaliador.

Dois fatores garantem a integridade do avaliador: cada pergunta deve abordar apenas um aspecto específico; além disso, antes de ser utilizado, o avaliador passa por um teste de calibração para certificar-se de que realmente cumprirá sua função, sem ignorar ou suavizar as regras.

Margens e empates

Cada pontuação possui uma margem de erro calculada via bootstrap a partir dos casos de teste. Dois modelos cujas pontuações estejam dentro dessa margem são considerados empatados, independentemente da ordem em que aparecem na tabela. As comparações de pontuação são feitas apenas dentro de uma mesma versão do conjunto de testes; essa informação é indicada em cada linha do relatório.

Execute você mesmo em dez minutos

São necessárias três coisas: um modelo para testar por trás de um endpoint no estilo OpenAI, um “juiz” e uma máquina com o uv instalado. A máquina não precisa de GPU; portanto, você pode executá-la em um laptop usando uma API hospedada. No Linux, as respostas geradas são executadas dentro do bwrap (bubblewrap). No Windows e macOS não há esse recurso; assim, use a imagem Docker descrita no README ou adicione o parâmetro --allow-unsandboxed antes do subcomando, aceitando que o código gerado pelo modelo será executado diretamente.

1. Instalação

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

O último comando cria um arquivo inicial models.yaml contendo configurações para o LM Studio, Ollama, llama.cpp ou qualquer servidor local, DeepSeek, OpenRouter, OpenAI e outros. Nada é executado até que você ative algum provedor.

2. Indique onde seu modelo está

Abra o arquivo models.yaml. Um “provedor” define onde fica um servidor, e a entrada “modelo” indica qual modelo está disponível nele. Para um servidor local:

providers:
  mylocal:
    type: openai
    base_url: http://localhost:8080/v1   # your llama.cpp / LM Studio / StudioForge address

models:
  - name: my-model
    provider: mylocal
    model_id: the-id-your-server-reports
    context_length: 32768

Para ver quais IDs de modelo o servidor oferece, faça uma consulta a ele:

uv run crucibleforge models discover mylocal

3. Verifique a configuração

uv run crucibleforge status

Essa etapa lista cada provedor como “UP” ou “DOWN”, se sua chave de acesso está configurada, seus modelos, o “juiz” e a quantidade de casos a serem testados. Corrija qualquer item marcado como “DOWN” ou “NOT SET” antes de prosseguir.

4. Planeje e faça um teste preliminar

Adicione --plan a qualquer comando de execução; assim, nada será realmente executado. O programa exibirá o que seria feito e uma estimativa do tempo necessário.

uv run crucibleforge all --models my-model --judge mylocal:my-judge --plan
uv run crucibleforge all --smoke --models my-model --judge mylocal:my-judge --yes

O teste preliminar abrange um pequeno conjunto de casos: geração de respostas, avaliação pelo “juiz” e geração do relatório. Ele comprova que sua configuração está correta. Em nosso teste com um modelo hospedado, o processo levou menos de dois minutos e custou cerca de dois centavos. O teste preliminar não gera uma pontuação definitiva, pois abrange apenas alguns dos 33 casos disponíveis; o relatório indica que o modelo teve desempenho “parcial”, sem um valor total nem classificação.

5. Leia o relatório

Abra o arquivo results/report.html em um navegador, ou leia results/report.md. Ao lado dele estão failures.md, report.json e o registro completo de cada prompt e resposta gerada pelo modelo. Uma execução completa, feita com o mesmo comando porém sem --smoke, leva aproximadamente 25 a 30 minutos para cada modelo local, considerando também o tempo de avaliação pelo “juiz”. Para uma versão com interface gráfica, execute uv run crucibleforge gui e abra o endereço exibido; por padrão, ele funciona apenas na sua própria máquina.

Conectando um backend ou uma API

O CrucibleForge não possui nenhum modelo interno; ele é apenas um cliente. Tudo o que precisa está em models.yaml, dividido em três partes: um provedor, um modelo e um juiz.

Servidor local

Use type: openai e o endereço do servidor. Endereços típicos:

• O llama-server do llama.cpp: http://127.0.0.1:8080/v1
• LM Studio: http://localhost:1234/v1
• Ollama: http://localhost:11434/v1
• vLLM: http://localhost:8000/v1
• StudioForge: seu gateway na porta 1234, /v1 (não a porta do painel de controle). Use type: studioforge se quiser que o CrucibleForge aloque uma GPU e carregue modelos por meio do planejador do servidor.

Caso o servidor exija uma chave, nomeie a variável de ambiente como api_key_env. Não cole a chave diretamente no arquivo.

API hospedada

providers:
  deepseek:
    type: openai
    base_url: https://api.deepseek.com/v1
    api_key_env: DEEPSEEK_API_KEY
    concurrency: 8

models:
  - name: deepseek-flash
    provider: deepseek
    model_id: deepseek-flash
    context_length: 131072

export DEEPSEEK_API_KEY=...        # your own key, set in your shell
uv run crucibleforge status

O arquivo de configuração inicial já contém entradas para DeepSeek, OpenAI, OpenRouter e outros. O Claude também funciona diretamente: a Anthropic possui um endpoint compatível com o padrão da OpenAI; portanto, basta usar um provedor com type: openai, base_url: https://api.anthropic.com/v1 e sua chave da Anthropic. Provedores sem endpoint no estilo OpenAI geralmente podem ser acessados via OpenRouter. Execuções em ambientes hospedados custam dinheiro; por isso, use --plan para fazer um teste preliminar. Atribua a cada modelo hospedado um price (valor em dólares por milhão de tokens processados); o relatório exibirá então uma coluna Custo da execução: quanto custa, nessa taxa, uma execução dos testes padrão de Código e Chat, considerando apenas a geração de texto. Planos fixos não cobram por token; nesse caso, insira basis: list no bloco de preços; o custo será indicado com um símbolo ~, como estimativa baseada na contagem de tokens segundo a tarifa padrão. Modelos rodando em seu próprio hardware aparecem com um traço no relatório. O CrucibleForge emite um aviso e se recusa a iniciar caso um modelo hospedado não tenha preço definido.

Alguns provedores aplicam filtros de conteúdo que podem bloquear respostas. O CrucibleForge registra esses casos nos relatórios, marca a linha correspondente com a contagem de “bloqueados” e uma nota; além disso, atribui pontuação zero às respostas bloqueadas. Não é necessário fazer nada para ativar esse comportamento.

O juiz

Para o teste de Chat, é preciso um juiz – que não pode ser o próprio modelo em teste. Pode ser um segundo modelo no seu servidor local ou um modelo hospedado. Indique-o por execução usando --judge provider:model_id, ou liste os candidatos em judge: dentro de models.yaml. Duas coisas são importantes:

• O juiz influencia as pontuações do Chat. Os resultados do Chat só coincidirão com os do quadro de classificação do MakoBench se você usar o mesmo juiz. Já no teste de Código, a pontuação independe disso, pois ele é avaliado pela execução real.
• A maioria dos juízes hospedados rejeita ou suaviza textos adultos. O processo de calibração detecta isso. O restante das respostas do Chat continua sendo pontuado; as linhas com conteúdo inadequado permanecem como “não julgadas” até que você as avalie com um modelo capaz de fazê-lo.

Avançando ainda mais

• crucibleforge conform --models my-model executa sozinho os sete testes de configuração.
• crucibleforge cases verify recalcula todas as respostas esperadas offline, como um auto-teste.
• crucibleforge report gera novamente o relatório a partir dos resultados armazenados.
• Os resultados ficam em results/, ao lado do seu arquivo models.yaml; assim, eles permanecem no seu computador.

O README explica como usar o Docker, como executar os testes de forma independente, como manter um teste personalizado em privado e como adicionar novos casos de teste. Você quer apenas os números? O painel do MakoBench mostra esses valores para os modelos que já rodamos; além disso, você pode nos pedir para testar o seu modelo. Para saber como interpretar as pontuações, consulte Como o MakoBench funciona. Para um guia passo a passo de instalação com exemplos reais, veja Como executar o CrucibleForge com seus próprios modelos.