Hoarder项目中的Ollama超时问题分析与解决方案

问题背景

在Hoarder项目中使用Ollama进行AI标签生成时，开发人员发现一个关键问题：尽管设置了1200秒(20分钟)的超时时间(INFERENCE_JOB_TIMEOUT_SEC)，但系统在5分钟后就会自动终止请求并重新运行推理任务。这个问题严重影响了长时间推理任务的正常执行。

问题现象

通过日志分析可以观察到以下典型模式：

1. 推理任务启动
2. 5分钟后Ollama记录显示200状态码的POST请求
3. Hoarder重新启动相同的推理任务
4. 此循环可能重复多次
5. 最终可能以"fetch failed"错误结束

有趣的是，直接使用curl测试时，可以成功完成超过5分钟的请求，这表明问题并非来自Ollama服务本身。

根本原因分析

经过深入调查，发现问题根源在于Node.js的fetch API默认行为：

1. Node.js的undici库(用于实现fetch)默认设置了5分钟的超时时间(headersTimeout)
2. 这个超时是全局性的，影响所有fetch请求
3. 即使Ollama客户端使用流式响应，这个底层超时仍然会生效
4. Hoarder设置的INFERENCE_JOB_TIMEOUT_SEC仅控制任务级别的超时，不影响底层HTTP请求

解决方案演进

社区提出了几种解决方案：

临时解决方案（不推荐）

1. 直接修改node_modules中的ollama库文件
2. 通过Docker volume挂载修改后的文件
3. 这种方法虽然有效，但破坏了包管理的完整性

推荐解决方案

1. 创建自定义fetch包装器，允许配置超时时间
2. 通过环境变量INFERENCE_FETCH_TIMEOUT_SEC控制超时
3. 在Ollama客户端初始化时注入自定义fetch函数

实现要点：

const { Agent } = require('undici');

const customFetch = (input, init = {}) => {
  const timeout = process.env.INFERENCE_FETCH_TIMEOUT_SEC 
    ? parseInt(process.env.INFERENCE_FETCH_TIMEOUT_SEC, 10) * 1000
    : 5 * 60 * 1000; // 默认5分钟

  return fetch(input, {
    ...init,
    dispatcher: new Agent({ headersTimeout: timeout }),
  });
};

实施建议

对于Hoarder用户，建议：

1. 更新到包含此修复的最新版本
2. 在docker-compose.yml中添加环境变量：

services:
  web:
    environment:
      - INFERENCE_FETCH_TIMEOUT_SEC=3600 # 1小时超时

3. 根据实际推理任务需求调整超时值
4. 监控系统资源使用情况，避免过长的超时导致资源耗尽

技术深度解析

这个问题揭示了现代JavaScript应用中多层超时控制的复杂性：

1. 应用层超时：Hoarder的任务超时控制
2. HTTP客户端层超时：Node.js fetch实现的默认行为
3. 服务层超时：Ollama自身的keep_alive设置

正确的做法应该是让每一层的超时设置协调工作，而不是相互冲突。这个案例也展示了如何通过包装模式在不修改第三方库的情况下解决兼容性问题。

总结

Hoarder项目中Ollama集成遇到的5分钟超时问题，本质上是Node.js运行时环境与应用程序预期行为之间的不匹配。通过创建自定义fetch实现并暴露配置接口，开发者可以在不破坏现有架构的情况下灵活控制HTTP请求超时，从而满足长时间运行AI推理任务的需求。这个解决方案不仅解决了眼前的问题，也为类似集成场景提供了可借鉴的模式。