LocalAI 故障排查实战指南从安装、模型加载到 GPU 内存与 API 连接问题全解析【免费下载链接】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 官方故障排查文档docs/content/getting-started/troubleshooting.md为核心系统覆盖部署与日常使用中最高频的几类问题安装启动失败、模型无法加载或配置错误、GPU 未被识别与内存耗尽、API 连接与鉴权异常、推理性能不达标、Docker 部署与 P2P 分布式网络的疑难杂症。对每类问题文中均给出症状 → 诊断步骤 → 解决方案的完整链路并结合仓库源码说明底层机制如 LRU 后端淘汰、watchdog 自动卸载、后端能力覆盖等读完即可对照自身环境逐条排障。一、快速诊断先收集环境信息再谈修复在深入具体问题之前先用一组命令确认 LocalAI 当前的健康状态、已加载模型与版本信息。这些命令对应仓库中真实存在的接口与命令行参数# 1. 检查 LocalAI 是否已启动且就绪 curl http://localhost:8080/readyz # 2. 列出已加载模型 curl http://localhost:8080/v1/models # 3. 查看 LocalAI 版本 local-ai --version # 4. 开启 debug 日志以获得详细输出两种方式等价 DEBUGtrue local-ai run # 或 local-ai run --log-leveldebug几点机制说明/readyz是 LocalAI 的就绪探针端点对应后端core/application/application.go中的就绪状态追踪逻辑并在core/http/auth/public_routes.go中被声明为免认证的公开 GET 路由因此在配置了 API Key 的环境中也可直接探测聊天等子命令在连接服务端前也会轮询该端点直到返回 200见core/cli/chat/server.go。/v1/models返回当前实例上所有可用模型的 OpenAI 兼容列表可用于比对请求中的model名称是否与实际一致。DEBUGtrue等价于把日志级别提到 debug适合后续所有需要观察请求体/响应体/后端加载细节的排障场景。Docker 部署环境请使用容器视角收集信息# 查看容器日志 docker logs local-ai # 检查容器状态是否频繁重启 docker ps -a | grep local-ai # 测试 NVIDIA GPU 是否透传进容器若使用 GPU docker run --rm --gpus all nvidia/cuda:12.8.0-base-ubuntu24.04 nvidia-smi二、安装类问题1. Linux 二进制无法执行症状提示Permission denied或cannot execute binary file错误。解决先给二进制添加执行权限再运行chmod x local-ai-* ./local-ai-Linux-x86_64 run如果出现cannot execute binary file: Exec format error说明下载了错误架构的二进制。用uname -m确认 CPU 架构后再选择对应安装包uname -m # x86_64 → 下载 x86_64 二进制 # aarch64 → 下载 arm64 二进制不同平台的完整安装步骤可参考 docs/content/getting-started/linux.md、docs/content/getting-started/macos.md 与 docs/content/getting-started/install.md。2. macOS应用被隔离Quarantine症状因 DMG 未经过 Apple 签名macOS Gatekeeper 阻止 LocalAI 运行。解决官方 Issue #6268 中提供了绕过隔离quarantine的操作说明该问题当前在 Issue #6244 中持续跟踪。操作思路是移除下载文件上的隔离扩展属性后再启动即以xattr方式解除隔离执行前请确保文件来源可信并留意 Gatekeeper 的策略变化。三、模型加载问题1. Model Not Found模型不存在 / 404症状API 返回404或model not found错误。诊断步骤确认模型文件确实存在于模型目录中ls -la /path/to/models/核对 LocalAI 实际使用的模型目录路径并用 debug 日志观察它扫描到了什么local-ai run --models-path /path/to/models --log-leveldebug确认请求中的模型名与已注册模型完全一致包括大小写与后缀# 列出可用模型 curl http://localhost:8080/v1/models | jq .data[].id模型的放置、命名与注册方式可进一步参考 docs/content/getting-started/models.md。2. 模型存在但加载失败Backend Error症状模型文件能被找到但加载时日志出现 backend 级错误。常见原因与对策backend 选择错误模型 YAML 中的backend必须与模型格式匹配——GGUF 模型用llama-cppDiffusers 扩散模型用diffusers语音、图像、视频类模型各自对应专用 backend。可对照兼容性对照表核实。backend 未安装检查当前已安装的 backend并补装缺失项local-ai backends list # 安装缺失的 backend local-ai backends install llama-cpp该组命令在core/cli/backends.go中实现支持list、install、uninstall等子命令backend 本质是按模型类型分发推理请求的独立运行时参见 docs/content/features/backends.md。模型文件损坏下载中断或磁盘错误可能产生残缺文件请重新下载模型。模型格式过时llama.cpp 系列模型应使用 GGUF 格式旧 GGML 格式已被弃用。补充说明为防止某个模型因崩溃而反复加载、每次都重启 backendLocalAI 内置了加载失败冷却机制——默认单次失败后 10 秒内拒绝再次加载同一模型并返回503 Retry-After连续失败会指数退避至最长 5 分钟可用--model-load-failure-cooldown调节或置0关闭见 core/cli/run.go 中ModelLoadFailureCooldown的定义。如果日志中出现周期性 503请先定位模型为何反复加载失败而不是盲目等待重试。3. 模型配置问题加载成功但推理异常症状模型能加载但推理结果异常或运行时报错。核对模型 YAML 配置# 模型配置示例 name: my-model backend: llama-cpp parameters: model: my-model.gguf # 相对 models 目录的路径 context_size: 2048 threads: 4 # 应匹配物理 CPU 核数常见错误parameters.model必须是相对 models 目录的路径而不是绝对路径threads大于物理核数会造成线程争用thread contention推理反而变慢context_size超出可用内存会导致 OOM。仓库中真实的模型定义样例见 gallery/llama3.1-instruct.yaml它展示了完整字段结构backend: llama-cpp、mmap: true、context_size: 8192、f16: true、stopwords与 chat/function 模板等。可以看到context_size这类字段直接写在外层backend决定由哪个推理后端承载而mmap等加载选项也以 YAML 字段形式暴露排障时请对照这些字段逐一检查自己的配置文件。更多字段语义见 docs/content/advanced/model-configuration.md。四、GPU 与内存问题1. GPU 未被检测到NVIDIACUDA# 验证 CUDA 是否可用 nvidia-smi # Docker 场景验证 GPU 是否成功透传 docker run --rm --gpus all nvidia/cuda:12.8.0-base-ubuntu24.04 nvidia-smi正常工作情况下LocalAI 日志应出现ggml_init_cublas: found X CUDA devices。请务必使用启用了 CUDA 的容器镜像镜像 tag 含cuda11、cuda12或cuda13纯 CPU 镜像无法使用 NVIDIA GPU。AMDROCm# 验证 ROCm 安装 rocminfo # Docker 需要透传设备 docker run --device/dev/kfd --device/dev/dri --group-addvideo ...如果所用 GPU 不在默认目标列表中请到项目 Issue 区反馈。目前已支持的 ROCm 目标包括gfx908、gfx90a、gfx942、gfx950、gfx1030、gfx1100、gfx1101、gfx1102、gfx1200、gfx1201。IntelSYCL# Docker 需要透传 dri 设备 docker run --device /dev/dri ...请使用镜像 tag 含gpu-intel的容器镜像。已知问题SYCL 后端在mmap: true时会挂起hang请在模型配置中关闭 mmapmmap: false覆盖后端的自动检测当 LocalAI 自动选择的 GPU backend 不正确时可通过环境变量强制指定LOCALAI_FORCE_META_BACKEND_CAPABILITYnvidia local-ai run # 可选值default, nvidia, amd, intel该环境变量在仓库中被用于后端选择与变体解析如core/gallery/backends_test.go中即用LOCALAI_FORCE_META_BACKEND_CAPABILITYnvidia模拟 NVIDIA 环境在 gallery 安装模型时决定拉取哪个 GPU 变体。更完整的 GPU 后端选择说明见 docs/content/features/GPU-acceleration.md。2. 内存耗尽OOM症状模型加载失败或进程被操作系统直接 kill。解决方案按成本从低到高改用更小的量化版本Q4_K_S 或 Q2_K 显著比 Q8_0 / Q6_K 省内存调低上下文长度减小模型 YAML 中的context_size开启低显存模式在模型配置中加入low_vram: true限制同时驻留的模型数量local-ai run --max-active-backends1开启空闲 watchdog自动卸载空闲超时的模型local-ai run --enable-watchdog-idle --watchdog-idle-timeout10m手动卸载指定模型curl -X POST http://localhost:8080/backend/shutdown \ -H Content-Type: application/json \ -d {model: model-name}其中/backend/shutdown及等价的/v1/backend/shutdown是真实存在的管理端点在 core/http/routes/localai.go 中注册并挂载了 admin 中间件它调用 backend monitor 服务卸载对应模型与/backend/load互为逆操作。3. 模型常驻内存、切换时显存被耗尽默认情况下模型首次使用后会一直驻留内存/显存。频繁切换大模型时容易撑爆显存可通过LRU 淘汰与watchdog 自动卸载两条途径治理。LRU 淘汰限制常驻数量淘汰最久未用# 最多保持 2 个模型加载超出后淘汰最久未使用的 local-ai run --max-active-backends2底层逻辑在 core/config/application_config.go 的GetEffectiveMaxActiveBackends()中统一收敛MaxActiveBackends 0时以其为准否则回退到已弃用的SingleBackend等价于--max-active-backends1。加载调度与 LRU 检查分别发生在 core/application/startup.go 与 core/application/watchdog.go。watchdog 自动卸载空闲/繁忙超时双通道local-ai run \ --enable-watchdog-idle --watchdog-idle-timeout15m \ --enable-watchdog-busy --watchdog-busy-timeout5m这些开关均可通过环境变量设置LOCALAI_WATCHDOG_IDLEtrue、LOCALAI_WATCHDOG_IDLE_TIMEOUT15m也可在 Web UI 的 Settings → Watchdog Settings 中配置。相关 flag、默认值与运行期可覆盖项总结如下均来自 core/cli/run.go 与 core/config/runtime_settings.go命令行 flag环境变量默认值含义--max-active-backendsNLOCALAI_MAX_ACTIVE_BACKENDS0不限同时驻留的最大后端数超出后按 LRU 淘汰1即单后端模式--single-active-backendLOCALAI_SINGLE_ACTIVE_BACKENDfalse已弃用等价于--max-active-backends1--enable-watchdog-idleLOCALAI_WATCHDOG_IDLEfalse开启空闲超时自动卸载--watchdog-idle-timeoutLOCALAI_WATCHDOG_IDLE_TIMEOUT15m空闲超过该阈值即停止后端--enable-watchdog-busyLOCALAI_WATCHDOG_BUSYfalse开启繁忙超时保护防止请求卡死占用后端--watchdog-busy-timeoutLOCALAI_WATCHDOG_BUSY_TIMEOUT5m单请求占用后端超过该阈值即停止--watchdog-interval—500mswatchdog 轮询检查间隔watchdog 的超时值属于运行期可调设置可在不改动启动参数的情况下通过运行期设置持久化接口动态调整见 core/config/runtime_settings_registry.go。对显存预算、淘汰策略与多模型共存的完整治理思路参见 VRAM 内存管理指南。五、API 连接问题1. Connection Refused连接被拒绝症状curl: (7) Failed to connect to localhost port 8080: Connection refused诊断步骤确认 LocalAI 进程/容器确实在运行# 直接安装 ps aux | grep local-ai # Docker docker ps | grep local-ai检查监听地址与端口默认:8080# 覆盖默认监听地址 local-ai run --address0.0.0.0:8080 # 或 LOCALAI_ADDRESS:8080 local-ai run排查端口冲突ss -tlnp | grep 8080安全提示若把监听地址设为公网地址且未配置任何认证LocalAI 会默认拒绝启动安全加固项LOCALAI_ALLOW_INSECURE_PUBLIC_BIND见 core/cli/run.go。因此生产环境请务必先配置 API Key 或接入认证后端再考虑对外暴露。2. 认证错误401 Unauthorized症状返回401 Unauthorized。当启用了 API Key 认证LOCALAI_API_KEY环境变量或--api-keys参数时所有请求都必须携带有效 Keycurl http://localhost:8080/v1/models \ -H Authorization: Bearer YOUR_API_KEY除标准Authorization: Bearer外Key 也可通过x-api-key或xi-api-key请求头传递。3. 请求错误400 / 422症状返回400 Bad Request或422 Unprocessable Entity。常见原因请求体 JSON 格式错误多/少括号、非法转义等缺少必填字段如model或messages参数值非法例如 rerank 请求中top_n为负数。开启 debug 日志可看到完整请求/响应内容便于定位具体字段DEBUGtrue local-ai run错误码的完整清单与含义见 API 错误参考。六、性能问题1. 推理缓慢诊断步骤开启 debug 模式观察推理耗时分布DEBUGtrue local-ai run使用流式请求测量首个 token 延迟TTFTcurl http://localhost:8080/v1/chat/completions \ -H Content-Type: application/json \ -d {model: my-model, messages: [{role: user, content: Hello}], stream: true}常见原因与对策模型放在 HDD 上尽量把模型迁移到 SSD。若只能使用 HDD可关闭内存映射让模型整体加载进 RAM 以减少随机读# 模型配置中 mmap: false注意权衡上文提到 Intel SYCL 场景需要mmap: false此处 HDD 场景同理反过来若模型放 SSD 且内存紧张保留mmap: true让系统按需换页通常更省内存。线程过度订阅threads应匹配物理核数而非逻辑超线程核数threads: 4 # 以物理核心数为准默认采样策略开销LocalAI 默认启用 mirostat 采样输出质量更好但更慢。基准测试可临时关闭# 模型配置中 mirostat: 0未启用 GPU 卸载确认模型配置中设置了gpu_layers把尽可能多的层卸载到 GPUgpu_layers: 99 # 卸载全部层到 GPU上下文过长越大的context_size占用越多内存并拖慢推理。请使用刚好满足需求的最小上下文。2. 内存占用过高优先使用量化模型Q4_K_M 在质量与体积之间较为均衡减小context_size在模型配置中开启low_vram: true若开启了mmlock内存锁定请关闭它避免模型长期锁死在物理内存中设置--max-active-backends1让内存中只保留一个模型。七、Docker 特有问题的排查1. 容器无法启动诊断步骤# 查看容器日志定位启动阶段的具体报错 docker logs local-ai # 检查 8080 端口是否已被占用 ss -tlnp | grep 8080 # 确认镜像确实存在 docker images | grep localai若端口被占用调整宿主机端口映射或在容器内更换监听端口即可。Docker 部署的完整参数与镜像 tag 说明见 docs/content/getting-started/docker.md。2. 容器内看不到 GPUNVIDIA# 先确保宿主机已安装 nvidia-container-toolkit再运行 docker run --gpus all ...AMDdocker run --device/dev/kfd --device/dev/dri --group-addvideo ...Inteldocker run --device /dev/dri ...注意镜像 tag 必须与 GPU 能力匹配CUDA 镜像 tag 含cuda11/cuda12/cuda13Intel 含gpu-intel详见上文的 GPU 检测一节。3. 健康检查失败在 Docker Compose 中为服务添加健康检查直接探测/readyzservices: local-ai: image: localai/localai:latest healthcheck: test: [CMD, curl, -f, http://localhost:8080/readyz] interval: 30s timeout: 10s retries: 34. 升级后模型或设置丢失升级容器会重建容器容器本地文件随之丢失。必须把 LocalAI 所有有状态的目录以卷形式挂载出来services: local-ai: volumes: - ./models:/models - ./backends:/backends - ./configuration:/configuration - ./data:/data左侧路径可以是任意宿主机持久目录或命名卷named volume右侧容器内路径必须与上例完全一致。Docker、Podman 与 UnRAID 场景下的持久化存储指引见容器化部署与持久化存储。八、网络与 P2P 分布式问题1. P2P Worker 节点无法被发现症状已配置分布式推理但 worker 节点之间互相发现不了。关键前置条件Docker 场景必须使用--net host即network_mode: hostP2P 需要直连主机网络所有节点必须共享同一个 P2P Token。调试 P2P 连通性LOCALAI_P2P_LOGLEVELdebug \ LOCALAI_P2P_LIB_LOGLEVELdebug \ LOCALAI_P2P_ENABLE_LIMITStrue \ LOCALAI_P2P_TOKENTOKEN \ local-ai run相关环境变量的定义可在 core/cli/run.go 的 P2P 分组中找到例如LOCALAI_P2P_TOKEN、LOCALAI_P2P_NETWORK_ID等。如果 DHT 导致问题可关闭 DHT改用本地 mDNS 发现LOCALAI_P2P_DISABLE_DHTtrue local-ai run2. P2P / 分布式推理的已知限制当前分布式推理同时只支持单个模型Worker 必须在推理开始前被发现——推理中途无法动态追加 workerWorker 模式目前仅支持 llama-cpp 兼容模型。完整的分布式配置token 生成、多节点注册、NATS/联邦等见分布式推理指南面向 worker/federated 模式的 P2P 实现可进一步阅读 core/p2p 下的源码。九、问题仍未解决时的求助路径如果上文没有覆盖你的场景建议按以下顺序推进检索既有问题在项目 GitHub Issues 中用关键词如 backend 名、模型名、报错片段搜索是否有相似案例及已确认的 workaround开启 debug 日志并复现以DEBUGtrue或--log-leveldebug启动完整复现一次问题保留整段日志提交新 Issue报告时请附上操作系统、硬件CPU/GPU、LocalAI 版本local-ai --version、所用模型与模型 YAML、完整错误日志、最小复现步骤。可一并提供local-ai backends list与curl /readyz的结果帮助维护者快速定位社区求助可加入 LocalAI 的 Discord 社区在相关频道附带同样完整的环境信息提问。十、预防性建议把排障经验固化成启动配置结合上文多个问题的根因可以把最有价值的防护手段固化到日常启动命令中从源头降低故障概率# 生产/长期运行实例的推荐启动参数组合 local-ai run \ --address127.0.0.1:8080 \ # 明确监听地址避免端口与暴露歧义 --max-active-backends2 \ # 限制模型驻留数量防止显存/内存被多模型耗尽 --enable-watchdog-idle \ # 空闲模型自动卸载 --watchdog-idle-timeout15m \ --enable-watchdog-busy \ # 卡死的繁忙请求兜底 --watchdog-busy-timeout5m \ --log-levelinfo # 日常 info排查时切 debug对应模型侧也请养成一个模型一个 YAML、关键参数显式声明的习惯backend、parameters.model相对路径、context_size、threads物理核数、gpu_layersGPU 可用时、low_vram显存吃紧时都显式写出能显著减少配置错误导致推理异常这类隐性故障。LocalAI 的模型配置与后端参数体系均可参照 docs/content/getting-started/models.md 与 docs/content/features/backends.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 故障排查实战指南：从安装、模型加载到 GPU 内存与 API 连接问题全解析
LocalAI 故障排查实战指南从安装、模型加载到 GPU 内存与 API 连接问题全解析【免费下载链接】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 官方故障排查文档docs/content/getting-started/troubleshooting.md为核心系统覆盖部署与日常使用中最高频的几类问题安装启动失败、模型无法加载或配置错误、GPU 未被识别与内存耗尽、API 连接与鉴权异常、推理性能不达标、Docker 部署与 P2P 分布式网络的疑难杂症。对每类问题文中均给出症状 → 诊断步骤 → 解决方案的完整链路并结合仓库源码说明底层机制如 LRU 后端淘汰、watchdog 自动卸载、后端能力覆盖等读完即可对照自身环境逐条排障。一、快速诊断先收集环境信息再谈修复在深入具体问题之前先用一组命令确认 LocalAI 当前的健康状态、已加载模型与版本信息。这些命令对应仓库中真实存在的接口与命令行参数# 1. 检查 LocalAI 是否已启动且就绪 curl http://localhost:8080/readyz # 2. 列出已加载模型 curl http://localhost:8080/v1/models # 3. 查看 LocalAI 版本 local-ai --version # 4. 开启 debug 日志以获得详细输出两种方式等价 DEBUGtrue local-ai run # 或 local-ai run --log-leveldebug几点机制说明/readyz是 LocalAI 的就绪探针端点对应后端core/application/application.go中的就绪状态追踪逻辑并在core/http/auth/public_routes.go中被声明为免认证的公开 GET 路由因此在配置了 API Key 的环境中也可直接探测聊天等子命令在连接服务端前也会轮询该端点直到返回 200见core/cli/chat/server.go。/v1/models返回当前实例上所有可用模型的 OpenAI 兼容列表可用于比对请求中的model名称是否与实际一致。DEBUGtrue等价于把日志级别提到 debug适合后续所有需要观察请求体/响应体/后端加载细节的排障场景。Docker 部署环境请使用容器视角收集信息# 查看容器日志 docker logs local-ai # 检查容器状态是否频繁重启 docker ps -a | grep local-ai # 测试 NVIDIA GPU 是否透传进容器若使用 GPU docker run --rm --gpus all nvidia/cuda:12.8.0-base-ubuntu24.04 nvidia-smi二、安装类问题1. Linux 二进制无法执行症状提示Permission denied或cannot execute binary file错误。解决先给二进制添加执行权限再运行chmod x local-ai-* ./local-ai-Linux-x86_64 run如果出现cannot execute binary file: Exec format error说明下载了错误架构的二进制。用uname -m确认 CPU 架构后再选择对应安装包uname -m # x86_64 → 下载 x86_64 二进制 # aarch64 → 下载 arm64 二进制不同平台的完整安装步骤可参考 docs/content/getting-started/linux.md、docs/content/getting-started/macos.md 与 docs/content/getting-started/install.md。2. macOS应用被隔离Quarantine症状因 DMG 未经过 Apple 签名macOS Gatekeeper 阻止 LocalAI 运行。解决官方 Issue #6268 中提供了绕过隔离quarantine的操作说明该问题当前在 Issue #6244 中持续跟踪。操作思路是移除下载文件上的隔离扩展属性后再启动即以xattr方式解除隔离执行前请确保文件来源可信并留意 Gatekeeper 的策略变化。三、模型加载问题1. Model Not Found模型不存在 / 404症状API 返回404或model not found错误。诊断步骤确认模型文件确实存在于模型目录中ls -la /path/to/models/核对 LocalAI 实际使用的模型目录路径并用 debug 日志观察它扫描到了什么local-ai run --models-path /path/to/models --log-leveldebug确认请求中的模型名与已注册模型完全一致包括大小写与后缀# 列出可用模型 curl http://localhost:8080/v1/models | jq .data[].id模型的放置、命名与注册方式可进一步参考 docs/content/getting-started/models.md。2. 模型存在但加载失败Backend Error症状模型文件能被找到但加载时日志出现 backend 级错误。常见原因与对策backend 选择错误模型 YAML 中的backend必须与模型格式匹配——GGUF 模型用llama-cppDiffusers 扩散模型用diffusers语音、图像、视频类模型各自对应专用 backend。可对照兼容性对照表核实。backend 未安装检查当前已安装的 backend并补装缺失项local-ai backends list # 安装缺失的 backend local-ai backends install llama-cpp该组命令在core/cli/backends.go中实现支持list、install、uninstall等子命令backend 本质是按模型类型分发推理请求的独立运行时参见 docs/content/features/backends.md。模型文件损坏下载中断或磁盘错误可能产生残缺文件请重新下载模型。模型格式过时llama.cpp 系列模型应使用 GGUF 格式旧 GGML 格式已被弃用。补充说明为防止某个模型因崩溃而反复加载、每次都重启 backendLocalAI 内置了加载失败冷却机制——默认单次失败后 10 秒内拒绝再次加载同一模型并返回503 Retry-After连续失败会指数退避至最长 5 分钟可用--model-load-failure-cooldown调节或置0关闭见 core/cli/run.go 中ModelLoadFailureCooldown的定义。如果日志中出现周期性 503请先定位模型为何反复加载失败而不是盲目等待重试。3. 模型配置问题加载成功但推理异常症状模型能加载但推理结果异常或运行时报错。核对模型 YAML 配置# 模型配置示例 name: my-model backend: llama-cpp parameters: model: my-model.gguf # 相对 models 目录的路径 context_size: 2048 threads: 4 # 应匹配物理 CPU 核数常见错误parameters.model必须是相对 models 目录的路径而不是绝对路径threads大于物理核数会造成线程争用thread contention推理反而变慢context_size超出可用内存会导致 OOM。仓库中真实的模型定义样例见 gallery/llama3.1-instruct.yaml它展示了完整字段结构backend: llama-cpp、mmap: true、context_size: 8192、f16: true、stopwords与 chat/function 模板等。可以看到context_size这类字段直接写在外层backend决定由哪个推理后端承载而mmap等加载选项也以 YAML 字段形式暴露排障时请对照这些字段逐一检查自己的配置文件。更多字段语义见 docs/content/advanced/model-configuration.md。四、GPU 与内存问题1. GPU 未被检测到NVIDIACUDA# 验证 CUDA 是否可用 nvidia-smi # Docker 场景验证 GPU 是否成功透传 docker run --rm --gpus all nvidia/cuda:12.8.0-base-ubuntu24.04 nvidia-smi正常工作情况下LocalAI 日志应出现ggml_init_cublas: found X CUDA devices。请务必使用启用了 CUDA 的容器镜像镜像 tag 含cuda11、cuda12或cuda13纯 CPU 镜像无法使用 NVIDIA GPU。AMDROCm# 验证 ROCm 安装 rocminfo # Docker 需要透传设备 docker run --device/dev/kfd --device/dev/dri --group-addvideo ...如果所用 GPU 不在默认目标列表中请到项目 Issue 区反馈。目前已支持的 ROCm 目标包括gfx908、gfx90a、gfx942、gfx950、gfx1030、gfx1100、gfx1101、gfx1102、gfx1200、gfx1201。IntelSYCL# Docker 需要透传 dri 设备 docker run --device /dev/dri ...请使用镜像 tag 含gpu-intel的容器镜像。已知问题SYCL 后端在mmap: true时会挂起hang请在模型配置中关闭 mmapmmap: false覆盖后端的自动检测当 LocalAI 自动选择的 GPU backend 不正确时可通过环境变量强制指定LOCALAI_FORCE_META_BACKEND_CAPABILITYnvidia local-ai run # 可选值default, nvidia, amd, intel该环境变量在仓库中被用于后端选择与变体解析如core/gallery/backends_test.go中即用LOCALAI_FORCE_META_BACKEND_CAPABILITYnvidia模拟 NVIDIA 环境在 gallery 安装模型时决定拉取哪个 GPU 变体。更完整的 GPU 后端选择说明见 docs/content/features/GPU-acceleration.md。2. 内存耗尽OOM症状模型加载失败或进程被操作系统直接 kill。解决方案按成本从低到高改用更小的量化版本Q4_K_S 或 Q2_K 显著比 Q8_0 / Q6_K 省内存调低上下文长度减小模型 YAML 中的context_size开启低显存模式在模型配置中加入low_vram: true限制同时驻留的模型数量local-ai run --max-active-backends1开启空闲 watchdog自动卸载空闲超时的模型local-ai run --enable-watchdog-idle --watchdog-idle-timeout10m手动卸载指定模型curl -X POST http://localhost:8080/backend/shutdown \ -H Content-Type: application/json \ -d {model: model-name}其中/backend/shutdown及等价的/v1/backend/shutdown是真实存在的管理端点在 core/http/routes/localai.go 中注册并挂载了 admin 中间件它调用 backend monitor 服务卸载对应模型与/backend/load互为逆操作。3. 模型常驻内存、切换时显存被耗尽默认情况下模型首次使用后会一直驻留内存/显存。频繁切换大模型时容易撑爆显存可通过LRU 淘汰与watchdog 自动卸载两条途径治理。LRU 淘汰限制常驻数量淘汰最久未用# 最多保持 2 个模型加载超出后淘汰最久未使用的 local-ai run --max-active-backends2底层逻辑在 core/config/application_config.go 的GetEffectiveMaxActiveBackends()中统一收敛MaxActiveBackends 0时以其为准否则回退到已弃用的SingleBackend等价于--max-active-backends1。加载调度与 LRU 检查分别发生在 core/application/startup.go 与 core/application/watchdog.go。watchdog 自动卸载空闲/繁忙超时双通道local-ai run \ --enable-watchdog-idle --watchdog-idle-timeout15m \ --enable-watchdog-busy --watchdog-busy-timeout5m这些开关均可通过环境变量设置LOCALAI_WATCHDOG_IDLEtrue、LOCALAI_WATCHDOG_IDLE_TIMEOUT15m也可在 Web UI 的 Settings → Watchdog Settings 中配置。相关 flag、默认值与运行期可覆盖项总结如下均来自 core/cli/run.go 与 core/config/runtime_settings.go命令行 flag环境变量默认值含义--max-active-backendsNLOCALAI_MAX_ACTIVE_BACKENDS0不限同时驻留的最大后端数超出后按 LRU 淘汰1即单后端模式--single-active-backendLOCALAI_SINGLE_ACTIVE_BACKENDfalse已弃用等价于--max-active-backends1--enable-watchdog-idleLOCALAI_WATCHDOG_IDLEfalse开启空闲超时自动卸载--watchdog-idle-timeoutLOCALAI_WATCHDOG_IDLE_TIMEOUT15m空闲超过该阈值即停止后端--enable-watchdog-busyLOCALAI_WATCHDOG_BUSYfalse开启繁忙超时保护防止请求卡死占用后端--watchdog-busy-timeoutLOCALAI_WATCHDOG_BUSY_TIMEOUT5m单请求占用后端超过该阈值即停止--watchdog-interval—500mswatchdog 轮询检查间隔watchdog 的超时值属于运行期可调设置可在不改动启动参数的情况下通过运行期设置持久化接口动态调整见 core/config/runtime_settings_registry.go。对显存预算、淘汰策略与多模型共存的完整治理思路参见 VRAM 内存管理指南。五、API 连接问题1. Connection Refused连接被拒绝症状curl: (7) Failed to connect to localhost port 8080: Connection refused诊断步骤确认 LocalAI 进程/容器确实在运行# 直接安装 ps aux | grep local-ai # Docker docker ps | grep local-ai检查监听地址与端口默认:8080# 覆盖默认监听地址 local-ai run --address0.0.0.0:8080 # 或 LOCALAI_ADDRESS:8080 local-ai run排查端口冲突ss -tlnp | grep 8080安全提示若把监听地址设为公网地址且未配置任何认证LocalAI 会默认拒绝启动安全加固项LOCALAI_ALLOW_INSECURE_PUBLIC_BIND见 core/cli/run.go。因此生产环境请务必先配置 API Key 或接入认证后端再考虑对外暴露。2. 认证错误401 Unauthorized症状返回401 Unauthorized。当启用了 API Key 认证LOCALAI_API_KEY环境变量或--api-keys参数时所有请求都必须携带有效 Keycurl http://localhost:8080/v1/models \ -H Authorization: Bearer YOUR_API_KEY除标准Authorization: Bearer外Key 也可通过x-api-key或xi-api-key请求头传递。3. 请求错误400 / 422症状返回400 Bad Request或422 Unprocessable Entity。常见原因请求体 JSON 格式错误多/少括号、非法转义等缺少必填字段如model或messages参数值非法例如 rerank 请求中top_n为负数。开启 debug 日志可看到完整请求/响应内容便于定位具体字段DEBUGtrue local-ai run错误码的完整清单与含义见 API 错误参考。六、性能问题1. 推理缓慢诊断步骤开启 debug 模式观察推理耗时分布DEBUGtrue local-ai run使用流式请求测量首个 token 延迟TTFTcurl http://localhost:8080/v1/chat/completions \ -H Content-Type: application/json \ -d {model: my-model, messages: [{role: user, content: Hello}], stream: true}常见原因与对策模型放在 HDD 上尽量把模型迁移到 SSD。若只能使用 HDD可关闭内存映射让模型整体加载进 RAM 以减少随机读# 模型配置中 mmap: false注意权衡上文提到 Intel SYCL 场景需要mmap: false此处 HDD 场景同理反过来若模型放 SSD 且内存紧张保留mmap: true让系统按需换页通常更省内存。线程过度订阅threads应匹配物理核数而非逻辑超线程核数threads: 4 # 以物理核心数为准默认采样策略开销LocalAI 默认启用 mirostat 采样输出质量更好但更慢。基准测试可临时关闭# 模型配置中 mirostat: 0未启用 GPU 卸载确认模型配置中设置了gpu_layers把尽可能多的层卸载到 GPUgpu_layers: 99 # 卸载全部层到 GPU上下文过长越大的context_size占用越多内存并拖慢推理。请使用刚好满足需求的最小上下文。2. 内存占用过高优先使用量化模型Q4_K_M 在质量与体积之间较为均衡减小context_size在模型配置中开启low_vram: true若开启了mmlock内存锁定请关闭它避免模型长期锁死在物理内存中设置--max-active-backends1让内存中只保留一个模型。七、Docker 特有问题的排查1. 容器无法启动诊断步骤# 查看容器日志定位启动阶段的具体报错 docker logs local-ai # 检查 8080 端口是否已被占用 ss -tlnp | grep 8080 # 确认镜像确实存在 docker images | grep localai若端口被占用调整宿主机端口映射或在容器内更换监听端口即可。Docker 部署的完整参数与镜像 tag 说明见 docs/content/getting-started/docker.md。2. 容器内看不到 GPUNVIDIA# 先确保宿主机已安装 nvidia-container-toolkit再运行 docker run --gpus all ...AMDdocker run --device/dev/kfd --device/dev/dri --group-addvideo ...Inteldocker run --device /dev/dri ...注意镜像 tag 必须与 GPU 能力匹配CUDA 镜像 tag 含cuda11/cuda12/cuda13Intel 含gpu-intel详见上文的 GPU 检测一节。3. 健康检查失败在 Docker Compose 中为服务添加健康检查直接探测/readyzservices: local-ai: image: localai/localai:latest healthcheck: test: [CMD, curl, -f, http://localhost:8080/readyz] interval: 30s timeout: 10s retries: 34. 升级后模型或设置丢失升级容器会重建容器容器本地文件随之丢失。必须把 LocalAI 所有有状态的目录以卷形式挂载出来services: local-ai: volumes: - ./models:/models - ./backends:/backends - ./configuration:/configuration - ./data:/data左侧路径可以是任意宿主机持久目录或命名卷named volume右侧容器内路径必须与上例完全一致。Docker、Podman 与 UnRAID 场景下的持久化存储指引见容器化部署与持久化存储。八、网络与 P2P 分布式问题1. P2P Worker 节点无法被发现症状已配置分布式推理但 worker 节点之间互相发现不了。关键前置条件Docker 场景必须使用--net host即network_mode: hostP2P 需要直连主机网络所有节点必须共享同一个 P2P Token。调试 P2P 连通性LOCALAI_P2P_LOGLEVELdebug \ LOCALAI_P2P_LIB_LOGLEVELdebug \ LOCALAI_P2P_ENABLE_LIMITStrue \ LOCALAI_P2P_TOKENTOKEN \ local-ai run相关环境变量的定义可在 core/cli/run.go 的 P2P 分组中找到例如LOCALAI_P2P_TOKEN、LOCALAI_P2P_NETWORK_ID等。如果 DHT 导致问题可关闭 DHT改用本地 mDNS 发现LOCALAI_P2P_DISABLE_DHTtrue local-ai run2. P2P / 分布式推理的已知限制当前分布式推理同时只支持单个模型Worker 必须在推理开始前被发现——推理中途无法动态追加 workerWorker 模式目前仅支持 llama-cpp 兼容模型。完整的分布式配置token 生成、多节点注册、NATS/联邦等见分布式推理指南面向 worker/federated 模式的 P2P 实现可进一步阅读 core/p2p 下的源码。九、问题仍未解决时的求助路径如果上文没有覆盖你的场景建议按以下顺序推进检索既有问题在项目 GitHub Issues 中用关键词如 backend 名、模型名、报错片段搜索是否有相似案例及已确认的 workaround开启 debug 日志并复现以DEBUGtrue或--log-leveldebug启动完整复现一次问题保留整段日志提交新 Issue报告时请附上操作系统、硬件CPU/GPU、LocalAI 版本local-ai --version、所用模型与模型 YAML、完整错误日志、最小复现步骤。可一并提供local-ai backends list与curl /readyz的结果帮助维护者快速定位社区求助可加入 LocalAI 的 Discord 社区在相关频道附带同样完整的环境信息提问。十、预防性建议把排障经验固化成启动配置结合上文多个问题的根因可以把最有价值的防护手段固化到日常启动命令中从源头降低故障概率# 生产/长期运行实例的推荐启动参数组合 local-ai run \ --address127.0.0.1:8080 \ # 明确监听地址避免端口与暴露歧义 --max-active-backends2 \ # 限制模型驻留数量防止显存/内存被多模型耗尽 --enable-watchdog-idle \ # 空闲模型自动卸载 --watchdog-idle-timeout15m \ --enable-watchdog-busy \ # 卡死的繁忙请求兜底 --watchdog-busy-timeout5m \ --log-levelinfo # 日常 info排查时切 debug对应模型侧也请养成一个模型一个 YAML、关键参数显式声明的习惯backend、parameters.model相对路径、context_size、threads物理核数、gpu_layersGPU 可用时、low_vram显存吃紧时都显式写出能显著减少配置错误导致推理异常这类隐性故障。LocalAI 的模型配置与后端参数体系均可参照 docs/content/getting-started/models.md 与 docs/content/features/backends.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），仅供参考