LocalAI 运行时设置（Runtime Settings）深度指南：Web UI 配置、runtime_settings.json 持久化与“环境变量优先“三级体系

LocalAI 运行时设置（Runtime Settings）深度指南：Web UI 配置、runtime_settings.json 持久化与"环境变量优先"三级体系

【免费下载链接】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 面向运维与集成的动态配置子系统：管理员可在http://localhost:8080/manage的Settings页面中调整看门狗、后端淘汰、性能、安全、P2P、Gallery 与 Agent Pool 等参数，改动自动写入runtime_settings.json并无需重启进程即可生效。本文以 官方文档 docs/content/features/runtime-settings.md 为骨架，结合源码讲解每一项配置的含义与默认值、配置持久化机制、三级优先级规则（环境变量/CLI > 配置文件 > 默认值）以及三类触发入口（启动、POST /api/settings、手工改文件），帮助你既能用好 Web UI，也能安全地直接操作配置文件。

运行时设置系统概览

LocalAI 的运行时设置不是一张孤立的 JSON 表，而是一套"单一声明、四处一致"的完整机制，其核心设计体现在三层源码中：

• 字段模型：core/config/runtime_settings.go 定义RuntimeSettings结构体，注释明确说明它同时服务GET/POST /api/settings、runtime_settings.json的持久化与启动加载四种场景。所有字段都是指针类型，目的正是区分"未设置"与"被显式设置为零值/false"——这是整个优先级判定能成立的前提。
• 字段注册表：core/config/runtime_settings_registry.go 用一张runtimeSettingsFields表（fieldSpec结构）逐字段描述"如何从ApplicationConfig快照、如何应用回去、如何判断该字段是否已被环境变量/CLI 认领"。ToRuntimeSettings、ApplyRuntimeSettings、ApplyRuntimeSettingsAtStartup都是对这一张表的循环遍历，避免各入口之间逐字段手写导致的漂移。
• 统一优先级：三个能改动设置的入口（启动时读取文件、POST /api/settings、配置文件热更新）使用同一条规则：环境变量与 CLI 参数（最高）> 配置文件（runtime_settings.json、api_keys.json）> 默认值（最低）。

访问运行时设置

LocalAI 启动后（默认localhost:8080），从管理界面导航到Settings页面（地址http://localhost:8080/manage）即可看到完整的可视化配置界面。页面背后的数据通道就是 HTTP API：

• GET /api/settings：返回合并后的当前生效设置。实现见 core/http/endpoints/localai/settings.go，通过appConfig.ToRuntimeSettings()把ApplicationConfig快照成RuntimeSettings返回。
• POST /api/settings：接收 JSON 请求体、校验、持久化并立即应用。见 settings.go 的 UpdateSettingsEndpoint。

POST端点会先做防御性校验（详见下文中各字段说明），然后按"读取磁盘已有设置 → 只合并请求体里出现的字段 → 写回文件"的顺序落盘，最后按变更类型触发对应的运行时动作：重启看门狗、重启 P2P、重启 MITM 监听或更新 Agent Job 服务。

可用设置项详解

看门狗（Watchdog）设置

看门狗负责监控后端（backend）活动，自动停止长期空闲（idle）或持续繁忙（busy）的模型以释放内存/显存资源。相关字段：

在注册表中，这些字段通过durationField建模（runtime_settings_registry.go），配置侧接受标准 Go 时长字符串（30s、15m、2h）。此外还隐含一个watchdog_interval（两次检查之间的间隔，默认继承model.DefaultWatchdogInterval），普通用户通常无需调整。

看门狗设置的变更会立即生效：文档明确说明"通过重启看门狗服务实现"。对应源码是 core/application/watchdog.go 中的StartWatchdog/RestartWatchdog/StopWatchdog。值得注意的细节是startWatchdog（watchdog.go L82-L145）的启动判据并非只看总开关：

1. WatchDog开关打开、或LRU 上限（max_active_backends）大于 0、或内存回收器（memory reclaimer）启用，都会创建看门狗实例——LRU 淘汰即使不开启 idle/busy 检查也需要看门狗基础设施；
2. RestartWatchdog会先关闭旧实例并WaitDone等待其完全退出，再以新配置启动，最后通过RestoreState(oldState)把已加载模型的状态迁移给新看门狗，避免一次保存设置就把已就绪的模型全部"遗忘"（watchdog.go L155-L200）。

