Hızlı Başlangıç: Bir AI Gateway tier (önizleme) örneği oluştur

UYGULANIR: AI Gateway seviyesi (önizleme)

Important

AI Gateway seviyesi şu anda halka açık önizleme aşamasında. Kamu önizleme sırasında, AI Gateway seviyesi aşağıdaki bölgelerde mevcuttur:

Birleşik Devletler - Doğu ABD 2
Avrupa - İsveç Orta

Bu hızlı başlangıçta, bir AI Gateway seviye (önizleme) örneği oluşturuyor, sohbet modeli ekliyor, gateway'i çağırıyor, bir çalışma zamanı erişim anahtarı oluşturuyor ve telemetri izliyorsun.

Azure API Management'ten AI Gateway katmanı, yapay zeka iş yükleri için özel bir katmandır. Microsoft Foundry, Azure OpenAI, AWS Bedrock, Google Vertex, OpenAI, Anthropic veya diğer sağlayıcılardan modellere ve mevcut MCP sunucuları, OpenAPI tanımları veya bağlayıcılardan oluşturulan araçlara trafik yönetimini destekler. AI Gateway seviyesi genellikle bir dakika içinde hızlıca tedarik sağlar.

Tamamlanma süresi: yaklaşık 20-30 dakika. Şunları oluşturursunuz: bir ağ geçidi, bir sohbet modeli, bir çalışma zamanı erişim anahtarı ve başarıyla tamamlanan bir sohbet tamamlama isteği.

Note

AI Gateway katmanı genel önizleme aşamasındadır. Önizleme özellikleri, hizmet düzeyi anlaşması olmadan sağlanır ve kuruluşunuz önizleme şartlarını kabul etmedikçe üretim iş yükleri için kullanılmamalıdır.

Prerequisites

Microsoft Entra ID ile bir Azure hesabı. AI Gateway katman önizlemesine erişim şu anda Microsoft Entra ID ile giriş yapan Azure kullanıcılarıyla sınırlıdır.
Bir Azure aboneliği ve bir kaynak grubunda kaynak oluşturma izni (örneğin, Katkıcı rolü).
Microsoft Foundry veya Azure OpenAI'de konuşlandırılmış model gibi en az bir desteklenen model sağlayıcısına erişim.
Sağlayıcınız API anahtarı istiyorsa, anahtarı elinizde bulundurun.
Ağ geçidini çağırmak için curl’ü (kurulum gerektirmez) veya openai paketiyle birlikte Python 3.9 ya da üzeri ya da Node.js 18 ya da üzeri için OpenAI SDK’sını kullanın.

AI Gateway katman portalı bağımsız bir web deneyimidir - Azure portalını kullanmıyorsunuz.

Yapay Zeka Geçidi seviye portalına gidin.ai.gateway.azure.com
Giriş seçeneğini seçin ve Microsoft Entra ID ile kimlik doğrulama yapın.

Portalı modelleri, MCP sunucularını, çalışma zamanı erişim anahtarlarını, politikalarını ve izlemeyi Entra ID izinlerinize göre yönetmek için kullanın. Çalışma zamanı istemcileri portala giriş yapmaz; bunun yerine, daha sonra oluşturacağınız çalışma zamanı erişim anahtarlarıyla ağ geçidini çağırırlar.

2. Bir geçit oluşturun

Portalda Ağ geçidi oluştur seçeneğini seçin. Mevcut bir gateway kullanmak için onu seçin ve bir sonraki adıma geçin.
Bir Ad girin. İsim, çalışma zamanı uç noktasının bir parçası haline gelir:

https://<gateway>.azure-api.net
Aboneliğinizi ve desteklenen bir önizleme bölgesini (Doğu ABD 2 veya İsveç Merkezi) seçin.
Kaynak grubunu isteğe bağlı olarak İlerialtında ayarlayabilirsiniz. Varsayılan olarak, portal sizin için bir tane oluşturur.
Oluştur'i seçin. Aktivasyon genellikle bir dakikadan kısa sürer.

Gateway, Azure aboneliğinizde özel bir kaynaktır. Modelleri eklemeden önce kapasite seçmez veya ölçek birimleri eklemezsiniz. Otomasyon için önizleme yönetim API sürümü 2026-05-01-preview’dir; çalışma zamanı istekleri Azure Resource Manager'ı değil, ağ geçidi ana bilgisayar adını kullanır.

3. Bir model ekleyin

Bir model oluşturmanın en hızlı yolu, onu Microsoft Foundry hesaplarından içe aktarmaktır.

