CAMEL 多智能体框架接入 Azure OpenAIAzureOpenAIModel 统一模型后端与 Responses API 实战指南【免费下载链接】camel CAMEL: The first and the best multi-agent framework. Finding the Scaling Law of Agents. https://www.camel-ai.org项目地址: https://gitcode.com/GitHub_Trending/ca/camel本篇技术指南以 CAMEL 仓库中的 AzureOpenAIModel 参考文档 为主体结合 源码实现、官方示例与单元测试系统讲解如何在 CAMEL 中通过统一模型后端接入 Azure OpenAI 服务。读完本文你将掌握 Azure 环境变量配置、AzureOpenAIModel全部构造参数的含义与取舍、Chat Completions 与 Responses 两种 API 模式的切换以及如何把 Azure 模型接入ChatAgent、工具调用与结构化输出等完整实战链路。AzureOpenAIModel把 Azure OpenAI 纳入 CAMEL 统一模型接口AzureOpenAIModel是 CAMEL 多智能体框架为 Azure OpenAI 服务提供的模型后端实现其类定义与定位在参考文档中表述为class AzureOpenAIModel(BaseModelBackend):它把 Azure OpenAI API 封装进 CAMEL 统一的BaseModelBackend接口使上层ChatAgent、Workforce、Task等组件无需关心底层是 OpenAI 直连还是 Azure 部署。从源码看camel/models/azure_openai_model.py该类直接继承自OpenAIModelInherits all Responses API, chat completion, and streaming methods fromOpenAIModel. Only the client initialization and Azure-specific configuration are different.这意味着OpenAIModel提供的 Responses API、Chat Completion、流式推理、结构化输出等全部能力都被继承复用AzureOpenAIModel只需覆盖两块差异化逻辑客户端初始化使用openai.AzureOpenAI/openai.AsyncAzureOpenAI并注入 Azure 特有的azure_endpoint、azure_deployment、api_version、azure_ad_token等参数Azure 特有配置如api_modechat_completions或responses、弃用参数兼容逻辑等。因此在 CAMEL 中通过ModelFactory创建模型时只需要指定平台类型为ModelPlatformType.AZURE工厂内部就会自动映射到本类。camel/models/model_factory.py 中注册了ModelPlatformType.AZURE: AzureOpenAIModel的对应关系这是官方推荐的创建入口下文详述。部署前提与环境变量使用 Azure OpenAI 前你需要在 Azure 门户中完成模型部署并获取三类信息资源终结点endpoint、API Key与API 版本号。CAMEL 通过环境变量与构造参数双重途径读取这些配置对应关系如下表环境变量对应构造参数说明AZURE_OPENAI_API_KEYapi_keyAzure OpenAI 资源的 API Key必填AZURE_OPENAI_BASE_URLurl资源终结点形如https://resource.openai.azure.com/AZURE_API_VERSIONapi_versionAPI 版本号必填详见下文校验逻辑如2024-12-01-previewAZURE_AD_TOKENazure_ad_tokenAzure Active Directory 令牌使用 Entra ID 认证时设置MODEL_TIMEOUTtimeout请求超时秒数默认180AZURE_DEPLOYMENT_NAMEmodel_type已弃用见下文说明这些环境变量在仓库的 .env.example 中有明确注释模板可按from dotenv import load_dotenv; load_dotenv()的方式加载# Azure OpenAI API (https://azure.microsoft.com/products/cognitive-services/openai-service/) export AZURE_OPENAI_API_KEYFill your API key here export AZURE_API_VERSIONFill your API Version here export AZURE_DEPLOYMENT_NAMEFill your Deployment Name here export AZURE_OPENAI_BASE_URLFill your Base URL here值得注意的是参考文档与源码都指出AZURE_DEPLOYMENT_NAME环境变量已进入弃用流程。源码在__init__中会检查该变量并发出DeprecationWarning提示改用model_type参数camel/models/azure_openai_model.py。因此新代码请把部署名直接作为model_type传入。api_version 的强制校验在 源码初始化逻辑 中api_version的解析顺序是构造参数api_version→ 环境变量AZURE_API_VERSION。如果两者都未提供会直接抛出异常if self.api_version is None: raise ValueError( Must provide either the api_version argument or AZURE_API_VERSION environment variable. )这是 Azure 与 OpenAI 直连最大的差异点Azure 要求每个请求都携带 API 版本号示例代码中普遍使用2024-12-01-preview或2025-03-01-preview请以你实际部署时选择的版本为准。构造函数参数详解参考文档完整列出了AzureOpenAIModel.__init__的签名与全部参数现结合源码逐一展开def __init__( self, model_type: Union[ModelType, str], model_config_dict: Optional[Dict[str, Any]] None, api_key: Optional[str] None, url: Optional[str] None, timeout: Optional[float] None, token_counter: Optional[BaseTokenCounter] None, api_version: Optional[str] None, azure_ad_token_provider: Optional[AzureADTokenProvider] None, azure_ad_token: Optional[str] None, max_retries: int 3, client: Optional[Any] None, async_client: Optional[Any] None, azure_deployment_name: Optional[str] None, **kwargs: Any ):参数类型默认值含义与要点model_typeUnion[ModelType, str]必填要创建后端的模型必须是你在 Azure 中部署模型时选择的部署名deployment name而非模型 ID。可传ModelType枚举如ModelType.GPT_4O或字符串如gpt-4.1model_config_dictOptional[Dict[str, Any]]None会透传给openai.ChatCompletion.create()的配置字典为None时使用ChatGPTConfig().as_dict()api_keyOptional[str]None认证用的 API Key缺省回落到AZURE_OPENAI_API_KEY环境变量urlOptional[str]None服务地址缺省回落到AZURE_OPENAI_BASE_URL环境变量timeoutOptional[float]NoneAPI 调用超时秒。缺省时读取MODEL_TIMEOUT环境变量最终默认180秒token_counterOptional[BaseTokenCounter]None自定义 token 计数器不提供时使用OpenAITokenCounterapi_versionOptional[str]NoneAzure API 版本缺省读AZURE_API_VERSION仍为空则抛ValueErrorazure_ad_tokenOptional[str]NoneAzure Active Directory 令牌Entra ID 认证场景缺省读AZURE_AD_TOKENazure_ad_token_providerOptional[AzureADTokenProvider]None一个返回 AD 令牌的函数每次请求都会调用适合令牌自动刷新的场景max_retriesint3API 调用的最大重试次数clientOptional[Any]None自定义同步AzureOpenAI客户端实例提供后不再自建。要求实现.chat.completions.create()与.beta.chat.completions.parse()接口典型场景是 AReaL、rLLM 等 RL 框架提供的 Azure OpenAI 兼容客户端async_clientOptional[Any]None自定义异步AsyncAzureOpenAI客户端实例语义同上azure_deployment_nameOptional[str]None已弃用仅为向后兼容保留未来版本将移除使用时会发出DeprecationWarning且参数被忽略**kwargsAny—透传给客户端初始化的额外参数提供自定义客户端时被忽略参考文档还额外说明了继承而来的api_mode参数源码签名为api_mode: Literal[chat_completions, responses] chat_completionschat_completions默认走传统的 Chat Completions 接口responses走 Azure OpenAI Responses API支持通过previous_response_id进行有状态响应链式调用。非法值会直接抛错ValueError: api_mode must be chat_completions or responses该行为有单元测试覆盖见下文。底层初始化行为源码级__init__的执行链路大致如下camel/models/azure_openai_model.py检查并警告弃用的azure_deployment_name参数与AZURE_DEPLOYMENT_NAME环境变量校验api_mode合法性并初始化 Responses API 链式状态字典_responses_previous_response_id_by_session、_responses_last_message_count_by_sessionmodel_config_dict为None时回退到ChatGPTConfig().as_dict()依次从参数/环境变量解析api_key、url、timeout跳过OpenAIModel.__init__它要求OPENAI_API_KEY直接调用BaseModelBackend.__init__完成公共初始化解析api_version并强制校验若已安装 langfuse 且未传自定义客户端会优先使用langfuse.openai.AzureOpenAI/AsyncAzureOpenAI构造可观测客户端实现自动链路追踪否则构造原生AzureOpenAI/AsyncAzureOpenAI客户端azure_endpoint取urlazure_deployment取model_type并透传api_version、api_key、AD 令牌、timeout、max_retries。此外参考文档列出的_sanitize_config与_adapt_messages_for_o1_models在 Azure 实现中均为 no-op直接原样返回源码注释明确说明Azure does not need——Azure 侧无需对配置做清理或对 o1 系消息做适配。快速上手通过 ModelFactory 创建模型并驱动 ChatAgent官方推荐通过ModelFactory.create创建模型参考仓库中的 examples/models/azure_openai_model_example.pyimport os from camel.agents import ChatAgent from camel.models import ModelFactory from camel.types import ModelPlatformType # 请先设置以下环境变量 # export AZURE_OPENAI_BASE_URL # export AZURE_API_VERSION # export AZURE_OPENAI_API_KEY model ModelFactory.create( model_platformModelPlatformType.AZURE, model_typegpt-4.1, # Azure 部署名 api_keyos.getenv(AZURE_OPENAI_API_KEY), urlos.getenv(AZURE_OPENAI_BASE_URL), api_version2024-12-01-preview, ) # 定义系统消息 sys_msg You are a helpful assistant. # 创建 Agent camel_agent ChatAgent(system_messagesys_msg, modelmodel) user_msg Say hi to CAMEL AI, one open-source community dedicated to the study of autonomous and communicative agents. # 获取回复 response camel_agent.step(user_msg) print(response.msgs[0].content)要点model_type传的是部署名字符串如gpt-4.1也可传ModelType枚举如ModelType.GPT_4O、ModelType.GPT_4_1_MINI测试用例 test/models/test_azure_openai_model.py 对GPT_3_5_TURBO、GPT_4、GPT_4_TURBO、GPT_4O、GPT_4O_MINI等枚举均做了参数化验证显式传入api_version是最稳妥的写法可避免依赖环境变量通过ChatAgent的step()即可完成一次对话推理response.msgs[0].content为生成的文本内容。核心方法解析与请求路由参考文档列出了AzureOpenAIModel的几个核心方法这些方法从OpenAIModel继承并在 Azure 客户端上复用其职责与返回类型如下方法职责返回类型token_counter返回与该模型 token 化风格一致的计数器BaseTokenCounter默认OpenAITokenCounter_run执行 Azure OpenAI Chat Completion 推理ChatCompletion非流式或Stream[ChatCompletionChunk]流式结构化输出流式时返回ChatCompletionStreamManager[BaseModel]_request_chat_completion底层 Chat Completions 请求chat.completions.createChatCompletion或Stream[ChatCompletionChunk]_request_parse结构化输出请求beta.chat.completions.parseChatCompletion_request_stream_parse流式结构化输出解析ChatCompletionStreamManager[BaseModel]stream返回模型是否处于流式模式bool请求路由chat_completions 还是 responses_run是推理的统一入口其路由行为取决于api_mode相关逻辑有明确测试佐证默认模式下调用self._client.chat.completions.create(...)且不会触碰responses.createresponses模式下调用self._client.responses.create(...)并传入model部署名与stream标志。测试用例 test/models/test_azure_openai_model.py 通过 mock 客户端分别断言了两种模式只走对应的调用路径可用test/models/test_azure_openai_model.py中相关用例验证。stream方法的布尔值则取自model_config_dict中的stream配置项用于上层判断是否按流式协议消费结果。Responses API 模式实战当api_moderesponses时AzureOpenAIModel走 Azure OpenAI Responses API。这一模式的核心优势是有状态的响应链通过previous_response_id把多轮请求串成状态链减少重复上下文传输。源码中通过_responses_previous_response_id_by_session与_responses_last_message_count_by_session两个字典按会话session维护链式状态测试断言了每次成功调用后 response ID 会被保存test/models/test_azure_openai_model.py。仓库提供了完整的五合一示例 examples/models/azure_openai_responses_api_example.py覆盖基本对话、工具调用、流式工具调用、结构化输出与流式结构化输出其环境要求为export AZURE_OPENAI_API_KEYyour_azure_openai_api_key export AZURE_OPENAI_BASE_URLhttps://resource.openai.azure.com/ export AZURE_API_VERSION2025-03-01-preview注意model_type传入的部署名必须与 Azure 部署名完全一致。创建 Responses 模式模型from camel.models import ModelFactory from camel.types import ModelPlatformType, ModelType def create_responses_model( stream: bool False, model_type: ModelType ModelType.GPT_4_1_MINI, temperature: float 0.2, tools: list | None None, ): model_config { temperature: temperature, stream: stream, } if tools: model_config[tools] tools if stream: model_config[stream_options] {include_usage: True} return ModelFactory.create( model_platformModelPlatformType.AZURE, model_typemodel_type, model_config_dictmodel_config, api_moderesponses, )场景一工具调用from camel.toolkits import FunctionTool from camel.agents import ChatAgent def get_weather(city: str) - str: rA tiny tool function for demo purposes. fake_weather { beijing: sunny, 28C, new york: cloudy, 19C, san francisco: foggy, 16C, } return fake_weather.get(city.lower(), funknown weather for {city}) weather_tool FunctionTool(get_weather) model create_responses_model( streamFalse, model_typeModelType.GPT_4_1, temperature0.0, tools[weather_tool.get_openai_tool_schema()], ) agent ChatAgent( system_messageYou are a weather assistant. Use tools when needed., modelmodel, tools[weather_tool], ) resp agent.step(How is the weather in Beijing today?) print(resp.msgs[0].content) print(tool_calls:, resp.info.get(tool_calls))Responses API 模式下底层会把 OpenAI 风格的tool_calls历史转换为function_call/function_call_output输入项——该转换逻辑_convert_messages_to_responses_input在测试 test/models/test_azure_openai_model.py 中有明确断言。场景二结构化输出from pydantic import BaseModel, Field class TravelAdvice(BaseModel): city: str Field(descriptionCity name) clothing: str Field(descriptionRecommended clothing) reason: str Field(descriptionBrief reasoning) model create_responses_model(streamFalse) agent ChatAgent( system_messageYou are a travel assistant., modelmodel, ) resp agent.step( I am going to New York in autumn. Give advice as JSON., response_formatTravelAdvice, ) print(raw:, resp.msgs[0].content) print(parsed:, resp.msgs[0].parsed)当传入response_formatPydantic 模型时底层会为 Responses API 附加 JSON Schema 约束测试断言配置中会出现{type: json_schema, name: MySchema}test/models/test_azure_openai_model.py保证模型输出严格符合 schema。场景三流式输出与流式工具调用流式场景需将streamTrue并配合ChatAgent(..., stream_accumulateFalse)逐块消费stream_resp agent.step(How is the weather in Beijing today?) full_text for chunk in stream_resp: msg chunk.msgs[0] if msg.content: full_text msg.content print(msg.content, end, flushTrue) print() print(final:, full_text) print(tool_calls:, stream_resp.info.get(tool_calls)) print(usage:, stream_resp.info.get(usage))流式模式下可通过stream_options{include_usage: True}让响应携带 usage 统计便于做 token 计量与成本核算。测试验证行为保障一览仓库通过 test/models/test_azure_openai_model.py 对AzureOpenAIModel的关键行为做了系统性验证可作为你理解实现细节与排查问题的参考测试用例验证点test_openai_model/test_openai_model_create枚举类型创建、model_config_dict透传、token_counter类型、token 限制与 tiktoken 取值test_api_mode_default_is_chat_completions默认api_mode chat_completionstest_api_mode_responses_sets_moderesponses模式初始化链式状态字典test_api_mode_invalid_raises非法api_mode抛出ValueErrortest_normalize_tools_for_responses_api工具 schema 从嵌套function结构规范化为扁平name/parameters结构test_convert_messages_tool_call_history历史工具调用消息转换为function_call/function_call_outputtest_run_routes_to_responses_apiresponses模式下_run调用responses.createtest_run_chat_completions_mode_does_not_call_responses默认模式只调用chat.completions.createtest_responses_chain_state_saved_after_run成功调用后保存 response ID 以支持状态链test_prepare_responses_request_config_structured_outputresponse_format转换为json_schema文本格式test_prepare_responses_request_config_n_warningResponses 模式不支持n 1发出警告并移除n参数进阶应用Prompt Caching 与混合多智能体Azure 自动 Prompt CachingAzure OpenAI 对 GPT-4o 及以上模型、且请求前缀达到 1024 token 时会自动启用缓存。仓库示例 examples/models/prompt_caching_azure_example.py 展示了在 CAMEL 中让 Agent 自动抓取并分析博客内容、配合ChatGPTConfig(prompt_cache_key...)显式标记缓存的写法model ModelFactory.create( model_platformModelPlatformType.AZURE, model_typedeployment_name, # 默认 gpt-4o api_versionapi_version, # 默认 2024-12-01-preview model_config_dictChatGPTConfig( prompt_cache_keyblog_analysis_cache, # 可选显式缓存键 ).as_dict(), ) agent ChatAgent( system_messageYou are a helpful assistant., modelmodel, tools[FunctionTool(fetch_url)], )该示例还演示了model_type直接读取AZURE_DEPLOYMENT_NAME环境变量缺省gpt-4o的兼容写法。混合多智能体Azure Claude 协作CAMEL 的模型后端彼此独立因此可以在同一个Workforce多智能体工作流中混用不同厂商的模型。仓库 cookbook docs/cookbooks/multi_agent_society/azure_openai_claude_society.md 演示了如何用 Claude 4 与 Azure OpenAI 组合出多研究者协作的智能体社会ARENA AI Alignment 研究场景其中 Azure 模型正是通过ModelPlatformType.AZURE与AzureOpenAIModel注入的。这印证了统一模型后端的设计价值上层任务编排完全感知不到底层厂商差异。常见问题与注意事项api_version必填构造参数与环境变量AZURE_API_VERSION至少提供一个否则抛出ValueError。版本号需与你的 Azure 资源支持范围匹配。model_type即部署名传错部署名会导致 404 或认证失败部署名不一定等于模型 ID请以 Azure 门户中实际创建的部署为准。azure_deployment_name已弃用当前版本会忽略该参数并发出DeprecationWarning请迁移到model_type。Responses 模式的限制n 1不受支持传入会告警并被移除工具调用历史需要按function_call/function_call_output结构转换框架已自动处理。自定义客户端接口约束传入自定义client/async_client时如 RL 框架 AReaL、rLLM 提供的兼容客户端必须实现.chat.completions.create()与.beta.chat.completions.parse()接口且此时kwargs中的客户端初始化参数会被忽略。认证方式除 API Key 外支持通过azure_ad_tokenEntra ID 令牌与azure_ad_token_provider每次请求调用的令牌提供函数适合自动刷新进行认证。超时与重试timeout未指定时依次回落MODEL_TIMEOUT环境变量、默认 180 秒max_retries默认 3 次均可按需调整。如需进一步深入可继续阅读参考文档 docs/reference/camel.models.azure_openai_model.md、继承自OpenAIModel的完整方法实现 camel/models/openai_model.py、模型工厂 camel/models/model_factory.py以及上文提到的 基础示例、Responses API 示例 与 测试用例。【免费下载链接】camel CAMEL: The first and the best multi-agent framework. Finding the Scaling Law of Agents. https://www.camel-ai.org项目地址: https://gitcode.com/GitHub_Trending/ca/camel创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考