如果内存回收器（memory_reclaimer_enabled）被启用，应用逻辑会把看门狗总开关强制置为开启——这是注册表注释明确记载的跨字段不变量（见 runtime_settings_registry.go L174-L175 附近）。

后端（Backend）管理

• Max Active Backends：最大并发活跃后端（即已加载模型数）。超出后自动淘汰最久未使用（LRU）的模型。0表示不限制，1即单后端模式。
• Force Eviction When Busy：是否允许在模型仍有活跃 API 调用时强行淘汰（默认关闭以保证安全）。警告：开启会中断正在进行的请求。
• LRU Eviction Max Retries：等待繁忙模型变空闲后重试淘汰的最大次数，默认30。
• LRU Eviction Retry Interval：两次重试之间的间隔，默认1s。

注意："Single Backend"（single_backend）设置已被废弃，请使用max_active_backends: 1获得等价的单后端行为。

从源码看，max_active_backends与其废弃别名single_backend在注册表中是同一个复合行（runtime_settings_registry.go L137-L164），二者必须保持互斥一致：两者同时被提交时max_active_backends胜出；若只提交single_backend=true，则反向把max_active_backends置 1。此外还有两个文档未展开但同属该分组的注册表字段：auto_upgrade_backends（检测到新版本后端时自动升级）与prefer_development_backends（UI 中默认偏好开发版后端）。

LRU 淘汰的行为序列

默认情况下，LocalAI 会跳过仍有活跃 API 调用的模型，避免中断进行中的请求。当所有模型都繁忙而又必须淘汰时：

1. 系统等待模型变空闲；
2. 按配置的最大重试次数反复重试淘汰；
3. 重试间隔（lru_eviction_retry_interval）决定两次尝试间的等待时长；
4. 若所有重试均已用尽，系统仍会继续执行淘汰流程（如果资源确实耗尽，可能因此触发内存不足/OOM错误）。

这些参数既可在 Web UI 配置，也可用环境变量设置；它们直接作用于ApplicationConfig，并可在POST时热更新到运行中的ModelLoader（见 settings.go L209-L232 的SetLRUEvictionRetrySettings）。更细的 VRAM 分配说明参见 VRAM 管理指南。

性能设置

• Threads（线程数）：用于并行计算的线程数量，官方建议设为物理核心数。映射到ApplicationConfig.Threads，最终下发到各推理后端。
• Context Size（上下文大小）：模型默认上下文长度，默认512。
• Artifact Download Concurrency：同时下载的模型产物（artifact）文件数上限。1表示串行下载，默认1。应用侧对小于 1 的值会强制收敛为 1（runtime_settings_registry.go L230-L238）。
• F16：启用 16 位浮点的 GPU 加速。
• VRAM Budget：模型分配时的 VRAM 用量上限，例如80%或12GB；留空表示不设上限。

VRAM Budget 值得单独说明：它不止写入配置，还会在应用时通过vrambudget.Parse解析并调用xsysinfo.SetDefaultVRAMBudget安装进程级分配上限（见 core/config/runtime_settings_startup.go）。因此手工把vram_budget写进文件会被配置监听器热应用，无需重启即可让新的显存上限即时生效。POST端点会对非法格式（如既非百分比也非容量）预先拒绝，避免坏值进入配置（settings.go L100-L110）。

调试与日志

• Debug Mode：开启调试日志。注意该设置已废弃，请改用日志级别（log-level）机制。

注册表中同属调试域但文档正文未逐一列举的还包括：enable_tracing（追踪开关）与tracing_max_items（追踪条目上限）、tracing_max_body_bytes（单请求体抓取字节上限，0表示不设上限——该字段被标记为fromFileAlways，即磁盘上的0必须被理解为"显式不设限"而不能误判为未设置）、enable_backend_logging（后端日志，单机模式下默认开启，持久化的false在重启后必须继续生效，因此同样由文件权威决定，见 runtime_settings_registry.go L273-L277）。

API 安全

• CORS：开启跨域资源共享。
• CORS Allow Origins：允许的 CORS 来源，逗号分隔列表。
• CSRF：开启 CSRF 防护中间件。
• API Keys：管理用于认证的 API 密钥（每行一个，或用逗号分隔）。

细节上，配置里的csrf线上字段承载的是历史命名的DisableCSRF取反语义（runtime_settings_registry.go L285-L288），即 UI 上勾选 CSRF 防护 = 不禁用 CSRF。需要多用户角色、OAuth 与用量追踪的完整认证体系，请参见 Authentication & Authorization。

