注册
教程中心 / LM Panel 教程

LM Panel 教程

LM Panel 本地大模型管理面板：安装配置、模型管理、多模型网关、Agent 接入与故障排查，从入门到进阶

12 · 故障排查

LM Panel 教程 更新于 2026-10-10 16:46:00

常见问题速查表。按现象找到处理办法；LMPanel 的启动失败诊断会直接给出中文原因，多数情况照做即可。

演示图占位
此处放：启动失败诊断弹窗示例
说明：显示中文原因与处理建议

速查表

现象 原因 处理
启动报「GPU 显存不足」 模型太大 / -ngl 过高 / 上下文过长 换更小量化版本，减小 -ngl 或 --ctx-size
报「模型文件无法打开」 GGUF 路径错误或文件损坏 核对启动命令预览中的路径；重新下载（自动校验 SHA-256）
提示「端口被占用」 其他程序占用端口 停止占用程序，或修改全局起始端口（startPort）
顶部「未检测到网络连接」 网络不可达 模型搜索/下载与更新不可用；本地已启动的模型不受影响
防火墙询问 / 网关无法工作 未放行本地监听 允许 llama-swap 监听本地端口
缺少 VC++ 运行库 系统组件缺失 安装 VC++ 运行库
启动按钮一直转圈 健康检查超时 检查模型路径与后端是否就绪；加大 healthCheckTimeout
启动后立刻退出 后端进程崩溃 查看运行日志定位具体原因
API 报模型不存在 model 字段与配置不一致 核对模型名称（含大小写）
网关转发超时 模型冷启动慢 先在模型页手动启动一次，或加大 proxyTimeout

诊断思路（按顺序）

  1. 看模型卡：失败时 LMPanel 会给出具体中文原因，先照提示做
  2. 看启动命令预览：核对 --model 路径、-ngl、--ctx-size 是否合理
  3. 看日志页：切到 error / warn 级，看后端输出的真实报错
  4. 看资源：状态栏 GPU 占用，判断是否显存瓶颈
  5. 看进程页：是否有残留孤儿进程占着显存，回收后重试

常见场景详解

显存不足（CUDA OOM）

优先级调整顺序：

  1. 换小量化文件（Q4_K_M → Q3_K / IQ 系列）
  2. 减小 -ngl（留一部分层在 CPU）
  3. 减小 --ctx-size（上下文是显存大头）
  4. 关闭不用的模型 / 回收孤儿进程

模型文件打不开

  • 确认路径中的文件名与实际一致（GGUF 文件可能被移动或改名）
  • 确认文件下载完整：重新在下载页下载一次，自动做 SHA-256 校验
  • 中文路径 / 空格路径可能引发问题，建议 models 下用简单文件名

网关不可用

  • 网关页状态是否正常，http://127.0.0.1:8199 能否访问
  • 防火墙是否放行 llama-swap
  • 网关与直连混用时注意端口冲突

需要更多帮助

TOP