Ana Sayfa, Geçit Geçidinizi Yapılandır bölümünde, Başlat seçeneğini seçin veya rotanın hemen /settings/start üzerinde kurulum sayfasını açın.
Taramak için bir veya daha fazla abonelik seçin. İsteğe göre, sonuçları daraltmak için bir kaynak grubu filtresi uygulayabilirsiniz.
Keşfedilen hesapları gözden geçirin. Dağıtımlar, ana Foundry hesabı (Azure kaynağı) tarafından gruplanır. Seçim hesap başına yapılır: bir hesap seçtiğinizde, sihirbaz tüm model dağıtımlarını içe aktarır.
Bu aktarma için bir arka uç kimlik doğrulama yöntemi seçin:
- Anahtar tabanlı (varsayılan). Ağ geçidi, hesabın API anahtarını saklar ve bunu api-key üst bilgisinde gönderir. Sihirbaz, anahtarı içe aktarma sırasında alır.
- Yönetilen kimlik (Microsoft Entra ID). Gateway, yönetilen kimliğiyle kimlik doğrulama sağlar. Gateway'in yönetilen kimliği yoksa, sihirbaz sistem tarafından atanan bir kimlik etkinleştirir. Eğer zaten varsa, hangi kimliği kullanacağınızı seçersiniz. Sihirbaz, seçilen her hesapta kimliğe Foundry User rolünü atar.
İçe aktar'ı seçin.
İçe Aktar seçildiğinde, sihirbaz herhangi bir şey oluşturmadan önce seçilen her hesap için Gereksinimleri doğrulama denetimini çalıştırır. Bu kontrol, kimlik doğrulamanın doğru yapılandırıldığını ve model adlarının gateway'deki modellerle çakışmadığını doğrular. Kontrolü geçen hesaplar içe aktarılır; başarısız olan hesaplar satır içi bir uyarıyla atlanır ve işlemin geri kalanı devam eder.

Foundry olmayan bir sağlayıcıyı (AWS Bedrock, Google Vertex, OpenAI veya Anthropic) bağlamak için bunun yerine Özel bir model ekle seçeneğini seçin. Modelleri ve araçları yönet bölümünü bkz.

İstemciler, model adını OpenAI uyumlu isteklerdeki model alanına iletir. Bu hızlı başlangıçta gpt-5.6-sol kullanılır; bunu kaydettiğiniz modelle değiştirin.

Tip

Modeli hemen denemek için Discover sayfasını açın ve dahili oyun alanında onu çağıracak modeli seçin. Deneme alanı, ağ geçidinin yerleşik anahtarını kullanır; bu sayede çalışma zamanı erişim anahtarı oluşturmadan önce eklenen modelleri veya araçları keşfedebilir ve test edebilirsiniz.

4. Gateway'i çağır

Gateway, arka uç modelinin desteklediği API'yi açığa çıkarır. Microsoft Foundry, Azure OpenAI, AWS Bedrock, Google Vertex ve OpenAI gibi OpenAI uyumlu sağlayıcıların modelleri OpenAI uyumlu bir uç noktada sunuluyor. Herhangi bir OpenAI istemcisini ağ geçidinin temel URL’sine yönlendirin, api-key başlığını gönderin ve model adını model alanına iletin. Anthropic modeller bunun yerine Anthropic Messages API'sini kullanır; bkz. Modelleri ve araçları yönet.

Hızlı bir test için, gateway'in yerleşik anahtarını kullanın — Discover oyun alanının kullandığı aynı anahtar. Bunu Keys sayfasından kopyalayın; burada yerleşik anahtar, geçitteki her varlığa çalışma zamanı erişimi sağlayan API anahtarlarıyla birlikte listelenir. Kendi uygulamalarınız için bir çalışma zamanı erişim anahtarı oluşturun (bir sonraki bölüme bakınız).

Bu değerleri bir kez ayarlayın:

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

Tip

El ile oluşturmak yerine gateway'inizin genel bakış sayfasından tam olarak temel URL'yi kopyalayın.

Seçtiğiniz müşteriyle ilk görüşmenizi yapın:

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

Tokenları sunucu tarafından gönderilen olaylar olarak yayınlamak için istek gövdesine ekleyin "stream": true .

İstemciyi pip install openai ile kurun.

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)

Tokenları oluşturuldukça akış olarak iletmek için stream=True ekleyin ve yanıt üzerinde yineleme yapın:

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)

Paketi npm install openai ile kurun.

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);

Akış gerçekleştirmek için stream: true ekleyin ve asenkron yanıt üzerinde yineleme yapın.

/chat/completions uç noktasından gelen her yanıt, modele arka planda hangi OpenAI uyumlu sağlayıcı güç verirse versin, OpenAI Chat Completions formatını kullanır.

