Você já passou por isso: conecta um servidor vLLM local ao Hermes e, depois de algumas trocas, ele anuncia “contexto cheio” — mesmo que o seu modelo lide tranquilamente com 8K ou 128K tokens. Ou troca para um modelo recém-lançado que claramente tem visão, e o Hermes insiste que “este modelo não suporta imagens”. Na maioria das vezes o problema não é o modelo — é que a imagem que o Hermes tem dele vem de um catálogo de modelos, e o seu modelo não está lá, ou a entrada está desatualizada. A boa notícia: desde a v0.20.1 você pode corrigir tudo isso diretamente no config.yaml com model_overrides e dizer ao Hermes exatamente o que o seu modelo é.

Por que isso acontece: pontos cegos no catálogo de modelos

O Hermes decide o que um modelo é capaz de fazer — o tamanho da janela de contexto, se ele suporta ferramentas, visão ou raciocínio — principalmente com base no models.dev, um catálogo público de modelos, além de algumas regras internas de fallback. Isso cobre bem os modelos de nuvem mais populares, mas sempre há lacunas:

• Modelos locais: seu servidor vLLM, Ollama ou llama.cpp usa IDs de modelo que você mesmo inventou; eles não estão no catálogo;
• Modelos recém-lançados: acabaram de sair do fornecedor e ainda não foram catalogados;
• Entradas desatualizadas: a janela de contexto está marcada como menor do que realmente é, os recursos estão errados, ou o fornecedor lançou uma atualização que o catálogo ainda não acompanhou.

Nesses casos, o Hermes recorre a “padrões seguros”: modelos desconhecidos recebem uma estimativa de 200K de contexto, chamadas de ferramenta ativadas, mas visão e raciocínio desligados. Quando a suposição está errada, você tem exatamente o comportamento estranho do começo — recursos que existem são tratados como inexistentes e o contexto pelo qual você pagou vai para o lixo.

A correção: model_overrides no config.yaml

model_overrides é uma nova seção de configuração de nível superior que chegou na v0.20.1 (PR #85560). A função dela é simples: para um modelo específico sob um provedor específico, você declara os metadados manualmente e eles sobrescrevem o catálogo. Assim:

model_overrides:
  custom:my-local-vllm:        # provider name, then the model ID
    my-llava-model:
      context_window: 8192     # this model's real context is 8K
      supports_vision: true    # it does accept images
    my-llama-model:
      context_window: 32768
      supports_tools: false    # tool calls are flaky here — turn them off
  upstage:                     # you can also fix cloud models
    solar-pro4:
      context_window: 524288   # not in the catalog; actually 512K

Reinicie o Hermes depois de salvar (edite com hermes config edit e reinicie a sessão) e as substituições entram em vigor. Escreva apenas os campos que o catálogo erra ou omite — tudo o que você deixar de fora mantém o valor do catálogo, então é impossível quebrar outras configurações por acidente.

Os três campos que você mais vai usar

Raramente você precisa de todos. No dia a dia, costuma ser um destes:

• context_window: o tamanho da janela de contexto do modelo, em tokens. Definir um valor baixo demais corta as conversas cedo demais; alto demais, e o modelo divaga em um contexto superdimensionado — consulte o número real sempre que possível.
• supports_vision: se o modelo aceita entrada de imagem. É a armadilha mais comum com modelos de visão locais (estilo LLaVA): sem a declaração, o Hermes nunca oferece a opção de enviar imagens.
• supports_tools: se o modelo é capaz de fazer chamadas de ferramenta. Se um modelo não é confiável no uso de ferramentas, é melhor desativá-lo explicitamente aqui do que vê-lo falhar repetidamente.

A lista completa de campos

model_overrides aceita todos estes campos, com o mesmo significado dos metadados de modelo:

Campo	Significado
context_window	Tamanho da janela de contexto, em tokens
max_output_tokens	Máximo de tokens de saída por resposta
supports_tools	Suporte a chamadas de ferramenta (padrão: true para modelos desconhecidos)
supports_vision	Suporte a entrada de imagem (padrão: false)
supports_reasoning	Suporte a modo de raciocínio (padrão: false)
model_family	Identificador de família de modelos usado na correspondência de fallback

_default: uma rede de segurança para modelos não catalogados

Escrever cada modelo à mão é tedioso. Você pode definir um _default por provedor — ou globalmente — como fallback para os modelos que o catálogo não conhece:

model_overrides:
  custom:my-vllm:
    _default:                  # applies only to uncataloged models
      context_window: 32768
  _default:                    # global fallback, gap-filling only
    context_window: 128000

_default é, por design, apenas um preenchedor de lacunas: ele só se aplica a modelos que o catálogo não conhece e nunca substitui os dados do catálogo para os modelos conhecidos. Assim, um padrão global não pode, por acidente, limitar todos os modelos de um provedor — os modelos conhecidos mantêm seus valores do catálogo.

Dois cenários reais

Cenário um: um modelo de visão local. Você está servindo um modelo de ID personalizado pelo vLLM e ele aceita imagens. Sem configuração, o Hermes assume que ele não tem visão nenhuma:

model_overrides:
  custom:my-vllm:
    my-llava-model:
      context_window: 8192
      supports_vision: true

Cenário dois: um modelo de nuvem recém-lançado. O solar-pro4 da Upstage não estava no catálogo no lançamento, então a regra de fallback o tratou como se tivesse 256K de contexto quando na verdade tem 512K. Declare-o e você pode usar a janela inteira:

model_overrides:
  upstage:
    solar-pro4:
      context_window: 524288

O que você precisa saber

• Os nomes de provedores aceitam as duas grafias: o ID do provedor do Hermes (ex.: custom:my-vllm) ou o ID do models.dev (ex.: github-copilot) — ambos são reconhecidos.
• Os IDs de modelo são correspondidos sem diferenciar maiúsculas de minúsculas, espelhando a busca do catálogo.
• Valores inválidos geram aviso, nunca travam: um valor malformado (digamos context_window: "512k") registra um aviso no log e os campos irmãos válidos continuam valendo.
• Precedência: entradas explícitas ganham dos padrões do models.dev / OpenRouter / internos; um context_length definido por modelo em custom_providers tem prioridade sobre tudo, então nunca é sobrescrito.
• Isso combina perfeitamente com custom_providers (endpoints de API personalizados) — servidores locais, gateways de proxy e modelos internos rodam todos na mesma combinação.

Conclusão

Metadados de modelo errados são uma das armadilhas mais traiçoeiras para quem usa modelos locais e modelos novos: o recurso existe, o Hermes só não sabe. O model_overrides existe exatamente para isso — sem mudar código, sem esperar uma atualização do catálogo; declare algumas linhas no config.yaml e o Hermes finalmente conhece o seu modelo. Se você ainda não explorou a configuração de modelos personalizados, o guia de instalação mostra como configurar provedores, e os provedores de modelo instalados via pip apresentam um caminho complementar para apresentar novos modelos ao Hermes.