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 APIGET /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的模型以释放内存/显存资源。相关字段设置项说明默认值Watchdog Enabled看门狗总开关—Watchdog Idle Enabled启用空闲超过阈值即停—Watchdog Busy Enabled启用繁忙超过阈值即停—Watchdog Idle Timeout空闲后端的判定时间阈值时长字符串如15m15mWatchdog Busy Timeout繁忙后端的判定时间阈值时长字符串如5m5m在注册表中这些字段通过durationField建模runtime_settings_registry.go配置侧接受标准 Go 时长字符串30s、15m、2h。此外还隐含一个watchdog_interval两次检查之间的间隔默认继承model.DefaultWatchdogInterval普通用户通常无需调整。看门狗设置的变更会立即生效文档明确说明通过重启看门狗服务实现。对应源码是 core/application/watchdog.go 中的StartWatchdog/RestartWatchdog/StopWatchdog。值得注意的细节是startWatchdogwatchdog.go L82-L145的启动判据并非只看总开关WatchDog开关打开、或LRU 上限max_active_backends大于 0、或内存回收器memory reclaimer启用都会创建看门狗实例——LRU 淘汰即使不开启 idle/busy 检查也需要看门狗基础设施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 Backendsingle_backend设置已被废弃请使用max_active_backends: 1获得等价的单后端行为。从源码看max_active_backends与其废弃别名single_backend在注册表中是同一个复合行runtime_settings_registry.go L137-L164二者必须保持互斥一致两者同时被提交时max_active_backends胜出若只提交single_backendtrue则反向把max_active_backends置 1。此外还有两个文档未展开但同属该分组的注册表字段auto_upgrade_backends检测到新版本后端时自动升级与prefer_development_backendsUI 中默认偏好开发版后端。LRU 淘汰的行为序列默认情况下LocalAI 会跳过仍有活跃 API 调用的模型避免中断进行中的请求。当所有模型都繁忙而又必须淘汰时系统等待模型变空闲按配置的最大重试次数反复重试淘汰重试间隔lru_eviction_retry_interval决定两次尝试间的等待时长若所有重试均已用尽系统仍会继续执行淘汰流程如果资源确实耗尽可能因此触发内存不足/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 的值会强制收敛为 1runtime_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 TokenP2P 网络的认证令牌。P2P Network IDP2P 连接的网络标识。Federated Mode启用 P2P 网络的联邦模式。P2P 设置变更后会自动重启整个 P2P 协议栈以应用新配置。端点实现里有两条贴心逻辑请求体里若 P2P Token 传的是特殊值0服务端会调用p2p.GenerateToken(60, 60)生成真实随机令牌再持久化settings.go L112-L116而若提交的是空字符串则直接StopP2P()关闭 P2Psettings.go L311-L331。Gallery 设置管理模型与后端 Gallery模型目录源Model GalleriesGallery 对象的 JSON 数组每个对象含url与name字段并支持可选的mirrors回退地址列表镜像机制详见 Model Gallery 文档中的 Gallery mirrors 一节。Backend Galleries后端 Gallery 对象的 JSON 数组同样接受mirrors键。Load and pre-warm galleries on bootLocalAI 启动时加载模型 Gallery 并预热其远程大小与 VRAM 估算。关闭该项可同时跳过这两个启动操作。Autoload Backend Galleries启动时自动加载后端 Gallery。源码侧预热能力与vram_persistent_cacheVRAM 估算持久化缓存联动当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.yamlmaster后端源同理对应.../backends与backend/index.yaml。Agent Pool 设置配置 LocalAI 内置的 Agent 平台完整文档见 AgentsAgent 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_ttl0/空 永不过期与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.yamlmaster], name: localai } ], backend_galleries: [ { url: https://index.localai.io/backends, mirrors: [github:mudler/LocalAI/backend/index.yamlmaster], name: localai } ], autoload_galleries: true, autoload_backend_galleries: true, vram_persistent_cache: true, api_keys: [] }使用要点时长类字段watchdog 超时、重试间隔接受15m、1s、30s、2h这类 Go 时长字符串非法格式会被日志告警并拒之门外context_size之类未持久化的字段在启动时会回落到代码默认值文档记载默认512galleries/backend_galleries是对象数组mirrors中github:user/repo/pathbranch格式用于描述 GitHub 源镜像回退链回退逻辑见 core/gallery/gallery_mirrors.goapi_keys不带omitempty空数组[]会被照常写盘从而表达清空运行时密钥这一意图见下文 API Keys 管理。设置优先级与三类生效场景所有运行时设置遵循唯一一条优先级规则环境变量与 CLI 参数最高配置文件runtime_settings.json、api_keys.json默认值最低同一条规则在三个能改变设置的场景中被一致地执行① 启动boot时runtime_settings.json中持久化的值会填入所有未被环境变量或 CLI 参数显式设置的字段。其判定技巧在于LocalAI 维护了一份无任何参数裸跑时的基准配置DefaultRuntimeBaselinecore/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_THREADS0的行为与未设置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_DIRCLI 参数与环境变量同名另支持LOCALAI_CONFIG_DIR_POLL_INTERVAL轮询间隔兜底后LocalAI 持续监听以下文件runtime_settings.json—— 统一运行时设置api_keys.json—— API Keys向后兼容external_backends.json—— 外部后端配置。监听实现位于 core/application/config_file_watcher.go启动时把这三个文件注册为 handlerapi_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自行监视重载。对这些文件的修改会被自动检测并应用无需重启且统一遵循上文设置优先级一节描述的同一条规则。最佳实践生产环境优先使用环境变量关键设置用环境变量/CLI 参数固化可防止被 Web UI 误改——被 env 认领的字段在设置页不可编辑、在文件层不可覆盖。先备份配置文件做重大调整前先备份runtime_settings.json最好连同目录一并保存因为它是重启后一切 UI 改动的还原点。开启看门狗后要监控资源空闲/繁忙超时没有放之四海皆准的值需结合自身工作负载验证超时太短会导致模型被频繁卸载重载太长则资源空转。可参考前文提到的日志关键字定位看门狗决策。保护 API Keys配置文件权限应严格限制为仅 LocalAI 进程可读写入侧已用0o600切勿让 Web 服务或其他账号可读含密钥/P2P Token 的文件。小步测试部分设置尤其看门狗超时、LRU 淘汰参数需要针对具体模型负载反复调优改动后留意日志与/api/settings返回的合并结果确认是否生效。故障排查设置未生效若修改后设置没有按预期应用检查该设置项是否由环境变量控制——被 env/CLI 认领的字段在 UI 保存时会被跳过设置页会有相应标识核对LOCALAI_CONFIG_DIR是否正确设置确认写盘的是预期目录下的runtime_settings.json默认BASEPATH/configuration检查runtime_settings.json的文件权限与可写性回顾应用日志中是否存在配置相关错误如非法时长/非法 VRAM 预算格式的告警、invalid duration in runtime settings等。看门狗不工作确认 Watchdog Enabled 已打开确认 idle 或 busy 看门狗至少启用一个若未启用任何检查且无 LRU 上限/内存回收器看门狗不会启动Run()循环参见 watchdog.go L88-L121检查超时值对当前工作负载是否合理默认 idle15m、busy5m检索日志中的 watchdog 相关消息启动时会打印Watchdog started with new settings及各参数见 watchdog.go L139。P2P 无法启动确认 P2P Token 已设置且非空空 token 提交会被解析为关闭 P2P 而非启动检查节点间的网络连通性联邦模式下确保各节点的 P2P Network ID 一致检索日志中的 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考