你有没有过这样的经历：刚把本地跑起来的 vLLM 模型接进 Hermes，聊了没几句，它就说“上下文满了”——可你的模型明明支持 8K 甚至 128K；又或者你换了个刚发布的新模型，明明带视觉能力，Hermes 却一口咬定“这个模型不支持看图”。问题多半不在模型，而在 Hermes 对模型的“印象”来自一份模型目录，而目录里没有你的模型，或者数据过时了。好消息是，从 v0.20.1 起，你可以在 config.yaml 里用 model_overrides 直接纠正这些信息，告诉 Hermes 你的模型到底是什么样。

为什么会这样：模型目录的盲区

Hermes 判断一个模型能做什么、能装多长的上下文，主要靠 models.dev 这份公开的模型目录，外加一些内置的兜底规则。这覆盖了主流云厂商的大模型，但总有照顾不到的地方：

• 本地模型：你用 vLLM、Ollama、llama.cpp 起的服务，模型 ID 是你自己起的，目录里根本没有；
• 刚发布的新模型：厂商刚上线，目录还没来得及收录；
• 目录数据不准：上下文窗口标小了、能力标错了，或者厂商更新了版本但目录没跟上。

在这些情况下，Hermes 只能按“安全默认值”猜：上下文按 20 万 token 算（对目录外的模型），工具调用默认开，但视觉和推理默认关。猜错了，就会出现开头说的那些怪现象——明明能用的功能被当成不能用，该有的上下文被白白浪费。

解决办法：config.yaml 里的 model_overrides

model_overrides 是 v0.20.1 新增的顶层配置节（合入该版本的 PR #85560）。它的作用很简单：针对某个 provider 下的某个模型，手动声明它的元数据，覆盖目录里的值。写法如下：

model_overrides:
  custom:my-local-vllm:        # provider 名，冒号后是模型 ID
    my-llava-model:
      context_window: 8192     # 这个模型真实上下文是 8K
      supports_vision: true    # 它确实支持看图
    my-llama-model:
      context_window: 32768
      supports_tools: false    # 这个模型工具调用不稳定，干脆关掉
  upstage:                     # 也可以直接覆盖云厂商的模型
    solar-pro4:
      context_window: 524288   # 目录没收录，实际是 512K

保存后重启 Hermes（或执行 hermes config edit 修改后重启会话），覆盖立即生效。你只需要写目录里“错的”或“缺的”字段——没写的字段仍然沿用目录数据，不会误伤其他配置。

最常用的三个字段

不是所有字段都需要填，日常场景里通常只动这几个：

• context_window：模型的上下文窗口长度（token 数）。填小了对话会被过早截断，填大了模型会在超长上下文上胡言乱语，所以尽量查清真实值。
• supports_vision：是否支持图片输入。本地视觉模型（比如 LLaVA 系）最常踩这个坑——不声明的话，Hermes 永远不给你发图的能力。
• supports_tools：是否支持工具调用。如果你用的模型在工具调用上不稳定，与其让它反复出错，不如在这里明确关掉。

完整的字段清单

model_overrides 支持以下全部字段，含义和模型元数据一致：

字段	说明
context_window	上下文窗口长度（token）
max_output_tokens	单次回复最大输出 token 数
supports_tools	是否支持工具调用（默认目录外模型为 true）
supports_vision	是否支持图像输入（默认 false）
supports_reasoning	是否支持推理模式（默认 false）
model_family	模型家族标识，用于兜底规则匹配

_default：给目录外的模型兜底

一个个模型写太麻烦？可以给整个 provider 甚至全局设置一个 _default，作为目录未收录模型的兜底值：

model_overrides:
  custom:my-vllm:
    _default:                  # 只对目录里没有的模型生效
      context_window: 32768
  _default:                    # 全局兜底，同样只填目录空缺
    context_window: 128000

注意 _default 是“填坑专用”：它只对目录不认识的模型生效，绝不会覆盖目录里已有的数据。所以不用担心设了个全局默认值会误伤所有已知模型——目录里有的模型依然按目录数据走。

实战：两个真实场景

场景一：本地视觉模型。 你起了个 vLLM 服务，模型是自定义 ID，支持看图。不改配置的话 Hermes 会以为它没有视觉能力：

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

场景二：云厂商新模型。 Upstage 的 solar-pro4 刚发布时目录还没收录，上下文被兜底规则按 256K 处理，实际是 512K。声明后就能用满：

model_overrides:
  upstage:
    solar-pro4:
      context_window: 524288

注意事项

• provider 名可以写两种：Hermes 内部的 provider ID（如 custom:my-vllm），或 models.dev 的 ID（如 github-copilot），都能识别。
• 模型 ID 不区分大小写，和目录查询行为一致。
• 写错了只警告不崩溃：值格式不对（比如 context_window: "512k"）会打一条警告日志，其他合法字段照常生效。
• 优先级：显式条目 > models.dev / OpenRouter / 内置默认值；custom_providers 里按模型配置的 context_length 优先级更高，不会被覆盖。
• 这个配置项和 custom_providers（自定义 API 端点）配合使用效果最好——本地模型、代理网关、公司内部模型都能用这套组合跑通。

总结

模型元数据不准，是本地模型和新模型用户最常遇到的“隐形坑”：功能明明在，Hermes 却不知道。model_overrides 就是为这个场景设计的——不用改代码、不用等目录更新，在 config.yaml 里声明几行，Hermes 就能正确认识你的模型。如果你还没接触过自定义模型接入，可以先看看安装指南了解怎么配置 provider；pip 模型 provider 插件这篇讲了另一种让 Hermes 认识新模型的方式，两者正好互补。