إشعار
يتطلب الوصول إلى هذه الصفحة تخويلاً. يمكنك محاولة تسجيل الدخول أو تغيير الدلائل.
يتطلب الوصول إلى هذه الصفحة تخويلاً. يمكنك محاولة تغيير الدلائل.
يوفر مورد Foundry وصولا موحدا إلى النماذج والوكلاء والأدوات. تشرح هذه المقالة أي SDK ونقطة نهاية يجب استخدامها في سيناريوك.
| SDK | ما الغرض منها | نقطة النهاية |
|---|---|---|
| مجموعة تطوير Foundry | قدرات خاصة بالمصنع مع واجهات متوافقة مع OpenAI. يشمل الوصول إلى نماذج Foundry المباشرة من خلال واجهة برمجة تطبيقات Responses API (وليس إكمال الدردشة). | https://<resource-name>.services.ai.azure.com/api/projects/<project-name> |
| حزمة تطوير OpenAI | أحدث نماذج وميزات OpenAI SDK مع واجهة برمجة التطبيقات OpenAI الكاملة. نماذج Foundry المباشرة متاحة عبر واجهة برمجة تطبيقات إكمال الدردشة (وليس Responses). | https://<resource-name>.openai.azure.com/openai/v1 |
| مجموعات SDK لأدوات Foundry | حلول جاهزة (رؤية، خطاب، سلامة المحتوى، والمزيد). | نقاط النهاية الخاصة بالأدوات (تختلف حسب الخدمة). |
| إطار عمل الوكيل | تنسيق متعدد الوكلاء في الشيفرة. محايد للسحابة. | يستخدم نقطة نهاية المشروع عبر حزمة تطوير Foundry. |
اختر حزمة تطوير البرمجيات الخاصة بك:
- استخدم Foundry SDK عند بناء تطبيقات تحتوي على وكلاء أو تقييمات أو ميزات خاصة ب Foundry
- استخدم حزمة تطوير البرمجيات OpenAI عندما يتطلب الأمر أقصى قدر من التوافق مع OpenAI، أو باستخدام نماذج Foundry المباشرة عبر إتمام الدردشة
- استخدم مجموعات تطوير البرمجيات الخاصة ب Foundry Tools عند العمل مع خدمات ذكاء اصطناعي محددة (الرؤية، الكلام، اللغة، إلخ).
- استخدم إطار عمل الوكلاء عند بناء أنظمة متعددة الوكلاء في الكود (التنسيق المحلي)
ملاحظة
أنواع الموارد: يوفر مورد Foundry جميع النقاط النهائية المذكورة سابقا. يوفر مورد Azure OpenAI نقطة /openai/v1 النهاية فقط.
التوثيق: العينات هنا تستخدم معرف Microsoft Entra (DefaultAzureCredential). مفاتيح API تعمل على /openai/v1. مرر المفتاح كمزود api_key رموز بدلا من الرمز.
المتطلبات المسبقه
-
حساب Azure مع اشتراك نشط. إذا لم يكن لديك حساب، فأنشئ حساب Azure مجانيا، والذي يتضمن اشتراكا تجريبيا مجانيا.
امتلكوا أحد أدوار Azure RBAC التالية لإنشاء وإدارة موارد Foundry:
- Azure الذكاء الاصطناعي المستخدم (دور أقل امتيازات للتطوير)
- Azure الذكاء الاصطناعي مدير المشاريع (لإدارة مشاريع Foundry)
- مساهم أو مالك (للحصول على أذونات على مستوى الاشتراك)
للحصول على تفاصيل حول صلاحيات كل دور، راجع التحكم في الوصول القائم على الأدوار في Microsoft Foundry.
قم بتثبيت أوقات تشغيل اللغة المطلوبة والأدوات العمومية وملحقات VS Code كما هو موضح في إعداد بيئة التطوير الخاصة بك.
مهم
قبل البدء ، تأكد من أن بيئة التطوير الخاصة بك جاهزة.
تركز هذه المقالة على خطوات محددة مثل تثبيت SDK، المصادقة، وتشغيل الكود النموذجي.
التعرف على ٱلْمُتَطَلَّبَاتُ ٱلْأَسَاسِيَّةُ
قبل المتابعة، أكد:
- اشتراك Azure نشط:
az account show - لديك الدور المطلوب في RBAC: تحقق من بوابة Azure → موارد Foundry → التحكم في الوصول (IAM)
- وقت تشغيل اللغة المثبت:
- بايثون:
python --version(≥3.8) - Node.js:
node --version(≥18) - .NET:
dotnet --version(≥6.0) - جافا:
java --version(≥11)
- بايثون:
مجموعة تطوير Foundry
تتصل مجموعة تطوير تطوير Foundry بنقطة نهاية مشروع واحدة توفر الوصول إلى أكثر قدرات Foundry شعبية:
https://<resource-name>.services.ai.azure.com/api/projects/<project-name>
ملاحظة
إذا كانت مؤسستك تستخدم نطاقا فرعيا مخصصا، استبله <resource-name> ب <your-custom-subdomain> في رابط نقطة النهاية.
هذا النهج يبسط تكوين التطبيقات. بدلا من إدارة عدة نقاط نهاية، تقوم بتكوين واحدة.
تثبيت حزمة SDK
| إصدار SDK | نسخة البوابة | الحالة | حزمة Python |
|---|---|---|---|
| 2.x | المصنع (جديد) | مستقر | azure-ai-projects>=2.0.0 |
| 1.x | المسبك (كلاسيكي) | مستقر | azure-ai-projects==1.0.0 |
مكتبة عملاء مشاريع Azure الذكاء الاصطناعي لبايثون هي مكتبة موحدة تتيح لك استخدام عدة مكتبات عملاء معا عن طريق الاتصال بنقطة نهاية مشروع واحدة.
شغل هذا الأمر لتثبيت الحزم الخاصة بمشاريع Foundry.
pip install azure-ai-projects >=2.0.0
::: نهاية المنطقة
| إصدار SDK | نسخة البوابة | الحالة | حزمة جافا |
|---|---|---|---|
| 1.0.0-بيتا.3 1.0.0-بيتا.1 |
المصنع (جديد) | الإصدار الأولي | azure-ai-projectsazure-ai-agents |
| إصدار SDK | نسخة البوابة | الحالة | حزمة جافاسكريبت |
|---|---|---|---|
| 2.0.0-beta.4 (معاينة) | المصنع (جديد) | الإصدار الأولي | @azure/ai-projects 'prerelease' |
| 1.0.1 | كلاسيك فاوندري | مستقر | @azure/ai-projects |
| إصدار SDK | نسخة البوابة | الحالة | حزمة .NET |
|---|---|---|---|
| 1.2.0-beta.5 (معاينة) | المصنع (جديد) | الإصدار الأولي | Azure.AI.ProjectsAzure.AI.Projects.Openai |
| 1.x (جورجيا) | كلاسيك فاوندري | مستقر | Azure.AI.Projects |
مكتبة عملاء مشاريع Azure الذكاء الاصطناعي لجافا (المعاينة) هي مكتبة موحدة تتيح لك استخدام عدة مكتبات عملاء معا من خلال الاتصال بنقطة نهاية مشروع واحدة.
مهم
العناصر التي تم وضع علامة عليها (إصدار أولي) في هذه المقالة موجودة حالياً في الإصدار الأولي العام. يتم توفير هذه المعاينة دون اتفاقية على مستوى الخدمة، ولا نوصي بها لأحمال عمل الإنتاج. بعض الميزات ربما لا تكون مدعمة أو بها بعض القدرات المقيدة. لمزيد من المعلومات، راجع شروط الاستخدام التكميلية لمعاينات Microsoft Azure.
أضف هذه الحزم إلى تركيبك لمشاريع Foundry.
package com.azure.ai.agents;
import com.azure.core.util.Configuration;
import com.azure.identity.DefaultAzureCredentialBuilder;
import com.openai.models.responses.Response;
import com.openai.models.responses.ResponseCreateParams;
مكتبة عملاء Azure الذكاء الاصطناعي Projects لجافا سكريبت هي مكتبة موحدة تتيح لك استخدام عدة مكتبات عميل معا من خلال الاتصال بنقطة نهاية مشروع واحدة.
شغل هذا الأمر لتثبيت حزم معاينة JavaScript لمشاريع Foundry.
npm install @azure/ai-projects@beta @azure/identity dotenv
مكتبة عملاء مشاريع Azure الذكاء الاصطناعي ل .NET هي مكتبة موحدة تتيح لك استخدام عدة مكتبات عملاء معا من خلال الاتصال بنقطة نهاية مشروع واحدة.
شغل هذا الأمر لإضافة حزمة Azure.الذكاء الاصطناعي.Projects إلى مشروع .NET الخاص بك.
dotnet add package Azure.AI.Projects --prerelease
dotnet add package Azure.AI.Projects.OpenAI --prerelease
dotnet add package Azure.Identity
استخدام مجموعة تطوير تطوير اللعبة الخاصة ب Foundry
يعرض SDK نوعين من العملاء لأن Foundry وOpenAI لهما أشكال API مختلفة:
- عميل المشروع – استخدامه للعمليات الأصلية في Foundry حيث لا يوجد له نظير في OpenAI. أمثلة: إدراج الروابط، استرجاع خصائص المشروع، تمكين التتبع.
-
عميل متوافق مع OpenAI – وظيفة استخدام Foundry التي تبني على مفاهيم OpenAI. تستخدم واجهة برمجة التطبيقات للاستجابات، والوكلاء، والتقييمات، والضبط الدقيق جميعها أنماط طلب/استجابة على نمط OpenAI. هذا العميل يمنحك أيضا الوصول إلى نماذج Foundry المباشرة (نماذج غيرAzure-OpenAI المستضافة في Foundry). تخدم نقطة نهاية المشروع هذه الحركة على
/openaiالمسار.
معظم التطبيقات تستخدم كلا العميلين. استخدم عميل المشروع للإعداد والتكوين، ثم استخدم العميل المتوافق مع OpenAI لتشغيل الوكلاء، والتقييمات، واستدعاء النماذج (بما في ذلك نماذج Foundry المباشرة).
أنشئ عميل مشروع:
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
project_client = AIProjectClient(
endpoint="https://<resource-name>.services.ai.azure.com/api/projects/<project-name>",
credential=DefaultAzureCredential())
أنشئ عميل متوافق مع OpenAI من مشروعك:
with project_client.get_openai_client() as openai_client:
response = openai_client.responses.create(
model="gpt-5.2",
input="What is the size of France in square miles?",
)
print(f"Response output: {response.output_text}")
الإنتاج المتوقع:
Response output: France has an area of approximately 213,011 square miles (551,695 square kilometers).
أنشئ عميل مشروع:
import com.azure.ai.projects.ProjectsClient;
import com.azure.ai.projects.ProjectsClientBuilder;
import com.azure.identity.DefaultAzureCredentialBuilder;
String endpoint = "https://<resource-name>.services.ai.azure.com/api/projects/<project-name>";
ProjectsClient projectClient = new ProjectsClientBuilder()
.credential(new DefaultAzureCredentialBuilder().build())
.endpoint(endpoint)
.buildClient();
```**Create and use an OpenAI-compatible client from your project:**
```java
OpenAIClient openAIClient = projectClient.getOpenAIClient();
أنشئ عميل مشروع:
import { DefaultAzureCredential } from "@azure/identity";
import { AIProjectClient } from "@azure/ai-projects";
import "dotenv/config";
const projectEndpoint = "https://<resource-name>.services.ai.azure.com/api/projects/<project-name>";
const deploymentName = "gpt-5.2";
const project = new AIProjectClient(projectEndpoint, new DefaultAzureCredential());
أنشئ عميل متوافق مع OpenAI من مشروعك:
const openAIClient = await project.getOpenAIClient();
const response = await openAIClient.responses.create({
model: deploymentName,
input: "What is the size of France in square miles?",
});
console.log(`Response output: ${response.output_text}`);
أنشئ عميل مشروع:
using Azure.AI.Projects.OpenAI;
using Azure.Identity;
using OpenAI.Responses;
string endpoint = "https://<resource-name>.services.ai.azure.com/api/projects/<project-name>";
AIProjectClient projectClient = new(
endpoint: new Uri(endpoint),
tokenProvider: new DefaultAzureCredential());
أنشئ عميل متوافق مع OpenAI من مشروعك:
#pragma warning disable OPENAI001
OpenAIResponseClient responseClient = projectClient.OpenAI.GetProjectResponsesClientForModel("gpt-5.2");
OpenAIResponse response = responseClient.CreateResponse("What is the speed of light?");
Console.WriteLine(response.GetOutputText());
#pragma warning restore OPENAI001
ما الذي يمكنك فعله بحزمة تطوير تطوير Foundry
- نماذج الوصول إلى Foundry، بما في ذلك Azure OpenAI
- استخدم خدمة وكلاء المسبك
- تشغيل تقييمات الدفعات
- تفعيل تتبع التطبيقات
- ضبط نموذج بدقة
- احصل على نقاط نهاية ومفاتيح لأدوات Foundry، والتوزيع المحلي، والمزيد
استكشاف الأخطاء وإصلاحها
أخطاء المصادقة
إذا رأيت DefaultAzureCredential failed to retrieve a token:
تحقق من صحة Azure CLI:
az account show az login # if not logged inتحقق من تعيين دور RBAC:
- تأكد من أن لديك على الأقل دور مستخدم الذكاء الاصطناعي في Azure في مشروع Foundry
- انظر تعيين أدوار Azure
بالنسبة لهوية مدارة في الإنتاج:
- تأكد من أن الهوية المدارة لها الدور المناسب
- انظر تكوين الهويات المدارة
أخطاء تكوين نقطة النهاية
إذا رأيت Connection refused أو 404 Not Found:
- تحقق من أن أسماء الموارد والمشاريع تطابق مع نشرك الفعلي
-
تحقق من تنسيق رابط نقطة النهاية: يجب أن يكون
https://<resource-name>.services.ai.azure.com/api/projects/<project-name> -
بالنسبة للنطاقات الفرعية المخصصة: استبدلها
<resource-name>بنطاق فرعي مخصص
عدم تطابقات إصدارات SDK
إذا فشلت عينات الكود مع AttributeError أو ModuleNotFoundError:
-
تحقق من إصدار SDK:
pip show azure-ai-projects # Python npm list @azure/ai-projects # JavaScript dotnet list package # .NET - تحقق من محاذاة الاسم: 2.x SDK يتطلب بوابة Foundry، و1.x SDK يتطلب Foundry classic
- أعد التثبيت مع علامات الإصدار الصحيحة: راجع أوامر التثبيت في كل قسم لغوي أعلاه
حزمة تطوير OpenAI
استخدم حزمة تطوير OpenAI عندما تريد واجهة برمجة تطبيقات OpenAI كاملة وأقصى توافق مع العملاء. توفر هذه النقطة الوصول إلى نماذج Azure OpenAI ونماذج Foundry المباشرة (عبر واجهة برمجة تطبيقات الاستجابات). لا يوفر الوصول إلى ميزات خاصة ب Foundry مثل الوكلاء والتقييمات.
المقطع التالي يوضح كيفية استخدام نقطة نهاية Azure OpenAI /openai/v1 مباشرة.
from openai import OpenAI
from azure.identity import DefaultAzureCredential, get_bearer_token_provider
token_provider = get_bearer_token_provider(
DefaultAzureCredential(), "https://ai.azure.com/.default"
)
client = OpenAI(
base_url = "https://<resource-name>.openai.azure.com/openai/v1/",
api_key=token_provider,
)
response = client.responses.create(
model="model_deployment_name",
input= "What is the size of France in square miles?"
)
print(response.model_dump_json(indent=2))
الإنتاج المتوقع:
{
"id": "resp_abc123",
"object": "response",
"created": 1234567890,
"model": "gpt-5.2",
"output_text": "France has an area of approximately 213,011 square miles (551,695 square kilometers)."
}
لمزيد من المعلومات، راجع لغات البرمجة المدعومة من Azure OpenAI
مهم
العناصر التي تم وضع علامة عليها (إصدار أولي) في هذه المقالة موجودة حالياً في الإصدار الأولي العام. يتم توفير هذه المعاينة دون اتفاقية على مستوى الخدمة، ولا نوصي بها لأحمال عمل الإنتاج. بعض الميزات ربما لا تكون مدعمة أو بها بعض القدرات المقيدة. لمزيد من المعلومات، راجع شروط الاستخدام التكميلية لمعاينات Microsoft Azure.
المقطع التالي يوضح كيفية استخدام نقطة نهاية Azure OpenAI /openai/v1 مباشرة.
import com.azure.identity.AuthenticationUtil;
import com.azure.identity.DefaultAzureCredential;
import com.azure.identity.DefaultAzureCredentialBuilder;
import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.credential.BearerTokenCredential;
import java.util.function.Supplier;
DefaultAzureCredential tokenCredential = new DefaultAzureCredentialBuilder().build();
String endpoint = "https://<resource-name>.openai.azure.com/openai/v1";
String deploymentName = "gpt-5.2";
Supplier<String> bearerTokenSupplier = AuthenticationUtil.getBearerTokenSupplier(
tokenCredential, "https://ai.azure.com/.default");
OpenAIClient openAIClient = OpenAIOkHttpClient.builder()
.baseUrl(endpoint)
.credential(BearerTokenCredential.create(bearerTokenSupplier))
.build();
ResponseCreateParams responseCreateParams = ResponseCreateParams.builder()
.input("What is the speed of light?")
.model(deploymentName)
.build();
Response response = openAIClient.responses().create(responseCreateParams);
System.out.println("Response output: " + response.getOutputText());
لمزيد من المعلومات حول استخدام مجموعة تطوير البرمجيات OpenAI، راجع لغات البرمجة المدعومة من Azure OpenAI
const endpoint = "https://<resource-name>.openai.azure.com/openai/v1";
const scope = "https://ai.azure.com/.default";
const azureADTokenProvider = getBearerTokenProvider(new DefaultAzureCredential(), scope);
const client = new OpenAI({ baseURL: endpoint, apiKey: azureADTokenProvider });
const response = await client.responses.create({
model: deploymentName,
input: "What is the size of France in square miles?",
});
console.log(`Response output: ${response.output_text}`);
لمزيد من المعلومات حول استخدام مجموعة تطوير البرمجيات OpenAI، راجع لغات البرمجة المدعومة من Azure OpenAI
- تثبيت حزمة OpenAI: شغل هذا الأمر لإضافة مكتبة عملاء OpenAI إلى مشروعك .NET.
dotnet add package OpenAI ```When it succeeds, the .NET CLI confirms that it installed the `OpenAI` package. This snippet configures `DefaultAzureCredential`, builds `OpenAIClientOptions`, and creates a `ResponseClient` for the Azure OpenAI v1 endpoint. ```csharp using Azure.Identity; using Azure.Core; using OpenAI; using System; using System.ClientModel.Primitives; #pragma warning disable OPENAI001 const string directModelEndpoint = "https://<resource-name>.openai.azure.com/openai/v1/"; const string deploymentName = "gpt-5.2"; BearerTokenPolicy tokenPolicy = new( new DefaultAzureCredential(), "https://ai.azure.com/.default"); OpenAIResponseClient client = new( model: deploymentName, authenticationPolicy: tokenPolicy, // To use Entra // credential: new ApiKeyCredential("<YOUR-AZURE-OPENAI-API-KEY>") // To use APIKEY options: new OpenAIClientOptions() { Endpoint = new($"{directModelEndpoint}"), }); ResponseCreationOptions options = new ResponseCreationOptions { Temperature = (float)0.7, }; OpenAIResponse modelDirectResponse = client.CreateResponse( [ ResponseItem.CreateUserMessageItem("What is the size of France in square miles?"), ], options); Console.WriteLine($"[ASSISTANT]: {modelDirectResponse.GetOutputText()}"); #pragma warning restore OPENAI001 // The ResponseClient lets you interact with models and services in your project.
لمزيد من المعلومات حول استخدام مجموعة تطوير البرمجيات OpenAI، راجع لغات البرمجة المدعومة من Azure OpenAI
استخدام إطار عمل الوكيل للتوزيع المحلي
إطار عمل Microsoft Agent هو حزمة تطوير تطوير مفتوحة المصدر لبناء أنظمة متعددة الوكلاء في الكود (مثل .NET وPython) مع واجهة لا تعتمد على مزودي السحابة.
استخدم إطار عمل الوكلاء عندما تريد تعريف وتنسيق الوكلاء محليا. قم بإقرانها بحزمة تطوير تطوير Foundry عندما تريد أن تعمل هذه الوكلاء ضد نماذج Foundry أو عندما تريد من Agent Framework لتنسيق الوكلاء المستضافين في Foundry.
لمزيد من المعلومات، راجع نظرة عامة على إطار عمل وكلاء مايكروسوفت.
مجموعات SDK لأدوات Foundry
أدوات Foundry Tools (المعروفة سابقا باسم Azure الذكاء الاصطناعي Services) هي حلول نقاط مبنية مسبقا مع مجموعات SDK مخصصة. استخدم النقاط النهائية التالية للعمل مع أدوات الصاهر.
أي نقطة نهاية يجب أن تستخدم؟
اختر نقطة نهاية بناء على احتياجاتك:
استخدم نقطة النهاية في خدمات الذكاء الاصطناعي Azure للوصول إلى أدوات رؤية الحاسوب، سلامة المحتوى، ذكاء المستندات، اللغة، الترجمة، وأدوات مسبك الرموز.
نقطة نهاية أدوات الصاهر: https://<your-resource-name>.cognitiveservices.azure.com/
ملاحظة
النقاط النهائية تستخدم إما اسم المورد الخاص بك أو نطاق فرعي مخصص. إذا قامت مؤسستك بإعداد نطاق فرعي مخصص، استبدل your-resource-name ب your-custom-subdomain في جميع أمثلة نقاط النهاية.
لأدوات مسبك الكلام والترجمة، استخدم نقاط النهاية في الجداول التالية. استبدل البدلاء بمعلومات المصادر الخاصة بك.
نقاط نهاية الخطاب
| أداة الصبك | نقطة النهاية |
|---|---|
| تحويل الكلام إلى نص (القياسي) | https://<YOUR-RESOURCE-REGION>.stt.speech.microsoft.com |
| تحويل النص إلى كلام (عصبي) | https://<YOUR-RESOURCE-REGION>.tts.speech.microsoft.com |
| الصوت المخصص | https://<YOUR-RESOURCE-NAME>.cognitiveservices.azure.com/ |
نقاط نهاية الترجمة
| أداة الصبك | نقطة النهاية |
|---|---|
| ترجمة النص | https://api.cognitive.microsofttranslator.com/ |
| ترجمة المستندات | https://<YOUR-RESOURCE-NAME>.cognitiveservices.azure.com/ |
تشمل الأقسام التالية روابط البدء السريع لمجموعات SDK الخاصة بأدوات Foundry ومعلومات المرجع.
