ADK-Python项目中使用Ollama模型实现工具调用的技术实践

在基于ADK-Python框架开发AI助手时，开发者可能会遇到需要集成本地运行的Ollama模型的需求。本文将详细介绍如何正确配置和使用Ollama模型，特别是解决工具调用过程中遇到的常见问题。

核心问题分析

当开发者尝试在ADK-Python中使用Ollama模型时，通常会遇到两个主要问题：

1. 基础消息响应问题：部分模型如Llama3.2、Gemma3等无法正常响应普通消息
2. 工具调用异常：当需要触发工具调用时，会出现JSON解析错误，提示"cannot process array into Go struct field"

这些问题源于Ollama API对请求格式的特殊要求，特别是对消息内容结构的处理方式与标准API存在差异。

解决方案演进

临时解决方案：OpenAI兼容模式

在官方修复发布前，开发者可以采用OpenAI兼容模式作为临时解决方案。这种方法通过环境变量重定向API请求：

import os
os.environ["OPENAI_API_BASE"] = "http://localhost:11434/v1"
os.environ["OPENAI_API_KEY"] = "unused"  # 占位值，实际不需要

然后在创建Agent时使用OpenAI兼容模式：

agent = Agent(
    name="weather_reporter",
    model=LiteLlm(model="openai/qwen2.5:3b"),  # 注意模型命名格式
    tools=[get_weather]
)

这种方法利用了Ollama提供的OpenAI兼容端点，绕过了原始实现中的解析问题。需要注意的是，较小的模型（如<3B参数）可能在工具调用可靠性上表现不佳。

官方修复方案

项目团队随后发布了针对Ollama原生集成的修复方案，主要改进包括：

1. 正确处理消息内容数组格式
2. 优化API端点路由配置
3. 增强错误处理和调试信息

修复后，开发者可以回归使用原生Ollama集成方式：

export OLLAMA_API_BASE="http://localhost:11434"

在代码中直接指定ollama_chat提供者：

agent = Agent(
    name="weather_reporter",
    model=LiteLlm(model="ollama_chat/qwen2.5"),
    tools=[get_weather]
)

调试技巧

为了深入分析请求过程，开发者可以启用LiteLLM的调试模式：

import litellm
litellm._turn_on_debug()

这将输出详细的请求日志，帮助开发者理解：

• 实际发送的请求负载
• API端点路由选择
• 响应处理过程

最佳实践建议

1. 模型选择：优先使用参数规模较大的模型（如3B以上）以保证工具调用的可靠性
2. 环境隔离：为不同项目配置独立的环境变量，避免冲突
3. 版本控制：关注ADK-Python的版本更新，及时获取最新修复
4. 异常处理：在代码中添加适当的异常捕获和处理逻辑

总结

ADK-Python框架通过不断完善的Ollama集成方案，为开发者提供了在本地运行大型语言模型的便捷途径。无论是采用临时的OpenAI兼容模式，还是等待官方修复后的原生集成方案，开发者都可以根据项目需求选择最适合的实施方案。随着项目的持续发展，这类本地模型集成方案将为AI应用开发带来更多可能性。