البدء السريع: إنشاء نسخة من طبقة بوابة الذكاء الاصطناعي (المعاينة)

ينطبق على: مستوى بوابة الذكاء الاصطناعي (معاينة)

مهم

مستوى AI Gateway حاليا في مرحلة المعاينة العامة. خلال المعاينة العامة، يتوفر مستوى بوابة الذكاء الاصطناعي في المناطق التالية:

• United States - شرق US 2
• أوروبا - السويد سنترال

في هذه البداية السريعة، تقوم بإنشاء نسخة من مستوى بوابة الذكاء الاصطناعي (معاينة)، تضيف نموذج دردشة، تتصل بالبوابة، تنشئ مفتاح وصول وقت التشغيل، وتعرض التليمترية.

طبقة AI Gateway من إدارة Azure API هي طبقة مخصصة لأعباء عمل الذكاء الاصطناعي. يدعم إدارة حركة المرور إلى النماذج — من Microsoft Foundry وAzure OpenAI وAWS Bedrock وGoogle Vertex وOpenAI وAnthropic أو مزودين آخرين — والأدوات التي تم إنشاؤها من خوادم MCP الحالية، أو تعريفات OpenAPI، أو الموصلات. توفر مستويات بوابة الذكاء الاصطناعي بسرعة، عادة خلال دقيقة واحدة.

مدة الإنجاز: حوالي 20-30 دقيقة. تقوم بإنشاؤ: بوابة واحدة، نموذج دردشة واحد، مفتاح وصول وقت تشغيل واحد، وطلب إكمال محادثة ناجح واحد.

ملحوظة

مستوى بوابة الذكاء الاصطناعي قيد المعاينة العامة. يتم توفير ميزات المعاينة دون اتفاقية على مستوى الخدمة ولا ينبغي استخدامها لأعباء العمل الإنتاجية إلا إذا قبلت منظمتك شروط المعاينة.

المتطلبات المسبقه

• حساب Azure مع Microsoft Entra ID. الوصول إلى معاينة مستوى AI Gateway محدود حاليا لمستخدمي Azure الذين يسجلون الدخول باستخدام Microsoft Entra ID.
• اشتراك في Azure، وإذن لإنشاء الموارد في مجموعة موارد (مثل دور المساهم).
• الوصول إلى مزود نماذج مدعوم واحد على الأقل، مثل نموذج منشور في Microsoft Foundry أو Azure OpenAI.
• إذا كان مزودك يحتاج إلى مفتاح API، فاحتفظ بالمفتاح متاحا.
• لاستدعاء البوابة، استخدم curl (بدون تثبيت) أو حزمة تطوير OpenAI - Python 3.9 أو أحدث، أو Node.js 18 أو أبعد، مع الحزمةopenai.

1. تسجيل الدخول إلى بوابة مستوى بوابة الذكاء الاصطناعي

بوابة مستوى AI Gateway هي تجربة ويب مستقلة - لا تستخدم بوابة Azure.

1. اذهب إلى بوابة مستوى بوابة الذكاء الاصطناعي على ai.gateway.azure.com.
2. اختر تسجيل الدخول وتحقق من المصادقة باستخدام Microsoft Entra ID.

استخدم البوابة لإدارة النماذج، خوادم MCP، مفاتيح الوصول أثناء التشغيل، السياسات، والمراقبة، بناء على صلاحيات Entra ID الخاصة بك. المستدعيون في وقت التشغيل لا يسجلون الدخول إلى البوابة - بل يستدعون البوابة باستخدام مفاتيح الوصول أثناء التشغيل التي تنشئها لاحقا.

2. إنشاء بوابة

1. في البوابة، اختر إنشاء البوابة. لاستخدام بوابة موجودة بدلا من ذلك، اخترها وتخطى الخطوة التالية.

2. أدخل اسمًا. يصبح الاسم جزءا من نقطة نهاية وقت التشغيل:

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

3. اختر اشتراكك ومنطقة معاينة مدعومة (شرق الولايات المتحدة 2 أو وسط السويد).

4. اختياريا، يمكنك تعيين مجموعة الموارد تحت المتقدمة. افتراضيا، البوابة تنشئ واحدة لك.

5. حدد إنشاء. عادة ما يستغرق التفعيل أقل من دقيقة.

