Microsoft Foundry Models v1 API'sinde Azure OpenAI

Bu makalede v1 Azure OpenAI API'sinin nasıl kullanılacağı gösterilmektedir. v1 API kimlik doğrulamasını basitleştirir, tarihli api-version parametrelere olan ihtiyacı ortadan kaldırır ve sağlayıcılar arası model çağrılarını destekler.

Uyarı

Api yanıtına istediğiniz zaman yeni API yanıt nesneleri eklenebilir. Yalnızca ihtiyacınız olan yanıt nesnelerini ayrıştırmanızı öneririz.

Önkoşullar

• Azure aboneliği - Ücretsiz bir tane oluşturun
• Desteklenen bir bölgede dağıtılan bir Foundry kaynağı veya Azure OpenAI kaynağı
• En az bir model dağıtımı
• Microsoft Entra ID kimlik doğrulaması için: Cognitive Services OpenAI User Kimliğinize atanan rol. Daha fazla bilgi için bkz. Azure OpenAI için rol tabanlı erişim denetimi

API evrimi

Daha önce Azure OpenAI yeni API sürümlerinin aylık güncelleştirmelerini almıştı. Yeni özelliklerden tam anlamıyla yararlanmak için, her yeni API sürümüyle birlikte kodu ve ortam değişkenlerini sürekli güncellemek gerekir. Azure OpenAI ayrıca Kodu OpenAI ile Azure OpenAI arasında geçirirken ek yük oluşturan Azure'a özgü istemcileri kullanmanın ek adımını da gerektiriyordu.

Ağustos 2025'den itibaren aşağıdakiler için destek ekleyen yeni nesil v1 Azure OpenAI API'lerini kabul edebilirsiniz:

• Her ay yenilerini api-versionbelirtmeye gerek olmadan en son özelliklere sürekli erişim.
• Daha sık başlatılan yeni özelliklerle daha hızlı API yayın döngüsü.
• Anahtar tabanlı kimlik doğrulaması kullanılırken OpenAI ile Azure OpenAI arasında geçiş yapmak için en az kod değişikliğiyle OpenAI istemci desteği.
• Ayrı bir Azure OpenAI istemcisine bağımlılık gerektirmeden belirteç tabanlı kimlik doğrulaması ve otomatik belirteç yenileme için OpenAI istemci desteği.
• DeepSeek ve Grok gibi v1 sohbet tamamlama söz dizimini destekleyen diğer sağlayıcılardan gelen modellerle sohbet tamamlama çağrıları yapın.

Hala önizleme aşamasında olan yeni API çağrılarına erişim, API sürümlerini değiştirmek zorunda kalmadan istediğiniz özellikleri kabul etmenize olanak sağlayan özelliğe özgü önizleme üst bilgileri geçirilerek denetlenecektir. Alternatif olarak, bazı özellikler API yolu üzerinden önizleme durumunu gösterir ve ek üst bilgi gerektirmez.

Examples:

• Daha önce /openai/v1/evals önizleme aşamasındayken bir "aoai-evals":"preview" header geçirilmesi gerekiyordu. /evals artık önizlemede değil.
• /openai/v1/fine_tuning/alpha/graders/ önizleme aşamasındadır ve API yolunda alpha bulunması nedeniyle özelleştirilmiş bir başlık gerektirmez.

İlk v1 Genel Kullanıma Açık (GA) API başlatma işlemi için, çıkarım ve yazma API'sinin özelliklerinin yalnızca bir alt kümesi desteklenir. Tüm GA özellikleri üretimde kullanılmak üzere desteklenir. Daha fazla özellik için destek hızla eklenmektedir.

Kod değişiklikleri

Python

v1 API

Python v1 örnekleri

API Anahtarı:

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

Önceki API'den önemli farklar:

• OpenAI() istemcisi yerine AzureOpenAI()kullanılır.
• base_url Azure OpenAI uç noktasını geçirir ve /openai/v1 uç nokta adresine eklenir.
• api-version artık v1 GA API'siyle gerekli bir parametre değildir.

Ortam değişkenleriyle API Anahtarı:

Kodu çalıştırmadan önce aşağıdaki ortam değişkenlerini ayarlayın:

Variable	Değer
OPENAI_BASE_URL	https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/
OPENAI_API_KEY	Azure OpenAI API anahtarınız

Ardından parametresiz istemci oluşturun:

client = OpenAI()

Microsoft Entra Id:

Önemli

Otomatik belirteç yenilemesi daha önce istemcinin AzureOpenAI() kullanımıyla işleniyordu. v1 API'si, istemciye otomatik belirteç yenileme desteği OpenAI() ekleyerek bu bağımlılığı kaldırır.

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 uç noktasını geçirir ve /openai/v1 uç nokta adresine eklenir.
• api_key parametresi olarak ayarlanır token_providerve statik API anahtarı kullanmak yerine bir kimlik doğrulama belirtecinin otomatik olarak alınmasını ve yenilenmesini etkinleştirir.

C#

v1 API

C# v1 örnekleri

API Anahtarı:

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

JavaScript

v1 API

JavaScript v1 örnekleri

API Anahtarı:

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

Ayarlanmış ortam değişkenleri ile API Anahtarı için OPENAI_BASE_URL ve 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
});

Başla

v1 API

Go v1 örnekleri

API Anahtarı:

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

