你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

在 Microsoft Foundry v1 模型 API 中的 Azure OpenAI

本文介绍如何使用 v1 Azure OpenAI API。 v1 API 简化了身份验证，消除了对日期 api-version 参数的需求，并支持跨提供程序模型调用。

注意

可以随时将新的 API 响应对象添加到 API 响应中。建议仅分析所需的响应对象。

先决条件

Azure订阅 - 免费创建一个订阅
在支持的区域中部署的 Foundry 资源或 Azure OpenAI 资源
至少一个模型部署
对于 Microsoft Entra ID 身份验证：分配给标识的 Cognitive Services OpenAI User 角色。有关详细信息，请参阅 Azure OpenAI 角色基于的访问控制

API 演变

以前，Azure OpenAI 收到新 API 版本的每月更新。使用新功能需要在每次新的 API 发布时不断更新代码和环境变量。 Azure OpenAI 还需要额外的一步，即使用 Azure 专用客户端，这在 OpenAI 与 Azure OpenAI 之间迁移代码时增加了开销。

从 2025 年 8 月开始，可以选择加入下一代 v1 Azure OpenAI API，该 API 添加了对以下方面的支持：

持续访问最新功能，无需每月指定新的 api-version。
随着新功能的启动频率更高，API 发布周期更快。
使用基于密钥的身份验证时，OpenAI 客户端支持最少的代码更改，以在 OpenAI 与 Azure OpenAI 之间交换。
OpenAI 客户端支持基于令牌的身份验证和自动令牌刷新，而不需要依赖单独的 Azure OpenAI 客户端。
使用支持 v1 聊天补全语法的其他提供程序（例如 DeepSeek 和 Grok）的模型进行聊天补全调用。

通过传递功能特定的预览标头来控制对仍处于预览状态的新 API 调用的访问，从而允许你选择加入所需的功能，而无需交换 API 版本。或者，某些功能将通过 API 路径指示预览状态，并且不需要其他标头。

例子：

以前/openai/v1/evals处于预览状态时，需要传递"aoai-evals":"preview"标头。 /evals 不再处于预览状态。
/openai/v1/fine_tuning/alpha/graders/ 处于预览状态，由于 API 路径中存在 alpha ，不需要自定义标头。

对于初始 v1 正式版 (GA) API 发布，仅支持推理和创作 API 功能的子集。所有 GA 功能都支持在生产环境中使用。正在迅速添加对更多功能的支持。

代码更改

v1 API

Python v1 示例

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

与上一 API 的主要区别：

OpenAI() 使用客户端而不是 AzureOpenAI().
base_url传递 Azure OpenAI 终结点，并将 /openai/v1追加到终结点地址。
api-version 不再是 v1 GA API 的必需参数。

包含环境变量的 API 密钥：

运行代码之前，请设置以下环境变量：

变量	价值
`OPENAI_BASE_URL`	`https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/`
`OPENAI_API_KEY`	Azure OpenAI API 密钥

然后创建不带参数的客户端：

client = OpenAI()

Microsoft Entra ID：

重要

以前通过使用AzureOpenAI() 客户端来处理自动令牌刷新。 v1 API 通过向客户端添加自动令牌刷新支持 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，启用身份验证令牌的自动检索和刷新，而不是使用静态 API 密钥。

v1 API

C# v1 示例

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

v1 API

JavaScript v1 示例

API 密钥：

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

为 OPENAI_BASE_URL 和 OPENAI_API_KEY 设置环境变量的 API 密钥：

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 API

Go v1 示例

API 密钥：

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 设置环境变量的 API 密钥：

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 v1 示例

v1 API

API 密钥：


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

为 OPENAI_BASE_URL 和 OPENAI_API_KEY 设置环境变量的 API 密钥：

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 API

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

模型支持

对于Azure OpenAI 模型，我们建议使用 Responses API，但 v1 API 还允许你与其他提供程序（例如 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/ 格式。

注意

响应 API 还适用于Azure直接销售的 Foundry 模型，例如 Microsoft AI、DeepSeek 和 Grok 模型。若要了解如何将这些模型使用响应 API，请参阅 How to generate text responses with Microsoft Foundry Models。

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

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

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 API 支持

v1 OpenAPI 3.0 规范

API 版本更改日志

以下部分汇总了 API 版本之间的更改。

v1 预览版和 2025-04-01-preview 之间的更改

v1 预览版 API
视频生成支持
新增功能 响应 API 功能：
- 远程模型上下文协议（MCP）服务器工具集成
- 支持异步后台任务
- 加密推理项
- 图像生成

2025-04-01-preview 和 2025-03-01-preview 之间的更改

2025-03-01-preview 和 2025-02-01-preview 之间的更改

响应 API
计算机使用

2025-02-01-preview 和 2025-01-01-preview 之间的更改

存储补全（蒸馏 API 支持）。

2025-01-01-preview 和 2024-12-01-preview 之间的更改

prediction 为预测输出支持添加了参数。
gpt-4o-audio-preview 模型支持。

2024-12-01-preview 和 2024-10-01-preview 之间的更改

为存储补全支持添加了 store 以及 metadata 参数。
reasoning_effort 添加了最新推理模型。
为 Microsoft Defender for Cloud 集成添加了 user_security_context。

2024-09-01-preview 和 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 API 规范之间的更改

结构化输出支持。
添加了大型文件上传 API。
关于您的数据更改
- Mongo DB 集成。
- role_information 参数已删除。
- 添加到引文对象的 rerank_score。
- AML 数据源已删除。
- AI 搜索矢量化集成改进。

2024-05-01-preview 和 2024-07-01-preview API 规范之间的更改

添加了 Batch API 支持
矢量存储分块策略参数
文件搜索工具应输出的 max_num_results。

2024-04-01-preview 和 2024-05-01-preview API 规范之间的更改

助手 v2 支持 - 文件搜索工具和矢量存储
微调检查点、种子、事件
关于您的数据更新
DALL-E 2 现在支持模型部署，可用于最新的预览 API。
内容筛选更新

2024-03-01-preview 和 2024-04-01-preview API 规范之间的更改

重大变更：删除了增强功能的参数。这会影响 gpt-4版本：vision-preview 模型。
添加了 timestamp_granularities 参数。
添加了 audioWord 对象。
其他 TTS response_formats: wav & pcm。

已知问题

2025-04-01-preview Azure OpenAI 规范使用 OpenAPI 3.1。 Azure API 管理对该版本不完全支持是一个已知问题。

后续步骤

反馈

此页面是否有帮助？

Last updated on 2026-05-04

在 Microsoft Foundry v1 模型 API 中的 Azure OpenAI

先决条件

API 演变

代码更改

v1 API

模型支持

v1 API 支持

API 版本更改日志

v1 预览版和 2025-04-01-preview 之间的更改

2025-04-01-preview 和 2025-03-01-preview 之间的更改

2025-03-01-preview 和 2025-02-01-preview 之间的更改

2025-02-01-preview 和 2025-01-01-preview 之间的更改

2025-01-01-preview 和 2024-12-01-preview 之间的更改

2024-12-01-preview 和 2024-10-01-preview 之间的更改

2024-09-01-preview 和 2024-08-01-preview 之间的更改

2024-07-01-preview 和 2024-08-01-preview API 规范之间的更改

2024-05-01-preview 和 2024-07-01-preview API 规范之间的更改

2024-04-01-preview 和 2024-05-01-preview API 规范之间的更改

2024-03-01-preview 和 2024-04-01-preview API 规范之间的更改

已知问题

后续步骤

反馈

其他资源