Azure OpenAI di Microsoft Foundry Models v1 API

Artikel ini menunjukkan kepada Anda cara menggunakan API OpenAI Azure v1. API v1 menyederhanakan autentikasi, menghapus kebutuhan akan parameter tanggal api-version , dan mendukung panggilan model lintas penyedia.

Catatan

Objek respons API baru mungkin ditambahkan ke respons API kapan saja. Kami merekomendasikan Anda hanya mengurai objek respons yang Anda butuhkan.

Prasyarat

• Langganan Azure - Buat langganan secara gratis
• Sumber daya Foundry atau sumber daya Azure OpenAI disebarkan di wilayah didukung
• Setidaknya satu penerapan model
• Untuk autentikasi Microsoft Entra ID: peran Cognitive Services OpenAI User yang ditetapkan ke identitas Anda. Untuk informasi selengkapnya, lihat kontrol akses berbasis Role untuk Azure OpenAI

Evolusi API

Sebelumnya, Azure OpenAI menerima pembaruan bulanan dari versi API baru. Memanfaatkan fitur baru yang diperlukan terus memperbarui kode dan variabel lingkungan dengan setiap rilis API baru. Azure OpenAI juga memerlukan langkah tambahan untuk menggunakan klien tertentu Azure yang membuat overhead saat memigrasikan kode antara OpenAI dan Azure OpenAI.

Mulai Agustus 2025, Anda dapat ikut serta ke API OpenAI Azure generasi berikutnya yang menambahkan dukungan untuk:

• Akses berkelanjutan ke fitur terbaru tanpa perlu menentukan api-version baru setiap bulan.
• Siklus rilis API yang lebih cepat dengan fitur baru diluncurkan lebih sering.
• Dukungan klien OpenAI dengan perubahan kode minimal untuk bertukar antara OpenAI dan Azure OpenAI saat menggunakan autentikasi berbasis kunci.
• Dukungan klien OpenAI untuk autentikasi berbasis token dan refresh token otomatis tanpa perlu mengambil dependensi pada klien OpenAI Azure terpisah.
• Lakukan panggilan penyelesaian obrolan dengan model dari penyedia lain seperti DeepSeek dan Grok yang mendukung sintaks penyelesaian obrolan v1.

Akses ke panggilan API baru yang masih dalam pratinjau diatur dengan menyertakan header pratinjau khusus untuk fitur tertentu. Pendekatan ini memungkinkan Anda untuk ikut serta dalam fitur yang Anda inginkan, tanpa harus menukar versi API. Atau, beberapa fitur menunjukkan status pratinjau melalui jalur API mereka dan tidak memerlukan header tambahan.

Contoh:

• Saat /openai/v1/evals masih dalam pratinjau, perlu mengirimkan header "aoai-evals":"preview". /evals sudah tidak dalam tahap pratinjau.
• /openai/v1/fine_tuning/alpha/graders/ dalam pratinjau dan tidak memerlukan header kustom karena adanya alpha di jalur API.

Untuk peluncuran API awal v1 Generally Available (GA), hanya sebagian kemampuan API inferensi dan penulisan yang didukung. Semua fitur GA didukung untuk digunakan dalam produksi. Dukungan untuk lebih banyak kemampuan sedang ditambahkan dengan cepat.

Perubahan kode

Python

API v1

contoh Python v1

Kunci API:

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

Perbedaan utama dari API sebelumnya:

• OpenAI() klien digunakan alih-alih AzureOpenAI().
• Teruskan endpoint Azure OpenAI ke base_url dan tambahkan /openai/v1 ke alamat endpoint.
• api-version bukan lagi parameter yang diperlukan dengan API GA v1.

Kunci API dengan variabel lingkungan:

Atur variabel lingkungan berikut sebelum menjalankan kode:

Variabel	Nilai
OPENAI_BASE_URL	https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/
OPENAI_API_KEY	Kunci API OpenAI Azure Anda

Kemudian buat klien tanpa parameter:

client = OpenAI()

Microsoft Entra ID:

Penting

Menangani refresh token otomatis sebelumnya ditangani melalui penggunaan AzureOpenAI() klien. API v1 menghapus dependensi ini, dengan menambahkan dukungan refresh token otomatis ke OpenAI() klien.

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

• Teruskan endpoint Azure OpenAI ke base_url dan tambahkan /openai/v1 ke alamat endpoint.
• Atur api_key parameter ke token_provider untuk mengaktifkan pengambilan otomatis dan refresh token autentikasi alih-alih menggunakan kunci API statis.

C#

API v1

Contoh C# v1

Kunci API:

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

API v1

Contoh JavaScript v1

Kunci API:

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

Kunci API dengan variabel lingkungan yang ditetapkan untuk OPENAI_BASE_URL dan 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
});

Pergi

API v1

Contoh Go v1

Kunci API:

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

Kunci API dengan variabel lingkungan yang ditetapkan untuk OPENAI_BASE_URL dan 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

contoh Java v1

API v1

Kunci API:

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

