Azure OpenAI in Microsoft Foundry Models v1 API

توضح لك هذه المقالة كيفية استخدام واجهة برمجة التطبيقات OpenAI للإصدار الأول Azure. تبسط واجهة برمجة التطبيقات v1 المصادقة، وتلغي الحاجة إلى معلمات مؤرخة api-version ، وتدعم استدعاءات نماذج عبر المزودين.

ملاحظة

قد تضاف كائنات استجابة API جديدة إلى استجابة API في أي وقت. نوصي بأن تقوم فقط بتحليل كائنات الاستجابة التي تحتاجها.

المتطلبات الأساسية

• اشتراك Azure - أنشئ واحدا مجانا
• مورد Foundry أو مورد OpenAI <Azure > تم نشره في منطقة مدعومة
• على الأقل نشر نموذج واحد
• بالنسبة Microsoft Entra ID المصادقة: الدور Cognitive Services OpenAI User المعين لهويتك. لمزيد من المعلومات، راجع التحكم في الوصول القائم على الأدوار ل Azure OpenAI

تطور واجهات برمجة التطبيقات

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

ابتداء من أغسطس 2025، يمكنك الاشتراك في واجهات برمجة التطبيقات الجيل الأول من Azure OpenAI التي تضيف دعما ل:

• الوصول المستمر إلى أحدث الميزات دون الحاجة لتحديد ميزات جديدة api-versionكل شهر.
• دورة إصدار API أسرع مع ظهور ميزات جديدة بشكل أكثر تكرارا.
• دعم عملاء OpenAI مع تغييرات بسيطة في الكود للتبديل بين OpenAI و Azure OpenAI عند استخدام المصادقة المعتمدة على المفاتيح.
• دعم عميل OpenAI للمصادقة المعتمدة على الرموز وتحديث التوكن التلقائي دون الحاجة إلى الاعتماد على عميل Azure OpenAI منفصل.
• قم بإجراء مكالمات إكمال الدردشة باستخدام نماذج من مزودين آخرين مثل DeepSeek وGrok الذين يدعمون صياغة إكمال الدردشة v1.

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

امثله:

• عندما /openai/v1/evals كان في المعاينة سابقا، كان يتطلب تمرير "aoai-evals":"preview" رأس. /evals لم يعد في مرحلة المعاينة.
• /openai/v1/fine_tuning/alpha/graders/ في مرحلة المعاينة ولا يتطلب رأس مخصص بسبب وجود في alpha مسار واجهة برمجة التطبيقات.

في التشغيل الأولي لواجهة برمجة التطبيقات المتاحة عموما (GA) في الإصدار الأول، يتم دعم مجموعة فرعية فقط من قدرات الاستدلال وواجهة برمجة التطبيقات التأليفية. جميع ميزات GA مدعومة للاستخدام في الإنتاج. يتم إضافة دعم المزيد من القدرات بسرعة.

تغييرات الكود

Python

واجهة برمجة التطبيقات v1

أمثلة Python v1

مفتاح واجهة برمجة التطبيقات:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),
    base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/"
)

response = client.responses.create(   
  model="gpt-4.1-nano", # Replace with your model deployment name 
  input="This is a test.",
)

print(response.model_dump_json(indent=2)) 

الاختلافات الرئيسية عن واجهة برمجة التطبيقات السابقة:

• OpenAI() يستخدم العميل بدلا من AzureOpenAI().
• مرر نقطة نهاية OpenAI Azure إلى base_url وأضيف /openai/v1 إلى عنوان نقطة النهاية.
• api-version لم يعد معاملا مطلوبا مع واجهة برمجة تطبيقات الإصدار 1 GA (GA).

مفتاح API مع متغيرات البيئة:

قم بتعيين المتغيرات البيئية التالية قبل تشغيل الكود:

المتغير	القيمة
OPENAI_BASE_URL	https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/
OPENAI_API_KEY	مفتاح واجهة برمجة التطبيقات الخاص بك في Azure OpenAI

ثم أنشئ العميل بدون معلمات:

client = OpenAI()

Microsoft Entra ID:

مهم

كان التعامل مع تحديث الرموز التلقائي يتم سابقا من خلال استخدام العميل AzureOpenAI() . تزيل واجهة برمجة التطبيقات v1 هذا الاعتماد، من خلال إضافة دعم تحديث الرموز التلقائي إلى OpenAI() العميل.

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://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",  
  api_key = token_provider  
)

