Docker GenAI Stack 中Ollama模型加载问题分析与解决方案

问题背景

在使用Docker GenAI Stack项目时，用户报告在Ubuntu 24.04系统上运行docker compose --profile linux up命令时出现错误。核心错误信息显示$HOME is not defined，具体表现为Ollama无法找到$HOME/.ollama/models目录，导致模型拉取服务(pull-model)异常退出。

错误现象分析

当用户尝试启动包含Ollama服务的Docker容器时，系统抛出以下关键错误：

pull-model-1 | panic: $HOME is not defined
pull-model-1 | goroutine 1 [running]:
pull-model-1 | github.com/ollama/ollama/envconfig.Models()

这表明Ollama服务在容器内部运行时无法识别HOME环境变量，而Ollama默认会将模型存储在$HOME/.ollama/models路径下。这种问题在多操作系统环境下尤为常见，特别是在Linux系统中。

根本原因

经过深入分析，发现该问题主要由以下几个因素导致：

1. 环境变量缺失：Docker容器内部未正确设置HOME环境变量，而Ollama服务依赖此变量来确定模型存储位置。

2. Ollama版本兼容性：较新版本的Ollama(特别是2024年6月后的版本)对环境变量的处理方式有所改变，导致在容器化环境中更容易出现此类问题。

3. 跨平台差异：在Linux系统上，host.docker.internal的解析方式与Windows/Mac不同，可能导致服务间通信问题。

解决方案

方案一：修改环境变量配置

对于使用Docker Compose的情况，可以在服务定义中添加HOME环境变量：

services:
  pull-model:
    environment:
      - HOME=/app  # 指定一个容器内的有效路径

方案二：使用特定版本的Ollama镜像

考虑到新版本Ollama可能存在的兼容性问题，可以回退到较稳定的旧版本：

services:
  llm:
    image: ollama/ollama:0.1.25  # 指定一个已知稳定的版本

方案三：代码层面修复

对于有能力修改源代码的用户，可以在Clojure脚本中显式设置HOME变量：

(System/setProperty "user.home" "/path/to/home")

或者在调用Ollama服务前确保环境变量已正确设置。

最佳实践建议

1. 统一环境配置：确保开发、测试和生产环境使用相同的Ollama版本和配置。

2. 显式路径指定：在容器中明确设置模型存储路径，而非依赖环境变量。

3. 健康检查配置：适当调整服务的健康检查策略，避免因初始化时间较长导致服务被误判为不健康。

4. 日志监控：加强对容器日志的监控，特别是模型加载阶段的输出。

总结

Docker GenAI Stack与Ollama集成时遇到的环境变量问题，本质上是容器化环境中配置管理的一个典型案例。通过理解Ollama的工作原理和Docker环境特性，我们可以采用多种方式解决这类问题。建议用户根据自身环境选择最适合的解决方案，并在部署前充分测试验证。