Mulai cepat: Buat instans tingkat AI Gateway (pratinjau)

BERLAKU UNTUK: tingkat AI Gateway (pratinjau)

Important

Tingkatan AI Gateway saat ini berada dalam pratinjau publik. Selama pratinjau publik, tingkatan AI Gateway tersedia di wilayah berikut ini:

Amerika Serikat - East US 2
Eropa - Swedia Tengah

Dalam panduan memulai cepat ini, Anda membuat instans tingkat AI Gateway (pratinjau), menambahkan model obrolan, memanggil gateway, membuat kunci akses runtime, dan melihat telemetri.

Tier AI Gateway dari Azure API Management adalah tier khusus untuk beban kerja AI. Aplikasi ini mendukung pengelolaan lalu lintas ke model — mulai dari Microsoft Foundry, Azure OpenAI, AWS Bedrock, Google Vertex, OpenAI, Anthropic, atau penyedia lainnya — serta alat yang dibuat dari server MCP yang sudah ada, definisi OpenAPI, atau konektor. Tingkat AI Gateway disediakan dengan cepat, biasanya dalam satu menit.

Waktu penyelesaian: sekitar 20-30 menit. Anda membuat: satu gateway, satu model chat, satu kunci akses runtime, dan satu permintaan penyelesaian chat yang berhasil.

Note

Tier AI Gateway sedang dalam pratinjau publik. Fitur pratinjau disediakan tanpa perjanjian tingkat layanan dan tidak boleh digunakan untuk beban kerja produksi kecuali organisasi Anda menerima syarat pratinjau.

Prasyarat

Akun Azure dengan Microsoft Entra ID. Akses ke pratinjau tier AI Gateway saat ini dibatasi hanya untuk pengguna Azure yang masuk dengan Microsoft Entra ID.
Langganan Azure, dan izin untuk membuat sumber daya dalam grup sumber daya (misalnya, peran Kontributor).
Akses ke setidaknya satu penyedia model yang didukung, seperti model yang diterapkan di Microsoft Foundry atau Azure OpenAI.
Jika penyedia Anda memerlukan kunci API, siapkan kunci tersebut.
Untuk memanggil gateway, gunakan curl (tanpa instalasi) atau OpenAI SDK - Python 3.9 atau lebih baru, atau Node.js 18 atau lebih baru, bersama openai paket.

Portal tier AI Gateway adalah pengalaman web mandiri - Anda tidak menggunakan portal Azure.

Kunjungi portal tingkat AI Gateway di ai.gateway.azure.com.
Pilih Masuk dan autentikasi dengan Microsoft Entra ID.

Gunakan portal untuk mengelola model, server MCP, kunci akses runtime, kebijakan, dan pemantauan, berdasarkan izin Entra ID Anda. Pemanggil runtime tidak perlu masuk ke portal—mereka mengakses gateway dengan kunci akses runtime yang nanti Anda buat.

2. Buat gerbang

Di portal, pilih Buat gateway. Untuk menggunakan gateway yang sudah ada, pilih gateway tersebut dan lompat ke langkah berikutnya.
Masukkan nama . Nama menjadi bagian dari endpoint runtime:

https://<gateway>.azure-api.net
Pilih Langganan Anda dan wilayah pratinjau yang didukung (East US 2 atau Sweden Central).
Secara opsional, atur grup Resource di bawah Advanced. Secara default, portal membuat satu untuk Anda.
Pilih Buat. Aktivasi biasanya memakan waktu kurang dari satu menit.

Gateway adalah sumber daya khusus dalam langganan Azure Anda. Anda tidak memilih kapasitas atau menambah satuan skala sebelum menambahkan model. Untuk otomatisasi, versi API manajemen pratinjau adalah 2026-05-01-preview; permintaan runtime menggunakan nama host gateway, bukan Azure Resource Manager.

3. Tambahkan model

Cara tercepat untuk membuat model adalah dengan mengimpornya dari akun Microsoft Foundry.

