Azure OpenAI v rozhraní API Microsoft Foundry v1

V tomto článku se dozvíte, jak používat rozhraní API OpenAI verze 1 Azure. Rozhraní API v1 zjednodušuje ověřování, eliminuje potřebu zastaralých api-version parametrů a podporuje volání modelu napříč poskytovateli.

Poznámka

Do odpovědi rozhraní API se můžou kdykoli přidat nové objekty odpovědi rozhraní API. Doporučujeme analyzovat pouze požadované objekty odpovědi.

Požadavky

• Předplatné Azure – Kreate si ho zdarma
• Prostředek Foundry nebo Azure OpenAI prostředek nasazený v podporované oblasti
• Alespoň jedno nasazení modelu
• Pro ověřování Microsoft Entra ID je role Cognitive Services OpenAI User přiřazena vaší identitě. Další informace najdete v tématu Řízení přístupu na základě oprávnění založené na Azure OpenAI

Vývoj rozhraní API

Dříve Azure OpenAI obdržely měsíční aktualizace nových verzí rozhraní API. Využívání nových funkcí vyžadovalo neustálou aktualizaci kódu a proměnných prostředí s každou novou verzí rozhraní API. Azure OpenAI také vyžadoval další krok použití konkrétních klientů Azure, což při migraci kódu mezi OpenAI a Azure OpenAI vytvářelo dodatečné zatížení.

Od srpna 2025 se můžete rozhodnout pro novou generaci v1 Azure rozhraní API OpenAI, která přidávají podporu pro:

• Průběžný přístup k nejnovějším funkcím bez nutnosti každý měsíc definovat nové api-version.
• Rychleji vydávané verze rozhraní API a s častějším zaváděním nových funkcí.
• Podpora klientů pro OpenAI s minimálními změnami kódu pro přepínání mezi OpenAI a Azure OpenAI při použití ověřování založeného na klíči.
• Podpora klientů OpenAI pro ověřování na základě tokenů a automatická aktualizace tokenů bez nutnosti využívat závislost na samostatném klientovi Azure OpenAI.
• Volání do chatu s modely od jiných poskytovatelů, jako je DeepSeek a Grok, které podporují syntaxi dokončování chatu v1.

Přístup k novým voláním rozhraní API, která jsou stále ve verzi Preview, se řídí předáváním hlaviček verze Preview specifických pro funkce. Tento přístup umožňuje přihlásit se k požadovaným funkcím, aniž byste museli prohodit verze rozhraní API. Některé funkce označují stav preview prostřednictvím cesty k rozhraní API a nevyžadují další hlavičku.

Příklady:

• Když /openai/v1/evals byl dříve ve verzi Preview, vyžadoval předání hlavičky "aoai-evals":"preview" . /evals už není ve verzi Preview.
• /openai/v1/fine_tuning/alpha/graders/ je ve verzi Preview a nevyžaduje vlastní hlavičku kvůli přítomnosti alpha v cestě rozhraní API.

Pro počáteční spuštění rozhraní API obecně dostupné verze 1 se podporuje pouze podmnožina funkcí odvozování a vytváření rozhraní API. Všechny funkce GA jsou podporované pro použití v produkčním prostředí. Podpora pro další možnosti se přidává rychle.

Změny kódu

Python

Rozhraní API v1

příklady Python v1

Klíč rozhraní 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)) 

Hlavní rozdíly oproti předchozímu rozhraní API:

• OpenAI() klient se používá místo AzureOpenAI().
• Předejte koncový bod Azure OpenAI do base_url a na konec adresy koncového bodu přidejte /openai/v1.
• api-version už není povinný parametr u verze GA API v1.

Klíč rozhraní API s proměnnými prostředí:

Před spuštěním kódu nastavte následující proměnné prostředí:

Proměnné	Hodnota
OPENAI_BASE_URL	https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/
OPENAI_API_KEY	Klíč vašeho rozhraní API Azure OpenAI

Pak vytvořte klienta bez parametrů:

client = OpenAI()

Microsoft Entra ID:

Důležité

Zpracování automatické aktualizace tokenu bylo dříve zpracováno pomocí AzureOpenAI() klienta. Rozhraní API v1 odstraňuje tuto závislost tím, že do klienta přidává podporu automatické obnovy tokenů 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)) 

• Předejte koncový bod Azure OpenAI do base_url a na konec adresy koncového bodu přidejte /openai/v1.
• api_key Nastavte parametr tak, aby token_provider povolil automatické načítání a aktualizaci ověřovacího tokenu místo použití statického klíče rozhraní API.

C#

Rozhraní API v1

Příklady jazyka C# v1

Klíč rozhraní 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

Rozhraní API v1

Příklady JavaScriptu v1

Klíč rozhraní API:

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

Klíč rozhraní API s nastavenými proměnnými prostředí pro OPENAI_BASE_URLOPENAI_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
});

Jít

Rozhraní API v1

Příklady Go v1

Klíč rozhraní API:

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

Klíč rozhraní API s nastavenými proměnnými prostředí pro OPENAI_BASE_URLOPENAI_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

