UFO 接入 Azure OpenAIAOAIAPI Key 与 Azure AD 两种认证方式的完整配置指南【免费下载链接】UFOUFO³: Weaving the Digital Agent Galaxy项目地址: https://gitcode.com/GitHub_Trending/uf/UFO导读本文讲解如何在 UFOWeaving the Digital Agent Galaxy中配置config/ufo/agents.yaml使 HOST_AGENT任务规划、APP_AGENT动作执行等核心 Agent 通过 Azure OpenAI 服务AOAI完成 LLM 调用。全文覆盖从创建 Azure OpenAI 资源、获取部署与密钥到 API Key 与 Azure AD 两种认证方式的配置细节并结合ufo/llm/openai.py、ufo/llm/base.py、ufo/config/__init__.py等源码说明底层实现原理。读完本文你将能独立完成 UFO 的 Azure OpenAI 接入、多 Agent 差异化选型与生产级认证配置。为什么选择 Azure OpenAIAzure OpenAI 与标准 OpenAI API 的差异在于模型必须先在 Azure 门户中以部署Deployment的形式创建每次请求都需要携带资源端点Endpoint与 API 版本API Version。UFO 在源码中为此专门支持了两种 API 类型——aoaiAPI Key 认证与azure_adAzure AD 认证两者都映射到同一套OpenAIService实现只是在客户端构造与鉴权方式上有所区别见 ufo/llm/base.py 中的服务映射表。对于企业环境Azure AD 认证可以避免在配置文件中硬编码密钥由身份令牌自动获取与刷新这也是官方推荐用于生产环境的方案。Step 1创建 Azure OpenAI 资源在使用 Azure OpenAI API 之前需要先完成以下准备创建 Azure 账号并开通 Azure OpenAI 服务在 Azure OpenAI Studio或 Azure 门户中创建资源得到形如https://{resource-name}.openai.azure.com的端点Endpoint在资源中部署Deploy模型得到部署名称Deployment Name——注意部署名与模型名如gpt-4o不是同一个概念部署名由你在创建部署时自定义获取API Key用于aoai方式或完成Azure AD 应用注册用于azure_ad方式需要租户 ID 与 API Scope。提示UFO 文档中给出的大多数示例使用2024-02-15-preview作为API_VERSION请以你实际部署时支持的版本为准模板 config/ufo/agents.yaml.template 默认使用2025-02-01-preview。Step 2配置 Agent 设置UFO 的所有 LLM 相关配置都集中在config/ufo/agents.yaml。如果该文件不存在先从模板复制Copy-Item config\ufo\agents.yaml.template config\ufo\agents.yaml之后编辑config/ufo/agents.yaml为HOST_AGENT与APP_AGENT写入 Azure OpenAI 配置。Option 1API Key 认证推荐用于开发环境将API_TYPE设为aoaiHOST_AGENT: VISUAL_MODE: True # 开启视觉模式以理解截图 REASONING_MODEL: False # 若为 o 系列推理模型请设为 True API_TYPE: aoai # 使用 Azure OpenAI API API_BASE: https://YOUR_RESOURCE.openai.azure.com # Azure 端点 API_KEY: YOUR_AOAI_KEY # Azure OpenAI API Key API_VERSION: 2024-02-15-preview # API 版本 API_MODEL: gpt-4o # 模型名 API_DEPLOYMENT_ID: YOUR_DEPLOYMENT_ID # 部署名 APP_AGENT: VISUAL_MODE: True REASONING_MODEL: False API_TYPE: aoai API_BASE: https://YOUR_RESOURCE.openai.azure.com API_KEY: YOUR_AOAI_KEY API_VERSION: 2024-02-15-preview API_MODEL: gpt-4o-mini # APP_AGENT 使用 gpt-4o-mini 以控制成本 API_DEPLOYMENT_ID: YOUR_DEPLOYMENT_IDOption 2Azure AD 认证推荐用于生产环境将API_TYPE设为azure_ad并补充三个 Azure AD 配置项。注意此时不需要API_KEYHOST_AGENT: VISUAL_MODE: True REASONING_MODEL: False API_TYPE: azure_ad # 使用 Azure AD 认证 API_BASE: https://YOUR_RESOURCE.openai.azure.com # Azure 端点 API_VERSION: 2024-02-15-preview API_MODEL: gpt-4o API_DEPLOYMENT_ID: YOUR_DEPLOYMENT_ID # Azure AD 配置 AAD_TENANT_ID: YOUR_TENANT_ID # Azure 租户 ID AAD_API_SCOPE: YOUR_SCOPE # API Scope AAD_API_SCOPE_BASE: YOUR_SCOPE_BASE # Scope 基址不含 api:// 前缀 APP_AGENT: VISUAL_MODE: True REASONING_MODEL: False API_TYPE: azure_ad API_BASE: https://YOUR_RESOURCE.openai.azure.com API_VERSION: 2024-02-15-preview API_MODEL: gpt-4o-mini API_DEPLOYMENT_ID: YOUR_DEPLOYMENT_ID AAD_TENANT_ID: YOUR_TENANT_ID AAD_API_SCOPE: YOUR_SCOPE AAD_API_SCOPE_BASE: YOUR_SCOPE_BASE配置字段说明字段说明VISUAL_MODE设为True开启视觉能力理解截图需要部署支持视觉输入API_TYPEaoai使用 API Key 认证azure_ad使用 Azure AD 认证API_BASEAzure OpenAI 端点格式https://{resource-name}.openai.azure.comAPI_KEYAzure OpenAI API KeyAzure AD 认证不需要API_VERSIONAzure API 版本例如2024-02-15-previewAPI_MODEL模型标识例如gpt-4o、gpt-4o-miniAPI_DEPLOYMENT_IDAzure 部署名AOAI 必填AAD_TENANT_IDAzure 租户 IDAzure AD 认证必填AAD_API_SCOPEAzure AD API ScopeAzure AD 认证必填AAD_API_SCOPE_BASEScope 基址不带api://前缀Azure AD 认证必填以上字段均在配置加载层有对应声明API_DEPLOYMENT_ID、AAD_TENANT_ID、AAD_API_SCOPE、AAD_API_SCOPE_BASE与API_TYPE等都是AgentConfig的已知字段支持大写键名访问与字典式取值见 config/config_schemas.py 的to_dict/from_dict字段映射。Step 3验证配置并启动 UFO配置完成后可以用以下脚本快速核对配置是否正确加载from config.config_loader import get_ufo_config config get_ufo_config() print(fHOST_AGENT model: {config.host_agent.api_model}) print(fHOST_AGENT api_type: {config.host_agent.api_type}) print(fAPP_AGENT model: {config.app_agent.api_model})然后参考 快速上手指南 运行你的第一个任务。源码级原理UFO 如何调用 Azure OpenAI1. 服务工厂aoai/azure_ad都走 OpenAIService在 ufo/llm/base.py 的get_service中aoai与azure_ad都被映射到OpenAIService并统一从ufo/llm/openai.py模块加载service_map { openai: OpenAIService, aoai: OpenAIService, azure_ad: OpenAIService, ... } if name in [aoai, azure_ad, operator]: module import_module(.openai, packageufo.llm)这意味着无论选择哪种认证方式上层 Agent 的调用路径完全一致认证差异被封装在客户端构造阶段。2. 客户端构造AzureOpenAI 与 token providerufo/llm/openai.py 的get_openai_client根据api_type分支构造客户端aoai要求API_KEY与API_VERSION使用AzureOpenAI(azure_endpointapi_base, api_keyapi_key, api_versionapi_version, ...)azure_ad要求AAD_API_SCOPE_BASE与AAD_TENANT_ID先通过get_aad_token_provider获取令牌提供器再以azure_ad_token_providertoken_provider构造AzureOpenAI客户端当配置了USE_RESPONSES: True使用 Responses API时客户端还会附加x-ms-enable-preview: true请求头。若api_type不是三者之一会在初始化时触发assert api_provider in [openai, aoai, azure_ad]的断言失败。3. URL 自动拼接API_DEPLOYMENT_ID如何生效在旧的配置加载逻辑 ufo/config/init.py 的update_api_base中当检测到API_TYPE aoai且API_BASE尚未包含deployments时会自动将端点拼接为{endpoint}/openai/deployments/{deployment_name}/chat/completions?api-version{api_version}同时把API_MODEL覆盖为API_DEPLOYMENT_ID的值。这正是Azure 部署名与模型名分离这一特性的底层体现对 Azure 而言真正用于路由的是部署名而非模型名。也正因如此API_DEPLOYMENT_ID在 AOAI 模式下是必填项若缺失或与门户中的部署名不一致会出现模型不存在的NotFoundError。4. Azure AD 令牌获取多认证模式与令牌缓存get_aad_token_provider见 ufo/llm/openai.py封装了 Azure Identity SDK 的多种认证方式包括AzureCliCredentialAzure CLI、InteractiveBrowserBrokerCredential交互式浏览器登录、ClientSecretCredential、ManagedIdentityCredential、DeviceCodeCredential等并支持将认证记录与令牌缓存在本地文件默认aoai-token-cache.bin避免每次调用重复交互式登录。最终通过get_bearer_token_provider(identity, scope)生成供 OpenAI 客户端使用的令牌提供器。其内部使用api:// AAD_API_SCOPE_BASE /.default作为请求 Scope这也解释了为何文档要求AAD_API_SCOPE_BASE不包含api://前缀。5. 成本估算在 ufo/llm/base.py 的get_cost_estimator中aoai与azure_ad会被统一映射为azure/{model}的价格键从PRICES配置中读取输入/输出单价进行成本估算。这意味着使用 Azure 部署的模型时你可以在 config/ufo/prices.yaml 中为对应模型登记价格让 UFO 自动输出成本统计。多 Agent 差异化配置与成本优化UFO 允许每个 Agent 使用不同的模型与提供方。一个常见的高性价比组合是HOST_AGENTgpt-4o负责任务规划与跨应用协调调用频率较低APP_AGENTgpt-4o-mini负责每个 UI 动作的执行调用频率极高使用小型模型可显著降低成本BACKUP_AGENT/EVALUATION_AGENT可复用同一模型。模板 config/ufo/agents.yaml.template 中BACKUP_AGENT与EVALUATION_AGENT也都预留了aoai/azure_ad的注释配置块可按需启用。若将REASONING_MODEL设为True则适用于 o 系列等推理模型如 o1、o3、o4-mini。使用环境变量保护密钥生产环境建议不要将密钥硬编码进agents.yaml而是通过环境变量注入HOST_AGENT: API_TYPE: aoai API_KEY: ${AZURE_OPENAI_KEY} # 从环境变量读取WindowsPowerShell设置方式$env:AZURE_OPENAI_KEY your-azure-keyLinux/macOS 设置方式export AZURE_OPENAI_KEYyour-azure-key此外agents.yaml包含敏感凭据切勿提交到版本控制应只提交agents.yaml.template。常见问题排查FileNotFoundError: config/ufo/agents.yaml not found执行Copy-Item config\ufo\agents.yaml.template config\ufo\agents.yaml从模板创建。openai.AuthenticationError: Invalid API key核对 API Key 是否正确、是否含多余空格或引号确认API_TYPE与你的认证方式一致azure_ad方式需确认AAD_TENANT_ID与AAD_API_SCOPE_BASE已正确设置。openai.NotFoundError: The model ... does not existAzure 场景下通常意味着API_DEPLOYMENT_ID与门户中的实际部署名不一致或该模型未被部署。openai.RateLimitError: Rate limit exceeded可在 documents/docs/configuration/system/system_config.md 对应的运行时配置中调整请求间隔或为不同 Agent 使用不同的 API Key。更多参考Agent 配置指南 —— 完整的 Agent 配置参考与全部字段表格模型配置总览 —— 对比各家 LLM 提供方的接入方式OpenAI 标准 API 配置 —— 非 Azure 环境的 OpenAI 接入配置模板 —— 仓库内的原始模板含全部注释与BACKUP_AGENT/EVALUATION_AGENT的 Azure 配置示例Azure 客户端实现 与 服务工厂 —— 客户端构造与令牌获取的源码细节【免费下载链接】UFOUFO³: Weaving the Digital Agent Galaxy项目地址: https://gitcode.com/GitHub_Trending/uf/UFO创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考