Hoarder项目中使用本地Ollama替代OpenAI的配置指南

在自托管内容管理工具Hoarder中，AI标注功能默认会优先使用OpenAI服务。但近期有用户反馈，在配置本地Ollama实例时遇到了"Country not supported"的错误提示。本文将深入分析该问题的技术原理，并提供完整的解决方案。

问题现象分析

当用户通过Docker Compose部署Hoarder系统时，若同时配置了以下两个环境变量：

1. OLLAMA_BASE_URL（指向本地Ollama实例）
2. OPENAI_API_KEY（包含任意值）

系统会优先尝试使用OpenAI服务，而非本地Ollama实例。这是由于Hoarder的代码逻辑中，当检测到OPENAI_API_KEY存在时，会默认启用OpenAI集成。

技术原理详解

Hoarder的推理服务采用分层设计：

1. 首先检查OPENAI_API_KEY环境变量
2. 若存在则创建OpenAI客户端
3. 若不存在则回退到OLLAMA_BASE_URL配置

这种设计虽然提供了灵活性，但也容易导致配置冲突。特别是在某些地区无法使用OpenAI服务的情况下，保留OPENAI_API_KEY会导致服务不可用。

完整解决方案

要正确使用本地Ollama实例，需要确保：

1. 完全移除.env文件中的OPENAI_API_KEY配置项
2. 正确配置OLLAMA_BASE_URL指向本地实例
3. 设置合适的推理模型参数（如llama3.1等本地可用模型）

示例配置：

OLLAMA_BASE_URL=http://localhost:11434/api
INFERENCE_TEXT_MODEL=llama3.1
INFERENCE_IMAGE_MODEL=llava
INFERENCE_CONTEXT_LENGTH=4096

最佳实践建议

1. 在自托管环境中，建议完全禁用OpenAI相关配置
2. 定期检查Ollama模型更新，确保兼容性
3. 对于生产环境，建议设置DISABLE_SIGNUPS=true增强安全性
4. 监控推理服务的资源使用情况，适当调整INFERENCE_CONTEXT_LENGTH参数

通过以上配置，用户可以充分利用本地AI资源，既保证了数据隐私，又避免了服务地域限制的问题。这种自托管方案特别适合对数据安全性要求较高的应用场景。

故障排查技巧

若仍遇到问题，可检查：

1. Hoarder容器日志中是否仍有OpenAI相关错误
2. Ollama服务是否正常运行并能响应API请求
3. 网络连接是否通畅（特别是在Docker跨容器通信场景）
4. 模型文件是否已正确下载到Ollama实例中