P2P 设置

配置分布式推理的对等网络：

• P2P Token：P2P 网络的认证令牌。
• P2P Network ID：P2P 连接的网络标识。
• Federated Mode：启用 P2P 网络的联邦模式。

P2P 设置变更后会自动重启整个 P2P 协议栈以应用新配置。端点实现里有两条贴心逻辑：请求体里若 P2P Token 传的是特殊值"0"，服务端会调用p2p.GenerateToken(60, 60)生成真实随机令牌再持久化（settings.go L112-L116）；而若提交的是空字符串，则直接StopP2P()关闭 P2P（settings.go L311-L331）。

Gallery 设置

管理模型与后端 Gallery（模型目录源）：

• Model Galleries：Gallery 对象的 JSON 数组，每个对象含url与name字段，并支持可选的mirrors回退地址列表（镜像机制详见 Model Gallery 文档中的 Gallery mirrors 一节）。
• Backend Galleries：后端 Gallery 对象的 JSON 数组，同样接受mirrors键。
• Load and pre-warm galleries on boot：LocalAI 启动时加载模型 Gallery 并预热其远程大小与 VRAM 估算。关闭该项可同时跳过这两个启动操作。
• Autoload Backend Galleries：启动时自动加载后端 Gallery。

源码侧"预热"能力与vram_persistent_cache（VRAM 估算持久化缓存）联动：当VRAMPersistentCache && AutoloadGalleries同时为真时，POST端点会调用vram.ConfigurePersistentCache(...)启用基于缓存目录的持久化（settings.go L190-L196）。默认 gallery 列表在 core/config/runtime_settings_startup.go 中定义为编译期常量：模型源主地址为https://index.localai.io/models，镜像为github:mudler/LocalAI/gallery/index.yaml@master；后端源同理对应.../backends与backend/index.yaml。

Agent Pool 设置

配置 LocalAI 内置的 Agent 平台（完整文档见 Agents）：

• Agent Pool Enabled：启用或停用 agent pool 功能。
• Default Model：新 Agent 使用的默认 LLM。
• Embedding Model：知识库向量化所用的嵌入模型，默认granite-embedding-107m-multilingual。
• Max Chunking Size：文档摄取的最大分块大小，默认400。
• Chunk Overlap：文档块之间的重叠长度，默认0。
• Enable Logs：开启详细的 Agent 日志。
• Collection DB Path：集合数据库的自定义路径。

注意：大多数 Agent Pool 设置需要重启 LocalAI才能生效（注册表中相关字段均标记了restartRequired()，见 runtime_settings_registry.go L384-L434）。

其他可运行时管理的字段

同一注册表还登记了一批超出传统"设置页"范畴的运行时字段，展示这套架构的通用性（runtime_settings_registry.go）：

• 分布式磁盘余量检查distributed_disk_headroom_check：智能路由器在每次调度决策时实时读取该值，拒绝"磁盘空间不足以存放模型"的节点，切换无需重启。
• LocalAI Assistantlocalai_assistant_enabled：由请求处理器在请求进入时实时读取。
• 白标/品牌化：instance_name、instance_tagline、logo_file、logo_horizontal_file、favicon_file——文件是唯一来源（无环境变量对应），因此被标记为fileAuthoritative，否则重启会静默丢掉已配置的名称与素材文件名。图片素材通过/api/branding/asset/{kind}单独上传。
• MITM 监听mitm_listen与PII 默认检测器pii_default_detectors：变更会触发RestartMITM()重建云代理拦截监听；pii_default_detectors使用空数组即可从 UI 清空默认检测器。
• Open Responses 存储 TTLopen_responses_store_ttl（"0"/空 = 永不过期）与Agent Job 保留天数agent_job_retention_days（变更后重启 Agent Job 服务）。

配置持久化：runtime_settings.json

所有设置会自动保存到LOCALAI_CONFIG_DIR目录下的runtime_settings.json。LOCALAI_CONFIG_DIR在 core/cli/run.go 中定义为环境变量，默认值是${basepath}/configuration（即通常的BASEPATH/configuration）。源码对写入有明确约束：

