Agent Skills
返回列表
🤖

Hugging Face 本地 GGUF 模型

AI Agent 更新于 2026.08.29

将以下提示词粘贴到你的 AI 对话框中：

请根据 https://skillhub.cn/install/skillhub.md，安装 @org-02qudk26/huggingface-local-models-zh。

技能介绍

要解决什么问题

本地跑大模型时，Hugging Face Hub 上仓库命名、量化标签和文件树并不统一：有的用 Q4_K_M，有的用 UD-Q4_K_M 或 IQ 变体；主权重和 mmproj-*.gguf 投影文件也容易混选。若不清楚 llama.cpp 与 Hub 的集成方式，很容易下错文件或反复试命令。

技能如何工作

技能把 Hub 发现到启动串成一条默认流程：

  1. 用 apps=llama.cpp 或 local-app=llama.cpp 筛兼容仓库，优先参考页面上 HF 给出的量化建议。
  2. 通过 Hub 树 API（.../api/models/{repo}/tree/main?recursive=true）核对精确的 .gguf 文件名，避免凭猜测拼路径。
  3. 优先用 llama-cli -hf <repo> 或 llama-server -hf <repo> 从 Hub 直接拉取运行；命名不规范时回退到 --hf-repo 加 --hf-file。
  4. 量化选择：默认 Q4_K_M；代码/技术负载在内存允许时倾向 Q5_K_M / Q6_K；RAM/VRAM 紧张时考虑 Q3_K_M、Q4_K_S 或仓库自带的 IQ/UD 变体，并保留仓库原生标签，不做「规范化」改名。
  5. 仅当仓库尚未提供 GGUF 时，才考虑从 Transformers 权重转换（并指向官方 GGUF 转换 Space）。

技能内还引用 hub-discovery.md、quantization.md、hardware.md，分别对应 URL 优先的检索流程、量化权衡与 Metal/CUDA/ROCm/CPU 构建要点。

适用边界

  • 面向 GGUF + llama.cpp 链路，不是通用的 Transformers from_pretrained 教程。
  • 受限（gated）仓库需自行完成 Hugging Face 身份验证后再拉取。
  • 多模态场景需区分主 checkpoint 与 mmproj 投影权重，不要误把投影文件当唯一模型文件。

使用场景

  • 要在内网 GPU 机器上用 `llama-server` 拉取指定 HF 仓库的 GGUF，需要先通过树 API 核对主权重文件名再写启动参数。
  • 笔记本 VRAM 只有 8GB，要从 Hub 的 llama.cpp 兼容页挑选 Q3/Q4 变体，避免误选更大的 UD 或 Q6 文件。
  • 仓库量化标签是 `UD-Q4_K_M` 等非标准命名，需要按技能流程用 `--hf-repo` 与 `--hf-file` 精确指定而非 `-hf` 简写。
  • 多模态模型仓库里同时有主 checkpoint 与 `mmproj-*.gguf`，要分开加载投影权重，避免只下载其中一个就启动失败。

适合人员

  • 负责把 Hugging Face 上的开源模型部署到公司内网推理节点、需要标准化 Hub 检索与 llama.cpp 启动参数的 MLOps 工程师。
  • 因数据不能出域、必须在离线环境从 Hub 拉 GGUF 做实验对比量化的隐私敏感场景下的算法研究员。
  • 在单机 Metal/CUDA 上自建 coding assistant，想按仓库页面建议选 Q4_K_M 或 Q5_K_M 并做冒烟测试的独立开发者。
  • 维护本地模型目录、经常遇到 gated 仓库与自定义文件命名、需要查 hub-discovery 与 quantization 参考流程的技术写作者。