LocalAI Model Gallery 模型画廊完全指南：一键安装、变体自动选择、镜像与离线机制全解析

LocalAI Model Gallery 模型画廊完全指南一键安装、变体自动选择、镜像与离线机制全解析【免费下载链接】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 引擎 LocalAI 内置了一套**模型画廊Model Gallery**机制它把模型的下载、校验、配置生成与后端绑定封装成一个可安装的条目让你通过 Web 界面、REST API 或启动前预加载即可完成从浏览模型、评估硬件适配到安装启动的完整生命周期管理。本文以 Model Gallery 官方文档 为骨架结合仓库内的 Gallery API 端点、镜像与离线缓存实现 和 变体描述逻辑 等源码证据系统讲解画廊的安装、镜像、变体variants、离线清单与作业追踪机制读完你就能自行配置自定义画廊、脚本化安装任意模型并理解其内部选择与降级策略。什么是 Model GalleryModel Gallery 是 LocalAI 维护的一组精选模型配置集合。注意它存放的不是模型权重本身而是描述该模型需要哪些文件、走哪个后端、用什么推理参数的 YAML 定义——仓库根目录的 gallery/ 目录如 whisper-base.yaml、deepseek.yaml、nanbeige4.1.yaml就是这类条目的原始形态索引汇总见 gallery/index.yaml。它的价值在于把三件事一键化下载模型权重与附加文件校验按声明的 SHA256 检查完整性写入配置到模型目录使模型立即可被加载服务。官方文档同时给出两条边界提示画廊中的模型并非由 LocalAI 直接维护发现某模型不可用应在主仓库提交 IssueGPT / 文本生成模型的许可证可能不兼容商用甚至缺失使用前必须自查许可证——官方画廊只收录开放许可证模型。除通过画廊安装外LocalAI 也保留传统方式手动把文件拷贝进models目录或在运行时通过 API / Web 界面让 LocalAI 替你完成配置、下载与资产校验。安装模型的三种入口与 WebUI 双视图LocalAI 从三条路径引导模型进入可用状态路径方式适用场景手动拷贝直接把模型文件与配置放进models目录离线、已备好文件运行时安装调用POST /models/apply或 WebUI服务运行中动态扩容启动前预加载PRELOAD_MODELS环境变量 /--preload-models参数 /--preload-models-configYAML容器与编排环境确定性启动在 WebUI 中打开Models页面即可看到模型的完整生命周期管理视图它有两个子视图Explore浏览——默认视图。浏览已配置的各个画廊比较模型的硬件适配度与变体variants并在此安装模型。Installed已安装——列出本机已有的模型配置及其状态运行中 running、空闲 idle、禁用 disabled、固定 pinned、分布式 distributed 等。选中某个模型后可执行加载/停止、编辑配置、打开支持的用例、查看后端日志或删除模型。两个视图共享同一套模型选择逻辑并将视图、搜索词、过滤器与当前选中项保存在 URL 中方便刷新/分享后恢复现场。在 Explore 中安装模型不会打断浏览流操作完成后条目在原地更新不会跳转离开目录页。下载体积与显存估算浏览画廊或用 URI 导入模型时LocalAI 会尽量展示两项估算下载体积和预估显存VRAM。出现位置画廊表格的 Size / VRAM 列、模型详情弹窗以及从 URI 发起导入后的成功提示消息。计算方式GGUF 模型基于文件体积HTTP HEAD 或本地 stat 可选的 GGUF 元数据通过 HTTP Range 读取用于计算 KV cache 与开销其他格式则使用 Hugging Face 的文件体积及可用的 config。当元数据不可用时退化为仅按体积的启发式估算。硬件适配指示灯当系统能上报 GPU 或内存容量时画廊会按95% headroom余量规则显示估算 VRAM 是否放得下——绿色表示适配红色表示可能放不下。估算属于best-effort尽力而为若服务端不支持 HEAD/Range 或请求超时相关估算字段会缺失。添加自定义 Gallery除了内置的localai默认画廊你可以通过三种方式挂接更多画廊方式一Web UI进入 Runtime Settings 页面Gallery Settings 小节通过界面直接配置画廊。方式二环境变量GALLERIES它是一个 JSON 数组每个元素含name与url两个字段GALLERIES[{name:GALLERY_NAME, url:GALLERY_URL}]方式三配置文件在LOCALAI_CONFIG_DIR目录下的runtime_settings.json中追加画廊配置。配置完成后画廊中的模型会被自动索引并出现在可安装列表中。Gallery Mirrors主 URL 之外的备选源单个画廊条目可通过mirrors字段声明若干份同一索引文件的备选地址。镜像的唯一目的是可用性而非负载均衡LocalAI始终优先尝试url仅当它无法获取时才按你声明的顺序逐个回退镜像主源可用时镜像永远不会被访问。镜像支持画廊加载器理解的全部 URI 类型https://、github:、huggingface://等价hf://、hf.co/以及file://对镜像的约束与主 URL 完全相同——例如file://镜像同样必须位于你的 models 目录之内。GALLERIES[{name:localai, url:https://example.org/gallery/index.yaml, mirrors:[github:mudler/LocalAI/gallery/index.yamlmaster]}]失败与冷却机制源码实现在 core/gallery/gallery_mirrors.go单次尝试以120 秒超时为界代码常量galleryFetchTimeout 120 * time.Second。该值刻意远大于健康拉取所需默认索引约 2.2MB120s 约等于容忍持续 19KB/s 的慢链路连接错误、超时或 HTTP 错误如 404/502都会让该源进入10 分钟冷却期galleryFailureCooldown避免每次列画廊都对着死主机白等一个完整超时成功应答的源立即恢复可用由你主动取消的请求不计入该源失败若所有源恰好都在冷却窗口内LocalAI 会仍然全部尝试一遍而不是拒绝服务见fetchGalleryIndex中的attempt 为空则回退为全量 candidates逻辑。.refURL 的例外重要警告镜像与离线缓存都不覆盖.refURL。若画廊url以.ref结尾LocalAI 会先抓取该引用文件并解析出真实索引地址这一步发生在镜像或缓存介入之前引用文件获取失败会使整个画廊直接失败——包括离线场景即使此前成功拉取过断网时.ref画廊依然会失败。镜像备选的是索引文件而不是指向索引的引用。若需要镜像覆盖或离线清单请让url直接指向索引文件本身。mirrors键整体可选不带镜像的画廊行为与旧版完全一致。离线画廊清单断网也能列出已知模型每次成功的画廊抓取都会被写入 models 目录旁的缓存目录MODELS_PATH/../cache/gallery/每个画廊 URL 一个文件文件名为 URL 的 SHA256 摘要见galleryCachePath。当主源与全部镜像都失败、完全没有网络或主机处于气隙airgapped环境时LocalAI 会改为提供最后一次成功抓取的副本来替代直接失败并记录警告日志。此机制适用于每个url直接指向索引文件的画廊无论有无 mirrors但不适用于.refURL其解析先于缓存查询。缓存写入有严格的内容把关isUsableGalleryIndex只有真正能被解析为画廊索引的响应才会被缓存。门户网站、代理或 CDN 可能对索引请求返回 HTTP 200 加 HTML 错误页——缓存它会用一份无法解析的内容覆盖掉好副本空索引同理会被拒绝以保住旧副本。缓存目录刻意不放在 models 目录内否则会被 LocalAI 当作已安装模型的.yaml配置误读。删除缓存目录是安全的——下次成功抓取会重建它从未成功连上过画廊的机器没有缓存其首次列清单仍然会失败。需要清醒认识的是磁盘上服务的清单可能是陈旧的其新鲜度取决于上一次能触达画廊的时间上游新增或移动过的模型不会出现。因此磁盘清单是降级模式不能替代可达的画廊。API Reference运行时安装模型运行中安装模型的核心端点是POST /models/apply其处理器与请求模型见 core/http/endpoints/localai/gallery.go请求体被绑定到GalleryModel结构内嵌GalleryModel并可选携带variant字段服务随即把作业EnqueueModelOp投入队列并立即返回uuid与状态查询 URL。LocalAI 默认已配置localai这一个仓库要使用更多仓库用GALLERIES环境变量启动local-ai。例如显式拼出默认仓库含镜像回退链GALLERIES[{name:localai, url:https://index.localai.io/models, mirrors:[github:mudler/LocalAI/gallery/index.yamlmaster]}]其中https://index.localai.io/models是同一份索引文件的缓存镜像github:条目是它不可达时的回退github:mudler/LocalAI/gallery/index.yamlmaster会被自动展开为对应 raw 地址。注意github与huggingface前缀会自动展开直接写https://与http://前缀同样有效。使用本地画廊索引文件file://file://前缀允许使用本地索引文件但出于安全原因本地画廊文件必须位于 models 目录之内即MODELS_PATH指定的目录或默认的models/。有效示例假设MODELS_PATH/opt/localai/modelsGALLERIES[{name:local, url:file:///opt/localai/models/galleries/my-gallery.yaml}]无效示例文件在 models 目录之外GALLERIES[{name:local, url:file:///home/user/my-gallery.yaml}]后者会被以安全错误拒绝。四条要点路径必须用file://前缀必须是绝对路径Unix 下以/开头解析后的路径必须落在 models 目录内越界访问一律拦截。官方文档亦提示目前尚无如何构建自有画廊的专门文档但默认画廊的源数据就在本仓库的 gallery/ 目录中可参考。列出可用模型/models/availablecurl http://localhost:8080/models/available配合jq可按名称、字段做灵活搜索curl http://localhost:8080/models/available | jq .[] | select(.name | contains(replit)) curl http://localhost:8080/models/available | jq .[] | .name | select(contains(localmodels)) curl http://localhost:8080/models/available | jq .[] | .urls | select(. ! null) | add | select(contains(orca))该端点由 ListModelFromGalleryEndpoint 实现聚合所有活动画廊的可用模型并序列化为元数据数组返回。从仓库安装模型模型可通过 YAML 配置文件的完整 URL 安装或通过画廊中的模型标识符安装。标识符语法为GALLERYMODEL_NAMElocalai是仓库名可选省略时 LocalAI 在全部仓库中按名称搜索同名冲突时先匹配者胜。例如安装bert-embeddingsLOCALAIhttp://localhost:8080 curl $LOCALAI/models/apply -H Content-Type: application/json -d { id: localaibert-embeddings }Model Variants同一个模型的多份构建与自动选择一些画廊条目会为同一模型提供多种构建不同量化、或同一权重交给不同引擎服务。这类条目携带variants列表普通安装时 LocalAI 按以下规则自动决择后端跑不起来的变体被丢弃放不进内存预算的变体被丢弃。预算在独立 GPU 主机上是 VRAM否则是系统内存——包括 Apple Silicon 这类统一内存机器GPU 共享系统内存、无独立 VRAM 池条目自身携带的构建永不丢弃。它与其他存活者同台竞争而非坐等其他全失败因此当条目自身就是放得下的最大构建时会保留自己的载荷幸存者中本机偏好的引擎优先NVIDIA/AMD 主机偏好 vLLM 构建Apple Silicon 偏好 MLX 构建其余走 llama.cpp。本地原生加速运行时的价值大于更大的下载量因此引擎偏好先于体积判定同一偏好的引擎上体积最大的构建胜出更大的足迹通常意味着同模型更高质量的构建没有偏好引擎的机器纯按体积挑选体积无法测量的构建排在条目自身构建之后避免读不到的体积悄悄顶替条目随附的载荷若没有其他幸存者则安装条目自身构建——任何机器上条目总是可安装的。正因为条目自身构建与其它候选同台竞争列表书写顺序毫无意义variants列表可以只含更小构建、只含更大构建或两者都有。变体体积按权重文件而非下载量测算并缓存。画廊列表只通过has_variants字段标记哪些条目提供变体刻意不在内联处展开描述——测量一个变体是每次对目标构建的一次网络往返若为每条目内联展开全部描述单次列清单请求就要付出整个页面变体数那么多的往返。查询带变体的条目curl http://localhost:8080/api/models | jq .models[] | select(.has_variants) | .name对应实现位于 core/http/routes/ui_api.goGET /api/models在collapse_variantstrue时执行去重分组并为带变体条目设置has_variants字段。把清单折叠为每模型一行默认列表返回每个条目包括父条目以变体形式提供的各构建一个模型可能占据多行。传入collapse_variantstrue即得到去重视图每个可独立安装的条目只出现一次curl http://localhost:8080/api/models?collapse_variantstrue折叠规则仅当另一条目已把它作为变体提供时某条目才被隐藏——它仍可通过安装那个父条目而触达声明了变体的条目始终保留任何无人引用的条目也保留过滤在分页之前执行页码因此保持正确。搜索同样遵循折叠term会对画廊持有的每个条目含其他条目提供的构建匹配因此任何东西都不会变得不可搜索折叠随后决定命中如何上报——命中别人提供的构建会以该父条目的身份返回因为父条目才是可独立安装的那一行# 折叠视图父条目代替它所提供的构建出现 curl http://localhost:8080/api/models?collapse_variantstrue # 折叠 搜索父条目提供的构建返回父条目 curl http://localhost:8080/api/models?collapse_variantstruetermnanbeige4.1-3b-q8 # 未折叠、同一词条返回构建本身 curl http://localhost:8080/api/models?termnanbeige4.1-3b-q8需要注意term、tag、backend均在替换发生前求值各自针对真正携带该名称/标签/后端的构建判定。于是产生一个值得了解的后果——只被某个变体声明的后端过滤会返回该变体的父条目而父条目自身的backend字段可能是别的值。Web UI 默认请求折叠视图并提供切换开关API 侧该参数默认关闭。逐条查看变体描述变体描述是一次一个条目地请求的Web UI 打开变体菜单时正是如此对应端点GET /api/models/variants/:idcurl http://localhost:8080/api/models/variants/localainanbeige4.1-3b-q4{ auto_selected: nanbeige4.1-3b-q8, variants: [ { model: nanbeige4.1-3b-q8, backend: llama-cpp, memory_bytes: 4187593113, fits: true, is_base: false }, { model: nanbeige4.1-3b-q4, backend: llama-cpp, fits: true, is_base: true } ] }字段语义与 core/gallery/describe_variants.go 中的VariantView一一对应auto_selected此刻不做选择直接安装时会选中的变体fits自动选择在本机上是否会考虑该变体is_base是否条目自身构建memory_bytes测得的内存足迹无法测量时整个字段被省略如上面第二条缺失应读作未知而非免费构建。实现上该端点运行与安装器完全相同的variantOptions SelectVariant决策链因此界面展示的自动选中永远不会与真实安装结果漂移。未声明变体的条目不携带has_variants字段并对该端点返回空列表——客户端无需多问。指定变体安装要安装某个具体变体在variant字段传其名称curl $LOCALAI/models/apply -H Content-Type: application/json -d { id: localainanbeige4.1-3b-q4, variant: nanbeige4.1-3b-q8 }关键行为显式选择即使机器看起来放不下也会被尊重——你可以刻意安装 LocalAI 本不会选的构建声明范围之外的variant会直接让安装失败并点名所请求项绝不会悄悄回退到自动选择选择会被记录之后对同模型的重新安装或升级会保持你选定的变体。同一选项在 CLI 上也存在见 core/cli/models.go 中带variant标志的安装命令local-ai models install nanbeige4.1-3b-q4 --variant nanbeige4.1-3b-q8此外MCP 的install_model工具也接受同名variant参数使会话式管理安装的助手同样能挑选构建。未声明variants的条目不受上述任何机制影响行为与从前完全一致。Artifact-backed 模型与物化阶段带有artifacts声明的画廊模型在安装期会被完整物化其操作依次经过如下阶段resolving - downloading - verifying - committing - persisting管理端操作去壳strip后Activity 运维页 与GET /api/operations会暴露currentBytes/totalBytes原始传输字节取消进行中的下载会保留其部分文件便于重试断点续传校验失败永远不会暴露已完成的快照而重试或另一次安装会复用已校验的内容寻址content-addressed快照删除模型配置不会删除其内容寻址快照字节——这使另一份配置或日后的重装可以复用缓存安全的缓存垃圾回收被有意推迟。安装不属于任何画廊的模型不想配置任何画廊仓库时可直接加载一份模型配置文件。请求体中至少要给出配置文件的urlconfig_url亦可二者等价可选提供安装名name、附加文件files与配置覆盖overrides。LocalAI 会下载模型文件并把配置写入模型存储目录LOCALAIhttp://localhost:8080 curl $LOCALAI/models/apply -H Content-Type: application/json -d { config_url: MODEL_CONFIG_FILE_URL } curl $LOCALAI/models/apply -H Content-Type: application/json -d { id: GALLERYMODEL_NAME } curl $LOCALAI/models/apply -H Content-Type: application/json -d { url: MODEL_CONFIG_FILE_URL }url可以是完整 URL、github 简写github:org/repo/file.yaml或本地文件file:///path/to/file.yamlid则是GALLERYMODEL_NAME形式的仓库标识。API 会返回一个作业uuid与状态查询地址{uuid:1059474d-f4f9-11ed-8d99-c4cbe106d571,status:http://localhost:8080/models/jobs/1059474d-f4f9-11ed-8d99-c4cbe106d571}一个等待作业完成的小型 bash 脚本需要jqresponse$(curl -s http://localhost:8080/models/apply -H Content-Type: application/json -d {url: $model_url}) job_id$(echo $response | jq -r .uuid) while [ $(curl -s http://localhost:8080/models/jobs/$job_id | jq -r .processed) ! true ]; do sleep 1 done echo Job completed启动前预加载PRELOAD_MODELS预加载模型可借助PRELOAD_MODELS环境变量须为 JSON 数组布尔值如true不是合法的预加载配置PRELOAD_MODELS[{url: MODEL_URL}]url与id至少其一url指向模型画廊配置的 URLid引用仓库内的模型两者都给时以id为准。例如PRELOAD_MODELS[{url: github:mudler/LocalAI/gallery/stablediffusion.yamlmaster}]或作为参数local-ai --preload-models [{url: github:mudler/LocalAI/gallery/stablediffusion.yamlmaster}]或使用 YAML 文件--preload-models-config- url: github:mudler/LocalAI/gallery/stablediffusion.yamlmaster覆盖安装名称、附加文件与配置覆盖覆盖名称画廊里没有合适的名字时用name参数改名安装。例如把模型装成gpt-3.5-turboLOCALAIhttp://localhost:8080 curl $LOCALAI/models/apply -H Content-Type: application/json -d { url: github:mudler/LocalAI/gallery/gpt4all-j.yaml, name: gpt-3.5-turbo }附加文件用files参数随模型下载更多文件每项含uri、可选的sha256与filenamecurl $LOCALAI/models/apply -H Content-Type: application/json -d { url: MODEL_CONFIG_FILE, name: MODEL_NAME, files: [ { uri: additional_file_url, sha256: additional_file_hash, filename: additional_file_name } ] }覆盖配置overrides参数可覆盖配置文件的局部内容如 backend、f16 等模型参数curl $LOCALAI/models/apply -H Content-Type: application/json -d { url: MODEL_CONFIG_FILE, name: MODEL_NAME, overrides: { backend: llama, f16: true, ... } }兜底base 模型 自备权重 URL若画廊中没有你需要的模型可加载 base 模型并自供权重 URLfiles[].uri加sha256filename写modelcurl $LOCALAI/models/apply -H Content-Type: application/json -d { url: github:mudler/LocalAI/gallery/base.yamlmaster, name: model-name, files: [ { uri: URL, sha256: SHA, filename: model } ] }作业状态查询/models/jobs/端点GET /models/jobs/uid返回模型安装批处理作业的状态实现见 GetOpStatusEndpointcurl http://localhost:8080/models/jobs/JOB_ID成功完成时返回{error:null,processed:true,message:completed}安装作业一次只处理一个当另一安装仍在运行时提交的作业会报告为排队queued直到安装器拾取它{error:null,processed:false,message:queued,phase:queued}/models/apply一旦返回作业 ID该 ID 就立即可查询——因此该端点返回404/500意味着 ID 确实未知而不是还在排队。端到端实战示例示例一Embeddings —— Bertcurl $LOCALAI/models/apply -H Content-Type: application/json -d { id: bert-embeddings, name: text-embedding-ada-002 }验证LOCALAIhttp://localhost:8080 curl $LOCALAI/v1/embeddings -H Content-Type: application/json -d { input: Test, model: text-embedding-ada-002 }示例二图像生成 —— Stable Diffusion运行时准备调用/models/apply指向 stablediffusion 条目curl $LOCALAI/models/apply -H Content-Type: application/json -d { url: github:mudler/LocalAI/gallery/stablediffusion.yamlmaster }启动前自动准备PRELOAD_MODELS/--preload-models/--preload-models-configYAML 三种等价方式PRELOAD_MODELS[{url: github:mudler/LocalAI/gallery/stablediffusion.yamlmaster}]local-ai --preload-models [{url: github:mudler/LocalAI/gallery/stablediffusion.yamlmaster}]- url: github:mudler/LocalAI/gallery/stablediffusion.yamlmaster测试文生图curl $LOCALAI/v1/images/generations -H Content-Type: application/json -d { prompt: floating hair, portrait, cute face, beautiful detailed eyes, mode: 2, seed:9000, size: 256x256, n:2 }示例三音频转写 —— Whisper运行时准备命名安装为whisper-1对应仓库内的 whisper-base.yaml 这类条目curl $LOCALAI/models/apply -H Content-Type: application/json -d { url: github:mudler/LocalAI/gallery/whisper-base.yamlmaster, name: whisper-1 }启动前自动准备PRELOAD_MODELS[{url: github:mudler/LocalAI/gallery/whisper-base.yamlmaster, name: whisper-1}]local-ai --preload-models [{url: github:mudler/LocalAI/gallery/whisper-base.yamlmaster, name: whisper-1}]- url: github:mudler/LocalAI/gallery/whisper-base.yamlmaster name: whisper-1机制与限制小结/models/apply的请求字段总览url或id必填其一url为模型定义文件的完整 URL / github 简写 / 本地file://id为GALLERYMODEL_NAMEname、files、overrides可选。安装过程以批处理方式在后台下载定义所需的文件完成后自动重载自身以纳入新模型。file://本地文件有安全限制路径必须在 models 目录内由MODELS_PATH指定目录外文件一律拒绝。安装作业串行执行其余请求进入排队状态作业 ID 从apply返回起即有效可查。画廊条目、镜像、冷却、离线缓存与变体描述的完整实现可分别追溯至 core/gallery/gallery_mirrors.go、core/gallery/describe_variants.go 与 core/http/routes/ui_api.go端点的路由汇总见 routes/localai.go。内容合规提示LLM 类模型许可证各有不同商用前请务必核对画廊内的模型可用性问题应反馈给模型维护者而 LocalAI 官方画廊只收录开放许可证条目。【免费下载链接】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），仅供参考