模型抽象与多提供商适配

模型抽象与多提供商适配

学习目标

本章要解决什么问题：AutoGen 如何通过统一的 ChatCompletionClient 抽象支持 OpenAI、Anthropic、Ollama 等多个模型提供商。你将学到：

• ModelFamily 能力分类体系
• 流式输出的 AsyncGenerator 模型
• 工具调用 schema 的自动生成
• 扩展包（autogen-ext）中的模型实现

前置知识

本章涉及多模型适配的通用原理，建议先阅读：

• 多模型适配架构

下文假设你已理解统一模型抽象的价值，直接聚焦 AutoGen 的具体实现。

---

项目实践

ChatCompletionClient 抽象

AutoGen Core 定义了 ChatCompletionClient 抽象基类，所有具体实现必须实现以下方法：

class ChatCompletionClient(ABC):
    @abstractmethod
    async def create(
        self,
        messages: Sequence[LLMMessage],
        *,
        tools: Sequence[Tool] = [],
        extra_create_args: Mapping[str, Any] = {},
        cancellation_token: CancellationToken | None = None,
    ) -> CreateResult:
        """生成补全（非流式）"""

    @abstractmethod
    def create_streaming(
        self,
        messages: Sequence[LLMMessage],
        *,
        ...
    ) -> AsyncGenerator[CreateResult, None]:
        """生成补全（流式）"""

关键设计：

• LLMMessage 统一表示对话消息（SystemMessage、UserMessage、AssistantMessage 等）
• CreateResult 统一表示生成结果（content、usage、finish_reason）
• Tool 和 ToolSchema 统一表示工具定义

ModelFamily 能力分类

class ModelFamily:
    GPT_4O = "gpt-4o"
    CLAUDE_4_SONNET = "claude-4-sonnet"
    GEMINI_2_5_PRO = "gemini-2.5-pro"
    LLAMA_4_MAVERICK = "llama-4-maverick"
    UNKNOWN = "unknown"

ModelFamily 按能力特征而非供应商对模型分类。AutoGen 内部使用 ModelFamily 决定是否启用某些功能（如 vision、function calling、json output）。

扩展包中的模型实现

autogen-ext 提供了多个模型后端：

扩展	类	支持特性
autogen-ext[openai]	OpenAIChatCompletionClient	OpenAI API 兼容
autogen-ext[azure]	AzureOpenAIChatCompletionClient	Azure OpenAI
autogen-ext[anthropic]	AnthropicChatCompletionClient	Claude 系列
autogen-ext[ollama]	OllamaChatCompletionClient	本地模型
autogen-ext[llama-cpp]	LlamaCppChatCompletionClient	llama.cpp 本地推理

安装方式：

pip install "autogen-ext[openai]"      # OpenAI
pip install "autogen-ext[anthropic]"   # Anthropic
pip install "autogen-ext[ollama]"      # Ollama

流式输出集成

AutoGen AgentChat 层将流式输出与 Agent 响应机制集成：

agent = AssistantAgent(
    "assistant",
    model_client=client,
    model_client_stream=True,  # 启用流式
)

# 流式输出：产生 ModelClientStreamingChunkEvent
async for message in agent.run_stream(task="Explain quantum computing"):
    if isinstance(message, ModelClientStreamingChunkEvent):
        print(message.content, end="", flush=True)

内部机制：当 model_client_stream=True 时，AssistantAgent 调用 create_streaming，将每个 token 块包装为 ModelClientStreamingChunkEvent 发出。

问题与规避

不同提供商的 Tool Calling 格式差异

陷阱：OpenAI、Anthropic、Google 的 function calling 格式不完全兼容。例如，Anthropic 的 tool 定义使用 input_schema 而 OpenAI 使用 parameters。

规避策略：

• 使用 AutoGen 的 ToolSchema 统一抽象，由扩展包负责转换
• 避免在 Agent 代码中直接使用提供商特定的参数

流式与非流式的状态管理

陷阱：在流式模式下，如果 Agent 同时需要处理工具调用和 token 流，可能导致状态混乱。

规避：

• AutoGen 内部在流式完成后才处理工具调用
• 不要在流式过程中尝试修改 Agent 状态

设计取舍

为什么自己定义抽象而非使用 LiteLLM？

AutoGen 自建抽象的优势：

• 完全控制接口设计，与 Core 架构无缝集成
• 不依赖第三方库的版本和兼容性
• 可以深度优化（如 Component 序列化）

LiteLLM 的优势：

• 开箱即用支持 100+ 模型
• 社区维护，更新及时

AutoGen 的选择：Core 定义抽象，Ext 提供具体实现。用户可以替换 Ext 实现（包括使用 LiteLLM 桥接），但 Core 接口保持稳定。

替代方案

方案	支持模型数	维护成本	控制力	示例
自建抽象 + 扩展	按需	高	最高	AutoGen
LiteLLM	100+	低	中	LiteLLM
直接 SDK 调用	1	低	高	OpenAI SDK

参考来源

• AutoGen Models Documentation — 模型配置指南
• 源码验证：autogen-core/models/_model_client.py（抽象基类）
• 源码验证：autogen-ext/models/openai/（OpenAI 实现）