Kunci API dengan variabel lingkungan yang ditetapkan untuk OPENAI_BASE_URL dan 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();

SISANYA

API v1

Kunci API:

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

Dukungan teknis model

Untuk Azure model OpenAI, sebaiknya gunakan API Responses, namun, API v1 juga memungkinkan Anda melakukan panggilan penyelesaian obrolan dengan model dari penyedia lain seperti DeepSeek dan Grok yang mendukung sintaks penyelesaian obrolan OpenAI v1.

base_url menerima format https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/ dan https://YOUR-RESOURCE-NAME.services.ai.azure.com/openai/v1/ .

Catatan

Api Respons juga berfungsi dengan Model Foundry yang dijual oleh Azure, seperti model AI Microsoft, DeepSeek, dan Grok. Untuk mempelajari cara menggunakan API Respons dengan model ini, lihat Cara menghasilkan respons teks dengan Model Foundry Microsoft.

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

Pergi

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

SISANYA

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

Dukungan API v1

• spesifikasi v1 OpenAPI 3.0

Changelog versi API

Bagian berikut ini meringkas perubahan antar versi API.

Perubahan antara rilis pratinjau v1 dan rilis pratinjau 2025-04-01

• API pratinjau v1
• Dukungan pembuatan video
• BARU Fitur API Respons:
  • Integrasi alat server Remote Model Context Protocol (MCP)
  • Dukungan untuk tugas latar belakang asinkron
  • Item penalaran yang terenkripsi
  • Pembuatan gambar

Perubahan antara 2025-04-01-preview dan 2025-03-01-preview

• GPT-image-1 Dukungan
• Ringkasan penalaran untuk o3 dan o4-mini
• API Evaluasi

Perubahan antara 2025-03-01-preview dan 2025-02-01-preview

• Response API
• Penggunaan komputer

Perubahan antara 2025-02-01-preview dan 2025-01-01-preview

• Penyelesaian tersimpan (dukungan API distilasi).

Perubahan antara 2025-01-01-preview dan 2024-12-01-preview

• prediction Ditambahkan parameter untuk dukungan output terprediksi .
• gpt-4o-audio-preview dukungan model.

Perubahan antara 2024-12-01-preview dan 2024-10-01-preview

• store, dan metadata parameter-paramater telah ditambahkan untuk mendukung penyelesaian yang tersimpan.
• reasoning_effort ditambahkan untuk model penalaran terbaru.
• user_security_context ditambahkan untuk integrasi Microsoft Defender untuk Cloud.

Perubahan antara 2024-09-01-preview dan 2024-08-01-preview

• max_completion_tokens ditambahkan untuk mendukung model o1-preview dan o1-mini. max_tokens tidak berfungsi dengan model seri o1 .
• parallel_tool_calls Ditambahkan.
• completion_tokens_details & reasoning_tokens ditambahkan.
• stream_options & include_usage ditambahkan.

Perubahan antara spesifikasi API 2024-07-01-preview dan 2024-08-01-preview

• Dukungan output terstruktur.
• API unggahan file besar ditambahkan.
• Pada perubahan data Anda:
  • Integrasi Mongo DB.
  • role_information parameter dihapus.
  • rerank_score ditambahkan ke objek kutipan.
  • Sumber data AML dihapus.
  • Peningkatan integrasi vektorisasi pencarian AI.

Perubahan antara spesifikasi API 2024-05-01-preview dan 2024-07-01-preview

• Dukungan API Batch ditambahkan.
• Parameter strategi pemotongan penyimpanan vektor.
• max_num_results bahwa alat pencarian file seharusnya menghasilkan keluaran.

Perubahan antara spesifikasi API 2024-04-01-preview dan 2024-05-01-preview

• Dukungan Asisten v2 - Alat pencarian file dan penyimpanan vektor
• Menyempurnakan checkpoints, seed, events
• Pada pembaruan data Anda
• DALL-E 2 sekarang mendukung penyebaran model dan dapat digunakan dengan API pratinjau terbaru.
• Pembaruan pemfilteran konten

Perubahan antara spesifikasi API 2024-03-01-preview dan 2024-04-01-preview

• Perubahan Yang Melanggar: Parameter penyempurnaan dihapus. Perubahan ini berdampak pada gpt-4Versi:vision-preview model.
• parameter timestamp_granularities ditambahkan.
• audioWord objek ditambahkan.
• TTS tambahan response_formats: wav & pcm.

Masalah yang diketahui

• Spesifikasi OpenAI 2025-04-01-preview Azure menggunakan OpenAPI 3.1. Ini adalah masalah umum bahwa versi ini tidak sepenuhnya didukung oleh Azure API Management.

Langkah berikutnya

• Kit Pemula Azure OpenAI
• Azure OpenAI ke Respons
• Bahasa pemrograman yang didukung untuk API v1
• Model Azure Foundry yang dijual oleh Azure
• Kerja dengan model OpenAI Azure
• Kuota dan batasan Azure OpenAI
• spesifikasi v1 OpenAPI 3.0