Local-Hermes-Portable
一个高级的、零配置的本地 AI 推理与智能体工作区。由 Windows、macOS 和 Linux 上的硬件加速 GPU 执行提供支持。
🎥 观看设置与演示视频： https://youtu.be/TWZv6fo3JLc
## 目录
* [核心功能](#key-features)
* [系统要求](#system-requirements)
* [快速入门](#getting-started)
* [主菜单选项](#main-menu-options)
* [目录结构](#folder-architecture)
* [高级选项](#advanced-options)
* [许可证](#license)
##
核心功能
* **100% 离线且私密：** 无需网络、遥测、云日志或 API 密钥。
* **零安装便携性：** 自包含的 runtime（Python、llama.cpp 二进制文件及依赖项），可在任何存储驱动器上直接运行。
* **自主 Hermes Agent：** 预配置的 Nous Research 终端编码智能体，具备文件编辑和 Web 任务处理能力。
* **自动配置的硬件加速：** 自动同步启动器设置，并将模型层卸载到兼容 Vulkan/Metal 的 GPU。
* **最佳资源管理：** 预配置 8-bit 量化的 KV cache，64K 上下文限制以及超时保护。
* **向导式设置与恢复：** 分析硬件规格以下载推荐的 GGUF 模型，并清理僵尸服务器实例。
##
系统要求
由于 `local-hermes-portable` 是完全自包含的，因此它不需要系统范围的 Python 或 Node.js 安装。但是，您需要：
* **操作系统：**
* **Windows：** Windows 10 / 11 (64 位)
* **macOS：** macOS 11.0 (Big Sur) 或更高版本（推荐 Apple Silicon，支持 Intel）
* **Linux：** 现代的 64 位内核（兼容 Vulkan / ROCm 以实现 GPU 加速）
* **系统实用程序：** `curl` 和 `tar`（在大多数现代操作系统中均预装，用于自动引导 runtime 资产）。
* **硬件建议：**
* **RAM：** 最低 8 GB（建议 16 GB 或以上）。
* **磁盘空间：** 驱动器上有 5 GB 到 15 GB 的可用空间（取决于下载的 GGUF 模型的大小）。
* **GPU 加速：**
* *Windows/Linux：* 兼容 Vulkan 的 GPU（NVIDIA、AMD 或 Intel），用于硬件加速。
* *macOS：* Apple Silicon（M 系列芯片），用于 Metal 加速推理。
##
快速入门
首先，从项目的根目录运行相应的启动器脚本：
### Windows 设置
```
.\windows.bat
```
* **它的作用：** 自动引导一个便携式的 Python 环境，如果需要，安装 VC++ Redistributable 和 llama.cpp Vulkan 预编译二进制文件，并启动交互式菜单。
### macOS 设置
```
./mac.sh
```
* **它的作用：** 自动检测 Apple Silicon/Intel 硬件，配置便携式 Python，并使用 Metal 加速的二进制文件启动服务器。
### Linux 设置
```
./linux.sh
```
* **它的作用：** 自动检测 Vulkan/ROCm GPU 环境，构建 runtime 库，并配置便携式 Python。
##
主菜单选项
当您运行启动器时，会看到一个终端控制台：
```
=== llama-ai Portable Setup & Launcher ===
Choose an action:
1] Start Chat Server and Web UI [default]
2] Run Hardware Analysis and Model Fit [llmfit]
3] Start Hermes Agent
4] Quit
```
1. **启动聊天服务器 (选项 1)：** 在 `http://localhost:9090` 上启动 `llama-server` 并进行完整的 GPU 卸载，自动检测完整的本地 GGUF 模型，并打开 Web UI。如果不存在模型，Windows、macOS 和 Linux 都提供相同的浏览器设置：llmfit 会检测总 RAM 和当前可用 RAM，推荐合适的模型，并支持搜索如 Gemma 或 Qwen。下载过程会显示实时进度，并且可以取消/恢复。在进入正常的聊天 Web UI 之前，可以选择输入首次聊天的 prompt。
2. **硬件分析 (选项 2)：** 运行 `llmfit` 以扫描您的 CPU、GPU、RAM 和 VRAM，并为您的系统推荐最合适的 GGUF 模型。
3. **启动 Hermes Agent (选项 3)：** 启动 **Hermes Agent TUI** (Nous Research)，完全配置为使用您的本地服务器和已激活的模型进行自动化编码和浏览器任务。
##
目录结构
该仓库保持了一个简洁的、跨平台的文件结构：
```
local-hermes-portable/
├── windows.bat # Windows setup & menu launcher
├── mac.sh # macOS setup & menu launcher
├── linux.sh # Linux setup & menu launcher
├── models/ # Place your downloaded GGUF models here
├── scripts/ # Platform-specific utilities (GPU detection, benchmarks)
├── hermes/ # Nous Research Hermes Agent folder
│ ├── data/ # Settings & active database (config.yaml, session history)
│ └── src/ # Agent codebase and tools
└── llama/ # Local inference binaries & configs
├── kv-cache/ # Cache directory for prompt sharing
└── windows/ # Bootstrapped Python, binaries, and wait-server scripts
```
##
高级选项
您可以配置环境变量来覆盖启动器的默认设置：
| 变量 | 默认值 | 用途 |
| :--- | :--- | :--- |
| `LLAMA_CTX_SIZE` | `65536` | `llama-server` 的上下文窗口大小（Hermes 要求 $\ge$ 64K）。 |
| `LLAMA_SLOTS` | `1` | 并行序列槽的数量（调低可节省内存）。 |
| `LLAMA_GPU_LAYERS` | `99` | 卸载到 GPU 的层数（99 表示卸载整个模型）。 |
| `AUTO_LAUNCH_BROWSER`| `false` | 服务器就绪时是否自动打开 Web 浏览器。 |
##
许可证
该项目基于 MIT 许可证授权。详情请参阅 [LICENSE](LICENSE)。
所有内置组件（llama.cpp、Hermes Agent、llmfit）的版权归各自创作者所有，并根据其原始的开源条款进行授权。