response = client.responses.create(
    model="gpt-4.1-nano",
    input= "This is a test" 
)

print(response.model_dump_json(indent=2)) 

• مرر نقطة نهاية OpenAI Azure إلى base_url وأضيف /openai/v1 إلى عنوان نقطة النهاية.
• اضبط المعلمة api_key بحيث token_provider تتيح الاسترجاع التلقائي وتحديث رمز المصادقة بدلا من استخدام مفتاح API ثابت.

C#‎

واجهة برمجة التطبيقات v1

أمثلة على C# v1

مفتاح واجهة برمجة التطبيقات:

OpenAIClient client = new(
    new ApiKeyCredential("{your-api-key}"),
    new OpenAIClientOptions()
    {
        Endpoint = new("https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/"),
    })

Microsoft Entra ID:

#pragma warning disable OPENAI001

BearerTokenPolicy tokenPolicy = new(
    new DefaultAzureCredential(),
    "https://ai.azure.com/.default");
OpenAIClient client = new(
    authenticationPolicy: tokenPolicy,
    options: new OpenAIClientOptions()
    {
        Endpoint = new("https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/"),
    })

جافا سكريبت

واجهة برمجة التطبيقات v1

أمثلة على JavaScript v1

مفتاح واجهة برمجة التطبيقات:

const client = new OpenAI({
    baseURL: "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
    apiKey: "{your-api-key}" 
});

مفتاح API مع متغيرات البيئة المحددة ل OPENAI_BASE_URL و OPENAI_API_KEY:

const client = new OpenAI();

Microsoft Entra ID:

const tokenProvider = getBearerTokenProvider(
    new DefaultAzureCredential(),
    'https://ai.azure.com/.default');
const client = new OpenAI({
    baseURL: "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
    apiKey: tokenProvider
});

انطلق

واجهة برمجة التطبيقات v1

أمثلة على Go v1

مفتاح واجهة برمجة التطبيقات:

client := openai.NewClient(
    option.WithBaseURL("https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/"),
    option.WithAPIKey("{your-api-key}")
)

مفتاح API مع متغيرات البيئة المحددة ل OPENAI_BASE_URL و OPENAI_API_KEY:

client := openai.NewClient()

Microsoft Entra ID:

tokenCredential, err := azidentity.NewDefaultAzureCredential(nil)

client := openai.NewClient(
    option.WithBaseURL("https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/"),
    azure.WithTokenCredential(tokenCredential)
)

Java

Java أمثلة v1

واجهة برمجة التطبيقات v1

مفتاح واجهة برمجة التطبيقات:

OpenAIClient client = OpenAIOkHttpClient.builder()
                .baseUrl("https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/")
                .apiKey(apiKey)
                .build();

مفتاح API مع متغيرات البيئة المحددة ل OPENAI_BASE_URL و OPENAI_API_KEY:

OpenAIClient client = OpenAIOkHttpClient.builder()
                .fromEnv()
                .build();

Microsoft Entra ID:

Credential tokenCredential = BearerTokenCredential.create(
        AuthenticationUtil.getBearerTokenSupplier(
                new DefaultAzureCredentialBuilder().build(),
                "https://ai.azure.com/.default"));
OpenAIClient client = OpenAIOkHttpClient.builder()
        .baseUrl("https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/")
        .credential(tokenCredential)
        .build();

بقيه

واجهة برمجة التطبيقات v1

مفتاح واجهة برمجة التطبيقات:

curl -X POST https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/responses \
  -H "Content-Type: application/json" \
  -H "api-key: $AZURE_OPENAI_API_KEY" \
  -d '{
     "model": "gpt-4.1-nano",
     "input": "This is a test"
    }'

Microsoft Entra ID:

curl -X POST https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AZURE_OPENAI_AUTH_TOKEN" \
  -d '{
     "model": "gpt-4o",
     "input": "This is a test"
    }'

دعم النماذج

بالنسبة لنماذج OpenAI Azure نوصي باستخدام واجهة برمجة التطبيقات Responses، ومع ذلك، تتيح لك واجهة v1 أيضا إجراء مكالمات إكمال الدردشة باستخدام نماذج من مزودين آخرين مثل DeepSeek وGrok التي تدعم صياغة إكمال الدردشة في OpenAI v1.

base_url يقبل كلا https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/ من التنسيقات https://YOUR-RESOURCE-NAME.services.ai.azure.com/openai/v1/ .

ملاحظة

