大模型应用开发 / 系统课时
排查模型下载与启动失败
排查模型下载与启动失败
学习目标
完成本课后,你将能够:
- 根据故障发生在下载、校验、加载还是启动阶段进行分类
- 检查模型标签、网络代理、磁盘空间和目录权限
- 使用 CLI、API、服务状态和日志定位根本原因
- 完成修复后的下载、加载和请求三层验证
先判断失败发生在哪一阶段
模型相关故障分为四类:
| 阶段 | 典型表现 | 主要资源 |
|---|---|---|
| 模型解析 | 提示模型不存在或标签错误 | 模型名称、清单 |
| 下载 | 连接失败、进度停滞、摘要校验失败 | 网络、代理、磁盘 |
| 加载 | 内存不足、文件损坏、格式不支持 | 内存、显存、模型文件 |
| 推理启动 | 服务端口、运行后端或模板异常 | 服务、驱动、配置 |
先分类可以避免把网络故障误判为 GPU 故障。
确认服务基础状态
版本与服务:
ollama --version
curl --silent --output /dev/null --write-out "%{{http_code}}\n" http://localhost:11434/api/tags预期输出:
ollama version is <VERSION>
200如果 API 不可达,先修复 Ollama 服务,不要继续排查模型下载。
验证模型名称和标签
查看本地模型:
ollama list预期输出:
NAME ID SIZE MODIFIED
<MODEL> <MODEL_ID> <SIZE> <MODIFIED>下载时使用模型库中真实存在的完整标签:
ollama pull <MODEL:TAG>预期结果:
显示清单与分层下载进度,完成后提示成功。常见错误包括拼写错误、把网页标题当成模型标签、遗漏命名空间或使用不存在的量化变体。
检查网络、DNS 和代理
检查 DNS 与 HTTPS:
getent hosts ollama.com 2>/dev/null || nslookup ollama.com
curl -I https://ollama.com预期结果:
域名能解析,HTTPS 请求返回有效 HTTP 响应。状态码可能包含跳转。查看代理环境:
env | grep -iE '^(http|https|no)_proxy='预期输出:
显示当前代理变量;没有配置时无输出。Ollama 拉取模型使用 HTTPS。代理应允许大文件和长连接,并让 Ollama 服务进程继承。只在当前终端设置变量不会自动影响 systemd 或桌面后台应用。
检查磁盘与 inode
Linux:
df -h /
df -i /
du -sh /usr/share/ollama/.ollama 2>/dev/null || true预期输出:
显示磁盘容量、inode 使用和 Ollama 数据目录大小。Docker:
docker system df
docker volume inspect ollama预期输出:
显示 Docker 镜像、容器、卷占用和 ollama 卷信息。磁盘有容量但 inode 用尽,同样无法创建新文件。不要在下载过程中执行无差别清理。
检查模型目录权限
Linux 服务用户:
systemctl show ollama -p User -p Group
systemctl show ollama -p Environment预期输出示例:
User=ollama
Group=ollama
Environment=<ENVIRONMENT_VALUES>检查写权限:
MODEL_DIR=/usr/share/ollama/.ollama/models
sudo -u ollama test -w "$MODEL_DIR" && echo writable预期输出:
writable自定义目录时,将 MODEL_DIR 改为真实路径。权限修复应针对服务用户,不要使用 chmod 777 作为长期方案。
查看日志定位具体错误
Linux:
sudo journalctl -u ollama -n 200 --no-pagerDocker:
docker logs --tail 200 ollama预期结果:
输出最近日志,用于识别网络、摘要、路径、内存、驱动和端口错误。建议按错误时间搜索,而不是只看日志中任意出现过的旧错误。
处理中断与损坏
下载中断后,优先重新执行相同 ollama pull,让工具复用已完成分层并继续校验。不要直接编辑 blobs 文件或伪造清单。如果反复出现摘要或文件损坏:
- 停止 Ollama。
- 备份模型目录。
- 确认磁盘和文件系统健康。
- 仅删除明确对应的损坏数据。
- 重新启动并拉取。
- 验证
ollama show和实际推理。
无法确定文件映射时,删除整个模型目录会导致所有模型重新下载,应作为最后手段。
修复后的三层验证
第一层,模型存在:
ollama list
ollama show <MODEL:TAG>预期结果:
模型出现在列表中,show 能显示模型详情。第二层,模型加载:
ollama run <MODEL:TAG> "只回答:启动成功。"预期结果:
模型返回“启动成功”或语义等价文本,没有加载错误。第三层,运行状态:
ollama ps预期结果:
列表中出现目标模型,并显示处理器、上下文和驻留时间。本课练习
练习 1:定位下载停滞
任务目标:区分网络、代理和磁盘问题。输入或初始条件:假设下载长时间没有进度。
实现要求:检查服务状态、HTTPS、代理、磁盘和日志。验收条件:每一步都有可观察证据。
练习 2:修复目录权限
任务目标:恢复服务用户写入能力。输入或初始条件:自定义模型目录属于 root,服务用户无法写入。实现要求:调整所有者和最小权限并重启
验收条件:服务用户测试可写且 ollama pull 成功。
练习 3:完成故障复验
任务目标:证明问题已彻底修复。输入或初始条件:模型曾出现下载或加载失败。
实现要求:执行 list、show、run 和 ps。验收条件:四项结果均正常并保存日志时间点。