Rychlý start: Vytvořte instanci AI Gateway tier (preview)

VZTAHUJE SE NA: ÚROVEŇ AI Gateway (náhled)

Important

Vrstva AI Gateway je v současné době ve verzi Public Preview. Během veřejné preview je úroveň AI Gateway dostupná v následujících regionech:

USA – Východní USA 2
Evropa - Švédsko střed

V tomto rychlém úvodu vytvoříte instanci úrovně AI Gateway (Preview), přidáte model chatu, zavoláte bránu, vytvoříte přístupový klíč za běhu a zobrazíte telemetrii.

AI Gateway tier od Azure API Management je specializovaná úroveň pro AI workloady. Podporuje řízení provozu směrovaného na modely — od Microsoft Foundry, Azure OpenAI, AWS Bedrock, Google Vertex, OpenAI, Anthropic nebo od jiných poskytovatelů — a nástroje vytvořené ze stávajících serverů MCP, definic OpenAPI nebo konektorů. AI Gateway se rychle zpřístupní, obvykle během minuty.

Čas na dokončení: asi 20–30 minut. Vytvoříte: jednu bránu, jeden chatovací model, jeden přístupový klíč za běhu a jeden úspěšný požadavek na dokončení chatu.

Poznámka:

Úroveň AI Gateway je ve fázi veřejného náhledu. Preview funkce jsou poskytovány bez dohody o úrovni služeb a neměly by být používány pro produkční pracovní zátěže, pokud vaše organizace nepřijme podmínky náhledu.

Předpoklady

Účet na Azure s Microsoft Entra ID. Přístup k preview úrovně AI Gateway je v současnosti omezen na uživatele Azure, kteří se přihlásí pomocí Microsoft Entra ID.
Předplatné Azure a oprávnění vytvářet zdroje ve skupině zdrojů (například role přispěvatele).
Přístup k alespoň jednomu podporovanému poskytovateli modelů, například k nasazenému modelu v Microsoft Foundry nebo Azure OpenAI.
Pokud váš poskytovatel vyžaduje API klíč, mějte klíč po ruce.
Pro volání brány použijte curl (bez instalace) nebo OpenAI SDK – Python verze 3.9 nebo novší, případně Node.js 18 či novější, s balíčkemopenai.

AI Gateway tier portál je samostatný webový zážitek – Azure portál nepoužíváte.

Přejděte na portál úrovně AI Gateway na adrese ai.gateway.azure.com.
Vyberte Přihlásit se a ověřit se pomocí Microsoft Entra ID.

Použijte portál ke správě modelů, MCP serverů, přístupových klíčů v běhu času, politik a monitorování na základě vašich oprávnění Entra ID. Klienti za běhu se do portálu nepřihlašují – ke gatewayi přistupují pomocí přístupových klíčů za běhu, které vytvoříte později.

2. Vytvořit bránu

V portálu vyberte Vytvořit bránu. Chcete-li použít existující bránu, vyberte ji a přejděte na další krok.
Zadejte Název. Název se stává součástí runtime endpointu:

https://<gateway>.azure-api.net
Vyberte si své předplatné a podporovaný preview region (East US 2 nebo Sweden Central).
Volitelně nastavte skupinu zdrojů pod Pokročilé. Ve výchozím nastavení portál vytvoří jeden pro vás.
Vyberte Vytvořit. Aktivace obvykle trvá méně než minutu.

Gateway je vyhrazený zdroj ve vašem předplatném Azure. Kapacitu nevybíráte ani nepřidáváte měřítkové jednotky před přidáním modelů. Pro automatizaci je verze Preview rozhraní API pro správu 2026-05-01-preview; požadavky za běhu používají název hostitele brány, nikoli Azure Resource Manager.

3. Přidat model

Nejrychlejší způsob, jak vytvořit model, je importovat ho z účtů Microsoft Foundry.

