Hugging Face's logo

Spaces:
JackKing001
/
Hermes
Running

App Files Community
Hermes / README.md
GitHub Action
Auto deploy from GitHub 2026-05-10 16:36:00
f735ff5
preview code
|
raw
history blame contribute delete
15.6 kB
metadata 
title: Hermes
emoji: 🐳
colorFrom: blue
colorTo: indigo
sdk: docker
pinned: false

Hermes AI Application

20260504更新内容

2.1 Baoyu 技能系统（Baoyu Skills）

什么是 Baoyu Skills？ 这是知名AI大神宝玉老师的一套开源的 AI 技能库，就像一本"AI 技能菜谱"，里面包含了各种预置的功能模块。 使用的三个核心技能：

1. baoyu-imagine（AI 画画技能）

  • 功能： 根据文字描述生成图片
  • 支持的后端： Google Gemini、SiliconFlow、OpenAI 等
  • 特点： 可以设置图片尺寸、质量、比例等参数

2. baoyu-cover-image（封面图生成）

  • 功能： 自动为文章生成封面图
  • 特点： 可以设置风格、配色、字体等

3. baoyu-article-illustrator（文章配图生成）

  • 功能： 为长篇文章自动生成插图
  • 特点： 根据文章内容智能匹配图片，支持批量生成
  • 适用场景： 公众号长文、博客文章、年度报告等需要大量配图的场景

2.2 数字卡兹克（Digital Kazik）—— 长文写作助手

"数字生命卡兹克"（Khazix-writer）是 独立的开源 AI 技能。它是一个公众号长文写作 skill，由另一位大神卡兹克（Khazix）个人开发。 核心功能： 当用户需要撰写公众号文章、写稿子、续写文章、根据素材产出长文时使用。 触发词包括但不限于： 写文章、写稿子、帮我写、续写、扩写、公众号文章、长文、出稿、按我的风格写

2.3 数据同步系统（Data Sync）

为什么要数据同步？ 因为 Hugging Face Spaces 的容器重启后会丢失所有数据，就像电脑重启后内存里的东西会消失一样。 工作原理（用邮局比喻）：

  1. 备份： 每次有新的聊天记录、图片、配置，就打包寄到"邮局"（Hugging Face Dataset）
  2. 恢复： 容器重启后，从邮局取回之前的包裹，恢复所有数据
  3. 注意SKIP_CONFIG_RESTORE 的作用是： 这是一个 "不恢复配置" 的开关。默认行为（不设置此变量）：
  • Space 重启时，会从 Dataset 恢复 所有 之前保存的文件
  • 包括 config.yaml、.env、以及各种配置
  • 这会把你调试配置阶段手动修改的设置覆盖掉 设置 SKIP_CONFIG_RESTORE=true 后：
  • 跳过恢复某些配置文件，比如 config.yaml和baoyu_skills/等等
  • 但其他数据正常恢复： 聊天记录、图片、记忆、skills、会话历史等
  • 容器重启后entrypoint.sh 会重新生成受保护的配置文件，比如 config.yaml 等。 建议如果没有修改配置的需求时或者配置稳定后使用设置SKIP_CONFIG_RESTORE=false，这样每次重启会从dataset中恢复所有备份。

2.4 图片浏览和下载服务

核心组件 image-proxy.js —— 一个 Node.js 代理服务器，部署在 Space 的 :7860 端口（对外暴露的端口）。 工作原理 用户访问 https://usernamename-spacename.hf.space/images/ ↓ image-proxy.js (端口 7860) ↓ 读取 /data/.hermes/image_cache/ 目录 ↓ 返回 HTML 图片列表页面 功能特性

  1. 图片列表页面（/images/）
  • 自动扫描 image_cache 目录下的所有图片
  • 生成美观的 HTML 页面展示所有图片
  • 支持缩略图预览、下载链接、原始大小查看
  1. 单图片访问（/images/）
  • 直接访问单张图片，可用于嵌入到聊天或其他页面
  • 支持常见的图片格式：png, jpg, jpeg, gif, webp
  1. 代理功能
  • 除了 /images/ 路径，其他所有请求都转发给 BFF（:7861）
  • 这意味着 :7860 是统一入口，既提供图片服务，又提供 Web UI 特点：
  1. 图片持久化：生成的图片保存在 /data/.hermes/image_cache/
  2. Web 可访问：通过 /images/ URL 可以直接在浏览器查看
  3. 方便分享：用户可以把图片 URL 分享给其他人
  4. 统一管理：所有 AI 生成的图片集中在一个地方

