快速入门：创建 AI 网关层级（预览）实例

适用于：AI Gateway 层级（预览）

Important

AI Gateway 级别目前处于公开预览阶段。 在公开预览阶段，AI Gateway 层级可在以下地区提供：

• 美国 - 美国东部 2
• 欧洲 - 瑞典中央

在这个快速入门中，你创建一个 AI 网关层（预览）实例，添加聊天模型，调用网关，创建运行时访问密钥，并查看遥测数据。

Azure API 管理 的 AI Gateway 层是专门用于 AI 工作负载的层级。 它支持管理面向模型的流量——这些模型来自 Microsoft Foundry、Azure OpenAI、AWS Bedrock、Google Vertex、OpenAI、Anthropic 或其他提供商——以及基于现有 MCP 服务器、OpenAPI 定义或连接器创建的工具。 AI网关层的配置非常快，通常一分钟内完成。

完成时间： 大约20-30分钟。 你创建： 一个网关，一个聊天模型，一个运行时访问密钥，以及一个成功的聊天完成请求。

注释

AI Gateway 层级现已进入公开预览阶段。 预览版功能不提供服务级别协议，除非你的组织接受预览版条款，否则不应将其用于生产环境的工作负载。

Prerequisites

• 具有 Microsoft Entra ID 的 Azure 帐户。 目前，使用 Microsoft Entra ID 登录的 Azure 用户可访问 AI Gateway tier 预览版。
• 一个 Azure 订阅，以及在资源组中创建资源的权限（例如，参与者角色）。
• 至少访问一个支持的模型提供者，例如Microsoft Foundry中已部署的模型或Azure OpenAI。
• 如果你的提供商需要API密钥，务必准备好密钥。
• 调用网关时，使用curl（无需安装）或OpenAI SDK——Python 3.9及以上版本，或 Node.js 18及以后版本，配合openai包使用。

1. 登录到 AI Gateway 层级门户

AI Gateway 层级门户是一个独立的网页体验——你不需要用 Azure 门户。

1. 前往位于 ai.gateway.azure.com 的 AI Gateway 层级门户。
2. 选择登录并使用 Microsoft Entra ID 进行身份验证。

使用该门户管理模型、MCP服务器、运行时访问密钥、策略和监控，基于您的Entra ID权限。 运行时调用者不登录门户——他们用你后来创建的运行时访问密钥调用网关。

2. 创建网关

1. 在门户中，选择 创建网关。 要改用现有网关，请选择它并跳至下一步。

2. 输入 名称。 该名称成为运行时端点的一部分：

   https://<gateway>.azure-api.net

3. 选择您的 订阅 和支持的预览区域（East US 2 或 Sweden Central）。

4. 可选地将 资源组 设置为 高级。 默认情况下，门户会为你创建一个。

5. 选择“创建”。 激活通常不到一分钟。

网关是您的 Azure 订阅中的专用资源。 你不会在添加模型前选择容量或添加比例单位。 自动化的预览管理API版本是2026-05-01-preview;运行时请求使用网关主机名称，而非Azure 资源管理器。

3. 添加模型

创建模型最快的方式是从Microsoft Foundry账户导入模型。

1. 在 “主页>配置你的网关”中，选择 “开始 ”选项，或直接在路由处 /settings/start 打开设置页面。

   

2. 选择要扫描的一个或多个订阅。 可选地，应用 资源组 筛选器来缩小结果范围。

3. 查看已发现的账户。 部署按其父 Foundry 账户（Azure 资源）分组。 选择是 按账户进行的：当你选择账户时，向导会导入其所有模型部署。

   

4. 为此导入选择一种后端 认证方式 ：

   • 基于密钥（默认）。 网关会存储账户的 API 密钥，并在 api-key 标头中发送该密钥。 向导在导入时取回密钥。
   • Managed identity （Microsoft Entra ID）. 网关使用其托管标识进行身份验证。 如果网关没有托管标识，向导会启用系统分配的托管标识。 如果已存在一个身份，则可选择要使用的身份。 该向导会在每个选定的帐户为该标识授予 Foundry 用户角色。

