尧图网站建设 
LocalAI 故障排查装不上、起不来、调不通这份排查清单 10 分钟帮你定位问题【免费下载链接】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/LocalAILocalAI 装不上、启动无响应、API 调用报错是不是正卡在这里别急装不上、起不来确实容易让人焦头烂额。这份 LocalAI 故障排查指南按环境 → 启动 → 调用 → 进阶的顺序帮你自查多数问题 10 分钟内可定位。先定位快速自检表先跑一遍官方排障文档里的自检命令curl http://localhost:8080/readyz看服务是否就绪curl http://localhost:8080/v1/models看模型是否已加载。然后对照下表跳到对应小节你看到的现象最可能原因对应小节二进制下载后无法执行架构不匹配或缺执行权限二进制架构不匹配时如何选对版本curl: (7) ... Connection refused服务没起来或端口不对服务连不上时如何确认进程与端口日志报could not load model或grpc service not ready后端缺失、模型文件损坏或内存不足模型加载失败时如何看真实报错API 返回 401开了鉴权但请求没带 key请求返回 401 时如何带上 API key请求返回 400 / 422JSON 格式错或缺必填字段请求报 400 或 422 时如何修请求体GPU 没加速日志没有 CUDA 设备用了 CPU 镜像或没透传设备GPU 不生效时如何验证镜像与设备进程被杀、OOM模型加 KV 缓存超出内存内存不足被杀时如何降配多节点互不发现P2P token 不一致或网络模式不对P2P 节点发现失败时如何排查环境与安装二进制架构不匹配时如何选对版本现象下载后的二进制执行报cannot execute binary file: Exec format error。原因你下的版本和 CPU 架构对不上比如 ARM 机器下了 x86_64 包。修复确认本机架构uname -m按结果下载对应版本x86_64 下local-ai-Linux-x86_64aarch64 下 arm64 版本补上执行权限chmod x local-ai-Linux-x86_64再执行./local-ai-Linux-x86_64 run验证local-ai --version能正常打印版本号就算通过。macOS 用户若 DMG 被系统拦截参考排障文档中的隔离解除说明。装好二进制仍起不来的通常是服务端口层面的问题看下一节。启动与配置服务连不上时如何确认进程与端口现象curl: (7) Failed to connect to localhost port 8080: Connection refused。原因LocalAI 根本没在运行或者监听地址/端口和你请求的不一致默认是:8080。修复确认进程活着docker ps | grep local-aiDocker或ps aux | grep local-ai查端口占用ss -tlnp | grep 8080被占用就换端口启动local-ai run --address0.0.0.0:8081请求也改成 8081验证curl http://localhost:8080/readyz返回正常即修复。Docker 场景建议按排障文档给 compose 加上/readyz健康检查升级容器前先把/models、/backends、/configuration、/data挂载成持久目录否则升级后模型和配置会丢。服务起来了但调模型报错的往下走。模型加载失败时如何看真实报错现象日志出现could not load model: ...、could not load model - all backends returned error: ...或grpc service not readyAPI 侧往往只有一个笼统的 500。原因真正的原因写在冒号后面的后端消息里路径不对、GGUF 文件不完整、量化格式不支持、内存不够而 HTTP 响应体常常不含这些信息。修复开调试日志拿完整输出DEBUGtrue local-ai run对照运行时错误速查表匹配 LocalAI 侧前缀重点看错误上方几行后端自己的 stderr按表处理缺后端就local-ai backends install llama-cpp文件损坏就重新下载内存不够就换更小量化注意失败后默认有冷却HTTP 503 Retry-After重试前等够秒数或重启服务清除验证再次请求不再报 500/v1/models里能看到模型。若加载成功后还慢多半是配置问题看下一节。调用与参数请求返回 401 时如何带上 API key现象接口统一返回401 Unauthorized。原因你启用了鉴权LOCALAI_API_KEY或LOCALAI_AUTHtrue但请求没带凭证。修复在请求头里带 keycurl http://localhost:8080/v1/models -H Authorization: Bearer YOUR_API_KEYx-api-key头也可以。验证同一请求不再返回 401正常返回模型列表。带了 key 还报错的一般是请求体本身的问题。请求报 400 或 422 时如何修请求体现象返回400 Bad Request典型消息failed parsing request body或422 Unprocessable Entity。原因400 是 JSON 解析失败或缺必填字段如model、messages422 是参数值非法比如 rerank 接口的top_n小于 1top_n - should be greater than or equal to 1。修复对照 API 错误参考查你调用的端点要求补齐model等必填字段用stream: true的简单请求验证连通性curl http://localhost:8080/v1/chat/completions -H Content-Type: application/json -d {model:qwen3-4b,messages:[{role:user,content:Hello}],stream:true}验证流式响应开始吐 token 即修复。能调通但速度起不来的通常是性能配置问题。进阶能力GPU 与分布式GPU 不生效时如何验证镜像与设备现象期望 GPU 加速但日志里没有ggml_init_cublas: found X CUDA devices这类字样推理全在 CPU 上。原因用了 CPU 镜像或容器没把设备透传进去。NVIDIA 必须用带cuda12/cuda13的镜像并加--gpus all。修复宿主机先确认驱动nvidia-smi换对镜像启动docker run -ti --name local-ai -p 8080:8080 --gpus all localai/localai:latest-gpu-nvidia-cuda-12自动选错后端时手动指定LOCALAI_FORCE_META_BACKEND_CAPABILITYnvidia local-ai run可选 nvidia/amd/intel验证日志出现 CUDA 设备发现记录且后端日志报告已卸载的 GPU 层数。Intel 卡注意一个已知坑mmap: true会让 SYCL 卡死需在模型配置里设mmap: false详见GPU 加速文档。内存不足被杀时如何降配现象模型加载时进程被系统杀掉或后端日志报CUDA error: out of memory。原因模型权重加 KV 缓存超出了可用内存/显存。修复换更小量化Q4_K_S 比 Q8_0 省很多并调低模型 YAML 里的context_size限制同时加载的模型数local-ai run --max-active-backends1开空闲看门狗自动卸载local-ai run --enable-watchdog-idle --watchdog-idle-timeout10m验证反复加载同一模型不再被杀docker stats或系统内存不再逼近上限。内存问题排除后还发现不了节点的看 P2P 排查。P2P 节点发现失败时如何排查现象多台 LocalAI 组成集群但 WebUI 的 Swarm 页面看不到其他节点。原因所有节点必须共享同一个 P2P tokenDocker 里还用桥接网络的话mDNS 类发现会失败。修复Docker 改用 host 网络--net host各节点带上同一个 token 启动例如LOCALAI_P2P_TOKENTOKEN local-ai run --p2p开 P2P 调试日志定位LOCALAI_P2P_LOGLEVELdebug LOCALAI_P2P_LIB_LOGLEVELdebug local-ai runDHT 有问题时可退回本地 mDNS 发现LOCALAI_P2P_DISABLE_DHTtrue local-ai run验证Swarm 页面列出全部节点即成功。注意 P2P 目前仅支持单模型分布式且 worker 必须在推理开始前被发现分布式推理文档有完整说明。避坑清单装前先看uname -m架构选错一切白搭Docker 启动前把/models、/backends、/configuration、/data挂成持久目录升级不丢东西模型放 SSD实在用 HDD 就设mmap: false否则加载慢得难受threads按物理核心数设超线程数不算context_size取够用即可别默认拉满跑基准测试前在模型配置里设mirostat: 0默认采样质量更好但更慢调后端行为前先DEBUGtrue拿日志猜参数不如看后端自己的 stderrP2P 集群三要素同一 token、host 网络、推理前完成节点发现结语如果按上面的顺序走完还是不行带着DEBUGtrue下的完整日志、系统/硬件信息和复现步骤去提 issue或到官方 Discord 社区提问比盲目重试高效得多。常备入口官方排障文档、运行时错误速查表、模型配置示例库。【免费下载链接】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 故障排查：装不上、起不来、调不通？这份排查清单 10 分钟帮你定位问题
LocalAI 故障排查装不上、起不来、调不通这份排查清单 10 分钟帮你定位问题【免费下载链接】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/LocalAILocalAI 装不上、启动无响应、API 调用报错是不是正卡在这里别急装不上、起不来确实容易让人焦头烂额。这份 LocalAI 故障排查指南按环境 → 启动 → 调用 → 进阶的顺序帮你自查多数问题 10 分钟内可定位。先定位快速自检表先跑一遍官方排障文档里的自检命令curl http://localhost:8080/readyz看服务是否就绪curl http://localhost:8080/v1/models看模型是否已加载。然后对照下表跳到对应小节你看到的现象最可能原因对应小节二进制下载后无法执行架构不匹配或缺执行权限二进制架构不匹配时如何选对版本curl: (7) ... Connection refused服务没起来或端口不对服务连不上时如何确认进程与端口日志报could not load model或grpc service not ready后端缺失、模型文件损坏或内存不足模型加载失败时如何看真实报错API 返回 401开了鉴权但请求没带 key请求返回 401 时如何带上 API key请求返回 400 / 422JSON 格式错或缺必填字段请求报 400 或 422 时如何修请求体GPU 没加速日志没有 CUDA 设备用了 CPU 镜像或没透传设备GPU 不生效时如何验证镜像与设备进程被杀、OOM模型加 KV 缓存超出内存内存不足被杀时如何降配多节点互不发现P2P token 不一致或网络模式不对P2P 节点发现失败时如何排查环境与安装二进制架构不匹配时如何选对版本现象下载后的二进制执行报cannot execute binary file: Exec format error。原因你下的版本和 CPU 架构对不上比如 ARM 机器下了 x86_64 包。修复确认本机架构uname -m按结果下载对应版本x86_64 下local-ai-Linux-x86_64aarch64 下 arm64 版本补上执行权限chmod x local-ai-Linux-x86_64再执行./local-ai-Linux-x86_64 run验证local-ai --version能正常打印版本号就算通过。macOS 用户若 DMG 被系统拦截参考排障文档中的隔离解除说明。装好二进制仍起不来的通常是服务端口层面的问题看下一节。启动与配置服务连不上时如何确认进程与端口现象curl: (7) Failed to connect to localhost port 8080: Connection refused。原因LocalAI 根本没在运行或者监听地址/端口和你请求的不一致默认是:8080。修复确认进程活着docker ps | grep local-aiDocker或ps aux | grep local-ai查端口占用ss -tlnp | grep 8080被占用就换端口启动local-ai run --address0.0.0.0:8081请求也改成 8081验证curl http://localhost:8080/readyz返回正常即修复。Docker 场景建议按排障文档给 compose 加上/readyz健康检查升级容器前先把/models、/backends、/configuration、/data挂载成持久目录否则升级后模型和配置会丢。服务起来了但调模型报错的往下走。模型加载失败时如何看真实报错现象日志出现could not load model: ...、could not load model - all backends returned error: ...或grpc service not readyAPI 侧往往只有一个笼统的 500。原因真正的原因写在冒号后面的后端消息里路径不对、GGUF 文件不完整、量化格式不支持、内存不够而 HTTP 响应体常常不含这些信息。修复开调试日志拿完整输出DEBUGtrue local-ai run对照运行时错误速查表匹配 LocalAI 侧前缀重点看错误上方几行后端自己的 stderr按表处理缺后端就local-ai backends install llama-cpp文件损坏就重新下载内存不够就换更小量化注意失败后默认有冷却HTTP 503 Retry-After重试前等够秒数或重启服务清除验证再次请求不再报 500/v1/models里能看到模型。若加载成功后还慢多半是配置问题看下一节。调用与参数请求返回 401 时如何带上 API key现象接口统一返回401 Unauthorized。原因你启用了鉴权LOCALAI_API_KEY或LOCALAI_AUTHtrue但请求没带凭证。修复在请求头里带 keycurl http://localhost:8080/v1/models -H Authorization: Bearer YOUR_API_KEYx-api-key头也可以。验证同一请求不再返回 401正常返回模型列表。带了 key 还报错的一般是请求体本身的问题。请求报 400 或 422 时如何修请求体现象返回400 Bad Request典型消息failed parsing request body或422 Unprocessable Entity。原因400 是 JSON 解析失败或缺必填字段如model、messages422 是参数值非法比如 rerank 接口的top_n小于 1top_n - should be greater than or equal to 1。修复对照 API 错误参考查你调用的端点要求补齐model等必填字段用stream: true的简单请求验证连通性curl http://localhost:8080/v1/chat/completions -H Content-Type: application/json -d {model:qwen3-4b,messages:[{role:user,content:Hello}],stream:true}验证流式响应开始吐 token 即修复。能调通但速度起不来的通常是性能配置问题。进阶能力GPU 与分布式GPU 不生效时如何验证镜像与设备现象期望 GPU 加速但日志里没有ggml_init_cublas: found X CUDA devices这类字样推理全在 CPU 上。原因用了 CPU 镜像或容器没把设备透传进去。NVIDIA 必须用带cuda12/cuda13的镜像并加--gpus all。修复宿主机先确认驱动nvidia-smi换对镜像启动docker run -ti --name local-ai -p 8080:8080 --gpus all localai/localai:latest-gpu-nvidia-cuda-12自动选错后端时手动指定LOCALAI_FORCE_META_BACKEND_CAPABILITYnvidia local-ai run可选 nvidia/amd/intel验证日志出现 CUDA 设备发现记录且后端日志报告已卸载的 GPU 层数。Intel 卡注意一个已知坑mmap: true会让 SYCL 卡死需在模型配置里设mmap: false详见GPU 加速文档。内存不足被杀时如何降配现象模型加载时进程被系统杀掉或后端日志报CUDA error: out of memory。原因模型权重加 KV 缓存超出了可用内存/显存。修复换更小量化Q4_K_S 比 Q8_0 省很多并调低模型 YAML 里的context_size限制同时加载的模型数local-ai run --max-active-backends1开空闲看门狗自动卸载local-ai run --enable-watchdog-idle --watchdog-idle-timeout10m验证反复加载同一模型不再被杀docker stats或系统内存不再逼近上限。内存问题排除后还发现不了节点的看 P2P 排查。P2P 节点发现失败时如何排查现象多台 LocalAI 组成集群但 WebUI 的 Swarm 页面看不到其他节点。原因所有节点必须共享同一个 P2P tokenDocker 里还用桥接网络的话mDNS 类发现会失败。修复Docker 改用 host 网络--net host各节点带上同一个 token 启动例如LOCALAI_P2P_TOKENTOKEN local-ai run --p2p开 P2P 调试日志定位LOCALAI_P2P_LOGLEVELdebug LOCALAI_P2P_LIB_LOGLEVELdebug local-ai runDHT 有问题时可退回本地 mDNS 发现LOCALAI_P2P_DISABLE_DHTtrue local-ai run验证Swarm 页面列出全部节点即成功。注意 P2P 目前仅支持单模型分布式且 worker 必须在推理开始前被发现分布式推理文档有完整说明。避坑清单装前先看uname -m架构选错一切白搭Docker 启动前把/models、/backends、/configuration、/data挂成持久目录升级不丢东西模型放 SSD实在用 HDD 就设mmap: false否则加载慢得难受threads按物理核心数设超线程数不算context_size取够用即可别默认拉满跑基准测试前在模型配置里设mirostat: 0默认采样质量更好但更慢调后端行为前先DEBUGtrue拿日志猜参数不如看后端自己的 stderrP2P 集群三要素同一 token、host 网络、推理前完成节点发现结语如果按上面的顺序走完还是不行带着DEBUGtrue下的完整日志、系统/硬件信息和复现步骤去提 issue或到官方 Discord 社区提问比盲目重试高效得多。常备入口官方排障文档、运行时错误速查表、模型配置示例库。【免费下载链接】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），仅供参考