V sekci Domůnakonfigurujte svou bránu, vyberte možnost Začít nebo otevřete stránku nastavení přímo u trasy /settings/start .
Vyberte jedno nebo více předplatných pro kontrolu. Volitelně použijte filtr skupiny zdrojů pro zúžení výsledků.
Prohlédněte si nalezené účty. Nasazení jsou seskupována podle jejich mateřského Foundry účtu (Azure resource). Výběr je podle účtu: když vyberete účet, průvodce importuje všechny jeho modelové nasazení.
Vyberte backendovou autentizační metodu pro tento import:
- Na základě klíče (výchozí). Gateway ukládá API klíč účtu a posílá ho do hlavičky api-key . Čaroděj získá klíč při importu.
- Spravovaná identita (Microsoft Entra ID). Brána se autentizuje pomocí své spravované identity. Pokud brána nemá spravovanou identitu, průvodce povolí systémově přiřazenou identitu. Pokud už existuje, vyberete si, kterou identitu použijete. Čaroděj přiděluje identitě roli uživatele Foundry na každém vybraném účtu.
Vyberte Import.
Když vyberete Import, průvodce spustí kontrolu požadavků pro každý vybraný účet, než cokoli vytvoří. Tato kontrola potvrzuje, že autentizace je správně nakonfigurována a že názvy modelů nejsou v konfliktu s modely již na bráně. Účty, které projdou, se importují; účty, které selžou, se přeskočí s upozorněním v řádku a zbytek procesu pokračuje.

Pro připojení k poskytovateli mimo Foundry (AWS Bedrock, Google Vertex, OpenAI nebo Anthropic) zvolte místo toho Přidat vlastní model. Viz Spravovat modely a nástroje.

Volající předávají název modelu v poli model v požadavcích kompatibilních s OpenAI. Tento rychlý úvod používá gpt-5.6-sol; nahraďte jej modelem, který jste zaregistrovali.

Tip

Chcete-li model hned vyzkoušet, otevřete stránku Discover a vyberte model, aby se spustil v integrovaném testovacím prostředí. Playground používá vestavěný klíč brány, takže můžete prozkoumat a vyzkoušet přidané modely nebo nástroje dříve, než vytvoříte přístupový klíč modulu runtime.

4. Vyvolejte bránu

Gateway zpřístupňuje API, které backendový model podporuje. Modely od poskytovatelů kompatibilních s OpenAI — jako jsou Microsoft Foundry, Azure OpenAI, AWS Bedrock, Google Vertex a OpenAI — jsou poskytovány na koncovém bodě kompatibilním s OpenAI. Nasměrujte libovolného klienta OpenAI na základní URL brány, pošlete hlavičku api-key a zadejte název modelu do model pole. Anthropic modely místo toho používají API Anthropic Messages; viz Spravovat modely a nástroje.

Pro rychlý test použijte vestavěný klíč brány — stejný klíč, jaký používá Discover playground. Zkopírujte ho ze stránky Klíče , kde je vestavěný klíč uveden spolu s API klíči, které umožňují přístup ke všem assetům v bráně za běhu času. Pro své vlastní aplikace si místo toho vytvořte přístupový klíč pro běh (viz další část).

Nastavte tyto hodnoty jednou:

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

Tip

Zkopírujte přesnou základní URL z přehledové stránky vašeho gateway, místo abyste ji vytvářeli ručně.

Udělejte první hovor s klientem dle vlastního výběru:

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." }
    ]
  }'

Pro streamování tokenů jako událostí odeslaných serverem přidejte "stream": true do těla požadavků.

Nainstalujte klienta pomocí 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)

Pro streamování tokenů při jejich generování stream=True přidejte a iterujte odpověď:

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)

Nainstalujte balíček pomocí 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);

Pro streamování přidejte stream: true a iterujte přes asynchronní odpověď.

Každá odpověď z endpointu /chat/completions používá formát OpenAI Chat Completions bez ohledu na to, který poskytovatel kompatibilní s OpenAI model zajišťuje.

Volání bez streamování vrátí dokončení chatu:

{
  "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 }
}

Při zapnutí streamování brána vrací chat.completion.chunk události:

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

