你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站,请访问 https://docs.azure.cn。

创建和管理统一模型 API

适用于:开发者 |基础版 |基础版 v2 |标准版 |标准版 v2 |高级版 |高级版 v2

可以在 Azure API 管理中创建统一的模型 API,以通过单个面向客户端的终结点公开多个 LLM 后端。 客户端应用程序使用一种熟悉的 API 格式(OpenAI 聊天完成 API),而 API 管理使用 OpenAI 聊天完成 API 或Anthropic消息 API 自动将请求转换为后端模型。

注释

统一模型 API 目前已在 V2 层级上线(GA)。 在经典层中,可通过 AI 网关早期发布通道提前访问此功能。

通过单一 API 层统一管理模型访问,您可以:

  • 独立于后端模型使用的格式,对客户端的单个 API 格式进行标准化。
  • 通过跨模型提供程序的策略统一可观测性、安全性和治理。
  • 配置模型提供商之间的模型故障转移。
  • 使用别名将面向客户端的模型名称与后端模型名称分离。

若要详细了解如何在 API 管理中管理 AI API,请参阅 Azure API 管理 中的 AI 网关功能。

支持的后端

统一模型 API 支持以下后端 API 格式:

  • OpenAI 聊天完成 API
  • 人类消息 API

先决条件

创建统一模型 API - Azure门户

使用以下步骤在 API 管理中创建统一的模型 API。

创建 API 时,API 管理会自动配置:

  • 一个用于模型发现的 /models 端点,列出所有已配置的模型。
  • 单个路由终结点,例如 /llm/v1/chat/completions 接受 OpenAI 聊天完成格式的请求。
  • 为添加的每个后端模型设置转换逻辑的格式。
  • 将请求定向到正确的提供程序终结点的后端资源。

若要创建统一模型 API,请执行以下操作:

  1. 在 Azure 门户中,转到 API 管理实例。

  2. 在边栏菜单中的 “API”下,选择“ 模型>+ 添加>统一模型 API”。

    Azure门户中统一模型API瓷砖的截图。

  3. 在 “配置统一模型 API ”选项卡上:

    1. 输入 API 的 显示名称 。 API 管理会根据显示名称自动生成 API 名称 ,但如果需要,可以对其进行编辑。
    2. 在 API 路径中,输入客户端用于调用 API 的路径。 默认值为 /llm/v1,这会导致聊天完成终结点位于 /llm/v1/chat/completions。
    3. (可选)选择要与 API 关联的一个或多个 产品 。
    4. 选择“下一步”。
  4. 在“ 配置模型 ”选项卡上,选择“ + 添加 ”以打开 “添加模型 ”窗格,然后为每个模型部署配置以下设置:

    1. 在 后端配置下:

      • 在 Model 中,输入后端模型名称(例如, gpt-4o 或 claude-sonnet-4.6)。
      • 在 API 格式中,选择后端模型所需的格式,例如 OpenAI 聊天完成 API 或 Anthropic 消息 API。
      • 在 URL 中,输入后端终结点 URL,例如,在 Foundry 中部署模型,或者对于其他提供程序,输入提供程序的 API 终结点 URL。
    2. 在 “授权凭据”下,选择 API 管理如何向后端进行身份验证:

      • 头部:输入 头部名称 (例如, api-key 或 Authorization)和对应的 头部值 (你的API密钥或秘密)。
      • 托管身份:在 Azure 中进行模型部署时,您可以使用实例的系统分配的托管身份或用户分配的托管身份来向后端进行身份验证。

      有关托管身份设置的说明,请参阅 authentication-managed-identity 策略的参考文档。

    在门户中添加模型设置的“添加模型”面板截图。

  5. 在“ 管理令牌使用 ”选项卡上,根据需要配置以下策略来监视和管理令牌使用情况:

  6. 在“设置 AI 内容安全性选项卡上,可以选择配置Azure AI 内容安全服务以阻止包含不安全内容的提示:

  7. 选择查看 + 创建,然后选择创建。

管理模型别名

模型别名为客户端提供了一个稳定且不依赖提供方的名称,用于调用模型。 通过分配别名(例如 gpt 或 claude-sonnet)将面向客户端的模型名称与实际的后端部署分离。 升级模型或想要运行 A/B 测试时,无需对客户端代码进行任何更改即可更新别名目标。

更新或添加模型别名

在创建统一模型 API 后更新模型别名:

  1. 在 Azure 门户中,转到 API 管理实例,然后选择 APIs。
  2. 选择统一模型 API。
  3. 选择“ 模型 ”选项卡以更新或添加模型别名。
    • 若要更新面向客户端的别名,请选择要更新的别名,然后更新 后端配置 以指定后端模型。 为新后端添加 授权凭据 。
    • 若要添加新模型,请选择“ + 添加 ”并配置后端、授权和客户端设置,如上一部分所述。
  4. 选择“保存”。

查找模型别名

开发人员可以通过调用 /models 统一模型 API 的终结点来发现可用的模型及其别名。 API 管理返回具有其面向客户端的别名的模型列表。

从客户端应用程序调用 API

客户端应用程序可以使用任何与 OpenAI 兼容的 SDK 调用统一模型 API。 将 SDK 的基本 URL 指向 API 管理终结点,并使用 API 管理订阅密钥或其他受支持的身份验证方法进行身份验证。

以下示例使用 Python OpenAI SDK,并在标头中传递 API 管理订阅密钥进行身份验证。 请求正文指定 API 管理中配置的面向客户端的模型别名,例如, gpt 或 claude-sonnet.:

[!重要提示]

Python OpenAI SDK 将api_key值发送为 Authorization: Bearer <api_key>。 它不会在 API Management 订阅密钥标头中发送 api_key。 要使用带 API 管理订阅密钥的此示例,请将properties.subscriptionKeyParameterNames.bearer设置为enabled,以启用该 API 的承载订阅密钥识别。 默认情况下,识别功能是被禁用的。 更多信息请参见 在 Authorization 标头中使用订阅密钥。

该订阅密钥用于向 API Management 验证客户端身份。 它不是模型提供者的API密钥,也不是OAuth访问令牌。 分别配置 API Management 的凭证或托管身份,针对每个后端。

from openai import OpenAI

client = OpenAI(
    base_url="https://<apim-instance>.azure-api.net/llm/v1",
    api_key="<api-management-subscription-key>",
)

# Specify the client-facing model alias
response = client.chat.completions.create(
    model="gpt",  # or "claude-sonnet", "gemini", or any other configured alias
    messages=[{"role": "user", "content": "What can you do?"}],
)
print(response.choices[0].message.content)

若要切换到其他后端模型,只需更改 model 的值。 不需要其他代码更改。