内网离线部署本地模型 Agent 的完整打法

一、绕开 GitHub：用国内可达的 hf-mirror.com 镜像替代。搜 HF 上按官方命名规范发布的 llama.cpp Windows 预编译包（仓库形如 <user>/llama.cpp-<tag>-Windows-Runtime，内含 llama-<tag>-bin-win-{cpu,cuda-12.4,cuda-13.3,vulkan}-x64.zip + checksums.sha256 + runtime-manifest.json），下载后必须用仓库公布的 SHA256 逐条校验，不符即弃用。 二、必须选 Vulkan 版而非 CUDA 版：镜像里的 CUDA zip

适用场景

解决思路

1. 一、绕开 GitHub：用国内可达的 hf-mirror.com 镜像替代。搜 HF 上按官方命名规范发布的 llama.cpp Windows 预编译包（仓库形如 <user>/llama.cpp-<tag>-Windows-Runtime，内含 llama-<tag>-bin-win-{cpu,cuda-12.4,cuda-13.3,vulkan}-x64.zip + checksums.sh
2. 二、必须选 Vulkan 版而非 CUDA 版：镜像里的 CUDA zip 只带 ggml-cuda.dll、不含 cudart 运行时库，解压后直接跑会静默降级到 CPU（日志 device_info 只有 CPU、显存占用不动、无报错），速度差 4-5 倍且极难排查。Vulkan 版自包含 ggml-vulkan.dll，实测 6GB 显存笔记本 GPU 可用。
3. 三、手工放置运行时并写 manifest：Hermes 的运行时下载地址硬编码指向 GitHub releases（binaries.py: RELEASE_URL=https://github.com/...），无环境变量可覆盖，内网必然失败。解决：把 zip 解压到 <hermes_root>/runtimes/llamacpp/<tag>/<backend>/，并写 manifest.jso
4. 四、手工放置模型：GGUF 直接丢进 <hermes_root>/models/ 即被识别（staged_model_ids() 可验证）
5. 模型 id = 文件名去掉 .gguf 的 stem。
6. 五、6GB 显存跑 8B@64K 的关键参数：8B Q4_K_M 权重 4.9GB + 64K KV 缓存放不进 6GB（实测报 ErrorOutOfDeviceMemory / failed to allocate buffer for kv cache）。解法是 --no-kv-offload 把 KV 缓存放内存、权重留 GPU，配合 -c 65536 -ngl 99 -ctk q4_0 -
7. 六、中文 Windows 采集 netstat/tasklist 时，子进程输出是 GBK 而非 UTF-8，用 text=True 会抛 UnicodeDecodeError，必须显式 decode('gbk', errors='replace')。

适用边界 · 注意事项

• 此打法依赖 hf-mirror.com 可达；若该镜像也不通需另找镜像或走审批单向导入
• 若内网已有私有推理服务（vLLM/TGI 等），应直接用 custom provider 指向它，不必在本机装 llama.cpp
• 该环境实测 Qwen2.5-Coder 全系原生上下文仅 32768，不满足需要 64K 上下文的应用要求，须选原生 128K 的模型（如 Llama-3.1-8B）或做 YaRN 扩展
• Vulkan 方案在非 NVIDIA 或驱动不支持的机器上需改选 CPU 版