Yayın dışı bir arama, sohbet tamamlanmasını sağlar:

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

Akış etkinleştirildiğinde, ağ geçidi chat.completion.chunk olaylarını döndürür:

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

Aynı temel URL, OpenAI Yanıtlar API'sine de hizmet verir./responses

Bir istek başarısız olursa, gateway standart bir HTTP durum kodu döner:

Durum	Meaning	Denetlenecek şeyler
400	Geçersiz istek	İstek gövdesini kontrol et.
400	İçerik güvenliği veya IP filtresi tarafından engellendi ya da arka uç tarafından reddedildi	Bir içerik güvenliği politikası, bir promptu veya yanıtı engelleyebilir; ayrıca herhangi bir IP filtre politikasını kontrol edin. Yönetilen kimlik için, arka uç kaynağı üzerindeki ağ geçidi kimliğine Foundry User rolünü atayın. Bkz. Arka uç kimlik doğrulaması için yönetilen kimlik kullan.
401	Eksik veya geçersiz çalışma zamanı erişim anahtarı	Anahtarı `api-key` üst bilgisinde gönderin ve anahtarın etkin olduğunu doğrulayın.
404	Bilinmeyen model	`model` Modeller sayfasında model adıyla eşleştiğini doğrulayın.
429	Bir oran sınırı poliçesi veya arka plan tarafından kısıtlanıyor	Token ve istek hız sınırı politikalarını gözden geçirin ve `Retry-After` yanıt üst bilgisini dikkate alın.
5xx	Arka uç hatası	Arka uç sağlayıcının sağlıklı olduğunu ve sağlayıcı kimlik doğrulamasının geçerli olduğunu doğrulayın.

OpenAI SDK'ları bu durum kodları için tipli istisnalar oluşturur, böylece mevcut hata işleme yönteminiz çalışır:

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. Bir çalışma zamanı erişim anahtarı oluşturun

Uygulamalar, gateway'e yerleşik anahtar yerine çalışma zamanı erişim anahtarı ile kimlik doğrulama sağlar. Her uygulama ve ortam için ayrı bir anahtar oluşturun.

Anahtarlar'ı seçin.
API anahtarı oluştur'u seçin.
gibi quickstart-clientbir ad girin.
Oluştur'i seçin.
Anahtar değerini kopyalayın ve güvenli bir şekilde saklayın. Daha sonra Keys sayfasında tekrar görebilirsiniz.

Gateway seviyesinde çalışma zamanında erişim anahtarları oluşturun. Bu anahtarlar, gateway'deki her model ve araca erişim sağlar. Onları sır gibi ele al. Anahtarları uygulamalar için gizli bir depoda sakla, düzenli olarak döndür ve artık gerekmeyen anahtarları geri alın. Ağ geçidini bir çalışma zamanı erişim anahtarıyla çağırmak için, daha önce gösterilen çağrılarda AI_GATEWAY_API_KEY öğesini bu değere ayarlayın.

6. Telemetriye bak

AI Gateway katmanı OpenTelemetry token kullanım metrikleri yayımlar. Bunları görmek için önce bir telemetri hedefi yapılandırın, ardından istekler gönderin:

Ağ geçidi için Application Insights gibi bir telemetri hedefi yapılandırın. Bkz. Yönet, güvence altına al, ve çalıştır.
Daha önce Call the gateway'de gösterildiği gibi, bir veya daha fazla isteği ağ geçidi üzerinden gönderin.
Token kullanımını incelemek için telemetri hedefinizi açın. Application Insights kullanıyorsanız, portal yerleşik token tüketim paneli sağlar.

Telemetri yalnızca bir hedefe bağlandıktan sonra yayıldığı için, ona güvenmeden önce izlemeyi yapılandırın. Şu anda yayımlanan tek metrik token kullanımıdır; Modeller ve araçlar için loglar, izler ve diğer metrikler yakında gelecek. Arayanlar, sağlayıcı kimlik bilgilerini istemci uygulamalarına açığa çıkarmadan trafiği izleyebilmek için gateway seviyesinde çalışma zamanı erişim anahtarları kullanır. Telemetri hedefi yapılandırmak için Yönet, güvence altına al, ve çalıştır bölümlerine bakabilirsiniz.

Kaynakları temizle

İşin bittiğinde, artık ihtiyacın olmayan kaynakları sil. Sadece değerlendirme için oluşturduğunuz AI Gateway katman örneğini, sağlayıcı test dağıtımlarını ve çalışma zamanı erişim anahtarlarını kaldırın.

Sonraki Adımlar

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Last updated on 2026-07-28