Di bawah Beranda, Konfigurasikan gateway Anda, pilih opsi Mulai atau buka halaman pengaturan langsung di /settings/start rute.
Pilih satu atau lebih langganan untuk dipindai. Opsional, terapkan filter grup sumber daya untuk mempersempit hasil.
Tinjau akun yang telah ditemukan. Deployment dikelompokkan berdasarkan akun Foundry induk mereka (sumber daya Azure). Seleksi dilakukan per akun: saat Anda memilih akun, wizard mengimpor semua penerapan modelnya.
Pilih metode autentikasi backend untuk impor ini:
- Berbasis kunci (default). Gateway menyimpan kunci API akun dan mengirimkannya di api-key header. Wizard mengambil kunci saat waktu impor.
- Identitas terkelola (Microsoft Entra ID). Gateway ini mengautentikasi dengan identitas yang dikelola. Jika gateway tidak memiliki identitas yang dikelola, wizard akan mengaktifkan identitas yang ditetapkan oleh sistem. Jika sudah ada, Anda memilih identitas mana yang akan digunakan. Panduan memberikan peran Pengguna Foundry kepada identitas pada setiap akun yang dipilih.
Pilih Import.
Saat Anda memilih Impor, wizard menjalankan pemeriksaan Verifikasi persyaratan untuk setiap akun yang dipilih sebelum membuat apa pun. Pemeriksaan ini mengonfirmasi bahwa autentikasi dikonfigurasi dengan benar dan nama model tidak bertentangan dengan model yang sudah ada di gateway. Akun yang lolos akan diimpor; akun yang gagal akan diabaikan dengan peringatan langsung di baris, dan proses selebihnya tetap berlanjut.

Untuk menghubungkan penyedia non-Foundry (AWS Bedrock, Google Vertex, OpenAI, atau Anthropic), pilih Tambahkan model kustom sebagai gantinya. Lihat Kelola model dan alat.

Pemanggil meneruskan nama model dalam kolom model pada permintaan yang kompatibel dengan OpenAI. Quickstart ini menggunakan gpt-5.6-sol; menggantinya dengan model yang Anda daftarkan.

Tip

Untuk mencoba model segera, buka halaman Discover dan pilih model untuk memanggilnya di playground bawaan. Playground menggunakan kunci bawaan gateway, sehingga Anda dapat menjelajahi dan menguji model atau alat tambahan sebelum membuat kunci akses runtime.

4. Hubungi gateway

Gateway menampilkan API yang didukung oleh model backend. Model dari penyedia yang kompatibel dengan OpenAI — seperti Microsoft Foundry, Azure OpenAI, AWS Bedrock, Google Vertex, dan OpenAI — disajikan pada endpoint yang kompatibel dengan OpenAI. Arahkan klien OpenAI mana pun ke URL dasar gateway, kirim api-key header, dan masukkan nama model ke model kolom. Model Anthropic menggunakan API Anthropic Messages sebagai gantinya; lihat Kelola model dan alat.

Untuk pengujian cepat, gunakan kunci bawaan gateway — kunci yang sama yang digunakan oleh playground Discover. Salin dari halaman Keys , yang mencantumkan kunci bawaan bersama dengan kunci API yang memberikan akses runtime ke setiap aset di gateway. Untuk aplikasi Anda sendiri, buatlah kunci akses runtime sebagai gantinya (lihat bagian berikutnya).

Atur nilai-nilai ini sekali:

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

Tip

Salin URL dasar yang tepat dari halaman ikhtisar gateway Anda daripada membangunnya secara manual.

Lakukan panggilan pertama Anda dengan klien pilihan Anda:

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

Untuk streaming token sebagai event yang dikirim server, tambahkan "stream": true ke isi permintaan.

Instal klien dengan 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)

Untuk streaming token saat dihasilkan, tambahkan stream=True dan iterasi responsnya:

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)

Instal paket dengan 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);

Untuk melakukan streaming, tambahkan stream: true dan lakukan iterasi pada respons asinkron.

Setiap respons dari /chat/completions endpoint menggunakan format OpenAI Chat Completions, penyedia mana pun yang kompatibel dengan OpenAI yang mendukung model tersebut.