5. 选择“导入”。

6. 当你选择 导入时，向导会在创建任何东西之前，对每个选中的账户执行 一次验证需求 检查。 此检查确认认证配置正确，且型号名称不会与网关上的模型冲突。 通过验证的帐户将被导入；未通过验证的帐户将被跳过并显示内联警告，随后执行流程继续进行。

要连接非 Foundry 提供商（AWS Bedrock、Google Vertex、OpenAI 或 Anthropic），请改为选择 添加自定义模型。 参见 “管理模型和工具”。

调用者在兼容 OpenAI 的请求字段中传递型号名称 model 。 本快速入门使用的是 gpt-5.6-sol；请将其替换为你已注册的模型。

小窍门

要立即尝试该模型，请打开 “发现 ”页面，选择该模型在内置游乐场中调用。 游乐场使用网关内置的密钥，因此你可以在创建运行时访问密钥前探索和测试新增的模型或工具。

4. 呼叫网关

网关会暴露后端模型支持的API。 来自兼容OpenAI的供应商的模型——如Microsoft Foundry、Azure OpenAI、AWS Bedrock、Google Vertex和OpenAI——都被服务于兼容OpenAI的端点上。 将任何 OpenAI 客户端指向网关基础 URL，发送一个 api-key 标头，并在 model 字段中传入模型名称。 Anthropic 模型则使用 Anthropic Messages API;参见管理模型和工具。

为了快速测试，可以使用网关 内置的密钥 ——Discover Playground使用的密钥。 从 密钥 页面复制，该页面列出了内置密钥和赋予网关中每个资产运行时访问权限的API密钥。 对于你自己的应用程序，可以创建一个运行时访问密钥（见下一节）。

将这些数值设置一次：

export AI_GATEWAY_BASE_URL="https://<gateway>.azure-api.net/default/models/openai/v1"
export AI_GATEWAY_API_KEY="<gateway-key>"

小窍门

请从网关的概览页面复制精确的基准 URL，而不是手动构建。

请与您选择的客户进行首次通话：

curl

curl "$AI_GATEWAY_BASE_URL/chat/completions" \
  -H "Content-Type: application/json" \
  -H "api-key: $AI_GATEWAY_API_KEY" \
  -d '{
    "model": "gpt-5.6-sol",
    "messages": [
      { "role": "system", "content": "You are a helpful assistant." },
      { "role": "user", "content": "Give me three benefits of using an AI gateway." }
    ]
  }'

要以服务器发送事件的形式流式传输令牌，请在请求体中添加 "stream": true。

Python

使用 pip install openai 安装客户端。

import os
from openai import OpenAI

# The gateway reads the api-key header, not the api_key argument.
client = OpenAI(
    base_url=os.environ["AI_GATEWAY_BASE_URL"],
    api_key="unused",
    default_headers={"api-key": os.environ["AI_GATEWAY_API_KEY"]},
)

response = client.chat.completions.create(
    model="gpt-5.6-sol",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Give me three benefits of using an AI gateway."},
    ],
)
print(response.choices[0].message.content)

若要流式传输刚生成的令牌，请添加 stream=True 并遍历响应：

stream = client.chat.completions.create(
    model="gpt-5.6-sol",
    messages=[{"role": "user", "content": "Stream a short greeting."}],
    stream=True,
)
for chunk in stream:
    print(chunk.choices[0].delta.content or "", end="", flush=True)

Node.js

使用 npm install openai 安装该软件包。

import OpenAI from "openai";

// The gateway reads the api-key header, not the apiKey argument.
const client = new OpenAI({
  baseURL: process.env.AI_GATEWAY_BASE_URL,
  apiKey: "unused",
  defaultHeaders: { "api-key": process.env.AI_GATEWAY_API_KEY },
});

const response = await client.chat.completions.create({
  model: "gpt-5.6-sol",
  messages: [
    { role: "system", content: "You are a helpful assistant." },
    { role: "user", content: "Give me three benefits of using an AI gateway." },
  ],
});
console.log(response.choices[0].message.content);

要流式传输，添加 stream: true 并重复异步响应。

