常见问题排查

通用排查顺序

建议按以下顺序定位问题：

1. 检查 Gateway 健康状态：curl http://127.0.0.1:9000/health
2. 查看 Gateway 控制台日志
3. 查看后端引擎日志
4. 确认模型文件存在且格式正确

OmniStudio 无法启动

常见原因：

• Python 版本低于 3.8
• Gateway 端口被占用，默认常见为 9000
• llama-server 缺失或路径配置错误

模型无法下载

常见原因与处理方式：

• 网络连接问题：模型下载依赖 HuggingFace 等外部平台
• 磁盘空间不足：需要确认模型目录所在分区可用空间
• 下载中断：可重试，系统支持断点续传
• 模型源不可用：源站可能临时维护

模型无法加载

常见原因：

• 模型文件不在模型目录中
• 模型文件损坏或不完整
• GGUF 格式与当前 llama.cpp 版本不兼容
• 内存不足
• 后端启动超时，可尝试调大 --startup-timeout

响应很慢

• 模型规模可能超出硬件承载能力
• 未启用 GPU 卸载
• 上下文长度过长
• 其他程序占用了大量 CPU、内存或显存

运行时或引擎版本问题

• 检查 llama-server 是否与当前系统架构匹配
• Windows 平台建议使用 Visual Studio 2022 Build Tools
• 确认实际 launcher 路径与 runtime 目录一致

GPU 显存错误

GPU 相关问题通常表现为模型加载失败或推理过程中崩溃，常见原因包括：

• n_gpu_layers 设置过大，显存不足
• CUDA 或驱动版本不匹配
• 其他程序占用显存
• 当前 GPU 型号并不适合所选后端

建议的排查动作

1. 先切回纯 CPU 模式，确认模型本身能正常加载
2. 逐步提高 n_gpu_layers，找到可稳定运行的区间
3. 根据日志判断是模型格式问题、资源问题还是后端兼容问题