Ayarlanmış ortam değişkenleri ile API Anahtarı için OPENAI_BASE_URL ve 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 örnekleri

v1 API

API Anahtarı:

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

Ayarlanmış ortam değişkenleri ile API Anahtarı için OPENAI_BASE_URL ve 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();

REST

v1 API

API Anahtarı:

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

Model desteği

Azure OpenAI modelleri için Yanıtlar API'sini kullanmanızı öneririz ancak v1 API'si, OpenAI v1 sohbet tamamlama söz dizimini destekleyen DeepSeek ve Grok gibi diğer sağlayıcılardan gelen modellerle sohbet tamamlama çağrıları yapmanıza da olanak tanır.

base_urlhem https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/ hem de https://YOUR-RESOURCE-NAME.services.ai.azure.com/openai/v1/ biçimlerini kabul eder.

Uyarı

Yanıtlar API'si doğrudan Azure tarafından satılan Microsoft AI, DeepSeek ve Grok modelleri gibi Döküm Modelleri ile de çalışır. Yanıtlar API'sini bu modellerle kullanmayı öğrenmek için bkz. Microsoft Foundry Modelleriyle metin yanıtları oluşturma.

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

Başla

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

REST

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 API desteği

• v1 OpenAPI 3.0 spesifikasyonu

API sürümü değişiklik günlüğü

Aşağıdaki bölümlerde API sürümleri arasındaki değişiklikler özetlenmektedir.

v1 önizleme sürümü ile 2025-04-01-preview arasındaki değişiklikler

• v1 önizleme API'si
• Video oluşturma desteği
• YENİ Yanıtlar API'si özellikleri:
  • Uzak Model Bağlam Protokolü (MCP) sunucuları araç tümleştirmesi
  • Zaman uyumsuz arka plan görevleri için destek
  • Şifrelenmiş akıl yürütme öğeleri
  • Görüntü oluşturma

2025-04-01-preview ile 2025-03-01-preview arasındaki değişiklikler

• GPT-image-1 destek
• o3 ve o4-mini için akıl yürütme özeti
• Değerlendirme API'si

2025-03-01-preview ile 2025-02-01-preview arasındaki değişiklikler

• Yanıtlar API'si
• Bilgisayar kullanımı

2025-02-01-preview ile 2025-01-01-preview arasındaki değişiklikler

• Depolanan tamamlamalar (distilasyon API desteği).

2025-01-01-preview ile 2024-12-01-preview arasındaki değişiklikler

• predictionparametresi, tahmin edilen çıkış desteği için eklendi.
• gpt-4o-audio-preview model desteği.

2024-12-01-preview ile 2024-10-01-preview arasındaki değişiklikler

• store ve metadata, depolanmış tamamlamalara destek için eklenen parametreler.
• reasoning_effort en son akıl yürütme modelleri için eklendi.
• Microsoft Defender for Cloud entegrasyonu için eklendi.

2024-09-01-preview ile 2024-08-01-preview arasındaki değişiklikler

• max_completion_tokens, o1-preview ve o1-mini modellerini desteklemek için eklendi. max_tokens o1 serisi modellerle çalışmaz.
• parallel_tool_calls eklendi.
• completion_tokens_details & reasoning_tokens eklendi.
• stream_options & include_usage eklendi.

2024-07-01-preview ile 2024-08-01-preview API belirtimi arasındaki değişiklikler

• Yapılandırılmış çıkışlar desteği.
• Büyük dosya yükleme API'si eklendi.
• Verilerinizde yapılan değişiklikler:
  • Mongo DB tümleştirmesi.
  • role_information parametresi kaldırıldı.
  • rerank_score alıntı nesnesine eklendi.
  • AML veri kaynağı kaldırıldı.
  • Yapay Zeka Arama vektörleştirme entegrasyon geliştirmeleri.

2024-05-01-preview ile 2024-07-01-preview API belirtimi arasındaki değişiklikler

• Batch API desteği eklendi
• Vektör deposu öbekleme stratejisi parametreleri
• max_num_results dosya arama aracının çıkarması gereken.

2024-04-01-preview ile 2024-05-01-preview API belirtimi arasındaki değişiklikler

• Yardımcılar v2 desteği - Dosya arama aracı ve vektör depolama
• Denetim noktalarını, tohumu, olayları ince ayarlama
• Veri güncelleştirmelerinizde
• DALL-E 2 artık model dağıtımını destekliyor ve en son önizleme API'siyle kullanılabilir.
• İçerik filtreleme güncelleştirmeleri

2024-03-01-preview ile 2024-04-01-preview API belirtimi arasındaki değişiklikler

• Hataya Neden Olan Değişiklik: Geliştirme parametreleri kaldırıldı. Bu, Sürüm: modelini etkiler gpt-4.vision-preview
• timestamp_granularities parametresi eklendi.
• audioWord nesnesi eklendi.
• İlave TTS response_formats: wav & pcm.

Bilinen sorunlar

• 2025-04-01-preview Azure OpenAI belirtimi OpenAPI 3.1'i kullanır. Bu sürümün Azure API Management tarafından tam olarak desteklenmediği bilinen bir sorundur.

Sonraki Adımlar

• v1 API için desteklenen programlama dilleri
• Azure tarafından doğrudan satılan Foundry Modelleri
• Azure OpenAI modelleriyle çalışma
• Azure OpenAI kotaları ve sınırları
• v1 OpenAPI 3.0 spesifikasyonu