来自 /chat/completions 端点的每个响应都使用 OpenAI Chat Completions 格式，无论该模型由哪个兼容 OpenAI 的提供商提供支持。

非流式调用会返回一个聊天完成事件：

{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "model": "gpt-5.6-sol",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "1. Centralized governance ...\n2. ...\n3. ..." },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 24, "completion_tokens": 61, "total_tokens": 85 }
}

启用流媒体时，网关返回 chat.completion.chunk 事件：

{
  "id": "chatcmpl-...",
  "object": "chat.completion.chunk",
  "model": "gpt-5.6-sol",
  "choices": [
    { "index": 0, "delta": { "content": "Hello" }, "finish_reason": null }
  ]
}

同一基础URL也为OpenAI响应API（地址 /responses）提供服务。

如果请求失败，网关会返回一个标准的HTTP状态码：

Status	Meaning	需要检查的事项
400	请求无效	查看请求正文。
400	被内容安全或IP过滤器阻挡，或被后端拒绝	内容安全策略可以阻止提示或回复;还要检查任何IP过滤策略。 对于托管标识，请将 Foundry 用户角色分配给后端资源上的网关标识。 参见 “使用管理身份进行后端认证”。
401	缺失或无效的运行时访问密钥	在 api-key 标头中发送密钥，并确认该密钥处于有效状态。
404	未知型号	确认 model 该价值是否与 模型 页面上的型号名称相符。
429	受到速率限制策略或后端限制	请检查令牌和请求速率限制策略，并遵守 Retry-After 响应头。
5xx	后端错误	确认后端提供商是健康的，且提供者凭证有效。

OpenAI SDK 会为这些状态码设置类型异常，所以你现有的错误处理方式是有效的：

from openai import AuthenticationError, RateLimitError, APIStatusError

try:
    response = client.chat.completions.create(
        model="gpt-5.6-sol",
        messages=[{"role": "user", "content": "Hello"}],
    )
except AuthenticationError:
    ...  # 401 — check the api-key header and that the key is active
except RateLimitError:
    ...  # 429 — back off and honor the Retry-After header
except APIStatusError as e:
    ...  # inspect e.status_code for 400, 403, 404, or 5xx

5. 创建运行时访问密钥

应用程序通过运行时访问密钥而非内置密钥向网关进行认证。 为每个应用和环境创建一个独立的密钥。

1. 选择密钥。
2. 选择“创建 API 密钥”。
3. 输入名称，例如 quickstart-client。
4. 选择“创建”。
5. 复制键值并安全存储。 你也可以稍后在 Keys 页面再次查看。

在网关层创建运行时访问密钥。 这些密钥允许访问网关中的所有模型和工具。 把它们当作秘密对待。 将密钥存储在应用的秘密存储中，定期轮换，并撤销不再需要的密钥。 要用运行时访问键调用网关，将 AI_GATEWAY_API_KEY 设置为前面所示调用中的值。

6. 查看遥测

AI网关层级会发布OpenTelemetry代币使用指标。 要查看它们，先配置遥测目的地，然后发送请求：

1. 为网关配置遥测目标，例如 Application Insights。 参见 治理、保障和运营。
2. 通过网关发送一个或多个请求，如前面“ 呼叫网关”所示。
3. 打开你的遥测目标以查看令牌使用情况。 如果你使用Application Insights，门户会内置代币使用仪表盘。

因为遥测数据只有在连接目标后才会发出，所以在依赖它之前，先先配置监测。 目前唯一的指标是代币使用;模型和工具的日志、追踪和其他指标即将推出。 调用方使用网关级运行时访问密钥，因此你可以监控流量，而无需向客户端应用暴露提供程序凭据。 要配置遥测目的地，请参见 “治理”、“安全”和“操作”。

清理资源

完成后，删除不再需要的资源。 移除你仅为评估创建的 AI Gateway 层实例、提供商测试部署和运行时访问密钥。

后续步骤

• 添加代理可以调用的MCP工具
• 将治理政策应用于你的模型和工具
• 配置专用网络
• 管理模型和工具
• AI Gateway 层级概述