Ollama 常见问题
本章节把排障知识收敛成一本随查随用的手册：从日志定位开始，按症状分流，覆盖显存不足、下载失败、端口冲突、GPU 异常、过载与升级兼容六大类问题。
万能第一步：先看日志
Ollama 的报错提示往往很简短，真正的病因几乎都写在日志里。
| 环境 | 查看命令 / 位置 |
|---|---|
| macOS | cat ~/.ollama/logs/server.log |
| Linux（systemd） | journalctl -u ollama --no-pager --follow --pager-end |
| Windows | %LOCALAPPDATA%\Ollama\server.log |
| Docker | docker logs <容器名> |
| 手动 serve | 日志直接打印在当前终端 |
默认日志不含细节时，开启调试模式重启服务，能看到 GPU 发现、显存估算等关键过程：
# 调试模式启动
OLLAMA_DEBUG=1 ollama serve遇到异常时，按下面的导航图先分流，再跳到对应小节：
显存 / 内存不足（OOM）
这是最常见的运行期问题，典型表现是生成到一半进程消失、系统卡死，或日志出现内存分配失败。
| 现象 | 原因 | 对策 |
|---|---|---|
| 加载大模型时进程被杀 | 物理内存不足 | 换更小规格标签；或用 create 量化压体积 |
| 生成中途崩溃 | 上下文累积导致 KV 缓存膨胀 | 调低 num_ctx；开启 Flash Attention 与 KV 缓存量化 |
| 多请求时集体失败 | NUM_PARALLEL 过大，显存被成倍占用 | 调回 1，逐步加回并观察 ollama ps |
| 模型能跑但被切分到 CPU | 显存略小于需求 | 清理后台显存占用；降一级参数规格 |
诊断命令三件套：ollama ps 看模型占用与切分比例，nvidia-smi（或 rocm-smi）看显卡实时显存，free -h 看系统内存。
模型下载失败与中断续传
下载问题几乎都出在网络路径上，好消息是 Ollama 支持按层断点续传，重试成本极低。
| 现象 | 原因 | 对策 |
|---|---|---|
| 下载反复中断 | 网络到源站不稳定 | 重跑同一命令续传；必要时配置 HTTPS_PROXY |
| 配置代理后依然失败 | 误设了 HTTP_PROXY | 只保留 HTTPS_PROXY，删除 HTTP_PROXY |
| 代理证书报错 | 自签名证书未被信任 | 把 CA 证书安装为系统证书 |
| 提示磁盘空间不足 | 目标分区容量不够 | 清理空间，或用 OLLAMA_MODELS 迁移存储路径 |
端口冲突与连接被拒
客户端报"连接被拒绝"，本质是 11434 端口上没有服务在应答。
| 现象 | 原因 | 对策 |
|---|---|---|
| 本机 curl 连接被拒 | Ollama 服务没有启动 | macOS / Windows 打开应用；Linux 执行 sudo systemctl start ollama |
| 日志报端口被占用 | 11434 被其他程序抢占 | 停掉占用进程，或换端口启动：OLLAMA_HOST=127.0.0.1:11435 |
| 远程机器连不上 | 服务只监听了回环地址 | 服务器端设置 OLLAMA_HOST=0.0.0.0 并放行防火墙 |
| Linux 手动安装后启动即退 | /tmp 挂载了 noexec，推理库无法加载 | 设置 OLLAMA_TMPDIR 指向可执行目录 |
GPU 未被使用 / 发现失败
症状是 ollama ps 显示 100% CPU，或日志出现 GPU 发现失败。NVIDIA 与 AMD 的排查路径不同。
NVIDIA 专项
先看驱动与直通环境，再按日志错误码对症处理：
| 检查项 | 方法 |
|---|---|
| 驱动版本 | nvidia-smi 能正常输出；升级到最新驱动 |
| 容器直通 | docker run --gpus all ubuntu nvidia-smi 不通则是 Container Toolkit 问题 |
| 驱动模块异常 | sudo rmmod nvidia_uvm && sudo modprobe nvidia_uvm 重载后重试 |
| 休眠恢复后失效 | Linux 睡眠唤醒后需重载 nvidia_uvm 模块 |
| Docker 运行久了掉 GPU | /etc/docker/daemon.json 加入 native.cgroupdriver=cgroupfs 后重启 Docker |
日志里的 CUDA 错误码有速记价值：3 表示未初始化、46 表示设备不可用、100 表示没有设备、999 表示未知错误，多数指向驱动或直通配置。
AMD 专项
| 现象 | 原因 | 对策 |
|---|---|---|
| Linux 上完全检测不到 | 用户不在 video / render 组 | 把运行用户加入对应组后重启服务 |
| 日志出现发现超时（discovery timeout） | ROCm 驱动过旧（低于 v7） | 用 amdgpu-install 升级 ROCm v7 后重启 |
| 老卡不被支持 | 架构不在官方支持列表 | 尝试 HSA_OVERRIDE_GFX_VERSION 指定相近架构 |
| Windows 部分老卡无 ROCm | 驱动栈限制 | 使用默认 Vulkan 路径；异常时检查 GGML_VK_VISIBLE_DEVICES |
503 过载与响应慢的系统性排查
把前面章节的方法串成一条固定流程，六步之内定位绝大多数性能问题：
第一步，ollama ps 确认 PROCESSOR 是否 100% GPU，出现切分先回到显存优化。
第二步，看日志有没有排队、卸载、发现失败的记录。
第三步，收到 503 说明队列满了，检查并发请求量与 OLLAMA_MAX_QUEUE，评估是否扩容。
第四步，多用户共享场景核对 OLLAMA_NUM_PARALLEL 与显存的乘法关系。
第五步，核对 keep_alive 策略：频繁卸载重装会让首字延迟暴涨。
第六步，用 API 的 usage 字段计算 token/s，与历史基线对比量化每次调整的效果。
升级后的兼容性问题与回退
升级后行为异常时，三个动作解决大部分情况：
# 1. Linux 手动升级前先清理旧库，避免新旧混用
sudo rm -rf /usr/lib/ollama
# 2. 回退到指定版本
curl -fsSL https://ollama.com/install.sh | OLLAMA_VERSION=0.5.7 sh
# 3. AMD 显卡同步升级 ROCm v7 驱动后重启Windows 终端出现乱码方块是旧终端字体问题，与模型无关，换用 Windows Terminal 即可。
AI 思考中...