LocalAI 高级使用指南YAML 模型配置、Prompt 模板、启动预载与外部 Backend 扩展【免费下载链接】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本文是 LocalAI 高级用法的系统化技术指南围绕“如何让任意模型在任意硬件上以你期望的方式跑起来”这一目标讲解 YAML 模型配置、.tmpl Prompt 模板、运行时/启动时安装模型、Prompt 缓存、外部 gRPC Backend 接入、并发请求、环境变量与 .env 文件等进阶操作。读完本文你将掌握一套可落地的“模型接入 行为定制 性能调优”组合方案并能在容器、命令行与配置文件三种形态之间自由切换。本文主体整理自仓库文档 docs/content/advanced/advanced-usage.md源码证据分别指向 core/cli/run.go、core/startup/model_preload.go、core/config/generic_defaults.go 以及 core/http/endpoints/openai 下各入口文件。YAML 模型配置定义参数、模板与行为LocalAI 使用 YAML 配置文件来定义模型的参数、模板与运行时行为。你既可以在模型目录下为每个模型单独建一个 YAML 文件也可以用一个配置文件承载多个模型。最简示例name: gpt-3.5-turbo parameters: model: luna-ai-llama2-uncensored.ggmlv3.q5_K_M.bin temperature: 0.3 context_size: 512 threads: 10 backend: llama-cpp template: completion: completion chat: chat各字段作用如下字段作用name模型对外名称API 请求如model: gpt-3.5-turbo中用它来定位该配置parameters.model模型权重文件路径相对模型目录也支持 URL配合download_files/artifacts自动下载parameters.temperature采样温度作为该模型所有请求的默认值context_size最大上下文长度token 数threads并行计算线程数按模型覆盖服务级--threads设置backend显式指定推理后端如llama-cpp、vllm、diffusers等template指定用于 completion / chat 等场景的模板见下文 Prompt 模板小节parameters一节可以容纳 OpenAI 兼容的整套请求参数top_p、max_tokens、frequency_penalty、presence_penalty、seed、n、logprobs等这些值会作为该模型所有 API 调用的默认值且仍能被单次请求中的同名参数覆盖。所有配置字段的完整参考表含每字段类型、默认值见 docs/content/advanced/model-configuration.md。三种配置文件加载位置独立文件在模型目录下创建以模型名命名的.yaml文件例如models/gpt-3.5-turbo.yaml。这是最常用的方式——把文件放进--models-path指向的目录即可被自动发现。单一配置文件多模型用--models-config-file或环境变量LOCALAI_MODELS_CONFIG_FILE兼容旧名--config-file/CONFIG_FILE指定一个 YAML 文件文件内以列表形式声明多个模型- name: model1 parameters: model: model1.bin context_size: 512 backend: llama-cpp - name: model2 parameters: model: model2.bin context_size: 1024 backend: llama-cpp从源码看该参数定义于 core/cli/run.goModelsConfigFile string ... env:LOCALAI_MODELS_CONFIG_FILE,CONFIG_FILE aliases:config-file并在启动时经config.WithConfigFile(r.ModelsConfigFile)注入配置管线见 core/cli/run.go。因此该开关既能以 kebab-case 命令行标志--models-config-file、--config-file使用也能写成LOCALAI_MODELS_CONFIG_FILExxx local-ai run。远程 URL启动时直接传入一个指向 YAML 配置文件的 URLgithub://、http(s)://、huggingface://等均可local-ai run github://mudler/LocalAI/examples/configurations/phi-2.yamlmaster运行时解析该列表的逻辑对应 core/cli/run.go 中的ModelArgs []string位置参数与Models []string字段env:LOCALAI_MODELS,MODELS两者最终合并进config.WithModelsURL(...)。使用 Prompt 模板定制模型的“人格”与交互格式LocalAI 的 API不会自动注入用于与模型对话的默认提示词prompt。要获得合适的对话效果你需要使用与 stanford-alpaca 文档中描述类似的提示结构来提问。一个更省事的做法是为模型目录下的每个模型文件准备一个同名.tmpl后缀的模板文件。例如模型叫foo.bin就在它旁边建foo.bin.tmpl该文件会被作为该模型的默认提示词模板alpaca 风格可写作The below instruction describes a task. Write a response that appropriately completes the request. ### Instruction: {{.Input}} ### Response:仓库根目录 prompt-templates 内已为多款主流模型准备了现成模板如alpaca.tmpl、vicuna.tmpl、koala.tmpl、wizardlm.tmpl、ggml-gpt4all-j.tmpl等。以 prompt-templates/alpaca.tmpl 为例其内容与上例完全一致可直接复制参考。仓库内模板均采用 Go template 语法并支持 Sprig 函数扩展。针对edit 端点文本改写/编辑alpaca 系模型可以准备带指令与输入的双变量模板Below is an instruction that describes a task, paired with an input that provides further context. Write a response that appropriately completes the request. ### Instruction: {{.Instruction}} ### Input: {{.Input}} ### Response:模板中常用的变量包括详见 docs/content/advanced/model-configuration.md{{.Input}}—— 用户输入{{.Instruction}}—— 编辑操作中的指令{{.System}}—— 系统消息{{.Prompt}}—— 完整提示词{{.Functions}}—— 函数/工具定义用于 function calling{{.FunctionCall}}—— 函数调用结果除了.tmpl旁挂文件同样可以把模板写进模型 YAML 的template段template.chat/template.completion/template.edit/template.function等实现“模板随模型配置一起分发”。通过 API 与启动参数安装模型除手动放置权重文件外LocalAI 支持通过 API 在运行时程序化安装模型。这里需要区分两类文件模型配置文件上文介绍的服务端 YAML负责“如何加载与运行模型”模型库model gallery文件描述“模型从哪下载、如何安装”的清单。仓库中的精选模型库清单位于 gallery 目录如vicuna.yaml、llama3-instruct.yaml、qwen3.yaml、piper.yaml等。通过/models/apply端点安装以安装lunademo为例向/models/apply发送 POST 请求url填模型库定义地址name可选指定模型在 LocalAI 内的名称curl --location http://localhost:8080/models/apply \ --header Content-Type: application/json \ --data-raw { id: TheBloke/Luna-AI-Llama2-Uncensored-GGML/luna-ai-llama2-uncensored.ggmlv3.q5_K_M.bin, name: lunademo }启动时预载模型首次启动即可用为让服务在首次启动时就具备全部所需模型可将模型库清单放到启动流程中。PRELOAD_MODELS[{url: https://raw.githubusercontent.com/go-skynet/model-gallery/main/gpt4all-j.yaml,name: gpt4all-j}] local-aiPRELOAD_MODELS或命令行--preload-models接收一段 JSON 列表其中每个元素与/models/apply端点的调用参数一致。与之等价也可以用PRELOAD_MODELS_CONFIG或--preload-models-config指向一个 YAML 列表文件- url: https://raw.githubusercontent.com/go-skynet/model-gallery/main/gpt4all-j.yaml name: gpt4all-j这两个启动开关的定义见 core/cli/run.goenv:LOCALAI_PRELOAD_MODELS,PRELOAD_MODELS与env:LOCALAI_PRELOAD_MODELS_CONFIG,PRELOAD_MODELS_CONFIG随后在 core/cli/run.go 通过config.WithJSONStringPreload与config.WithYAMLConfigPreload进入应用装配。真正执行安装的入口是 core/startup/model_preload.go 中的InstallModels/InstallModelsWithOptions——它会先在已注册 gallery 中查找模型命中则调用InstallModelFromGallery安装若未命中则视为“嵌入式 YAML 模型定义”经DiscoverModelConfig探测后送入模型库操作队列等待安装完成。整个流程会对每次下载显示进度因此非常适合首次冷启动时批量拉取模型。自动 Prompt 缓存加速带前缀模板的提示处理当模型需要“模板前缀文本 用户输入”这样的固定结构时LocalAI 可以把前缀部分缓存起来从而显著加快后续请求的提示处理速度。在模型配置 YAML 中开启缓存prompt_cache_path: cache prompt_cache_all: trueprompt_cache_path相对模型目录的路径你可以在此填写一个缓存文件名该文件会在首次加载时被自动创建当prompt_cache_all为true时。另有prompt_cache_ro只读模式可配合共享只读缓存使用。相关字段在 core/config/model_config.go 中定义PromptCachePath/PromptCacheAll/PromptCacheRO。值得注意的一点是 core/config/generic_defaults.go 的实现细节当prompt_cache_all未显式设置时其默认值会被置为true与上游 llama.cpp 的cache_prompt true默认一致从而让服务端 KV 缓存相关选项真正生效如需关闭可在模型 YAML 中显式写prompt_cache_all: false。补充说明如果你使用的是llama-cpp后端当前更推荐的是服务端 prompt cache通过options:数组中的cache_ram/kv_unified/cache_idle_slots控制自 LocalAI v4.3 起默认开启它能让重复系统提示在第二次调用时近乎零预填充prompt_cache_path系列字段来自上游 CLI 工具的兼容传递详见 docs/content/advanced/model-configuration.md。为模型显式指定 Backend默认情况下LocalAI 会尝试遍历所有后端对模型进行“自动加载”。这对大多数模型有效但并非所有后端都配置为可自动加载。所有可用后端见 docs/content/reference/compatibility-table.md 中的模型兼容性表。要显式指定后端只需在models目录下为该模型写一个 YAML 配置文件并声明backendname: gpt-3.5-turbo parameters: # 相对模型目录的权重文件路径 model: ... backend: llama-cppbackend的取值决定调用哪条推理链路——例如本地 GGUF 权重用llama-cpp/ik-llama-cpp/turboquant系Python 系模型用vllm、diffusers、transformers等多模态/语音模型则对应whisper、piper、qwen3-tts-cpp等后端名。连接外部 BackendgRPC 扩展机制LocalAI 的后端在内部都是基于gRPC 服务实现的。这一架构使 LocalAI 能在启动时连接外部 gRPC 服务通过第三方二进制扩展其能力。CLI 参数--external-grpc-backends既可以指定本地后端一个可执行文件也可以指定远程地址语法为BACKEND_NAME:BACKEND_URI。一旦 LocalAI 以该参数启动新后端名将对所有 API 端点可用。例如注册一个本地文件形式的后端./local-ai --debug --external-grpc-backends my-awesome-backend:/path/to/my/backend.py或者一个远程 URI./local-ai --debug --external-grpc-backends my-awesome-backend:host:port以手动启动 vLLM 后端为例假设在仓库根目录下执行且已编译 LocalAI./local-ai --external-grpc-backends vllm:$PWD/backend/python/vllm/run.sh首次使用前需要先构建其 Python 环境make -C backend/python/vllm源码层面该参数的解析逻辑位于 core/cli/run.goLocalAI 对--external-grpc-backends列表逐项按第一个:切分为“后端名 URI”再通过config.WithExternalBackend(name, uri)注册对应环境变量为LOCALAI_EXTERNAL_GRPC_BACKENDS/EXTERNAL_GRPC_BACKENDS见 core/cli/run.go。正因为后端与 LocalAI 主进程之间只有 gRPC 一个契约后端理论上可以用任何语言编写——只要能实现该 gRPC 服务即可。并发请求与并行度调优对于支持并行的后端LocalAI 允许多个请求并行处理例如 vLLM 与 llama.cpp 都支持并行请求。开启方式是传--parallel-requests或把环境变量PARALLEL_REQUEST设为true。控制并行度的关键环境变量如下环境变量含义PYTHON_GRPC_MAX_WORKERSPython 类 gRPC 后端的最大 worker 数它实际决定了后端能否同时处理多个请求LLAMACPP_PARALLELllama.cpp 的并行进程数需按你的 GPU/CPU 实际承受能力设置默认 1PARALLEL_REQUEST总开关开启并行请求对 llama.cpp你需要把LLAMACPP_PARALLEL设置成你的 GPU/CPU 能支撑的并行进程数对 Python 类后端如 vLLM则用PYTHON_GRPC_MAX_WORKERS指定并发的请求数量。此外LocalAI 进程级还有一个整体并发天花板--max-concurrent-backend-requests默认 1024对应LOCALAI_MAX_CONCURRENT_BACKEND_REQUESTS超出上限的推理请求会收到 HTTP 503 Retry-After但 UI 与管理端点不受影响见 core/cli/run.go。它与后端内的并行 worker 是两个层面前者管“LocalAI 放行多少路请求”后者管“单个后端实例内部开多少个 worker”。容器环境变量总览当 LocalAI 在容器中运行时有以下影响启动行为的附加环境变量环境变量默认值说明REBUILDfalse启动时重新构建 LocalAIBUILD_TYPE构建类型。可选cublas、openblas、clblas、intelIntel core、sycl_f16、sycl_f32Intel 后端GO_TAGSGo 编译标签。可选stablediffusionHUGGINGFACEHUB_API_TOKEN与 HuggingFace Inference API 交互所需令牌仅在用langchain-huggingface后端时需要EXTRA_BACKENDS需要预装的后端列表空格分隔。例如EXTRA_BACKENDSbackend/python/diffusers backend/python/transformers会在启动时准备对应 Python 环境DISABLE_AUTODETECTfalse启动时禁用 CPU 指令集自动探测LLAMACPP_GRPC_SERVERSllama.cpp worker 列表用于分发负载。例如LLAMACPP_GRPC_SERVERSaddress1:port,address2:port配置方式示例docker run --env REBUILDtrue localai docker run --env-file .env localai后一条命令通过--env-file一次性注入全部变量任何 CLI 参数都可以等价地用环境变量表达命名规则与示例见下一节。CLI 参数与环境变量的等价关系完整的 CLI 参数、环境变量与命令行选项清单见 docs/content/reference/cli-reference.md。LocalAI 的命令行参数可以控制绑定地址、线程数、模型路径等大量选项且每个命令行参数都可以通过环境变量指定环境变量优先于命令行标志。在源码 core/cli/run.go 中这种一一对应关系体现得极其直白——每个结构体字段都同时声明了 flag 与环境变量名例如CLI 参数环境变量说明--models-pathLOCALAI_MODELS_PATH/MODELS_PATH模型目录--addressLOCALAI_ADDRESS/ADDRESSAPI 绑定地址默认:8080-t, --threadsLOCALAI_THREADS/THREADS并行线程数--context-sizeLOCALAI_CONTEXT_SIZE/CONTEXT_SIZE默认上下文大小--f16LOCALAI_F16/F16启用 GPU 加速--api-keysLOCALAI_API_KEY/API_KEYAPI 鉴权密钥列表例如 core/cli/run.go 中ModelsPath字段写作env:LOCALAI_MODELS_PATH,MODELS_PATH意味着--models-path /a/b与export LOCALAI_MODELS_PATH/a/b完全等价。.env 文件批量管理配置任何通过环境变量提供的设置都可以放进.env文件。LocalAI 会按以下顺序查找越靠前优先级越高当前目录下的.env当前目录下的localai.env主目录下的localai.env主目录下的.config/localai.env/etc/localai.env列表中靠前文件中定义的变量会覆盖靠后文件中同名变量的值。示例.env文件LOCALAI_THREADS10 LOCALAI_MODELS_PATH/mnt/storage/localai/models LOCALAI_F16true这带来一种非常实用的运维方式把环境相关的差异路径、线程数、开关沉淀到.env而把模型定义沉淀到 YAML二者互不污染。使用 Extra-Usage 请求头获取推理耗时默认的 OpenAI 兼容usage字段只含 token 计数。如果你希望在响应中附带毫秒级推理耗时可以带上Extra-Usage: true请求头... { id: ..., created: ..., model: ..., choices: [ { ... }, ... ], object: ..., usage: { prompt_tokens: ..., completion_tokens: ..., total_tokens: ..., // 出现 Extra-Usage 请求头时将追加下面两个 float 字段 timing_prompt_processing: ..., timing_token_generation: ..., }, } ...该特性在源码中有完整闭环请求侧chat、completion、edit 三个 OpenAI 兼容入口均检测Extra-Usage头例如 core/http/endpoints/openai/chat.go 的extraUsage : c.Request().Header.Get(Extra-Usage) ! core/http/endpoints/openai/completion.go 与 core/http/endpoints/openai/edit.go 相同响应侧core/schema/openai.go 定义了TimingPromptProcessingtiming_prompt_processing与TimingTokenGenerationtiming_token_generation两个omitempty字段仅在开启该头时出现。这使其成为做基准测试、对比 prompt 处理与 token 生成两段耗时的便捷手段而无需解析外部日志。在运行时准备额外后端Extra Backends除编译期内置后端外LocalAI 还可以按需扩展更多后端同样以 gRPC 服务形式实现可用任意语言编写。若你使用-core容器镜像可在运行时用EXTRA_BACKENDS变量只准备自己需要的 Python 后端例如docker run --env EXTRA_BACKENDSbackend/python/diffusers quay.io/go-skynet/local-ai:master仓库 backend/python 下是各 Python 后端的实现目录每个子目录含run.sh启动脚本、依赖清单与 Python 服务代码需要接入新后端时可参照现有目录结构在本机或镜像内准备环境。VRAM/内存管理与 CPU 特性自动探测同时运行多个模型时如何管理显存与内存是常见的痛点。详细策略含各内存相关 CLI 参数、显存预算与回收机制请见专题页 docs/content/advanced/vram-management.md其中与 Backend 生命周期相关的开关在 core/cli/run.go 均有对应字段例如--max-active-backendsLRU 驱逐0 不限、--enable-watchdog-idle/--enable-watchdog-busy、--enable-memory-reclaimer内存阈值超限自动驱逐后端等。另一个值得了解的启动行为是LocalAI 会自动探测宿主机的CPU 指令集flagset并选用最适配的优化后端版本。如果希望关闭这一自动探测把环境变量DISABLE_AUTODETECT设为true即可容器环境变量表中同样列有此项默认false。小结把各部件串起来把上述能力组合起来一套典型的“高级用法”工作流是用.env或环境变量固定基础运行参数LOCALAI_MODELS_PATH、LOCALAI_THREADS、LOCALAI_F16为每个模型编写独立 YAML含backend、parameters、template或用--models-config-file统一管理首次部署用PRELOAD_MODELS/PRELOAD_MODELS_CONFIG在启动阶段自动拉取模型需要第三方推理引擎时通过--external-grpc-backends挂载外部 gRPC 服务调优阶段用Extra-Usage头观测两段耗时配合 prompt cache 与并行度参数找到吞吐与延迟的平衡点生产环境按需开启 watchdog、内存回收与显存预算控制多模型共存时的资源边界。这些配置项在仓库中均有对应的真实实现与默认值可查可放心对照 core/cli/run.go、docs/content/advanced/model-configuration.md 与 docs/content/reference/cli-reference.md 继续深入。【免费下载链接】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），仅供参考 LocalAI 高级使用指南：YAML 模型配置、Prompt 模板、启动预载与外部 Backend 扩展
LocalAI 高级使用指南YAML 模型配置、Prompt 模板、启动预载与外部 Backend 扩展【免费下载链接】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本文是 LocalAI 高级用法的系统化技术指南围绕“如何让任意模型在任意硬件上以你期望的方式跑起来”这一目标讲解 YAML 模型配置、.tmpl Prompt 模板、运行时/启动时安装模型、Prompt 缓存、外部 gRPC Backend 接入、并发请求、环境变量与 .env 文件等进阶操作。读完本文你将掌握一套可落地的“模型接入 行为定制 性能调优”组合方案并能在容器、命令行与配置文件三种形态之间自由切换。本文主体整理自仓库文档 docs/content/advanced/advanced-usage.md源码证据分别指向 core/cli/run.go、core/startup/model_preload.go、core/config/generic_defaults.go 以及 core/http/endpoints/openai 下各入口文件。YAML 模型配置定义参数、模板与行为LocalAI 使用 YAML 配置文件来定义模型的参数、模板与运行时行为。你既可以在模型目录下为每个模型单独建一个 YAML 文件也可以用一个配置文件承载多个模型。最简示例name: gpt-3.5-turbo parameters: model: luna-ai-llama2-uncensored.ggmlv3.q5_K_M.bin temperature: 0.3 context_size: 512 threads: 10 backend: llama-cpp template: completion: completion chat: chat各字段作用如下字段作用name模型对外名称API 请求如model: gpt-3.5-turbo中用它来定位该配置parameters.model模型权重文件路径相对模型目录也支持 URL配合download_files/artifacts自动下载parameters.temperature采样温度作为该模型所有请求的默认值context_size最大上下文长度token 数threads并行计算线程数按模型覆盖服务级--threads设置backend显式指定推理后端如llama-cpp、vllm、diffusers等template指定用于 completion / chat 等场景的模板见下文 Prompt 模板小节parameters一节可以容纳 OpenAI 兼容的整套请求参数top_p、max_tokens、frequency_penalty、presence_penalty、seed、n、logprobs等这些值会作为该模型所有 API 调用的默认值且仍能被单次请求中的同名参数覆盖。所有配置字段的完整参考表含每字段类型、默认值见 docs/content/advanced/model-configuration.md。三种配置文件加载位置独立文件在模型目录下创建以模型名命名的.yaml文件例如models/gpt-3.5-turbo.yaml。这是最常用的方式——把文件放进--models-path指向的目录即可被自动发现。单一配置文件多模型用--models-config-file或环境变量LOCALAI_MODELS_CONFIG_FILE兼容旧名--config-file/CONFIG_FILE指定一个 YAML 文件文件内以列表形式声明多个模型- name: model1 parameters: model: model1.bin context_size: 512 backend: llama-cpp - name: model2 parameters: model: model2.bin context_size: 1024 backend: llama-cpp从源码看该参数定义于 core/cli/run.goModelsConfigFile string ... env:LOCALAI_MODELS_CONFIG_FILE,CONFIG_FILE aliases:config-file并在启动时经config.WithConfigFile(r.ModelsConfigFile)注入配置管线见 core/cli/run.go。因此该开关既能以 kebab-case 命令行标志--models-config-file、--config-file使用也能写成LOCALAI_MODELS_CONFIG_FILExxx local-ai run。远程 URL启动时直接传入一个指向 YAML 配置文件的 URLgithub://、http(s)://、huggingface://等均可local-ai run github://mudler/LocalAI/examples/configurations/phi-2.yamlmaster运行时解析该列表的逻辑对应 core/cli/run.go 中的ModelArgs []string位置参数与Models []string字段env:LOCALAI_MODELS,MODELS两者最终合并进config.WithModelsURL(...)。使用 Prompt 模板定制模型的“人格”与交互格式LocalAI 的 API不会自动注入用于与模型对话的默认提示词prompt。要获得合适的对话效果你需要使用与 stanford-alpaca 文档中描述类似的提示结构来提问。一个更省事的做法是为模型目录下的每个模型文件准备一个同名.tmpl后缀的模板文件。例如模型叫foo.bin就在它旁边建foo.bin.tmpl该文件会被作为该模型的默认提示词模板alpaca 风格可写作The below instruction describes a task. Write a response that appropriately completes the request. ### Instruction: {{.Input}} ### Response:仓库根目录 prompt-templates 内已为多款主流模型准备了现成模板如alpaca.tmpl、vicuna.tmpl、koala.tmpl、wizardlm.tmpl、ggml-gpt4all-j.tmpl等。以 prompt-templates/alpaca.tmpl 为例其内容与上例完全一致可直接复制参考。仓库内模板均采用 Go template 语法并支持 Sprig 函数扩展。针对edit 端点文本改写/编辑alpaca 系模型可以准备带指令与输入的双变量模板Below is an instruction that describes a task, paired with an input that provides further context. Write a response that appropriately completes the request. ### Instruction: {{.Instruction}} ### Input: {{.Input}} ### Response:模板中常用的变量包括详见 docs/content/advanced/model-configuration.md{{.Input}}—— 用户输入{{.Instruction}}—— 编辑操作中的指令{{.System}}—— 系统消息{{.Prompt}}—— 完整提示词{{.Functions}}—— 函数/工具定义用于 function calling{{.FunctionCall}}—— 函数调用结果除了.tmpl旁挂文件同样可以把模板写进模型 YAML 的template段template.chat/template.completion/template.edit/template.function等实现“模板随模型配置一起分发”。通过 API 与启动参数安装模型除手动放置权重文件外LocalAI 支持通过 API 在运行时程序化安装模型。这里需要区分两类文件模型配置文件上文介绍的服务端 YAML负责“如何加载与运行模型”模型库model gallery文件描述“模型从哪下载、如何安装”的清单。仓库中的精选模型库清单位于 gallery 目录如vicuna.yaml、llama3-instruct.yaml、qwen3.yaml、piper.yaml等。通过/models/apply端点安装以安装lunademo为例向/models/apply发送 POST 请求url填模型库定义地址name可选指定模型在 LocalAI 内的名称curl --location http://localhost:8080/models/apply \ --header Content-Type: application/json \ --data-raw { id: TheBloke/Luna-AI-Llama2-Uncensored-GGML/luna-ai-llama2-uncensored.ggmlv3.q5_K_M.bin, name: lunademo }启动时预载模型首次启动即可用为让服务在首次启动时就具备全部所需模型可将模型库清单放到启动流程中。PRELOAD_MODELS[{url: https://raw.githubusercontent.com/go-skynet/model-gallery/main/gpt4all-j.yaml,name: gpt4all-j}] local-aiPRELOAD_MODELS或命令行--preload-models接收一段 JSON 列表其中每个元素与/models/apply端点的调用参数一致。与之等价也可以用PRELOAD_MODELS_CONFIG或--preload-models-config指向一个 YAML 列表文件- url: https://raw.githubusercontent.com/go-skynet/model-gallery/main/gpt4all-j.yaml name: gpt4all-j这两个启动开关的定义见 core/cli/run.goenv:LOCALAI_PRELOAD_MODELS,PRELOAD_MODELS与env:LOCALAI_PRELOAD_MODELS_CONFIG,PRELOAD_MODELS_CONFIG随后在 core/cli/run.go 通过config.WithJSONStringPreload与config.WithYAMLConfigPreload进入应用装配。真正执行安装的入口是 core/startup/model_preload.go 中的InstallModels/InstallModelsWithOptions——它会先在已注册 gallery 中查找模型命中则调用InstallModelFromGallery安装若未命中则视为“嵌入式 YAML 模型定义”经DiscoverModelConfig探测后送入模型库操作队列等待安装完成。整个流程会对每次下载显示进度因此非常适合首次冷启动时批量拉取模型。自动 Prompt 缓存加速带前缀模板的提示处理当模型需要“模板前缀文本 用户输入”这样的固定结构时LocalAI 可以把前缀部分缓存起来从而显著加快后续请求的提示处理速度。在模型配置 YAML 中开启缓存prompt_cache_path: cache prompt_cache_all: trueprompt_cache_path相对模型目录的路径你可以在此填写一个缓存文件名该文件会在首次加载时被自动创建当prompt_cache_all为true时。另有prompt_cache_ro只读模式可配合共享只读缓存使用。相关字段在 core/config/model_config.go 中定义PromptCachePath/PromptCacheAll/PromptCacheRO。值得注意的一点是 core/config/generic_defaults.go 的实现细节当prompt_cache_all未显式设置时其默认值会被置为true与上游 llama.cpp 的cache_prompt true默认一致从而让服务端 KV 缓存相关选项真正生效如需关闭可在模型 YAML 中显式写prompt_cache_all: false。补充说明如果你使用的是llama-cpp后端当前更推荐的是服务端 prompt cache通过options:数组中的cache_ram/kv_unified/cache_idle_slots控制自 LocalAI v4.3 起默认开启它能让重复系统提示在第二次调用时近乎零预填充prompt_cache_path系列字段来自上游 CLI 工具的兼容传递详见 docs/content/advanced/model-configuration.md。为模型显式指定 Backend默认情况下LocalAI 会尝试遍历所有后端对模型进行“自动加载”。这对大多数模型有效但并非所有后端都配置为可自动加载。所有可用后端见 docs/content/reference/compatibility-table.md 中的模型兼容性表。要显式指定后端只需在models目录下为该模型写一个 YAML 配置文件并声明backendname: gpt-3.5-turbo parameters: # 相对模型目录的权重文件路径 model: ... backend: llama-cppbackend的取值决定调用哪条推理链路——例如本地 GGUF 权重用llama-cpp/ik-llama-cpp/turboquant系Python 系模型用vllm、diffusers、transformers等多模态/语音模型则对应whisper、piper、qwen3-tts-cpp等后端名。连接外部 BackendgRPC 扩展机制LocalAI 的后端在内部都是基于gRPC 服务实现的。这一架构使 LocalAI 能在启动时连接外部 gRPC 服务通过第三方二进制扩展其能力。CLI 参数--external-grpc-backends既可以指定本地后端一个可执行文件也可以指定远程地址语法为BACKEND_NAME:BACKEND_URI。一旦 LocalAI 以该参数启动新后端名将对所有 API 端点可用。例如注册一个本地文件形式的后端./local-ai --debug --external-grpc-backends my-awesome-backend:/path/to/my/backend.py或者一个远程 URI./local-ai --debug --external-grpc-backends my-awesome-backend:host:port以手动启动 vLLM 后端为例假设在仓库根目录下执行且已编译 LocalAI./local-ai --external-grpc-backends vllm:$PWD/backend/python/vllm/run.sh首次使用前需要先构建其 Python 环境make -C backend/python/vllm源码层面该参数的解析逻辑位于 core/cli/run.goLocalAI 对--external-grpc-backends列表逐项按第一个:切分为“后端名 URI”再通过config.WithExternalBackend(name, uri)注册对应环境变量为LOCALAI_EXTERNAL_GRPC_BACKENDS/EXTERNAL_GRPC_BACKENDS见 core/cli/run.go。正因为后端与 LocalAI 主进程之间只有 gRPC 一个契约后端理论上可以用任何语言编写——只要能实现该 gRPC 服务即可。并发请求与并行度调优对于支持并行的后端LocalAI 允许多个请求并行处理例如 vLLM 与 llama.cpp 都支持并行请求。开启方式是传--parallel-requests或把环境变量PARALLEL_REQUEST设为true。控制并行度的关键环境变量如下环境变量含义PYTHON_GRPC_MAX_WORKERSPython 类 gRPC 后端的最大 worker 数它实际决定了后端能否同时处理多个请求LLAMACPP_PARALLELllama.cpp 的并行进程数需按你的 GPU/CPU 实际承受能力设置默认 1PARALLEL_REQUEST总开关开启并行请求对 llama.cpp你需要把LLAMACPP_PARALLEL设置成你的 GPU/CPU 能支撑的并行进程数对 Python 类后端如 vLLM则用PYTHON_GRPC_MAX_WORKERS指定并发的请求数量。此外LocalAI 进程级还有一个整体并发天花板--max-concurrent-backend-requests默认 1024对应LOCALAI_MAX_CONCURRENT_BACKEND_REQUESTS超出上限的推理请求会收到 HTTP 503 Retry-After但 UI 与管理端点不受影响见 core/cli/run.go。它与后端内的并行 worker 是两个层面前者管“LocalAI 放行多少路请求”后者管“单个后端实例内部开多少个 worker”。容器环境变量总览当 LocalAI 在容器中运行时有以下影响启动行为的附加环境变量环境变量默认值说明REBUILDfalse启动时重新构建 LocalAIBUILD_TYPE构建类型。可选cublas、openblas、clblas、intelIntel core、sycl_f16、sycl_f32Intel 后端GO_TAGSGo 编译标签。可选stablediffusionHUGGINGFACEHUB_API_TOKEN与 HuggingFace Inference API 交互所需令牌仅在用langchain-huggingface后端时需要EXTRA_BACKENDS需要预装的后端列表空格分隔。例如EXTRA_BACKENDSbackend/python/diffusers backend/python/transformers会在启动时准备对应 Python 环境DISABLE_AUTODETECTfalse启动时禁用 CPU 指令集自动探测LLAMACPP_GRPC_SERVERSllama.cpp worker 列表用于分发负载。例如LLAMACPP_GRPC_SERVERSaddress1:port,address2:port配置方式示例docker run --env REBUILDtrue localai docker run --env-file .env localai后一条命令通过--env-file一次性注入全部变量任何 CLI 参数都可以等价地用环境变量表达命名规则与示例见下一节。CLI 参数与环境变量的等价关系完整的 CLI 参数、环境变量与命令行选项清单见 docs/content/reference/cli-reference.md。LocalAI 的命令行参数可以控制绑定地址、线程数、模型路径等大量选项且每个命令行参数都可以通过环境变量指定环境变量优先于命令行标志。在源码 core/cli/run.go 中这种一一对应关系体现得极其直白——每个结构体字段都同时声明了 flag 与环境变量名例如CLI 参数环境变量说明--models-pathLOCALAI_MODELS_PATH/MODELS_PATH模型目录--addressLOCALAI_ADDRESS/ADDRESSAPI 绑定地址默认:8080-t, --threadsLOCALAI_THREADS/THREADS并行线程数--context-sizeLOCALAI_CONTEXT_SIZE/CONTEXT_SIZE默认上下文大小--f16LOCALAI_F16/F16启用 GPU 加速--api-keysLOCALAI_API_KEY/API_KEYAPI 鉴权密钥列表例如 core/cli/run.go 中ModelsPath字段写作env:LOCALAI_MODELS_PATH,MODELS_PATH意味着--models-path /a/b与export LOCALAI_MODELS_PATH/a/b完全等价。.env 文件批量管理配置任何通过环境变量提供的设置都可以放进.env文件。LocalAI 会按以下顺序查找越靠前优先级越高当前目录下的.env当前目录下的localai.env主目录下的localai.env主目录下的.config/localai.env/etc/localai.env列表中靠前文件中定义的变量会覆盖靠后文件中同名变量的值。示例.env文件LOCALAI_THREADS10 LOCALAI_MODELS_PATH/mnt/storage/localai/models LOCALAI_F16true这带来一种非常实用的运维方式把环境相关的差异路径、线程数、开关沉淀到.env而把模型定义沉淀到 YAML二者互不污染。使用 Extra-Usage 请求头获取推理耗时默认的 OpenAI 兼容usage字段只含 token 计数。如果你希望在响应中附带毫秒级推理耗时可以带上Extra-Usage: true请求头... { id: ..., created: ..., model: ..., choices: [ { ... }, ... ], object: ..., usage: { prompt_tokens: ..., completion_tokens: ..., total_tokens: ..., // 出现 Extra-Usage 请求头时将追加下面两个 float 字段 timing_prompt_processing: ..., timing_token_generation: ..., }, } ...该特性在源码中有完整闭环请求侧chat、completion、edit 三个 OpenAI 兼容入口均检测Extra-Usage头例如 core/http/endpoints/openai/chat.go 的extraUsage : c.Request().Header.Get(Extra-Usage) ! core/http/endpoints/openai/completion.go 与 core/http/endpoints/openai/edit.go 相同响应侧core/schema/openai.go 定义了TimingPromptProcessingtiming_prompt_processing与TimingTokenGenerationtiming_token_generation两个omitempty字段仅在开启该头时出现。这使其成为做基准测试、对比 prompt 处理与 token 生成两段耗时的便捷手段而无需解析外部日志。在运行时准备额外后端Extra Backends除编译期内置后端外LocalAI 还可以按需扩展更多后端同样以 gRPC 服务形式实现可用任意语言编写。若你使用-core容器镜像可在运行时用EXTRA_BACKENDS变量只准备自己需要的 Python 后端例如docker run --env EXTRA_BACKENDSbackend/python/diffusers quay.io/go-skynet/local-ai:master仓库 backend/python 下是各 Python 后端的实现目录每个子目录含run.sh启动脚本、依赖清单与 Python 服务代码需要接入新后端时可参照现有目录结构在本机或镜像内准备环境。VRAM/内存管理与 CPU 特性自动探测同时运行多个模型时如何管理显存与内存是常见的痛点。详细策略含各内存相关 CLI 参数、显存预算与回收机制请见专题页 docs/content/advanced/vram-management.md其中与 Backend 生命周期相关的开关在 core/cli/run.go 均有对应字段例如--max-active-backendsLRU 驱逐0 不限、--enable-watchdog-idle/--enable-watchdog-busy、--enable-memory-reclaimer内存阈值超限自动驱逐后端等。另一个值得了解的启动行为是LocalAI 会自动探测宿主机的CPU 指令集flagset并选用最适配的优化后端版本。如果希望关闭这一自动探测把环境变量DISABLE_AUTODETECT设为true即可容器环境变量表中同样列有此项默认false。小结把各部件串起来把上述能力组合起来一套典型的“高级用法”工作流是用.env或环境变量固定基础运行参数LOCALAI_MODELS_PATH、LOCALAI_THREADS、LOCALAI_F16为每个模型编写独立 YAML含backend、parameters、template或用--models-config-file统一管理首次部署用PRELOAD_MODELS/PRELOAD_MODELS_CONFIG在启动阶段自动拉取模型需要第三方推理引擎时通过--external-grpc-backends挂载外部 gRPC 服务调优阶段用Extra-Usage头观测两段耗时配合 prompt cache 与并行度参数找到吞吐与延迟的平衡点生产环境按需开启 watchdog、内存回收与显存预算控制多模型共存时的资源边界。这些配置项在仓库中均有对应的真实实现与默认值可查可放心对照 core/cli/run.go、docs/content/advanced/model-configuration.md 与 docs/content/reference/cli-reference.md 继续深入。【免费下载链接】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），仅供参考