البوابة هي مورد مخصص لاشتراكك في Azure. لا تختار السعة أو تضيف وحدات مقياس قبل إضافة النماذج. بالنسبة للأتمتة، إصدار واجهة برمجة التطبيقات لإدارة المعاينة هو 2026-05-01-preview؛ طلبات وقت التشغيل تستخدم اسم مضيف البوابة، وليس Azure Resource Manager.

3. إضافة نموذج

أسرع طريقة لإنشاء نموذج هي استيراده من حسابات Microsoft Foundry.

1. في قسم الصفحة الرئيسية، قم بتكوين البوابة، اختر خيار البدء أو افتح صفحة الإعداد مباشرة عند /settings/start المسار.

   

2. اختر اشتراكا أو أكثر للمسح. اختياريا، يمكنك تطبيق مرشح مجموعة موارد لتضييق النتائج.

3. راجع الحسابات المكتشفة. يتم تجميع عمليات النشر حسب حساب Foundry الأصلي (مورد Azure). الاختيار يتم حسب الحساب: عند اختيار حساب، يقوم المعالج باستيراد جميع نشرات نماذجه.

   

4. اختر طريقة مصادقة خلفية لهذا الاستيراد:

   • يعتمد على المفاتيح (الافتراضي). تخزن البوابة مفتاح واجهة برمجة التطبيقات للحساب وترسله في الرأس api-key . يسترجع الساحر المفتاح عند وقت الاستيراد.
   • الهوية المدارة (Microsoft Entra ID). تقوم البوابة بالتحقق من هويتها المدارة. إذا لم يكن للبوابة هوية مدارة، يقوم المعالج بتمكين هوية معينة من النظام. إذا كانت هناك هوية موجودة بالفعل، تختار أي هوية تستخدم. يمنح الساحر هوية هوية مستخدم المسبك في كل حساب محدد.

5. حدد استيراد.

6. عند اختيار الاستيراد، يقوم المعالج بإجراء فحص متطلبات التحقق لكل حساب محدد قبل إنشاء أي شيء. يؤكد هذا الفحص أن المصادقة مضبوطة بشكل صحيح وأن أسماء النماذج لا تتعارض مع النماذج الموجودة بالفعل على البوابة. الحسابات التي تمر يتم استيرادها؛ الحسابات التي تفشل يتم تخطيها بتحذير داخلي، وتستمر بقية اللعبة.

للاتصال بمزود غير Foundry (مثل AWS Bedrock، Google Vertex، OpenAI، أو Anthropic)، اختر إضافة نموذج مخصص بدلا من ذلك. انظر إدارة النماذج والأدوات.

يمرر المتصلون اسم النموذج في model حقل الطلبات المتوافقة مع OpenAI. يستخدم gpt-5.6-solهذا البدء السريع ؛ استبله بالنموذج الذي قمت بتسجيله.

تلميح

لتجربة النموذج فورا، افتح صفحة Discover واختر النموذج الذي يستدعيه في الملعب المدمج. يستخدم الملعب المفتاح المدمج في البوابة، لذا يمكنك استكشاف واختبار النماذج أو الأدوات المضافة قبل إنشاء مفتاح وصول أثناء التشغيل.

4. اتصل بالبوابة

تكشف البوابة عن واجهة برمجة التطبيقات التي يدعمها نموذج الواجهة الخلفية. يتم تقديم نماذج من مزودي خدمة متوافقين مع OpenAI — مثل Microsoft Foundry و Azure OpenAI و AWS Bedrock و Google Vertex و OpenAI — على نقطة نهاية متوافقة مع OpenAI. وجه أي عميل OpenAI إلى عنوان القاعدة للبوابة، وأرسل api-key رأس، ومرر اسم النموذج في model الحقل. تستخدم نماذج Anthropic واجهة برمجة تطبيقات Anthropic Messages بدلا من ذلك؛ انظر إدارة النماذج والأدوات.

لاختبار سريع، استخدم المفتاح المدمج في البوابة — وهو نفس المفتاح الذي يستخدمه ملعب Discover. انسخها من صفحة المفاتيح ، التي تدرج المفتاح المدمج بجانب مفاتيح واجهة برمجة التطبيقات التي تمنح الوصول إلى وقت التشغيل لكل أصل في البوابة. بالنسبة لتطبيقاتك الخاصة، أنشئ مفتاح وصول وقت التشغيل بدلا من ذلك (انظر القسم التالي).

اضبط هذه القيم مرة واحدة:

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

تلميح

انسخ عنوان URL الأساسي الدقيق من صفحة نظرة عامة على بوابتك بدلا من بنائها يدويا.