4.26更新内容；

web UI 主要功能上手指南 现在你的 AI 助手已经部署好、微信也接通了，来看看 Web UI 还能做什么。

7.1 聊天（Chat）

点击左侧的 Chat 按钮，进入聊天界面。

  • 新建对话：点左上角的 + New Chat 按钮
  • 切换模型：在聊天框上方的下拉菜单中切换不同的 AI 模型
  • 搜索历史：按 Ctrl+K 可以搜索所有历史对话
  • 上传文件：点击聊天框旁边的附件按钮，可以上传图片或文件让 AI 分析
  • 下载文件：AI 生成的文件可以在对话中直接下载

7.2 模型管理（Models）

点击左侧的 Models 按钮。

  • 这里列出了你所有可用的 AI 模型供应商
  • 点击任意供应商可以看到该供应商下有哪些模型
  • 你可以添加新的供应商（支持任何 OpenAI 兼容的接口）
  • Nous Portal 和 OpenAI Codex 还支持 OAuth 登录，直接在网页上点击授权就行

7.3 用量统计（Usage）

点击左侧的 Usage 按钮。

  • 你可以看到 token 使用量的每日趋势图
  • 每个模型的使用占比
  • 估算的费用（基于公开的模型定价）
  • 缓存命中率（缓存命中越多，速度越快、费用越低）

7.4 定时任务（Jobs）

点击左侧的 Jobs 按钮。

  • 你可以创建定时任务，让 AI 在指定时间自动做事
  • 比如每天早上 8 点总结新闻、每周一整理待办事项
  • 支持 Cron 表达式（高级用户），也有简单的预设可选
  • 可以随时暂停、恢复或手动触发执行

7.5 技能和记忆（Skills & Memory）

点击左侧对应的按钮。

  • Skills：查看 AI 自己学到的技能。AI 会在使用过程中自动创建技能，比如"如何调用某个 API"或"用户喜欢的代码风格"
  • Memory：查看和编辑 AI 关于你的记忆。你可以修改这些记忆来让 AI 更了解你

7.6 设置（Settings）

点击右上角的齿轮图标。

  • Display：调整显示偏好（流式输出、紧凑模式等）
  • Agent：AI 的行为参数（最大迭代次数、超时时间等）
  • Memory：记忆系统的开关和限制
  • Session：会话超时和重置设置
  • Privacy：隐私保护（自动去除个人信息）

4.20更新了哪些内容

1. 备份恢复不再覆盖模型配置

改动文件：src/data_sync.py

之前的工作流程是：Space 启动 → 从 Dataset 恢复旧配置（覆盖新配置）→ 启动 Hermes。这导致每次重启后模型配置都被旧数据覆盖。

现在的流程是：Space 启动 → 从 Dataset 恢复其他数据（聊天记录、人格设定等）→ 跳过 config.yaml → 由启动脚本根据当前环境变量重新生成配置。

具体来说，data_sync.py 的 restore_from_download() 方法现在会：

  • 默认跳过 config.yaml 的恢复（由环境变量 SKIP_CONFIG_RESTORE=true 控制）
  • 仅在本地完全不存在 config.yaml 时，才从备份中恢复一份作为初始值
  • 其他数据（聊天记录、人格、技能等）照常恢复，不受影响

2. 三层防覆盖机制保护模型配置

改动文件：entrypoint.sh

即使跳过了旧配置恢复，Hermes 内部仍然有一个"配置桥接"机制，会在启动时自动检测 API Key 并可能修改 config.yaml。为了防止这种情况，我们增加了三层保护：

第一层：环境变量注入

  • 在 Hermes 启动前，将所有供应商的 Base URL 导出到进程环境变量中
  • 导出 HERMES_MODEL 环境变量，确保定时任务等场景也使用正确的模型
  • 环境变量列表包括：NVIDIA_BASE_URL、SILICONFLOW_BASE_URL、GEMINI_BASE_URL、OPENROUTER_BASE_URL、LONGCAT_BASE_URL