• 序列化采用缩进 JSON 并以0o600权限写盘（core/config/runtime_settings_persist.go），因为文件里可能携带 API Key 与 P2P Token 等敏感信息；
• 读写遵循"读-改-写"契约：MergeNonNil用反射把请求体中非 nil的字段覆盖到磁盘已有设置上，因此聚焦式管理页（如只 POSTmitm_listen或pii_default_detectors的页面）不会把其余设置清空，且新增字段天然被覆盖逻辑纳入，不会漏持久化（runtime_settings_persist.go L55-L64）；
• 该文件被持续监听，因此直接编辑文件同样会在运行时被应用（详见"动态配置热加载"一节）。

完整示例配置

文档给出的runtime_settings.json结构如下（示例中的注释为本文件之外的说明，配置文件本身为纯 JSON）：

{ "watchdog_enabled": true, "watchdog_idle_enabled": true, "watchdog_busy_enabled": false, "watchdog_idle_timeout": "15m", "watchdog_busy_timeout": "5m", "max_active_backends": 0, "force_eviction_when_busy": false, "lru_eviction_max_retries": 30, "lru_eviction_retry_interval": "1s", "threads": 8, "context_size": 2048, "artifact_download_concurrency": 4, "f16": false, "debug": false, "cors": true, "csrf": false, "cors_allow_origins": "*", "p2p_token": "", "p2p_network_id": "", "federated": false, "galleries": [ { "url": "https://index.localai.io/models", "mirrors": ["github:mudler/LocalAI/gallery/index.yaml@master"], "name": "localai" } ], "backend_galleries": [ { "url": "https://index.localai.io/backends", "mirrors": ["github:mudler/LocalAI/backend/index.yaml@master"], "name": "localai" } ], "autoload_galleries": true, "autoload_backend_galleries": true, "vram_persistent_cache": true, "api_keys": [] }

使用要点：

• 时长类字段（watchdog 超时、重试间隔）接受15m、1s、30s、2h这类 Go 时长字符串，非法格式会被日志告警并拒之门外；
• context_size之类未持久化的字段在启动时会回落到代码默认值（文档记载默认512）；
• galleries/backend_galleries是对象数组，mirrors中github:user/repo/path@branch格式用于描述 GitHub 源镜像回退链（回退逻辑见 core/gallery/gallery_mirrors.go）；
• api_keys不带omitempty，空数组[]会被照常写盘，从而表达"清空运行时密钥"这一意图（见下文 API Keys 管理）。

设置优先级与三类生效场景

所有运行时设置遵循唯一一条优先级规则：

1. 环境变量与 CLI 参数（最高）
2. 配置文件（runtime_settings.json、api_keys.json）
3. 默认值（最低）

同一条规则在三个能改变设置的场景中被一致地执行：

① 启动（boot）时：runtime_settings.json中持久化的值会填入所有"未被环境变量或 CLI 参数显式设置"的字段。其判定技巧在于：LocalAI 维护了一份"无任何参数裸跑"时的基准配置DefaultRuntimeBaseline（core/config/runtime_settings_startup.go），启动时逐字段比对——当前值只要仍等于该基准，就说明没有 env/CLI 干预过，此时才允许文件值生效（ApplyRuntimeSettingsAtStartup，见同文件 L69-L107）。

② 通过POST /api/settings（即 Web UI Settings 页）：若某字段由环境变量控制，则无法通过网页修改——设置页会明确标识哪些设置项受环境变量接管（因为GET /api/settings快照后，env/CLI 认领的字段在应用层会被跳过覆盖）。

③ 手工编辑文件：配置文件监听器以"与启动完全相同的 env-over-file 语义"热应用对runtime_settings.json的改动。也就是说，手工编辑该文件的效果等价于"带着这份文件重启一次"——例如手工把vram_budget改成新的上限，会立即安装新的 VRAM 分配上限，无需重启。

已知限制

实现（runtime_settings_startup.go L65-L68 的注释与文档保持一致）明确接受两条边界情况：

• 一个被显式设置为默认值的环境变量，与"未设置"无法区分，此时runtime_settings.json中的值会胜出。典型例子：显式LOCALAI_THREADS=0的行为与未设置LOCALAI_THREADS完全一致。
• 某个字段若此前通过 API（或 Web UI）改过，文件监听器会把它误判为"由环境变量设置"，于是对该字段的手工文件编辑不会热应用，而会等到下次重启才生效。

API Keys 管理

API Keys 通过运行时设置界面统一管理，输入规则为每行一个或逗号分隔。几条重要规则：

