Azure OpenAI in Microsoft Foundry Models v1 API

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

‏‫ملاحظة‬

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

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

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

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

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

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

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

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

أمثلة:

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

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

تغييرات التعليمات البرمجية

Python

واجهة برمجة تطبيقات الإصدار 1

أمثلة على 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().
• base_url يمرر نقطة نهاية Azure OpenAI ويتم /openai/v1 إلحاقه بعنوان نقطة النهاية.
• api-version لم تعد معلمة مطلوبة مع واجهة برمجة تطبيقات الإصدار 1 GA.

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

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

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

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

client = OpenAI()

معرف Microsoft Entra:

مهم

تمت معالجة التحديث التلقائي للرمز المميز سابقا من خلال استخدام 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)) 

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

C#‎

واجهة برمجة تطبيقات الإصدار 1

أمثلة على 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:

#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/"),
    })

JavaScript

واجهة برمجة تطبيقات الإصدار 1

أمثلة JavaScript v1

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

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

مفتاح واجهة برمجة التطبيقات مع تعيين متغيرات البيئة ل OPENAI_BASE_URL و OPENAI_API_KEY:

const client = new OpenAI();

معرف Microsoft Entra:

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

ذهب

واجهة برمجة تطبيقات الإصدار 1

أمثلة Go v1

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

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

مفتاح واجهة برمجة التطبيقات مع تعيين متغيرات البيئة ل OPENAI_BASE_URL و OPENAI_API_KEY:

client := openai.NewClient()

معرف Microsoft Entra:

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

واجهة برمجة تطبيقات الإصدار 1

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

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

مفتاح واجهة برمجة التطبيقات مع تعيين متغيرات البيئة ل OPENAI_BASE_URL و OPENAI_API_KEY:

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

معرف Microsoft Entra:

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

استراح

واجهة برمجة تطبيقات الإصدار 1

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

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:

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

دعم النموذج

بالنسبة لنماذج Azure OpenAI، نوصي باستخدام واجهة برمجة تطبيقات الاستجابات، ومع ذلك، تتيح لك واجهة برمجة تطبيقات 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 الذكاء الاصطناعي وDeepSeek ونماذج Grok. لتعلم كيفية استخدام واجهة برمجة تطبيقات الاستجابات مع هذه النماذج، راجع كيفية توليد ردود نصية باستخدام نماذج مايكروسوفت فاوندري.

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

JavaScript

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

دعم واجهة برمجة تطبيقات الإصدار 1

• مواصفات الإصدار 1 OpenAPI 3.0

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

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

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

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

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

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

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

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

التغييرات بين معاينة 2025-02-01 و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.
  • تحسينات تكامل الذكاء الاصطناعي Search vectorization.

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

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

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

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

التغييرات بين 2024-03-01-preview ومواصفات واجهة برمجة التطبيقات 2024-04-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 Management.

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

• لغات البرمجة المدعومة لواجهة برمجة التطبيقات v1
• نماذج المسبك التي تباع مباشرة بواسطة Azure
• العمل مع نماذج Azure OpenAI
• حصص وحدود Azure OpenAI
• مواصفات الإصدار 1 OpenAPI 3.0