大模型应用开发 / 系统课时

排查模型下载与启动失败

排查模型下载与启动失败

学习目标

完成本课后,你将能够:

  • 根据故障发生在下载、校验、加载还是启动阶段进行分类
  • 检查模型标签、网络代理、磁盘空间和目录权限
  • 使用 CLI、API、服务状态和日志定位根本原因
  • 完成修复后的下载、加载和请求三层验证

先判断失败发生在哪一阶段

模型相关故障分为四类:

阶段 典型表现 主要资源
模型解析 提示模型不存在或标签错误 模型名称、清单
下载 连接失败、进度停滞、摘要校验失败 网络、代理、磁盘
加载 内存不足、文件损坏、格式不支持 内存、显存、模型文件
推理启动 服务端口、运行后端或模板异常 服务、驱动、配置

先分类可以避免把网络故障误判为 GPU 故障。

确认服务基础状态

版本与服务:

bash
ollama --version
curl --silent --output /dev/null --write-out "%{{http_code}}\n"   http://localhost:11434/api/tags

预期输出:

text
ollama version is <VERSION>
200

如果 API 不可达,先修复 Ollama 服务,不要继续排查模型下载。

验证模型名称和标签

查看本地模型:

bash
ollama list

预期输出:

text
NAME       ID          SIZE      MODIFIED
<MODEL>    <MODEL_ID>  <SIZE>    <MODIFIED>

下载时使用模型库中真实存在的完整标签:

bash
ollama pull <MODEL:TAG>

预期结果:

text
显示清单与分层下载进度,完成后提示成功。

常见错误包括拼写错误、把网页标题当成模型标签、遗漏命名空间或使用不存在的量化变体。

检查网络、DNS 和代理

检查 DNS 与 HTTPS:

bash
getent hosts ollama.com 2>/dev/null || nslookup ollama.com
curl -I https://ollama.com

预期结果:

text
域名能解析,HTTPS 请求返回有效 HTTP 响应。状态码可能包含跳转。

查看代理环境:

bash
env | grep -iE '^(http|https|no)_proxy='

预期输出:

text
显示当前代理变量;没有配置时无输出。

Ollama 拉取模型使用 HTTPS。代理应允许大文件和长连接,并让 Ollama 服务进程继承。只在当前终端设置变量不会自动影响 systemd 或桌面后台应用。

检查磁盘与 inode

Linux:

bash
df -h /
df -i /
du -sh /usr/share/ollama/.ollama 2>/dev/null || true

预期输出:

text
显示磁盘容量、inode 使用和 Ollama 数据目录大小。

Docker:

bash
docker system df
docker volume inspect ollama

预期输出:

text
显示 Docker 镜像、容器、卷占用和 ollama 卷信息。

磁盘有容量但 inode 用尽,同样无法创建新文件。不要在下载过程中执行无差别清理。

检查模型目录权限

Linux 服务用户:

bash
systemctl show ollama -p User -p Group
systemctl show ollama -p Environment

预期输出示例:

text
User=ollama
Group=ollama
Environment=<ENVIRONMENT_VALUES>

检查写权限:

bash
MODEL_DIR=/usr/share/ollama/.ollama/models
sudo -u ollama test -w "$MODEL_DIR" && echo writable

预期输出:

text
writable

自定义目录时,将 MODEL_DIR 改为真实路径。权限修复应针对服务用户,不要使用 chmod 777 作为长期方案。

查看日志定位具体错误

Linux:

bash
sudo journalctl -u ollama -n 200 --no-pager

Docker:

bash
docker logs --tail 200 ollama

预期结果:

text
输出最近日志,用于识别网络、摘要、路径、内存、驱动和端口错误。

建议按错误时间搜索,而不是只看日志中任意出现过的旧错误。

处理中断与损坏

下载中断后,优先重新执行相同 ollama pull,让工具复用已完成分层并继续校验。不要直接编辑 blobs 文件或伪造清单。如果反复出现摘要或文件损坏:

  1. 停止 Ollama。
  2. 备份模型目录。
  3. 确认磁盘和文件系统健康。
  4. 仅删除明确对应的损坏数据。
  5. 重新启动并拉取。
  6. 验证 ollama show 和实际推理。

无法确定文件映射时,删除整个模型目录会导致所有模型重新下载,应作为最后手段。

修复后的三层验证

第一层,模型存在:

bash
ollama list
ollama show <MODEL:TAG>

预期结果:

text
模型出现在列表中,show 能显示模型详情。

第二层,模型加载:

bash
ollama run <MODEL:TAG> "只回答:启动成功。"

预期结果:

text
模型返回“启动成功”或语义等价文本,没有加载错误。

第三层,运行状态:

bash
ollama ps

预期结果:

text
列表中出现目标模型,并显示处理器、上下文和驻留时间。

本课练习

练习 1:定位下载停滞

任务目标:区分网络、代理和磁盘问题。输入或初始条件:假设下载长时间没有进度。

实现要求:检查服务状态、HTTPS、代理、磁盘和日志。验收条件:每一步都有可观察证据。

练习 2:修复目录权限

任务目标:恢复服务用户写入能力。输入或初始条件:自定义模型目录属于 root,服务用户无法写入。实现要求:调整所有者和最小权限并重启

验收条件:服务用户测试可写且 ollama pull 成功。

练习 3:完成故障复验

任务目标:证明问题已彻底修复。输入或初始条件:模型曾出现下载或加载失败。

实现要求:执行 list、show、run 和 ps。验收条件:四项结果均正常并保存日志时间点。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

排查模型下载与启动失败

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通