OpenHands项目Github Actions集成中LLM_API_VERSION参数失效问题解析

在All-Hands-AI开源项目OpenHands的实际应用场景中，开发团队发现了一个影响Azure OpenAI服务集成的关键问题。该问题出现在使用Github Actions工作流调用OpenHands解析器时，系统无法正确处理API版本参数，导致与o3-mini模型的交互失败。

问题现象

当开发团队通过Github Actions工作流配置OpenHands解析器时，虽然明确指定了LLM_API_VERSION参数为"2024-12-01-preview"，但系统仍然报错提示"Model {modelName} is enabled only for api versions 2024-12-01-preview and later"。这表明参数传递机制存在缺陷，系统未能正确识别和使用指定的API版本。

技术分析

深入分析问题根源，我们可以发现几个关键点：

1. 参数传递机制缺陷：工作流配置中虽然正确设置了LLM_API_VERSION参数，但该参数仅被设置为环境变量，并未被实际应用到Azure OpenAI服务的API调用中。

2. Litellm库的集成问题：OpenHands底层使用Litellm库处理大语言模型交互，但当前实现中缺少对API版本参数的有效传递机制。

3. Azure OpenAI服务要求：新版模型如o3-mini强制要求使用特定API版本，这使得版本参数的正确传递变得至关重要。

解决方案

项目维护团队迅速响应，提交了修复方案。主要改进包括：

1. 完善参数传递链路：确保Github Actions工作流中设置的LLM_API_VERSION参数能够正确传递到Litellm的API调用层。

2. 增强环境变量处理：在Litellm集成层增加对API版本环境变量的识别和处理逻辑。

3. 版本兼容性保障：建立API版本参数的默认值机制，确保即使未显式指定也能使用兼容版本。

最佳实践建议

基于此问题的解决经验，我们建议开发者在集成OpenHands时注意：

1. 对于Azure OpenAI服务集成，务必检查并确认API版本参数的正确性。

2. 在使用新版模型时，提前验证所需的最低API版本要求。

3. 定期更新OpenHands版本以获取最新的兼容性修复。

4. 在复杂集成场景中，建议增加API版本参数的显式日志输出，便于问题排查。

总结

这个问题的解决不仅修复了当前的功能缺陷，更重要的是完善了OpenHands项目的参数传递机制，为后续更复杂的集成场景打下了良好基础。它提醒我们在AI服务集成中，API版本管理是一个需要特别关注的关键因素，特别是在服务提供商频繁更新模型的场景下。通过这次问题的分析和解决，OpenHands项目在稳定性和兼容性方面又向前迈进了一步。