使用 llama.cpp 与 GGUF 在本地运行 Hugging Face 模型huggingface-local-models 技能全流程实战【免费下载链接】skillsGive your agents the power of the Hugging Face ecosystem项目地址: https://gitcode.com/GitHub_Trending/skills7/skills本文以开源仓库 skills7/skills 中的huggingface-local-models技能为核心系统讲解如何在 CPU、Apple Metal、NVIDIA CUDA 与 AMD ROCm 硬件上借助 llama.cpp 与 GGUF 格式在本地运行 Hugging Face 模型。读完本文你将掌握从 Hub 搜索 GGUF 仓库、选择正确的量化档位、通过 tree API 精确定位.gguf文件、启动llama-cli/llama-server推理服务、在缺少现成 GGUF 时完成权重转换以及用 OpenAI 兼容接口做冒烟测试的完整实战链路。技能定位这个 Skill 解决什么问题huggingface-local-models是仓库中面向本地推理场景的工作流技能其 frontmatter 描述为使用 llama.cpp 与 GGUF 在 CPU、Mac Metal、CUDA 或 ROCm 上运行模型覆盖 GGUF 查找、量化选择、服务启动、精确文件定位、格式转换与 OpenAI 兼容本地服务。仓库 README.md 的技能表中将其定位为 select models to run locally with llama.cpp and GGUF on CPU, Mac Metal, CUDA, or ROCm。它的核心思想很明确在动手下载或转换之前先用 Hub 的检索能力找到现成的 GGUF 仓库并优先信任 Hugging Face 官方推荐的量化档位而不是凭经验猜测。这与仓库中其他技能形成互补——hf-cli技能提供hf download、hf auth login等底层 Hub 操作能力见 hf-cli/SKILL.md而本技能专注于选什么模型、用什么量化、怎么启动这条端到端路径。默认工作流七步总览技能定义了默认工作流是整个本地推理过程的骨架在 Hub 模型搜索页使用appsllama.cpp过滤器搜索仓库。打开目标仓库的 local-app 视图repo?local-appllama.cpp让页面渲染出适配 llama.cpp 的推荐量化。优先采用该页面给出的官方Use this model片段与量化推荐。通过 tree API/api/models/repo/tree/main?recursivetrue确认仓库内确切的.gguf文件名。用llama-cli -hf repo:QUANT或llama-server -hf repo:QUANT直接启动。当仓库使用自定义文件命名时回退到--hf-repo--hf-file精确指定文件。仅当仓库没有现成 GGUF 文件时才从 Transformers 权重转换。这条工作流强调先检索、后下载、最后才是转换可以最大化利用社区已经量化好的成果避免重复计算。URL 优先不装客户端也能完成模型发现技能对应的参考文档 references/hub-discovery.md 提出一个原则优先使用 URL 工作流。也就是说找到 GGUF 文件、选定量化档位、构造llama-server启动命令这三件事都可以只用浏览器 URL 完成不必先安装hfCLI 或调用 API 客户端。1. 搜索 llama.cpp 兼容的模型从模型浏览页出发在其 URL 上追加以下查询参数即可完成不同粒度的搜索# Hub 模型浏览页支持的查询参数 ?appsllama.cppsorttrending ?searchtermappsllama.cppsorttrending ?searchtermappsllama.cppnum_parametersmin:0,max:24Bsorttrending参数含义appsllama.cpp只显示声明兼容 llama.cpp 的仓库是搜索的第一道过滤searchterm按模型家族名搜索如Qwen、Gemma、Phi、Mistralnum_parametersmin:0,max:24B按参数量约束适配硬件内存上限例如 24B 以内sorttrending按当前热度排序适合寻找当下流行的仓库。文档特别强调如果用户还没有选定模型家族不要直接从随机 GGUF 仓库开始应该先搜索、再筛选。例如Qwen 24B 上限 trending 的组合搜索就是一个不错的起点。2. 用 local-app 页面读取推荐量化对具体仓库打开其 local-app 视图# 仓库的 local-app 视图在仓库页 URL 后追加 ?local-appllama.cpp # 完整形式repo?local-appllama.cpp按顺序从页面提取信息若页面以文本形式可见直接复制Use this model官方片段从页面的Hardware compatibility区域读取量化标签、文件大小、位深分组注意片段中可能出现的额外启动参数如--jinja。当官方片段可见时以 Hugging Face 的 local-app 片段作为事实来源。注意这里的读取方式是读取 URL 抓取到的页面源文本而不是假设浏览器渲染了界面如果抓取的页面源码没有暴露Hardware compatibility区域应当如实说明该区域不可见然后回退到 tree API 加 quantization.md 的通用指南。3. 用 tree API 确认确切文件名打开仓库的 tree API 端点# 仓库 tree API返回 JSON /api/models/repo/tree/main?recursivetrue # 仓库文件树网页视图人工回退 repo/tree/main把 JSON 响应当作仓库清单的事实来源筛选条件是type为file且path以.gguf结尾。重点字段包括path文件名与所在子目录size字节大小lfs.size可选用用于确认 LFS 负载大小。将筛选结果分类量化单文件检查点例如Qwen3.6-35B-A3B-UD-Q4_K_M.gguf投影器权重通常命名为mmproj-*.gguf这是多模态模型的视觉投影器不是主语言模型权重BF16 分片文件通常位于BF16/子目录下其他文件。除非用户要求忽略README.md、imatrix 校准数据等无关文件。网页版文件树只作为 API 失败或用户希望看网页时的人工回退。4. 根据结果构建启动命令命令构造的优先级如下优先复制 local-app 页面的官方片段页面给出干净量化标签时使用简写形式llama-server -hf repo:QUANT需要通过 tree API 指定确切文件时使用文件级形式llama-server --hf-repo repo --hf-file filename.gguf命令行交互而非服务场景使用llama-cli -hf repo:QUANT当仓库使用自定义标签或非标准命名可能导致:QUANT简写歧义时应当使用--hf-repo--hf-file精确文件形式。5. 完整示例unsloth/Qwen3.6-35B-A3B-GGUF以unsloth/Qwen3.6-35B-A3B-GGUF仓库为例技能的三个关键 URL 分别是搜索其 local-app 视图、tree API 与文件树网页。该仓库的 local-app 页面硬件兼容区通常展示如下量化档位UD-IQ4_XS17.7 GBUD-Q4_K_S20.9 GBUD-Q4_K_M22.1 GBUD-Q5_K_M26.5 GBUD-Q6_K29.3 GBQ8_036.9 GBtree API 则可确认这些确切文件名Qwen3.6-35B-A3B-UD-Q4_K_M.ggufQwen3.6-35B-A3B-UD-Q5_K_M.ggufQwen3.6-35B-A3B-UD-Q6_K.ggufQwen3.6-35B-A3B-Q8_0.ggufmmproj-F16.gguf投影器约 899 MB最终输出的推荐命令形态Repo: unsloth/Qwen3.6-35B-A3B-GGUF Recommended quant from HF: UD-Q4_K_M (22.1 GB) llama-server: llama-server --hf-repo unsloth/Qwen3.6-35B-A3B-GGUF --hf-file Qwen3.6-35B-A3B-UD-Q4_K_M.gguf Other GGUFs: - Qwen3.6-35B-A3B-UD-Q5_K_M.gguf - 26.5 GB - Qwen3.6-35B-A3B-UD-Q6_K.gguf - 29.3 GB - Qwen3.6-35B-A3B-Q8_0.gguf - 36.9 GB Projector: - mmproj-F16.gguf - 899 MB需要注意仓库特有的量化标签要原样保留。除非页面本身就写成Q4_K_M否则不要擅自把UD-Q4_K_M改写为Q4_K_M。快速开始安装、认证与直连启动安装 llama.cpp包管理器最省事brew install llama.cpp winget install llama.cpp无包管理器环境则克隆官方仓库源码编译git clone llama.cpp-官方仓库 llama.cpp cd llama.cpp make为 gated 仓库认证如果模型仓库受门控gated保护需要先登录 Hugging Facehf auth login该命令属于hfCLI 的auth子命令族与hf auth whoami、hf auth token等同级完整命令清单见 hf-cli/SKILL.md。从 Hub 直接运行简写形式直接拉取指定量化的 GGUF 并运行llama-cli -hf unsloth/Qwen3.6-35B-A3B-GGUF:UD-Q4_K_M llama-server -hf unsloth/Qwen3.6-35B-A3B-GGUF:UD-Q4_K_M其中llama-cli是交互式命令行llama-server会启动一个 HTTP 服务。冒号后的UD-Q4_K_M是量化标签对应仓库内确切文件名Qwen3.6-35B-A3B-UD-Q4_K_M.gguf。精确运行指定 GGUF 文件当仓库采用自定义命名UD-*、IQ*等变体导致简写歧义时用文件级参数精确定位llama-server \ --hf-repo unsloth/Qwen3.6-35B-A3B-GGUF \ --hf-file Qwen3.6-35B-A3B-UD-Q4_K_M.gguf \ -c 4096这里--hf-repo指定 Hub 仓库--hf-file指定仓库内确切文件名-c 4096设置上下文长度。仅当仓库没有 GGUF 时才转换不要在有现成 GGUF 的仓库上重复转换。只有当目标仓库没有暴露 GGUF 文件时才走转换链路hf download repo-without-gguf --local-dir ./model-src python convert_hf_to_gguf.py ./model-src \ --outfile model-f16.gguf \ --outtype f16 llama-quantize model-f16.gguf model-q4_k_m.gguf Q4_K_M三步分别是用hf download拉取原始 Transformers 权重--local-dir指定本地目录、用convert_hf_to_gguf.py转成 FP16 GGUF、再用llama-quantize量化到目标档位。hf download的命令细节--type、--revision、--cache-dir、--force-download等参数可在 hf-cli/SKILL.md 中查阅。冒烟测试本地服务启动本地服务器llama-server -hf unsloth/Qwen3.6-35B-A3B-GGUF:UD-Q4_K_M然后用 curl 调用 OpenAI 兼容的 chat completions 接口验证curl http://localhost:8080/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer no-key \ -d { messages: [ {role: user, content: Write a limerick about exception handling} ] }默认服务端口为 8080Authorization头在本地场景可以传任意值示例中为no-key。这条命令验证了服务器能否正确加载模型并完成一次完整生成。量化档位选择从推荐到原理技能内置的选型规则SKILL.md 给出六条量化选择规则优先采用 Hugging Face 在 local-app 页面上标注兼容的确切量化保留仓库原生标签如UD-Q4_K_M不要规整化改写默认使用Q4_K_M除非仓库页面或硬件配置另有建议代码或技术型负载、内存允许时优先Q5_K_M或Q6_K内存/显存紧张时考虑Q3_K_M、Q4_K_S或仓库特有的IQ/UD-*变体将mmproj-*.gguf视为投影器权重而不是主检查点。量化格式对比7B 参考数据参考文档 references/quantization.md 给出了完整格式对比表以 7B 模型、WikiText-2 困惑度为参考格式困惑度perplexity大小7B速度备注FP165.9565基线13.0 GB15 tok/s原始质量Q8_05.95840.03%7.0 GB25 tok/s几乎无损Q6_K5.96420.13%5.5 GB30 tok/s质量/体积最佳Q5_K_M5.97960.39%4.8 GB35 tok/s均衡Q4_K_M6.05651.68%4.1 GB40 tok/s推荐Q4_K_S6.11252.62%3.9 GB42 tok/s更快、质量略低Q3_K_M6.31846.07%3.3 GB45 tok/s仅建议小模型Q2_K6.867315.3%2.7 GB50 tok/s不推荐结论很清晰Q4_K_M是质量与速度的最佳平衡点是默认选择。K-quant 方法与标签语义K-quant 采用混合精度以提升质量注意力层权重用更高精度前馈层权重用更低精度。变体后缀含义_SSmall更快、质量更低_MMedium均衡推荐_LLarge质量更好、体积更大。以Q4_K_M为例拆解Q4表示 4-bit 量化K表示混合精度方法M表示中等质量档位。按场景选择参考文档给出了分场景建议通用用途聊天、助手Q4_K_M最佳平衡内存富余可选Q5_K_M代码生成Q5_K_M或Q6_K高精度有助于代码创意写作Q4_K_M足够Q3_K_M可用于草稿生成技术/医疗Q6_K或Q8_0追求最大准确度边缘设备如树莓派Q2_K或Q3_K_S以适配有限内存。不同规模模型的体积与内存需求7B 参数模型格式大小所需 RAMQ2_K2.7 GB5 GBQ3_K_M3.3 GB6 GBQ4_K_M4.1 GB7 GBQ5_K_M4.8 GB8 GBQ6_K5.5 GB9 GBQ8_07.0 GB11 GB13B 参数模型格式大小所需 RAMQ2_K5.1 GB8 GBQ3_K_M6.2 GB10 GBQ4_K_M7.9 GB12 GBQ5_K_M9.2 GB14 GBQ6_K10.7 GB16 GB70B 参数模型格式大小所需 RAMQ2_K26 GB32 GBQ3_K_M32 GB40 GBQ4_K_M41 GB48 GBQ4_K_S39 GB46 GBQ5_K_M48 GB56 GB70B 场景的实践建议是用Q3_K_M或Q4_K_S适配消费级硬件。需要精确估算加载某个 GGUF 权重所需内存时仓库中的hf-mem技能可以配合使用见 README.md 技能表。用 imatrix 提升量化质量imatriximportance matrix重要性矩阵是用于改进量化质量的校准数据对 Q4 可带来约 10–20% 的困惑度改善对 Q3 及以下档位几乎是必需。使用流程# 1. 用校准数据生成重要性矩阵 ./llama-imatrix \ -m model-f16.gguf \ -f calibration-data.txt \ -o model.imatrix # 2. 携带 imatrix 执行量化 ./llama-quantize \ --imatrix model.imatrix \ model-f16.gguf \ model-Q4_K_M.gguf \ Q4_K_M校准数据的选择建议使用领域相关文本如代码模型用代码语料约 100MB 代表性文本数据质量越高量化质量越好。批量量化一次生成多个量化档位for quant in Q4_K_M Q5_K_M Q6_K Q8_0; do ./llama-quantize \ model-f16.gguf \ model-${quant}.gguf \ $quant done硬件加速Metal、CUDA、ROCm 与 CPU参考文档 references/hardware.md 给出了按平台区分的构建与启动方式。Apple SiliconMetalmake clean make GGML_METAL1 llama-cli -m model.gguf -ngl 99 -p Hello-ngl 99表示把尽可能多的层卸载到 Metal GPU近似全部卸载。NVIDIACUDAmake clean make GGML_CUDA1 llama-cli -m model.gguf -ngl 35 -p Hello # 大模型混合卸载部分层留给 GPU llama-cli -m llama-70b.Q4_K_M.gguf -ngl 20 # 多 GPU 按比例切分 llama-cli -m large-model.gguf --tensor-split 0.5,0.5 -ngl 60--tensor-split 0.5,0.5在两块 GPU 间按 50/50 切分张量-ngl控制卸载到 GPU 的层数。AMDROCmmake LLAMA_HIP1 llama-cli -m model.gguf -ngl 999ROCm 构建用LLAMA_HIP1-ngl 999用于将全部层卸载到 AMD GPU。CPU# 线程数匹配物理核心而非逻辑线程 llama-cli -m model.gguf -t 8 -p Hello # BLAS 加速构建 make LLAMA_OPENBLAS1CPU 场景的关键点是-t线程数应按物理核心设置并可通过LLAMA_OPENBLAS1启用 BLAS 加速。质量测试与故障排查用困惑度量化质量# 计算困惑度质量指标数值越低越好 ./llama-perplexity \ -m model.gguf \ -f wikitext-2-raw/wiki.test.raw \ -c 512参照基准FP16 基线约 5.96Q4_K_M 约 6.061.7%Q2_K 约 6.8715.3%退化过大。常见问题与对策模型输出乱码量化过狠如 Q2_K改用Q4_K_M或Q5_K_M并核验模型转换是否正确。内存不足换更低量化如用Q4_K_S替代Q5_K_M、减少 GPU 卸载层数-ngl、缩小上下文-c 2048。推理缓慢高量化档位计算更重Q8_0明显慢于Q4_K_M需要在速度与质量间权衡。与其他技能的分工协作在仓库生态中huggingface-local-models与相邻技能各司其职hf-cli提供hf download、hf auth login等 Hub 底层操作本技能中的下载与认证命令正是它的子集hf-mem用于估算加载 Safetensors 或 GGUF 权重所需内存与本技能的量化选择环节互补当本地硬件无法满足需求时可转向仓库中的云端推理与训练技能如huggingface-zerogpu、huggingface-spaces作为扩展路径。进一步阅读references/hub-discovery.mdURL 优先工作流、模型搜索、tree API 提取与命令重建的完整细节references/quantization.md量化格式表、模型规模扩展、质量权衡与 imatrix 使用references/hardware.mdMetal、CUDA、ROCm、CPU 的构建与加速细节hf-cli/SKILL.mdhf命令全集覆盖下载、认证与仓库管理README.md技能安装方式与全量技能清单。以上所有命令与参数均来自本仓库技能文档安装与运行均在本机完成不涉及对仓库内容的任何修改。【免费下载链接】skillsGive your agents the power of the Hugging Face ecosystem项目地址: https://gitcode.com/GitHub_Trending/skills7/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考