تعمل واجهة برمجة تطبيقات Responses أيضا مع نماذج Foundry التي تبيعها Azure، مثل نماذج Microsoft AI وDeepSeek وGrok. لتعلم كيفية استخدام واجهة برمجة تطبيقات الاستجابات مع هذه النماذج، راجع كيفية توليد ردود نصية باستخدام نماذج Microsoft Foundry.

Python

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://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",  
  api_key=token_provider,
)
completion = client.chat.completions.create(
  model="MAI-DS-R1", # Replace with your model deployment name.
  messages=[
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "Tell me about the attention is all you need paper"}
  ]
)

#print(completion.choices[0].message)
print(completion.model_dump_json(indent=2))

C#‎

using Azure.Identity;
using OpenAI;
using OpenAI.Chat;
using System.ClientModel.Primitives;

#pragma warning disable OPENAI001

BearerTokenPolicy tokenPolicy = new(
    new DefaultAzureCredential(),
    "https://ai.azure.com/.default");

ChatClient client = new(
    model: "MAI-DS-R1", // Replace with your model deployment name.
    authenticationPolicy: tokenPolicy,
    options: new OpenAIClientOptions() { 
    
        Endpoint = new Uri("https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1")
   }
);

ChatCompletion completion = client.CompleteChat("Tell me about the attention is all you need paper");

Console.WriteLine($"[ASSISTANT]: {completion.Content[0].Text}");

جافا سكريبت

import { DefaultAzureCredential, getBearerTokenProvider } from "@azure/identity";
import { OpenAI } from "openai";

const tokenProvider = getBearerTokenProvider(
    new DefaultAzureCredential(),
    'https://ai.azure.com/.default');
const client = new OpenAI({
    baseURL: "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
    apiKey: tokenProvider
});

const messages = [
    { role: 'system', content: 'You are a helpful assistant.' },
    { role: 'user', content: 'Tell me about the attention is all you need paper' }
];

// Make the API request with top-level await
const result = await client.chat.completions.create({ 
    messages, 
    model: 'MAI-DS-R1', // model deployment name
    max_tokens: 100 
});

// Print the full response
console.log('Full response:', result);

// Print just the message content from the response
console.log('Response content:', result.choices[0].message.content);

انطلق

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/Azure/azure-sdk-for-go/sdk/azidentity"
	"github.com/openai/openai-go/v3"
	"github.com/openai/openai-go/v3/azure"
	"github.com/openai/openai-go/v3/option"
)

func main() {
	// Create an Azure credential
	tokenCredential, err := azidentity.NewDefaultAzureCredential(nil)
	if err != nil {
		log.Fatalf("Failed to create credential: %s", err)
	}

	// Create a client with Azure OpenAI endpoint and token credential
	client := openai.NewClient(
		option.WithBaseURL("https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/"),
		azure.WithTokenCredential(tokenCredential),
	)

	// Make a completion request
	chatCompletion, err := client.Chat.Completions.New(context.TODO(), openai.ChatCompletionNewParams{
		Messages: []openai.ChatCompletionMessageParamUnion{
			openai.UserMessage("Explain what the bitter lesson is?"),
		},
		Model: "MAI-DS-R1", // Use your deployed model name on Azure
	})
	if err != nil {
		log.Fatalf("Failed to get chat completions: %s", err)
	}

	fmt.Println(chatCompletion.Choices[0].Message.Content)
}

Java

package com.example;

import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.ChatModel;
import com.openai.models.chat.completions.ChatCompletion;
import com.openai.models.chat.completions.ChatCompletionCreateParams;

public class OpenAITest {
    public static void main(String[] args) {
        // Get API key from environment variable for security
        String apiKey = System.getenv("OPENAI_API_KEY");
        String resourceName = "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1";
        String modelDeploymentName = "MAI-DS-R1"; //replace with your model deployment name

        try {
            OpenAIClient client = OpenAIOkHttpClient.builder()
                    .baseUrl(resourceName)
                    .apiKey(apiKey)
                    .build();

           ChatCompletionCreateParams params = ChatCompletionCreateParams.builder()
              .addUserMessage("Explain what the bitter lesson is?")
              .model(modelDeploymentName)
              .build();
           ChatCompletion chatCompletion = client.chat().completions().create(params);
        }
    }
}

بقيه

curl -X POST https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AZURE_OPENAI_AUTH_TOKEN" \
  -d '{
      "model": "MAI-DS-R1",
      "messages": [
      {
        "role": "developer",
        "content": "You are a helpful assistant."
      },
      {
        "role": "user",
        "content": "Explain what the bitter lesson is?"
      }
    ]
  }'

