Hermes Agent 模型接入

Hermes Agent 接入 Hugging Face：Token 配置、模型选择与排错

Hermes Agent 原生支持 Hugging Face Inference Providers。接入时重点检查两件事：Token 是否有推理调用权限，以及所选模型是否能通过该服务进行对话。下面按配置顺序说明。

本文根据站内英文指南整理，适用于使用原生 Hugging Face 集成的 Hermes Agent。模型与提供商的可用性，以实际配置时的列表和账户权限为准。

Hermes 与 Hugging Face 如何配合？

Hugging Face Inference Providers 通过统一接口，连接多家推理合作伙伴提供的模型。Hermes 使用原生的 hf 提供商，读取你的 Hugging Face Token，再把对话请求发送给选定的模型。

本文介绍的是托管推理，无需在本地下载模型权重，也不需要本地 GPU。用量、提供商路由、模型可用性和账单由你的 Hugging Face 账户管理。

开始前准备什么？

已经安装并能正常运行的 Hermes Agent。
一个 Hugging Face 账户。
具有 Inference Providers 调用权限的细粒度 Token。
一个通过 Inference Providers 提供服务、支持对话推理的模型。

还没安装 Hermes，可以先按中文安装教程完成安装。在国内网络环境下，建议先从实际运行 Hermes 的机器测试 Hugging Face 推理接口的可达性。

第一步：创建具有推理权限的 Token

打开 Hugging Face 账户设置，进入「Access Tokens」。
创建一个细粒度（fine-grained）Token。
启用 Make calls to Inference Providers 权限。
复制新生成的 Token，存入密码管理器。

最容易遗漏的是第三步。普通读取 Token 即使可以访问受限模型仓库，也可能没有调用推理服务的权限。

第二步：在 Hermes 中配置 HF_TOKEN

在 Hermes 的环境文件中加入下面这一项，把占位符换成自己的 Token：

# ~/.hermes/.env
HF_TOKEN=hf_your_token_here

不要把真实 Token 写进文档、命令历史、截图，或受 Git 跟踪的 .env 文件。在多人共用的系统上，还应限制这个文件的访问权限。

第三步：选择 Hugging Face 提供商和模型

最直接的方式是打开交互式模型选择器：

hermes model

在提供商列表里选择 Hugging Face，再选择可用模型。如果只想在当前对话中试用，也可以执行：

hermes chat --provider hf

希望保存为日常使用的提供商，就通过模型选择器设置；只想在这一次对话里测试 Hugging Face，则使用 --provider hf 参数。

第四步：验证连接是否正常

先发送一条简短、不含敏感信息的提示词，依次确认：

Hermes 能识别 hf 提供商。
Token 能通过 Inference Providers 的权限检查。
所选模型当前可以进行对话推理。

第一次请求保持简单，方便区分授权或路由问题，以及特定模型的提示词或工具调用问题。

怎样选择可用模型？

结合 hermes model 显示的实时列表和对应的 Hugging Face 模型页面来选。可用性会因提供商、地区、账户和模型而变化。模型在 Hub 上有页面，不代表它一定能通过无服务器的 Inference Providers API 调用。

选型建议：优先从当前提供商列表中选择，不要直接照搬旧教程里的模型 ID。

常见问题排查

出现 401 或 403 授权错误

确认变量名准确写成 HF_TOKEN。
确认 Token 已启用 Inference Providers 调用权限。
修改环境变量后，重启 Hermes 进程。
检查 Token 是否混入空格、引号，或已被撤销。

提示模型不可用

重新运行 hermes model，从当前列表选择模型。
确认模型支持对话推理。
查看模型页面列出的提供商与访问要求。
如果是受限模型，先接受许可条款，并确认账户已获得访问权限。

提供商列表中没有 Hugging Face

将 Hermes 更新到包含原生 Hugging Face 集成的版本，再重新打开模型选择器。英文原文列有 Hugging Face 官方集成说明与 Hermes Agent 上游仓库入口，可进一步核对所用版本的行为。

Token 与用量管理

为 Hermes 创建专用的细粒度 Token，避免使用权限过大的账户 Token。
只将 Token 存放在 Hermes 的运行环境中。
不要提交 ~/.hermes/.env，也不要把文件内容粘贴到聊天中。
如果 Token 出现在日志或截图中，及时更换。
定期查看 Hugging Face 用量，尽早发现意外调用。

常见问题

Hermes Agent 可以直接使用 Hugging Face 吗？

可以。Hermes 原生支持 Hugging Face Inference Providers。配置 HF_TOKEN 后，通过 hermes model 选择 Hugging Face，或用 hermes chat --provider hf 为当前对话指定该提供商。

Hugging Face Token 需要勾选什么权限？

创建细粒度 Token 时，需要启用 Make calls to Inference Providers 权限。能读取模型仓库不代表能调用推理服务，缺少这项权限仍会导致请求失败。

HF_TOKEN 应该放在哪里？

英文原文引用的上游集成说明使用 ~/.hermes/.env。将 HF_TOKEN 写入这个 Hermes 环境文件，限制文件访问权限，不要把它提交到 Git 仓库。

Hugging Face 上的所有模型都能用于 Hermes 吗？

不能。模型需要支持对话推理，并且能通过 Hugging Face Inference Providers 调用。Hub 上有模型页面，并不意味着已有可用的推理提供商为它提供服务。