第二层：启动前强制锁定

  • 在 Dashboard 启动前，通过 hermes config set 命令将模型配置写入 config.yaml
  • 如果 hermes config set 不可用，回退到 yq 工具直接修改 YAML 文件
  • 修改后立刻用 yq 读取验证，确认模型字段没有被意外修改

第三层：启动后二次验证

  • Dashboard 改为后台启动，等待 5 秒初始化
  • 再次读取 config.yaml，检查模型配置是否被 Dashboard 启动流程覆盖
  • 如果发现被修改或被清空，立即用 yq 修正回正确值
  • 没有 yq 时回退到 sed 做局部修改（不会破坏其他配置项）

3. 修复压缩阈值错误

改动文件：entrypoint.sh、config/config.yaml

Hermes 的 compression.threshold 是一个比率值（0 到 1 之间的小数），不是绝对 token 数。例如 0.50 表示"当对话上下文使用到模型上下文窗口的 50% 时触发压缩"。

之前的配置写了 threshold: 4000，Hermes 把它当作"400000%"来计算，得出的压缩阈值为 8.19 亿 tokens，远超压缩模型 100 万 tokens 的处理能力，导致压缩功能完全失效。

现在改为 threshold: 0.50，含义清晰：对话上下文达到模型上限的 50% 时触发压缩，压缩模型 gemini-3-flash-preview（1M 上下文）完全能够处理。

4. Dockerfile 支持自动更新和 YAML 处理

改动文件：Dockerfile

  • 移除了 --branch v2026.4.13 固定版本参数，改为始终拉取最新代码。这样在 Hugging Face Space 的 Settings 页面点击 Factory Rebuild，就会自动获取 Hermes Agent 的最新版本
  • 新增安装 yq（YAML 处理工具），用于运行时精确修改 config.yaml 中的特定字段，而不是覆盖整个文件

5. 更新默认模型

改动文件：entrypoint.sh、config/config.yaml

NVIDIA 供应商的默认模型从 minimaxai/minimax-m2.7（该模型在实际使用中无响应）更换为 moonshotai/kimi-k2-thinking。

Hermes Agent v0.9.0 on Hugging Face Spaces

智能AI代理，支持16个消息平台，持久化记忆，和Web管理界面。

功能

  • 🤖 AI 对话与工具调用
  • 🌐 Web Dashboard 管理
  • 💾 数据持久化到 Hugging Face Dataset
  • 🔔 支持消息网关（Telegram/Discord/Slack等）
  • ⚡ 自动唤醒保持在线

技术栈

  • Hermes Agent v0.9.0
  • FastAPI Web Dashboard
  • Hugging Face Datasets 持久化
  • Docker Spaces

数据目录映射

Hermes 目录 Dataset 路径 说明
~/.hermes/config.yaml /config/config.yaml 核心配置
~/.hermes/.env /config/.env 环境变量
~/.hermes/auth.json /config/auth.json OAuth认证
~/.hermes/SOUL.md /personality/SOUL.md 代理人格
~/.hermes/memories/ /memories/ 持久记忆
~/.hermes/skills/ /skills/ 自定义技能
~/.hermes/sessions/ /sessions/ 会话历史
~/.hermes/state.db /state/state.db SQLite数据库
~/.hermes/logs/ /logs/ 日志文件
~/.hermes/cron/ /cron/ 定时任务

环境变量 

# 必需
HF_DATASET_REPO=your-username/hermes-data

# 可选
HERMES_HOME=/data/.hermes
SYNC_INTERVAL=300  # 同步间隔（秒）
HF_TOKEN=your-huggingface-token  # 用于访问私有 dataset

快速开始

1. 创建 Hugging Face Dataset 

# 创建一个新的 dataset 用于存储数据
huggingface-cli repo create hermes-data --type dataset

2. 设置环境变量

在 Hugging Face Spaces 的 Settings 中设置：

  • HF_DATASET_REPO: 你的 dataset 名称 (例如: username/hermes-data)
  • HF_TOKEN: Hugging Face access token

3. 配置唤醒服务

使用 UptimeRobot 或 Cron-job.org 定期访问 Space URL 以保持在线。

部署步骤

部署到 Hugging Face Spaces

