LLM 集成

相关源文件

• frontend/src/state/metrics-slice.ts
• frontend/src/types/message.tsx
• openhands/core/config/llm_config.py
• openhands/core/exceptions.py
• openhands/core/message.py
• openhands/llm/__init__.py
• openhands/llm/async_llm.py
• openhands/llm/bedrock.py
• openhands/llm/debug_mixin.py
• openhands/llm/llm.py
• openhands/llm/metrics.py
• openhands/llm/retry_mixin.py
• openhands/llm/streaming_llm.py
• openhands/utils/ensure_httpx_close.py
• tests/unit/test_ensure_httpx_close.py
• tests/unit/test_llm.py
• tests/unit/test_message_serialization.py

LLM 集成系统通过一个一致的抽象层，为与多个大型语言模型提供商的通信提供了一个统一的接口。该系统处理提供商特定的格式化、重试逻辑、成本跟踪、指标收集以及函数调用和视觉支持等高级功能。

有关特定于代理的 LLM 用法模式的信息，请参阅 Agent System。有关配置管理详细信息，请参阅 Configuration System。

架构概述

LLM 集成系统构建于核心 LLM 类之上，该类通过 LiteLLM 为多个模型提供商提供标准化的接口。该系统支持同步、异步和流式操作，同时在不同提供商之间保持一致的行为。

来源： openhands/llm/llm.py106-199 openhands/llm/async_llm.py17-39 openhands/llm/streaming_llm.py11-32 openhands/core/config/llm_config.py12-89

LLM 配置系统

LLMConfig 类管理所有 LLM 相关的配置参数，包括模型选择、API 凭证、重试设置和功能标志。它支持默认配置和通过 TOML 配置文件进行的自定义覆盖。

来源： openhands/core/config/llm_config.py12-89 openhands/core/config/llm_config.py92-154 openhands/core/config/llm_config.py156-174

核心 LLM 类实现

LLM 类作为模型交互的主要接口。它通过 OpenHands 特有的功能（包括重试逻辑、指标跟踪、函数调用支持和提供商特定的优化）来封装 LiteLLM 的完成功能。

组件	目的	关键方法
LLM.completion	主要完成接口	completion(), _completion_unwrapped
LLM.init_model_info	模型能力检测	init_model_info(), _supports_vision()
LLM.get_token_count	Token 计数	get_token_count(), 自定义分词器支持
LLM._post_completion	成本和指标跟踪	_completion_cost(), 使用情况日志记录

来源： openhands/llm/llm.py106-199 openhands/llm/llm.py391-451 openhands/llm/llm.py510-556 openhands/llm/llm.py50-96

消息系统和序列化

消息系统处理 OpenHands 内部消息格式与提供商特定格式之间的转换。它支持文本内容、图像、工具调用和特定于提供商的功能，如提示缓存。

来源： openhands/core/message.py53-159 openhands/core/message.py74-130 openhands/core/message.py131-158

指标和成本跟踪

指标系统提供对 LLM 使用情况的全面跟踪，包括成本、令牌消耗、响应延迟和缓存利用率。这些数据对于跨系统监视和优化 LLM 使用情况至关重要。

指标类型	类	跟踪数据
成本	成本	每次调用和累积的成本
令牌使用量	TokenUsage	提示、完成、缓存读取/写入令牌
响应延迟	ResponseLatency	每次完成的往返时间

来源： openhands/llm/metrics.py47-70 openhands/llm/metrics.py120-170 openhands/llm/metrics.py21-44

高级特性

函数调用支持

该系统支持本地函数调用（适用于兼容的模型）和通过提示工程进行的函数调用仿真。 FUNCTION_CALLING_SUPPORTED_MODELS 列表确定哪些模型使用本地支持。

视觉支持

视觉能力是根据 LiteLLM 的模型信息自动检测的。启用后，ImageContent 对象将被包含在消息序列化中。

提示缓存

对于支持的模型（主要是 Anthropic Claude），系统会自动启用提示缓存以降低重复上下文的成本。缓存控制标头将添加到适当的消息内容中。

来源： openhands/llm/llm.py496-508 openhands/llm/llm.py535-548 openhands/llm/llm.py63-85

异步和流式支持

该系统提供异步（AsyncLLM）和流式（StreamingLLM）变体，它们继承自基类 LLM，同时增加了异步功能和实时响应流式传输。

来源： openhands/llm/async_llm.py17-130 openhands/llm/streaming_llm.py11-114

错误处理和重试逻辑

重试系统通过指数退避来处理瞬态错误，例如速率限制和 API 超时。对于 LLMNoResponseError，有特殊的处理方式，其中温度会在重试时自动调整。

异常类型	重试行为	特殊处理
RateLimitError	指数退避	无
LLMNoResponseError	温度调整	如果温度最初为 0，则设置为 1.0
InternalServerError	标准重试	无
超时	标准重试	无

来源： openhands/llm/retry_mixin.py15-78 openhands/llm/llm.py40-46 openhands/llm/llm.py202-209

提供商集成

该系统通过LiteLLM与多个LLM提供商集成，LiteLLM提供统一的接口，同时处理提供商特定的要求和转换。

支持的提供商

提供商	配置	特殊功能
Anthropic Claude	api_key, base_url	提示缓存、函数调用
OpenAI GPT	api_key, base_url	函数调用、视觉
Google Gemini	提供商特定的身份验证	函数调用（2.5+ 模型）
AWS Bedrock	AWS 凭证	区域部署
Azure OpenAI	需要api_version	特定 API 版本管理
本地/Ollama	ollama_base_url	本地模型支持

模型特定的优化

该系统包含针对特定模型系列的优化。

• Claude 3.7 Sonnet：输出 token 限制增加到 64,000
• O1/O3 模型：推理努力参数、温度限制
• Hugging Face 模型：调整了top_p 参数以提高兼容性
• OpenHands-LM：专门的函数调用处理

来源： openhands/llm/llm.py456-495 openhands/llm/llm.py170-199 openhands/llm/llm.py241-269