Ollama支持的模型如何在离线环境下加载和运行？

Question

常见技术问题： 在无网络的离线环境中，Ollama 无法自动拉取模型（如 `ollama run llama3` 会报错“connection refused”或“failed to fetch manifest”），且默认依赖在线 registry（registry.ollama.ai）。即使已下载模型文件，若未正确导入或模型层缓存损坏，`ollama list` 可能不显示，`ollama run` 仍提示“model not found”。此外，离线部署常忽略 Ollama 服务需预先启动（`ollama serve`）、模型需通过 `.ollama` 目录或 `OLLAMA_MODELS` 环境变量指定本地路径、以及 Windows/macOS/Linux 下模型包（`manifest`, `blobs/`）结构完整性等关键前提。用户易误将单个 GGUF 文件直接加载（Ollama 不原生支持裸 GGUF），或混淆 `ollama create` 自定义 Modelfile 的离线构建流程，导致模型注册失败。如何确保模型二进制完整迁移、校验 SHA256、重载 registry 缓存并验证推理可用性，是离线落地的核心障碍。

Answer 1

```html

一、现象层：离线环境下 Ollama 的典型报错与表象行为

• ollama run llama3 报 connection refused 或 failed to fetch manifest —— 本质是客户端尝试连接 registry.ollama.ai:443 失败；
• ollama list 空输出，但 .ollama/models/blobs/ 下存在大量文件 —— 表明模型层已落盘，但 manifest 缺失或损坏；
• 将单个 llama3.Q4_K_M.gguf 文件复制到 .ollama/models 后仍报 model not found —— Ollama 不识别裸 GGUF，必须通过合法的 OCI 兼容模型包加载；
• Windows 上执行 ollama serve 后无监听（netstat -ano | findstr :11434 无结果）—— 服务未真正启动，常因权限、防火墙或配置路径错误导致。

二、机制层：Ollama 离线模型加载的完整生命周期

Ollama 模型非“即插即用”二进制，而是遵循 OCI Image Spec v1.1 的分层对象存储模型。其离线加载依赖以下四要素协同：

组件	作用	离线关键约束
manifest.json	模型元数据索引，含 config.digest + layer.digest 列表	必须与 blobs 中实际 SHA256 哈希严格一致，否则校验失败
blob/sha256:xxx	模型权重、tokenizer、adapter 等分块二进制	每个 blob 需独立校验，缺失任一 → model not found
OLLAMA_MODELS 环境变量	覆盖默认 ~/.ollama 路径，支持多实例隔离	Linux/macOS 需 export 后重启 ollama serve；Windows 需设为系统变量并重开终端

三、诊断层：结构化排障流程图

flowchart TD
  A[启动 ollama serve] --> B{端口 11434 是否监听？}
  B -- 否 --> C[检查服务进程、权限、防火墙]
  B -- 是 --> D[执行 ollama list]
  D -- 空列表 --> E[检查 .ollama/models/manifests/registry.ollama.ai/library/llama3/]
  E -- 目录不存在 --> F[需手动导入模型包]
  E -- 存在但无有效 manifest --> G[校验 manifest.json 与 blobs SHA256 是否匹配]
  G -- 不匹配 --> H[重新生成 manifest 或修复 blob]
  G -- 匹配 --> I[执行 ollama run llama3:test 推理验证]

四、解决层：生产级离线部署五步法

1. 模型包预提取：在联网环境执行 ollama pull llama3 → 进入 ~/.ollama/models/ 打包 manifests/ + blobs/ 全目录（保留层级）；
2. 完整性校验：使用 sha256sum -c manifests/registry.ollama.ai/library/llama3/sha256:xxx 验证所有 blobs；
3. 路径注入：Linux/macOS 设置 export OLLAMA_MODELS=/mnt/offline-ollama-models；Windows 在系统属性→环境变量中新增；
4. 服务冷启：以非 root 用户运行 ollama serve &，确认 curl http://localhost:11434/api/tags 返回 JSON；
5. 模型注册验证：执行 ollama create llama3-offline -f Modelfile（Modelfile 指向本地 GGUF + system prompt），再 ollama run llama3-offline 测试 token 流式输出。

五、高阶实践：构建可审计的离线模型交付物

面向金融、政务等强合规场景，建议构建带签名的模型交付包：

# 生成模型指纹清单
find .ollama/models -type f -name "sha256:*" -exec sha256sum {} \; > model-integrity.SHA256SUMS
gpg --clearsign model-integrity.SHA256SUMS

# 部署端校验脚本 verify-offline.sh
#!/bin/bash
cd $OLLAMA_MODELS
sha256sum -c ../model-integrity.SHA256SUMS 2>&1 | grep -q "OK"
if [ $? -eq 0 ]; then
  echo "[PASS] All blobs verified."
  ollama list
else
  echo "[FAIL] Integrity check failed."
  exit 1
fi

该方案满足等保2.0对“软件供应链完整性”的三级要求，且支持自动化 CI/CD 流水线集成。

```