方式一：通过 Web 界面部署

  1. 创建 Space: 访问 https://huggingface.co/new-space

    • 选择 "Docker" SDK
    • 设置 Space 名称
    • 选择硬件配置（免费版即可开始）

  2. 克隆 Space 仓库:

git clone https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME
cd YOUR_SPACE_NAME
  1. 复制项目文件:
# 复制所有项目文件到 Space 目录
cp -r /path/to/hermes-spaces/* .

  1. 配置环境变量:

    • 在 Space Settings → Variables 中设置:
      • HF_DATASET_REPO: your-username/hermes-data
      • HF_TOKEN: your-huggingface-token

  2. 提交并推送:

git add .
git commit -m "Initial deployment"
git push
  1. 等待部署完成:
    • 访问 https://huggingface.co/spaces/YOUR_USERNAME/YOUR_SPACE_NAME
    • 查看 Build 日志，等待部署完成

方式二：通过 GitHub Actions 自动部署

  1. Fork 本仓库 到你的 GitHub 账号

  2. 在 Hugging Face 创建 Space:

  3. 配置 GitHub Secrets:

    • 进入 GitHub 仓库 → Settings → Secrets and variables → Actions
    • 添加以下 secrets:
      • HF_TOKEN: 你的 Hugging Face access token
      • HF_SPACE_REPO: YOUR_USERNAME/YOUR_SPACE_NAME

  4. 推送代码到 main 分支:

git push origin main
  1. GitHub Actions 会自动部署:
    • 查看 Actions 标签页查看部署进度
    • 部署完成后访问 Space URL

配置唤醒服务

由于 Hugging Face Spaces 免费版会在 48 小时无活动后休眠，建议配置外部唤醒服务：

使用 UptimeRobot（推荐）

  1. 访问 https://uptimerobot.com 并注册账号
  2. 点击 "Add New Monitor"
  3. 配置如下：
    • Monitor Type: HTTP(s)
    • Friendly Name: Hermes Agent
    • URL: https://YOUR_USERNAME-YOUR_SPACE_NAME.hf.space/health
    • Monitoring Interval: 5 minutes
  4. 点击 "Create Monitor"

使用 Cron-job.org（备选）

  1. 访问 https://cron-job.org
  2. 创建新的 cron job
  3. 配置 URL: https://YOUR_USERNAME-YOUR_SPACE_NAME.hf.space/health
  4. 设置每 5 分钟执行一次

首次使用

  1. 访问 Space URL: https://YOUR_USERNAME-YOUR_SPACE_NAME.hf.space
  2. 首次启动会创建默认配置，从 Dataset 恢复数据（如果存在）
  3. 在 Web Dashboard 中配置：
    • API Keys（OpenAI, OpenRouter, etc.）
    • 消息网关（Telegram, Discord, etc.）
    • 代理人格（SOUL.md）

故障排除

Space 无法启动

  1. 检查构建日志:

    • 访问 Space 页面 → Files → "Build logs"
    • 查看错误信息

  2. 常见问题:

    • 内存不足: 升级到付费硬件（CPU Upgrade）
    • 依赖安装失败: 检查 requirements.txt 格式
    • 权限错误: 确保 Dockerfile 中设置了 USER appuser

数据未持久化

  1. 检查环境变量:

    • 确认 HF_DATASET_REPO 已正确设置
    • 确认 HF_TOKEN 有写入 Dataset 的权限

  2. 检查 Dataset 权限:

    • 确保 Dataset 是私有的（推荐）
    • 确保 Token 有 write 权限

  3. 查看同步日志:

    • 在 Space 的 Logs 中查看 data-sync 相关日志

消息网关断开

  1. 这是正常现象: Spaces 休眠后所有连接会断开
  2. 解决方案:
    • 升级到付费版保持持续运行
    • 或配置网关自动重连（在 Hermes 配置中设置）

文件说明

  • Dockerfile - Docker 镜像定义
  • entrypoint.sh - 容器启动脚本
  • requirements.txt - Python 依赖
  • src/data_sync.py - 数据同步服务
  • .github/workflows/deploy.yml - GitHub Actions 自动部署

许可证

MIT License - 详见 LICENSE 文件

贡献

欢迎提交 Issue 和 Pull Request！

相关链接