Panggilan tanpa streaming mengembalikan penyelesaian percakapan:

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

Dengan streaming diaktifkan, gateway mengembalikan chat.completion.chunk event:

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

URL dasar yang sama juga melayani API Respons OpenAI di ./responses

Jika permintaan gagal, gateway mengembalikan kode status HTTP standar:

Status	Meaning	Apa yang harus diperiksa
400	Permintaan tidak valid	Periksa isi permintaan.
400	Diblokir oleh keamanan konten atau filter IP, atau ditolak oleh backend	Kebijakan keamanan konten dapat memblokir prompt atau respons; juga periksa kebijakan filter IP apa pun. Untuk identitas terkelola, tetapkan peran Foundry User kepada identitas gateway pada sumber daya backend. Lihat Gunakan identitas terkelola untuk autentikasi backend.
401	Kunci akses runtime hilang atau tidak valid	Kirim kunci di `api-key` header, dan pastikan kunci aktif.
404	Model tidak diketahui	Konfirmasi `model` nilai cocok dengan nama model di halaman Models .
429	Dibatasi oleh kebijakan batas tarif atau backend	Tinjau kebijakan pembatasan laju untuk token dan permintaan, serta patuhi header respons `Retry-After`.
5xx	Kesalahan backend	Pastikan penyedia backend sehat dan kredensial penyedia valid.

OpenAI SDK memunculkan pengecualian yang diketik untuk kode status ini, sehingga penanganan kesalahan yang sudah ada berfungsi:

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. Buat kunci akses runtime

Aplikasi melakukan autentikasi ke gateway dengan kunci akses runtime, bukan kunci bawaan. Buat kunci terpisah untuk setiap aplikasi dan lingkungan.

Pilih Kunci.
Pilih Buat Kunci API.
Masukkan nama, seperti quickstart-client.
Pilih Buat.
Salin nilai kunci dan simpan dengan aman. Anda juga dapat melihatnya kembali nanti di halaman Keys .

Buat kunci akses runtime di tingkat gateway. Kunci ini memberikan akses ke setiap model dan alat di gateway. Perlakukan mereka seperti rahasia. Simpan kunci di penyimpanan rahasia untuk aplikasi, rotasikan secara berkala, dan cabut kunci yang tidak lagi diperlukan. Untuk memanggil gateway dengan kunci akses runtime, atur AI_GATEWAY_API_KEY ke nilainya pada panggilan yang ditampilkan sebelumnya.

6. Lihat telemetri

Tier AI Gateway menghasilkan metrik penggunaan token OpenTelemetry. Untuk melihatnya, konfigurasikan tujuan telemetri terlebih dahulu, lalu kirim permintaan:

Konfigurasikan tujuan telemetri untuk gateway, seperti Application Insights. Lihat Kelola, amankan, dan operasikan.
Kirim satu atau lebih permintaan melalui gateway, seperti yang ditunjukkan sebelumnya di Call the gateway.
Buka destinasi telemetri Anda untuk meninjau penggunaan token. Jika Anda menggunakan Application Insights, portal menyediakan dasbor konsumsi token bawaan.

Karena telemetri hanya dipancarkan setelah Anda menghubungkan tujuan, konfigurasikan pemantauan sebelum Anda mengandalkannya. Penggunaan token saat ini merupakan satu-satunya metrik yang dihasilkan; log, jejak, dan metrik lainnya untuk model dan alat akan segera tersedia. Pemanggil menggunakan kunci akses runtime pada tingkat gateway, sehingga Anda dapat memantau lalu lintas tanpa membuka kredensial penyedia kepada aplikasi klien. Untuk mengonfigurasi tujuan telemetri, lihat Kelola, amankan, dan operasikan.

Membersihkan sumber daya

Setelah selesai, hapus sumber daya yang tidak lagi Anda butuhkan. Hapus instance tier AI Gateway, deployment pengujian provider, dan kunci akses runtime yang hanya Anda buat untuk evaluasi.

Langkah berikutnya

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2026-07-28