دعم واجهة برمجة التطبيقات v1

• v1 مواصفات OpenAPI 3.0

سجل تغييرات إصدار API

تلخص الأقسام التالية التغيرات بين إصدارات واجهات برمجة التطبيقات.

التغييرات بين إصدار المعاينة v1 و2025-04-01-preview

• واجهة برمجة التطبيقات v1 لمعاينة اللعبة
• دعم توليد الفيديو
• جديد ميزات واجهة برمجة التطبيقات للاستجابات:
  • تكامل أدوات بروتوكول السياق عن بعد (MCP)
  • دعم المهام الخلفية غير المتزامنة
  • عناصر الاستدلال المشفرة
  • توليد الصور

التغييرات بين معاينة 2025-04-01 و2025-03-01-preview

• GPT-image-1 الدعم
• ملخص المنطق ل o3 و o4-mini
• واجهة برمجة تطبيقات التقييم

التغييرات بين معاينة 2025-03-01 و2025-02-01-preview

• واجهة برمجة التطبيقات للردود
• الاستخدام الحاسوب

التغييرات بين 2025-02-01-preview و2025-01-01-preview

• إكمال التخزين (دعم واجهة برمجة التطبيقات التقطيرية).

التغييرات بين معاينة 2025-01-01 و2024-12-01-Preview

• prediction تمت إضافة معلمة لدعم المخرجات المتوقعة .
• gpt-4o-audio-preview دعم النماذج.

التغييرات بين معاينة 2024-12-01 و2024-10-01-preview

• store، ومعلمات metadata أضيفت لدعم الإكمال المخزن.
• reasoning_effortتمت إضافة أحدث نماذج التفكير.
• user_security_context أضيف ل Microsoft Defender for Cloud التكامل.

التغييرات بين معاينة 2024-09-01-و2024-08-01-preview

• max_completion_tokens أضيفت إلى الدعم o1-preview والنماذج o1-mini . max_tokens لا يعمل مع نماذج سلسلة O1 .
• parallel_tool_calls أضيف.
• completion_tokens_details & reasoning_tokens أضاف.
• stream_options & include_usage أضاف.

التغييرات بين مواصفات 2024-07-01-preview و2024-08-01-preview

• دعم المخرجات المنظمة.
• تمت إضافة واجهة برمجة تطبيقات رفع ملفات كبيرة.
• حول تغييرات بياناتك:
  • دمج Mongo DB.
  • role_information تم إزالة المعاملة.
  • rerank_score أضيف إلى كائن الاستشهاد.
  • تم إزالة مصدر بيانات AML.
  • تحسينات تكامل تجميع التوجيه بالذكاء الاصطناعي للبحث.

التغييرات بين مواصفة واجهة برمجة التطبيقات 2024-05-01-preview و2024-07-01-Preview

• تمت إضافة دعم واجهة برمجة التطبيقات الدفعية.
• مخزن متجهات لمعلمات استراتيجية التقطيع.
• max_num_results يجب أن تخرج أداة البحث عن الملفات.

التغييرات بين مواصفة واجهة برمجة التطبيقات 2024-04-01-preview و2024-05-01-preview

• دعم Assistants v2 - أداة بحث الملفات وتخزين متجهات
• الضبط الدقيق checkpoints, seed, events
• على تحديثات بياناتك
• يدعم DALL-E 2 الآن نشر النماذج ويمكن استخدامه مع أحدث واجهة برمجة تطبيقات للمعاينة.
• تحديثات تصفية المحتوى

التغييرات بين مواصفة واجهة برمجة التطبيقات 2024-03-01-preview

• تغيير كسر: تم إزالة معايير التحسينات. هذا التغيير يؤثر على gpt-4 نموذج النسخة.vision-preview
• تمت إضافة معامل timestamp_granularities.
• audioWord أضيف كائن.
• TTS إضافية response_formats: wav & pcm.

القضايا المعروفة

• تستخدم مواصفات 2025-04-01-preview Azure OpenAI إصدار OpenAPI 3.1. من المعروف أن هذه النسخة غير مدعومة بالكامل من إدارة Azure API.

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

• لغات البرمجة المدعومة لواجهة برمجة التطبيقات v1
• Foundry Models تباع من قبل Azure
• العمل مع نماذج Azure OpenAI
• Azure حصص وحدود OpenAI
• v1 مواصفات OpenAPI 3.0