příklady Java v1

Rozhraní API v1

Klíč rozhraní API:

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

Klíč rozhraní API s nastavenými proměnnými prostředí pro OPENAI_BASE_URLOPENAI_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

Rozhraní API v1

Klíč rozhraní 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"
    }'

Podpora modelů

Pro Azure modely OpenAI doporučujeme používat rozhraní API Responses API rozhraní API verze 1 vám ale také umožňuje provádět volání chatu s modely od jiných poskytovatelů, jako je DeepSeek a Grok, které podporují syntaxi dokončování chatů OpenAI v1.

base_url přijímá oba https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/ formáty a https://YOUR-RESOURCE-NAME.services.ai.azure.com/openai/v1/ formáty.

Poznámka

Rozhraní API pro odpovědi také funguje s modely Foundry, které prodává Azure, jako jsou modely Microsoft AI, DeepSeek a Grok. Informace o tom, jak s těmito modely používat rozhraní API pro odpovědi, najdete v tématu Na generování textových odpovědí pomocí modelů 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}");

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

Jít

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

Podpora rozhraní API v1

• v1 Specifikace OpenAPI 3.0

Protokol změn verzí rozhraní API

Následující části shrnují změny mezi verzemi rozhraní API.

Změny mezi verzí "v1 preview" a "2025-04-01-preview"

• Preview API verze 1
• Podpora generování videa
• NEW Funkce rozhraní API pro odpovědi:
  • Integrace nástrojů pro servery MCP (Remote Model Context Protocol)
  • Podpora asynchronních úloh na pozadí
  • Šifrované položky zdůvodnění
  • Generování obrázků

Změny mezi 2025-04-01-preview a 2025-03-01-preview

• GPT-image-1 podporu
• Shrnutí odůvodnění pro o3 a o4-mini
• Rozhraní API pro vyhodnocení

Změny mezi 2025-03-01-preview a 2025-02-01-preview

• Rozhraní API pro odpovědi
• Použití počítače

Změny mezi 2025-02-01-preview a 2025-01-01-preview

• Uložená dokončení (podpora rozhraní API pro destilaci).

Změny mezi 2025-01-01-preview a 2024-12-01-preview

• predictionpřidání parametru pro podporu predikovaných výstupů
• gpt-4o-audio-preview podpora modelu.

Změny mezi 2024-12-01-preview a 2024-10-01-preview

• store a metadata parametry byly přidány pro podporu uložených dokončení.
• reasoning_effort přidáno pro nejnovější modely odůvodnění.
• user_security_context přidána pro integraci Microsoft Defender for Cloud.

Změny mezi 9. 9. 2024 a 2024-08-01-preview

• max_completion_tokens přidáno do podpory o1-preview a o1-mini modelů. max_tokens nefunguje s modely řady o1 .
• parallel_tool_calls přidáno.
• completion_tokens_details & reasoning_tokens přidáno.
• stream_options & include_usage přidáno.

Změny mezi specifikací rozhraní API verze 2024-07-01-preview a 2024-08-01-preview

• Podpora strukturovaných výstupů
• Bylo přidáno rozhraní API pro nahrávání velkých souborů.
• Ve vašich změnách dat:
  • Integrace MongoDB.
  • role_information parametr byl odebrán.
  • rerank_score přidán do objektu citace.
  • Zdroj dat AML byl odebrán.
  • Vylepšení integrace vektorizace vyhledávání AI

Změny mezi specifikací rozhraní API verze 2024-05-01-Preview a 2024-07-01-Preview

• Byla přidána podpora rozhraní API služby Batch.
• Parametry strategie rozdělování na bloky v úložišti vektorů.
• max_num_results by měl být výstupem nástroje pro vyhledávání souborů.

Změny ve specifikaci rozhraní API mezi verzemi 2024-04-01-preview a 2024-05-01-preview

• Podpora asistentů v2 – Nástroj pro vyhledávání souborů a vektorové úložiště
• Jemné ladění checkpoints, seed, events
• K vašim aktualizacím dat
• DALL-E 2 teď podporuje nasazení modelu a dá se použít s nejnovějším rozhraním API ve verzi Preview.
• Aktualizace filtrování obsahu

Změny ve specifikaci rozhraní API mezi verzemi 2024-03-01-preview a 2024-04-01-preview

• Změna způsobující chybu: Parametry vylepšení byly odebrány. Tato změna ovlivňuje model gpt-4Verze:vision-preview
• přidání parametru timestamp_granularities
• audioWord objekt byl přidán.
• Další TTS response_formats: wav & pcm.

Známé problémy

• Specifikace 2025-04-01-preview Azure OpenAI používá OpenAPI 3.1. Jedná se o známý problém, že tato verze není plně podporovaná nástrojem Azure API Management.

Další kroky

• Podporované programovací jazyky pro rozhraní API v1
• Foundry Models prodávané společností Azure
• Práce s modely Azure OpenAI
• Kvóty a omezení pro Azure OpenAI
• v1 Specifikace OpenAPI 3.0