LocalAI 模型库扩展实战：把 HuggingFace GGUF 模型发布进 Gallery（含 variants 变体机制全解析）

LocalAI 模型库扩展实战把 HuggingFace GGUF 模型发布进 Gallery含 variants 变体机制全解析【免费下载链接】LocalAILocalAI is the open-source AI engine. Run any model - LLMs, vision, voice, image, video - on any hardware. No GPU required.项目地址: https://gitcode.com/GitHub_Trending/lo/LocalAI本篇技术指南以仓库内的维护指南 adding-gallery-models.md 为核心系统讲解如何把 HuggingFace 上的 GGUF 权重发布为 LocalAI Model Gallery 中的一个条目从获取 SHA256、编写 embedding / chat 条目 YAML到理解variants变体自动选择、dflash/mtp特性标签规则与引擎偏好排序的底层实现。读完本文你将既能独立把一个新模型合规地写入gallery/index.yaml也能解释多个量化包、多引擎构建的同一模型最终该装哪一个这一本地化问题的完整答案。LocalAI 模型库是什么index.yaml 与模板配置的分工在动手之前先理解模型库的两层结构这与之后每一处字段都有关系条目目录gallery/index.yaml是唯一的模型清单。指南明确写着 All models are defined ingallery/index.yaml新增模型时应把条目放到合适的分区——embedding 模型靠近其他 embedding 模型chat 模型靠近同类型的 chat 模型并保持整体风格统一。模板配置gallery/目录下还存在大量以模型架构命名的.yaml如chatml.yaml、gemma.yaml、virtual.yaml、deepseek.yaml。它们不是另一个模型清单而是条目可引用的基础配置——每个文件内嵌一段config_file:定义后端引擎、上下文长度、stopwords、提示词模板chat/chat_message/completion/function等。以真实存在的 chatml.yaml 为例它把backend: llama-cpp、context_size: 4096、f16: true与一整套 ChatML 风格的chat_message模板绑定在一起gemma.yaml 则预设了 8192 上下文与 Gemma 家族的start_of_turn/end_of_turn模板。条目通过url:字段声明自己继承哪份模板配置。条目本体上的overrides:再对模板做局部覆盖换parameters.model文件名、追加options等。下载、校验、安装的行为由 core/gallery 下的解析逻辑驱动用户侧的一键安装入口WebUI 的Models页、POST /models/apply、CLI 与 MCP统一消费这份清单详细用户文档见 docs/content/features/model-gallery.md。第一步获取 GGUF 文件的 SHA256利用 x-linked-etagHuggingFace 上的 GGUF 文件会在 HTTP 响应头x-linked-etag中暴露其 SHA256无需下载整个权重即可取得curl -sI https://huggingface.co/org/repo/resolve/main/filename.gguf | grep -i x-linked-etag返回值的去除引号部分即为 SHA256。指南给了一个完整的可验证示例curl -sI https://huggingface.co/ggml-org/embeddinggemma-300m-qat-q8_0-GGUF/resolve/main/embeddinggemma-300m-qat-Q8_0.gguf | grep -i x-linked-etag # x-linked-etag: 6fa0c02a9c302be6f977521d399b4de3a46310a4f2621ee0063747881b673f67这个例子并非虚构——gallery/index.yaml#L27782-L27804 中真实的embeddinggemma-300m条目其files[].sha256正是6fa0c02a9c302be6f977521d399b4de3a46310a4f2621ee0063747881b673f67。务必注意文件名的精确大小写HuggingFace 文件名区分大小写例如Q8_0与q8_0是两个不同的对象同一仓库路径 URL 中也可能同时出现大小写混合上例仓库名是qat-q8_0文件名却含大写Q8_0。发布前一定要先核对仓库的文件列表照抄真实文件名而不是凭记忆或按其他量化命名规则推断。第二步选择正确的模板配置根据模型的架构与用途选择gallery/下的模板这些模板文件通过url:被条目引用模板适用模型备注gemma.yamlGemma 家族gemma、embeddinggemma、medgemma 等Gemma 的start_of_turn/end_of_turn对话模板8192 上下文chatml.yamlChatML 格式模型大量 Mistral / OpenHermes 微调|im_start|/|im_end|模板4096 上下文deepseek.yamlDeepSeek 系列按 DeepSeek 对话格式定制virtual.yaml最小基座很适合不需要对话模板的 embedding 模型只含name/description/license几乎不预设任何行为可以看到 virtual.yaml 仅声明了一个空壳定义embeddinggemma-300m这类纯 embedding 模型正是继承它、再由overrides注入 engine 与 embeddings 行为的。条目通用字段速查在逐个格式展开前先建立字段心智模型。下面是对照真实条目见下文归纳的字段含义字段作用name全局唯一标识用户据此安装local-ai models install name、/models/apply也是variants的引用键url所继承模板配置的仓库路径形如github:mudler/LocalAI/gallery/template.yamlmasterurls展示给用户的来源页列表原始模型页 GGUF 转换仓库页通常两行都要写icon/license展示与许可声明官方 gallery 只收录许可允许的模型description一段 Markdown说明模型规模、能力、量化方式tags检索与过滤用同时是variants排序读取特性的唯一信号见下文 dflash/mtp 规则overrides对模板config_file的合并覆盖如backend、embeddings、parameters.model、options、context_sizefiles每个需要下载并校验的权重filenamesha256urihuggingface://或完整 HTTPS URLvariants可选声明本模型的其他构建条目名列表不同量化 / 不同引擎编写 embedding 模型条目Embedding 模型以 virtual.yaml 为基座并设置embeddings: true。指南给出的标准模板如下字段被完整保留供直接套用- name: model-name url: github:mudler/LocalAI/gallery/virtual.yamlmaster urls: - https://huggingface.co/original-model-org/original-model-name - https://huggingface.co/gguf-org/gguf-repo-name description: | Short description of the model, its size, and capabilities. tags: - embeddings overrides: backend: llama-cpp embeddings: true parameters: model: filename.gguf files: - filename: filename.gguf uri: huggingface://gguf-org/gguf-repo-name/filename.gguf sha256: sha256-hash对照仓库中真实的embeddinggemma-300m条目 gallery/index.yaml#L27782-L27804可以看到完全相同的手法url指向virtual.yamlmasteroverrides里声明backend: llama-cpp、embeddings: true、known_usecases: [embeddings]并把parameters.model指到实际 GGUF 文件名files用huggingface://URI 与 sha256 锁定权重。真实条目还展示了若干实操细节embedding 模型可以继续沿用llama-cpp引擎不需要对话模板这正是选virtual.yaml的原因uri与filename不必同构——URI 决定下载源filename决定落地文件名与加载引用tags帮助 embedding 模型在检索与 WebUI 里归类。编写 chat / LLM 模型条目对话类模型通常会引用一个定义好提示词格式的模板配置例如gallery/gemma.yaml、gallery/chatml.yaml。指南给出的基础形态- model-anchor url: github:mudler/LocalAI/gallery/template.yamlmaster name: model-name icon: https://example.com/icon.png license: license urls: - https://huggingface.co/org/model - https://huggingface.co/gguf-org/gguf-repo description: | Model description. tags: - llm - gguf - gpu - cpu overrides: parameters: model: filename-Q4_K_M.gguf files: - filename: filename-Q4_K_M.gguf sha256: sha256 uri: huggingface://gguf-org/gguf-repo/filename-Q4_K_M.gguf注意两点锚点model-anchor是为同一模型的不同量化变体准备的name里通常带量化后缀如granite-4.2-3b-q4因为一个模型会有多个量化条目。真实例子可看 gallery/index.yaml#L312-L356 的granite-4.2-3b-q4它继承virtual.yaml但overrides写得更完整——context_size: 131072、function.automatic_tool_parsing_fallback、options: [use_jinja:true]、template.use_tokenizer_template: true说明模板只是起点真正决定运行时行为的细节都在overrides中按需补齐。用 YAML merge 添加量化变体同一模型的第二个量化版本用 YAML 合并语法!!merge :从锚点派生出最小差异条目- !!merge : *model-anchor name: model-name-q8 overrides: parameters: model: filename-Q8_0.gguf files: - filename: filename-Q8_0.gguf sha256: sha256 uri: huggingface://gguf-org/gguf-repo/filename-Q8_0.gguf合并只覆盖需要变化的字段name、overrides.parameters.model、files其余字段url、urls、tags、license自动从锚点继承。真实仓库中的granite-4.2-3b-q8正是这条派生路径的产物 gallery/index.yaml#L357-L381它从granite-4-2-3b派生出Q8_0版本并替换 description 与文件清单。用variants把同一模型的多个构建组织起来当一个模型同时以多种量化发布、或还能被其他引擎服务时例如同一个权重既有 llama.cpp GGUF 构建又有 vLLM / MLX 构建就把每个构建各自写成普通条目然后让其中一个条目用variants:指向其他条目- !!merge : *chatml name: nanbeige4.1-3b-q4 # ... the usual urls / overrides / files for the Q4 build ... variants: - model: nanbeige4.1-3b-q8仓库中nanbeige4.1的真实条目与之一致nanbeige4.1-3b-q4声明者的variants指向nanbeige4.1-3b-q8被引用者见 gallery/index.yaml#L11494-L11568。variants 的完整规则以下是指南明确定义的规则发布时逐条核对声明者是完整、普通的条目。它保留自己的files/overrides在任何主机上、被任何旧版 LocalAI 都可独立安装——旧版本解析到variants字段时直接忽略即可。variant 按name引用另一个条目。被引用的条目必须真实存在且它自己不能再声明variants。被引用的条目默认保留自己的 gallery 行。只有在折叠列表collapse_variantstrueWebUI 默认请求该参数中它才被隐藏、由声明者代表展示。折叠状态下搜索仍能命中被引用条目并返回声明它的条目——因此引用一个条目永远不会让它搜不到关闭折叠后它回归自己的名字。顺序无意义。不要试图用列表顺序表达偏好按可读性排列即可。variant 可以比声明者更小。为小内存主机提供降级档如大模型提供更小量化是正常形态声明者自己的构建照常参与竞争大主机自然选中大构建。不要手动描述硬件适配。安装时 LocalAI 先剔除后端在当前主机跑不起来的 variant再剔除装不进可用内存的 variant声明者自身的构建对两个过滤器都豁免因此选择总能终止于某个可安装项。权重体积在安装时从模型实测并缓存条目里无需书写。引擎偏好优先于体积。在通过上述过滤的候选中先按主机偏好的引擎取胜引擎相同时才比更大占用 更高质量的量化。例如NVIDIA 主机上 vLLM 构建胜过更大的 llama.cpp 构建Apple silicon 上 MLX 构建胜过更大的 GGUF 构建对两种引擎都没有偏好的主机则大构建胜出。各能力维度下的引擎顺序表位于engineNamePreferenceRulespkg/system/capabilities.go一个后端如何进入该表见 adding-backends.md。服务特性偏好排在引擎与体积之间。在引擎同等偏好的构建中能每步投机/预测多个 token的构建胜过同权重的普通构建DFlash 配对胜过 MTP二者都胜过普通构建。该顺序位于servingFeaturePreferenceTokenspkg/system/capabilities.go并且只按条目声明的tags匹配、绝不看其他字段不看条目名、不看overrides.options详见下节 dflash / mtp 标签规则。引擎刻意排在它前面服务特性只是让正确的引擎更快并不会把错误的引擎变正确。适配性体积过滤依旧排在两者之前——严格大于普通构建的 drafter 配对在小主机上会先于这套排序被剔除。variant 只是一个名字没有 per-variant 内存字段。当某构建的实测体积错误时应去被引用的条目上修正它自己的size:例如size: 20GiB。估算逻辑优先采纳声明值而非自己的猜测因此修正会作用于所有展示与比较体积的地方而不只影响 variant 选择。安装时的选择覆盖权自动选择不是不可推翻的。用户可以在以下入口显式指定想要的构建POST /models/apply携带variant参数CLIlocal-ai models install --variant model-name——--variant的帮助文本明确说明安装声明了 variants 的条目时用 variant 的模型名指定具体构建留空则由 LocalAI 自动选择先剔除跑不了/装不下的再按主机偏好引擎最后按体积见 core/cli/models.go#L44install_modelMCP 工具。variants的选择、折叠与描述逻辑对应仓库 core/gallery 下的resolve_variant.go、collapse_variants.go、describe_variants.go与各自的*_test.goWebUI 侧的折叠请求可参见 core/http/routes/ui_api.go 与 React 前端 core/http/react-ui/src/pages/Models.jsx。折叠与按名引用的行为在collapse_variants_test.go、variants_lint_test.go中都有规格化测试——因此指南要求只要加了variants列表就必须跑core/gallery的测试套件可执行go test ./core/gallery/...来验证 lint 规则与选择行为。引擎偏好表与体积排序的实现依据上面的规则并非黑盒——pkg/system/capabilities.go 中保留了极其详细的注释来解释三张偏好表以及为什么它们讲三种不同的语言backendBuildTagPreferenceRules构建标签cuda/rocm/metal…匹配的是已安装后端的构建目录名服务于后端别名解析engineNamePreferenceRules引擎名vllm/llama-cpp/mlx…以子串匹配条目backend:值服务于core/gallery/resolve_variant.go的 variant 自动选择。子串匹配是有意为之且承重的vllm同时覆盖vllm-omnimlx覆盖mlx-vlm/mlx-audiollama-cpp覆盖ik-llama-cpp。真实的引擎顺序为NVIDIA/AMD/Intel 上vLLM → sglang → llama-cppmetalApple silicon上MLX → llama-cppvLLM/sglang 无 metal 构建故不列出纯 Vulkan 与无加速器的 default 上llama-cpp居首GPU 服务引擎排在后面但仍可被点名安装Intel MacdarwinX86上llama-cpp → vLLM → sglang且 MLX 故意不列出MLX 需要 Apple silicon。servingFeaturePreferenceTokens服务特性dflash、mtp只与条目的tags做整词、不区分大小写的匹配。注释还解释了为什么引擎优先于体积、为什么服务特性不能上探到选项层等关键设计决策是阅读本主题时最有价值的第一手资料。体积与特性如何参与排序在 pkg/system/capabilities.go 的注释中作者进一步点破了排序决策的优先级安装时先过滤后端不兼容 → 剔除装不下 → 剔除再排序同引擎偏好下服务特性高者先引擎表在特性表之前且两者都在体积之前决定胜负。这也解释了一个看似反直觉的结论——预测下一个 token 的构建为何能胜过体积更大的普通构建因为特性表排序发生在已通过适配过滤的候选集内部能进入排序的构建都已经能装进当前主机。dflash/mtp标签规则只有当条目确实配置了该特性时才给它打dflash或mtp标签。variant 排序只读标签、不读任何其他字段。判断依据是该条目实际配置了什么使用其后端自己的词汇表后端配置了该特性当它声明……llama-cppoverrides.options含spec_type:draft-dflash或spec_type:draft-mtpds4overrides.options含mtp_path:/mtp_draft:sglang引用的gallery/*.yaml设置了speculative_algorithm:该检查仅在策展curation时执行。spec_type是 llama.cpp 的配置词汇跨后端的排序决策绝不能依赖某一个后端的选项写法——这正是排序器读标签而非读 options 的根本原因此设计决策在 pkg/system/capabilities.go 的注释中被原样记录下来。规则要防的两个典型错误带头的权重 ≠ 启用特性的条目。NVFP4 GGUF 条目携带了 MTP 权重但只设置了use_jinja:true并未启用任何投机解码因此绝不能打标签——给它们打标签会在毫不更快的情况下赢得特性轴源码注释即以qwen3.6-27b-nvfp4-mtp这类条目为例。名字不是声明。名字拼作-mtp却什么都没配置的条目不该有标签真正配置了特性的条目即使名字毫无提示注释中举的hy3、glm-5.2例子也要打标签。排序从不读名字因此一个确实启用特性却没打标签的构建只会按普通构建参与排名。对照真实条目验证上述词汇表GLM-5.3 的 llama.cpp 条目在overrides.options中声明了spec_type:draft-mtp及spec_n_max:6、spec_p_min:0.75等投机解码参数见 gallery/index.yaml#L44-L48sglang 侧的 MTP 声明则集中在模板里例如 sglang-gemma-4-e2b-mtp.yaml 设置了speculative_algorithm: NEXTN、speculative_num_steps: 5等 SGLang 参数注释还说明了NEXTN会被 SGLang 归一化为 EAGLE。提交前自查清单指南以一张清单收尾逐条核验后再合入找到 GGUF 文件——记下精确文件名区分大小写用curl -sIx-linked-etag方法取得 SHA256根据模型架构从gallery/选择正确的模板配置gemma / chatml / deepseek / virtual…把条目加入gallery/index.yaml放在相近模型附近embedding 模型必须设置embeddings: true同时给出两个 URL——原始模型页与 GGUF 仓库页撰写 description——说明模型规模、能力与量化类型。如果条目携带variants列表务必补上最后一项运行 core/gallery 的测试套件让 variants 的 lint 规格与选择逻辑测试在本地通过参见variants_lint_test.go、collapse_variants_test.go、resolve_variant_test.go因为这套测试正是把上文所有规则固化为可执行断言的地方。【免费下载链接】LocalAILocalAI is the open-source AI engine. Run any model - LLMs, vision, voice, image, video - on any hardware. No GPU required.项目地址: https://gitcode.com/GitHub_Trending/lo/LocalAI创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考