• 来自环境变量的 API Keys 永远被包含在内，且无法通过 UI 删除——端点实现会在保存前剥离请求体中的环境变量密钥，再以MergeAPIKeys(envKeys, runtimeKeys)合并（settings.go L150-L168、runtime_settings_persist.go L70-L83），因此反复保存不会让环境变量密钥层层重复堆积；
• 运行时管理的 API Keys 存储在runtime_settings.json的api_keys字段中；
• 出于向后兼容，API Keys 也可通过独立的api_keys.json管理；
• 空数组会清空全部运行时 API Keys（但保留环境变量密钥）。

动态配置：文件热加载机制

运行时设置系统内置动态配置文件监听。当设置LOCALAI_CONFIG_DIR（CLI 参数与环境变量同名，另支持LOCALAI_CONFIG_DIR_POLL_INTERVAL轮询间隔兜底）后，LocalAI 持续监听以下文件：

• runtime_settings.json—— 统一运行时设置；
• api_keys.json—— API Keys（向后兼容）；
• external_backends.json—— 外部后端配置。

监听实现位于 core/application/config_file_watcher.go：启动时把这三个文件注册为 handler（api_keys.json→readApiKeysJson、external_backends.json→readExternalBackendsJson、runtime_settings.json→readRuntimeSettingsJson），底层使用fsnotify监视目录内的Write | Create | Remove事件并按文件名分发（同文件 L98-L128）。事件机制失效的系统可设置LOCALAI_CONFIG_DIR_POLL_INTERVAL（如1m）退化为定时轮询。各 handler 重新加载文件时使用的合并语义与启动一致：env/CLI 认领的字段保留环境值，文件补齐其余字段（config_file_watcher.go L187-L210）。注意agent_tasks.json与agent_jobs.json不在此监听器内，它们由AgentJobService自行监视重载。

对这些文件的修改会被自动检测并应用，无需重启，且统一遵循上文"设置优先级"一节描述的同一条规则。

最佳实践

1. 生产环境优先使用环境变量：关键设置用环境变量/CLI 参数固化，可防止被 Web UI 误改——被 env 认领的字段在设置页不可编辑、在文件层不可覆盖。
2. 先备份配置文件：做重大调整前，先备份runtime_settings.json（最好连同目录一并保存），因为它是重启后一切 UI 改动的还原点。
3. 开启看门狗后要监控资源：空闲/繁忙超时没有放之四海皆准的值，需结合自身工作负载验证：超时太短会导致模型被频繁卸载重载，太长则资源空转。可参考前文提到的日志关键字定位看门狗决策。
4. 保护 API Keys：配置文件权限应严格限制为仅 LocalAI 进程可读（写入侧已用0o600），切勿让 Web 服务或其他账号可读含密钥/P2P Token 的文件。
5. 小步测试：部分设置（尤其看门狗超时、LRU 淘汰参数）需要针对具体模型负载反复调优；改动后留意日志与/api/settings返回的合并结果确认是否生效。

故障排查

设置未生效

若修改后设置没有按预期应用：

1. 检查该设置项是否由环境变量控制——被 env/CLI 认领的字段在 UI 保存时会被跳过，设置页会有相应标识；
2. 核对LOCALAI_CONFIG_DIR是否正确设置，确认写盘的是预期目录下的runtime_settings.json（默认BASEPATH/configuration）；
3. 检查runtime_settings.json的文件权限与可写性；
4. 回顾应用日志中是否存在配置相关错误（如非法时长/非法 VRAM 预算格式的告警、invalid duration in runtime settings等）。

看门狗不工作

1. 确认 "Watchdog Enabled" 已打开；
2. 确认 idle 或 busy 看门狗至少启用一个（若未启用任何检查且无 LRU 上限/内存回收器，看门狗不会启动Run()循环，参见 watchdog.go L88-L121）；
3. 检查超时值对当前工作负载是否合理（默认 idle15m、busy5m）；
4. 检索日志中的 watchdog 相关消息（启动时会打印Watchdog started with new settings及各参数，见 watchdog.go L139）。

P2P 无法启动

1. 确认 P2P Token 已设置且非空（空 token 提交会被解析为关闭 P2P 而非启动）；
2. 检查节点间的网络连通性；
3. 联邦模式下确保各节点的 P2P Network ID 一致；
4. 检索日志中的 P2P 相关错误信息。

进一步阅读：VRAM 管理、Model Gallery（含 mirrors 机制）、Authentication & Authorization、Agents，或在源码中跟进 RuntimeSettings 结构体、字段注册表与 配置监听器 理解这套体系的实现细节。

【免费下载链接】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