Azure OpenAI 在 Azure AI Foundry 模型 API 的開發流程中

本文可協助您瞭解 Azure OpenAI API 的支援生命週期。

備註

新的 API 回應物件可能會新增至 API 回應，而不會變更版本。 我們建議您只剖析所需的回應物件。

2025-04-01-preview Azure OpenAI 規格使用 OpenAPI 3.1，但目前 Azure API 管理 尚未完全支援，這是已知的問題。

API 演進

在過去，Azure OpenAI 收到新 API 版本的每月更新。 利用新功能需要每次新 API 版本發佈時不斷更新程式代碼和環境變數。 Azure OpenAI 也需要額外的步驟，即使用 Azure 特定用戶端，這在 OpenAI 和 Azure OpenAI 之間移轉程式代碼時造成了額外的負擔。 從 2025 年 5 月開始，您現在可以選擇加入新一代 v1 Azure OpenAI API，以新增下列支援：

• 持續存取最新功能，而不需要每月更新 api-version 。
• 當使用密鑰驗證時，通過最少的程式碼變更來切換 OpenAI 和 Azure OpenAI 的用戶端支援。

針對初次預覽發布，我們僅支援推理 API 的部分功能。 在預覽階段，操作可能會有不完整的功能，並將持續擴充。

程式碼變更

API 金鑰

上一世代 API

import os
from openai import AzureOpenAI

client = AzureOpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),  
    api_version="2025-04-01-preview",
    azure_endpoint="https://YOUR-RESOURCE-NAME.openai.azure.com")
    )

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

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/",
    default_query={"api-version": "preview"}, 
)

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 附加至端點位址。
• default_query={"api-version": "preview"} 表示使用無版本一律 up-to-date 預覽 API。

發行 GA 下一代 v1 API 之後，我們將支援兩個值： latest 和 preview。 如果未提供 api-version，流量將自動路由至 latest GA 版本。 目前僅支援 preview。

Microsoft Entra 身份識別

上一世代 API

from openai import AzureOpenAI
from azure.identity import DefaultAzureCredential, get_bearer_token_provider

token_provider = get_bearer_token_provider(
    DefaultAzureCredential(), "https://cognitiveservices.azure.com/.default"
)

client = AzureOpenAI(
  azure_endpoint = "https://YOUR-RESOURCE-NAME.openai.azure.com/", 
  azure_ad_token_provider=token_provider,
  api_version="2025-04-01-preview"
)

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

from openai import AzureOpenAI
from azure.identity import DefaultAzureCredential, get_bearer_token_provider

token_provider = get_bearer_token_provider(
    DefaultAzureCredential(), "https://cognitiveservices.azure.com/.default"
)

client = AzureOpenAI(  
  base_url = "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",  
  azure_ad_token_provider=token_provider,
  api_version="preview"
)

response = client.responses.create(
    model="gpt-4.1-nano",
    input= "This is a test" 
)

print(response.model_dump_json(indent=2)) 

• AzureOpenAI() 是用來利用 azure_ad_token_provider 所提供的自動令牌刷新功能。
• base_url 會傳遞 Azure OpenAI 端點，並 /openai/v1 附加至端點位址。
• api-version="preview" 表示使用無版本一律 up-to-date 預覽 API。

發行 GA 下一代 v1 API 之後，我們將支援兩個值： latest 和 preview。 如果未提供 api-version，流量將自動路由至 latest GA 版本。 目前僅支援 preview。

休息

上一世代 API

API 金鑰：

curl -X POST https://YOUR-RESOURCE-NAME.openai.azure.com/openai/responses?api-version=2025-04-01-preview \
  -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/responses?api-version=2025-04-01-preview \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AZURE_OPENAI_AUTH_TOKEN" \
  -d '{
     "model": "gpt-4.1-nano",
     "input": "This is a test"
    }'

新一代 API

API 金鑰：

curl -X POST https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/responses?api-version=preview \
  -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?api-version=preview \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AZURE_OPENAI_AUTH_TOKEN" \
  -d '{
     "model": "gpt-4o",
     "input": "This is a test"
    }'

輸出

{
  "id": "resp_682f7eb5dc408190b491cbbe57be2fbf0f98d661c3dc276d",
  "created_at": 1747943093.0,
  "error": null,
  "incomplete_details": null,
  "instructions": null,
  "metadata": {},
  "model": "gpt-4.1-nano",
  "object": "response",
  "output": [
    {
      "id": "msg_682f7eb61d908190926a004c15c5ddd00f98d661c3dc276d",
      "content": [
        {
          "annotations": [],
          "text": "Hello! It looks like you've sent a test message. How can I assist you today?",
          "type": "output_text"
        }
      ],
      "role": "assistant",
      "status": "completed",
      "type": "message"
    }
  ],
  "parallel_tool_calls": true,
  "temperature": 1.0,
  "tool_choice": "auto",
  "tools": [],
  "top_p": 1.0,
  "background": null,
  "max_output_tokens": null,
  "previous_response_id": null,
  "reasoning": {
    "effort": null,
    "generate_summary": null,
    "summary": null
  },
  "service_tier": "default",
  "status": "completed",
  "text": {
    "format": {
      "type": "text"
    }
  },
  "truncation": "disabled",
  "usage": {
    "input_tokens": 12,
    "input_tokens_details": {
      "cached_tokens": 0
    },
    "output_tokens": 19,
    "output_tokens_details": {
      "reasoning_tokens": 0
    },
    "total_tokens": 31
  },
  "user": null,
  "store": true
}

預覽 API 釋出

Azure OpenAI API 最新版本：

• 全新 v1 預覽 API
• 推論：2025-04-01-preview
• 撰寫： 2025-04-01-preview

v1 預覽版本與 2025-04-01-preview 之間的變更

• v1 預覽 API
• 影片產生支援
• 新增功能 回應 API 功能：
  • 遠端模型內容通訊協定 （MCP） 伺服器工具整合
  • 支援非同步背景任務
  • 加密的推理項目
  • 映射產生

2025-04-01-preview 與 2025-03-01-preview 之間的變更

• GPT-image-1 支援
• o3和o4-mini的推理摘要
• 評估 API

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 已針對最新的 推理模型新增 。
• user_security_context已新增 適用於雲端的 Microsoft Defender整合。

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-5-01-preview 與 2024-07-01-preview API 規格之間的變更

• 已新增 Batch API 支援
• 向量存放區區塊化策略參數
• max_num_results 檔案搜尋工具應該輸出。

2024-04-01-preview 與 2024-05-01-preview API 規格之間的變更

• Assistants 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。

最新的 GA API 版本

Azure OpenAI API 2024-10-21 版目前是最新的 GA API 版本。 此 API 版本會取代先前的 2024-06-01 GA API 版本。

更新 API 版本

我們建議先測試新 API 版本的升級以確認 API 更新不會對您的應用程式產生影響，然後再在您的環境中進行全域變更。

如果您使用的是 OpenAI Python 或 JavaScript 用戶端程式庫或 REST API，則需要將程式碼直接更新到最新的預覽 API 版本。

如果您使用的是其中一個適用於 C#、Go 或 JAVA 的 Azure OpenAI SDK，則需要更新到最新版本的 SDK。 每個 SDK 版本都經過硬式編碼，可與特定版本的 Azure OpenAI API 搭配使用。

後續步驟

• 深入了解 Azure OpenAI
• 了解如何使用 Azure OpenAI 模型