قم بإجراء أول مكالمة لك مع العميل الذي تختاره:

حليقه

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 Completesions، أي مزود متوافق مع 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 Responses عند /responses.

إذا فشل الطلب، تعيد البوابة رمز حالة HTTP قياسي:

حاله	المعنى	ما يجب التحقق منه
400	طلب غير صالح	تحقق من نص الطلب.
400	تم حظره بسبب أمان المحتوى أو فلتر IP، أو رفض من قبل الخلفية	يمكن لسياسة أمان المحتوى أن تمنع التنبيه أو الاستجابة؛ تحقق أيضا من أي سياسة تصفية IP. بالنسبة للهوية المدارة، قم بتعيين دور مستخدم Foundry لهوية البوابة في مورد الخلفية. انظر استخدام الهوية المدارة للمصادقة الخلفية.
401	مفتاح الوصول المفقود أو غير الصحيح في وقت التشغيل	أرسل المفتاح في api-key الرأس، وتأكد من أن المفتاح نشط.
404	نموذج غير معروف	تأكد من model أن القيمة تطابق اسم النموذج في صفحة النماذج .
429	يتم تقييده بسبب سياسة تحديد سعر الفائدة أو الخلفية	راجع الرموز وطلب سياسات تحديد المعدل، واحترم Retry-After رأس الرد.
5xx	خطأ في الخلفية	تأكد من صحة مزود الواجهة الخلفية وأن اعتماد المزود صالح.

تطرح مجموعات تطوير OpenAI استثناءات مكتوبة لهذه الرموز الحالة، لذا فإن طريقة معالجة الأخطاء الحالية لديك تعمل:

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. حدد Create API key.
3. أدخل اسما، مثل quickstart-client.
4. حدد إنشاء.
5. انسخ قيمة المفتاح واحتزنها بأمان. يمكنك أيضا مشاهدته مرة أخرى لاحقا في صفحة المفاتيح .

أنشئ مفاتيح وصول وقت التشغيل على مستوى البوابة. تمنح هذه المفاتيح الوصول إلى كل نموذج وأداة في البوابة. عاملهم كأسرار. تخزين المفاتيح في مخزن سري للتطبيقات، ودورانها بانتظام، وسحب المفاتيح التي لم تعد مطلوبة. لاستدعاء البوابة باستخدام مفتاح وصول وقت التشغيل، قم بتعيين AI_GATEWAY_API_KEY قيمتها في المكالمات المعروضة سابقا.

6. انظر القياس عن بعد

يصدر مستوى AI Gateway مقاييس استخدام رموز OpenTelemetry. لرؤيتها، قم بتكوين وجهة تتبع بيانات أولا، ثم أرسل الطلبات:

1. قم بتكوين وجهة قياس عن بعد للبوابة، مثل Application Insights. انظر الحكم، التأمين، والتشغيل.
2. أرسل طلبا أو أكثر عبر البوابة، كما هو موضح سابقا في نادي البوابة.
3. افتح وجهة التليمترية الخاصة بك لمراجعة استخدام الرموز. إذا كنت تستخدم Application Insights، توفر البوابة لوحة تحكم مدمجة لاستهلاك الرموز.

نظرا لأن التليمترية تصدر فقط بعد توصيل وجهة، قم بضبط المراقبة قبل الاعتماد عليها. استخدام الرموز هو المقياس الوحيد المنبعثة حاليا؛ السجلات والتتبع ومقاييس أخرى للنماذج والأدوات ستتوفر قريبا. يستخدم المتصلون مفاتيح وصول وقت التشغيل على مستوى البوابة، بحيث يمكنك مراقبة حركة المرور دون كشف بيانات اعتماد مزود الخدمة لتطبيقات العميل. لتكوين وجهة تتبع البيانات، راجع Govern، Secure، وRun.

تنظيف الموارد

عندما تنتهي، احذف أي موارد لم تعد بحاجة إليها. قم بإزالة مثيل مستوى AI Gateway، ونشر اختبار المزود، ومفاتيح الوصول أثناء التشغيل التي أنشأتها فقط للتقييم.

الخطوات التالية

• إضافة أدوات MCP يمكن للوكلاء الاتصال بها
• طبق سياسات الحوكمة على نماذجك وأدواتك
• تكوين الشبكات الخاصة
• إدارة النماذج والأدوات
• نظرة عامة على مستوى بوابة الذكاء الاصطناعي