Stejná základní adresa URL slouží také pro rozhraní OpenAI Responses API na adrese /responses.

Pokud požadavek selže, brána vrátí standardní HTTP stavový kód:

Status	Meaning	Co zkontrolovat
400	Neplatný požadavek	Zkontrolujte tělo žádostí.
400	Blokováno bezpečností obsahu nebo IP filtrem, nebo zamítnuto backendem	Politika bezpečnosti obsahu může blokovat výzvu nebo odpověď; Zkontrolujte také jakoukoli politiku IP filtrů. Pro spravovanou identitu přiřaďte roli uživatele Foundry identitě brány na backendovém zdroji. Viz Použít spravovanou identitu pro backendovou autentizaci.
401	Chybějící nebo neplatný přístupový klíč za běhu	Pošlete klíč do hlavičky `api-key` a potvrďte, že je klíč aktivní.
404	Neznámý model	Potvrďte, že `model` hodnota odpovídá názvu modelu na stránce Modely .
429	Omezené politikou limitu sazeb nebo backendem	Prohlédněte si politiky limitu rychlosti tokenů a požadavků a dodržujte hlavičku `Retry-After` odpovědi.
5xx	Chyba na pozadí	Ověřte, že poskytovatel backendu je zdravý a že oprávnění poskytovatele je platné.

OpenAI SDK vytvářejí typované výjimky pro tyto stavové kódy, takže vaše stávající zpracování chyb funguje:

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. Vytvořte přístupový klíč za běhu

Aplikace se autentizují k bráně pomocí runtime přístupového klíče místo vestavěného klíče. Vytvořte samostatný klíč pro každou aplikaci a prostředí.

Vyberte klíče.
Vyberte Vytvořit API klíč.
Zadejte název, například quickstart-client.
Vyberte Vytvořit.
Zkopírujte klíčovou hodnotu a uložte ji bezpečně. Později si ho můžete znovu prohlédnout na stránce Klíče .

Vytvořte klíče přístupu za běhu na úrovni brány. Tyto klíče umožňují přístup ke každému modelu a nástroji v bráně. Chovej se k nim jako k tajemstvím. Ukládejte klíče do tajného úložiště pro aplikace, pravidelně je otáčejte a odebírejte klíče, které již nejsou potřeba. Pro volání brány pomocí přístupového klíče modulu runtime nastavte AI_GATEWAY_API_KEY na jeho hodnotu ve voláních uvedených výše.

6. Zobrazit telemetrii

Úroveň AI Gateway zobrazuje metriky využití tokenů OpenTelemetry. Pro jejich zobrazení nejprve nakonfigurujte telemetrický cíl a poté odesílejte požadavky:

Nakonfigurujte telemetrický cíl pro bránu, například Application Insights. Viz Spravovat, zabezpečovat a provozovat.
Odešlete jeden či více požadavků prostřednictvím gatewaye, jak je uvedeno výše v Call the gateway.
Otevřete telemetrický cíl a zkontrolujte využití tokenů. Pokud používáte Application Insights, portál poskytuje vestavěný dashboard spotřeby tokenů.

Protože telemetrie se vysílá až po připojení k cíli, nastavte monitorování dříve, než se na něj spoléháte. Využití tokenů je v současnosti jedinou vykazovanou metrikou; logy, trasování a další metriky pro modely a nástroje budou brzy k dispozici. Volající používají přístupové klíče na úrovni brány, takže můžete sledovat provoz, aniž byste vystavovali přihlašovací údaje poskytovatelů klientským aplikacím. Konfiguraci telemetrického cíle naleznete v Govern, secure, and operate.

Vyčistěte zdroje

Až skončíte, smažte všechny zdroje, které už nepotřebujete. Odstraňte instanci AI Gateway tier, testovací nasazení poskytovatelů a přístupové klíče za běhu, které jste vytvořili pouze pro vyhodnocení.

Další kroky

Váš názor

Byla tato stránka užitečná?

Last updated on 2026-07-28