TaskWeaver本地LLM集成故障排查指南

问题背景

在使用TaskWeaver项目集成本地Ollama运行的LLM模型时，开发者可能会遇到404错误导致模型调用失败的情况。本文将从技术角度分析这一问题的成因，并提供详细的解决方案。

错误现象分析

当用户尝试通过TaskWeaver调用本地Ollama服务运行的LLM模型（如llama2:13b）时，控制台会抛出以下异常：

Exception: Failed to get completion with error code 404: 404 page not found

这个HTTP 404错误表明TaskWeaver客户端无法正确访问Ollama服务的API端点。经过深入分析，我们发现这通常由两个主要原因导致。

根本原因

1. API端点路径配置问题：TaskWeaver默认配置的API路径与Ollama实际服务路径存在冲突。在ollama.py文件中，默认的api_endpoint = "/api/chat"配置会导致路径拼接时产生双斜杠问题。

2. 服务端口不匹配：Ollama服务的默认端口(通常是11434)与TaskWeaver配置中的端口设置不一致，导致连接失败。

解决方案

方案一：修正API端点路径

1. 定位到TaskWeaver项目中的ollama.py文件
2. 找到约第90行的API端点配置
3. 将原有配置：

   api_endpoint = "/api/chat"
   

   修改为：

   api_endpoint = "api/chat"
   

4. 保存文件并重启TaskWeaver服务

这个修改消除了路径拼接时产生的多余斜杠，确保HTTP请求能够正确路由到Ollama服务。

方案二：检查端口配置

1. 确认Ollama服务实际监听的端口号（默认11434）
2. 检查TaskWeaver配置文件taskweaver_config.json中的相关设置
3. 确保配置中的端口与Ollama服务端口一致
4. 如有必要，修改配置后重启服务

验证步骤

为确保问题已解决，建议进行以下验证：

1. 首先确保Ollama服务已正确启动并能独立响应请求
2. 使用curl等工具测试API端点可达性：

   curl http://localhost:11434/api/chat
   

3. 观察返回结果是否正常
4. 最后通过TaskWeaver发起测试请求，确认功能正常

最佳实践建议

1. 在集成本地LLM时，建议先单独测试Ollama服务的可用性
2. 保持TaskWeaver和Ollama的版本同步更新
3. 对于生产环境，考虑添加服务健康检查机制
4. 记录详细的日志信息以便后续排查

通过以上解决方案，开发者应该能够成功解决TaskWeaver与本地Ollama LLM集成时的404错误问题，实现顺畅的本地大语言模型调用体验。