你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站,请访问 https://docs.azure.cn。
本文提供有关将应用程序从 Azure AI 推理 SDK 迁移到 OpenAI SDK 的指导。 OpenAI SDK 提供更广泛的兼容性、对最新 OpenAI 功能的访问权限,以及跨 Azure OpenAI 和 Foundry 模型使用统一模式简化代码。
注释
OpenAI SDK 是指连接到 openai的客户端库(例如 Python openai 包或 JavaScript npm 包)。 这些 SDK 具有与 API 版本不同的版本控制 -例如,Go OpenAI SDK 当前为 v3,但它仍连接到 URL 路径中的 OpenAI v1 API 终结点 /openai/v1/ 。
迁移的好处
迁移到 OpenAI SDK 提供了以下几个优势:
- 更广泛的模型支持:在 Foundry 模型中与 Azure OpenAI 配合使用,以及 DeepSeek 和 Grok 等提供商的其他 Foundry 模型
- 统一 API:对 OpenAI 和 Azure OpenAI 终结点使用相同的 SDK 库和客户端
- 最新功能:访问最新的 OpenAI 功能,而无需等待特定于 Azure 的更新
- 简化的身份验证:对 API 密钥和 Microsoft Entra ID 身份验证的内置支持
-
隐式 API 版本控制:v1 API 无需频繁更新
api-version参数
主要差异
下表显示了两个 SDK 之间的主要差异:
| 方面 | Azure AI 推理 SDK | OpenAI SDK |
|---|---|---|
| 客户端类 | ChatCompletionsClient |
OpenAI |
| 终结点格式 | https://<resource>.services.ai.azure.com/models |
https://<resource>.openai.azure.com/openai/v1/ |
| API 版本 | URL 或参数中必须包含 | 不需要(使用 v1 API) |
| 模型参数 | 可选(对于多模型终结点) | 必填(部署名称) |
| Authentication | 仅限 Azure 凭据 | API 密钥或 Azure 凭据 |
设置
安装 OpenAI SDK:
pip install openai
为了进行Microsoft Entra ID身份验证,还安装:
pip install azure-identity
客户端配置
使用 API 密钥身份验证:
import os
from openai import OpenAI
client = OpenAI(
api_key=os.getenv("AZURE_OPENAI_API_KEY"),
base_url="https://<resource>.openai.azure.com/openai/v1/",
)
使用 Microsoft Entra ID 身份验证:
from openai import OpenAI
from azure.identity import DefaultAzureCredential, get_bearer_token_provider
token_provider = get_bearer_token_provider(
DefaultAzureCredential(),
"https://cognitiveservices.azure.com/.default"
)
client = OpenAI(
base_url="https://<resource>.openai.azure.com/openai/v1/",
api_key=token_provider,
)
聊天补全
completion = client.chat.completions.create(
model="DeepSeek-V3.1", # Required: your deployment name
messages=[
{"role": "system", "content": "You are a helpful assistant."},
{"role": "user", "content": "What is Azure AI?"}
]
)
print(completion.choices[0].message.content)
流媒体
stream = client.chat.completions.create(
model="DeepSeek-V3.1",
messages=[
{"role": "system", "content": "You are a helpful assistant."},
{"role": "user", "content": "Write a poem about Azure."}
],
stream=True
)
for chunk in stream:
if chunk.choices[0].delta.content:
print(chunk.choices[0].delta.content, end="")
嵌入
from openai import OpenAI
from azure.identity import DefaultAzureCredential, get_bearer_token_provider
token_provider = get_bearer_token_provider(DefaultAzureCredential(),
"https://cognitiveservices.azure.com/.default")
client = OpenAI(
base_url = "https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
api_key = token_provider,
)
response = client.embeddings.create(
input = "How do I use Python in VS Code?",
model = "text-embedding-3-large" // Use the name of your deployment
)
print(response.data[0].embedding)
设置
安装 OpenAI SDK:
dotnet add package OpenAI
为了进行Microsoft Entra ID身份验证,还安装:
dotnet add package Azure.Identity
客户端配置
使用 API 密钥身份验证:
using OpenAI;
using OpenAI.Chat;
using System.ClientModel;
ChatClient client = new(
model: "gpt-4o-mini", // Your deployment name
credential: new ApiKeyCredential(Environment.GetEnvironmentVariable("AZURE_OPENAI_API_KEY")),
options: new OpenAIClientOptions() {
Endpoint = new Uri("https://<resource>.openai.azure.com/openai/v1/")
}
);
使用 Microsoft Entra ID 身份验证:
using Azure.Identity;
using OpenAI;
using OpenAI.Chat;
using System.ClientModel.Primitives;
#pragma warning disable OPENAI001
BearerTokenPolicy tokenPolicy = new(
new DefaultAzureCredential(),
"https://cognitiveservices.azure.com/.default"
);
ChatClient client = new(
model: "gpt-4o-mini", // Your deployment name
authenticationPolicy: tokenPolicy,
options: new OpenAIClientOptions() {
Endpoint = new Uri("https://<resource>.openai.azure.com/openai/v1/")
}
);
聊天补全
using OpenAI.Chat;
ChatCompletion completion = client.CompleteChat(
new SystemChatMessage("You are a helpful assistant."),
new UserChatMessage("What is Azure AI?")
);
Console.WriteLine(completion.Content[0].Text);
流媒体
using OpenAI.Chat;
CollectionResult<StreamingChatCompletionUpdate> updates = client.CompleteChatStreaming(
new SystemChatMessage("You are a helpful assistant."),
new UserChatMessage("Write a poem about Azure.")
);
foreach (StreamingChatCompletionUpdate update in updates)
{
foreach (ChatMessageContentPart part in update.ContentUpdate)
{
Console.Write(part.Text);
}
}
嵌入
using OpenAI;
using OpenAI.Embeddings;
using System.ClientModel;
EmbeddingClient client = new(
"text-embedding-3-small",
credential: new ApiKeyCredential("API-KEY"),
options: new OpenAIClientOptions()
{
Endpoint = new Uri("https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1")
}
);
string input = "This is a test";
OpenAIEmbedding embedding = client.GenerateEmbedding(input);
ReadOnlyMemory<float> vector = embedding.ToFloats();
Console.WriteLine($"Embeddings: [{string.Join(", ", vector.ToArray())}]");
设置
安装 OpenAI SDK:
npm install openai
为了进行Microsoft Entra ID身份验证,还安装:
npm install @azure/identity
客户端配置
使用 API 密钥身份验证:
import { OpenAI } from "openai";
const client = new OpenAI({
baseURL: "https://<resource>.openai.azure.com/openai/v1/",
apiKey: process.env.AZURE_OPENAI_API_KEY
});
使用 Microsoft Entra ID 身份验证:
import { DefaultAzureCredential, getBearerTokenProvider } from "@azure/identity";
import { OpenAI } from "openai";
const tokenProvider = getBearerTokenProvider(
new DefaultAzureCredential(),
'https://cognitiveservices.azure.com/.default'
);
const client = new OpenAI({
baseURL: "https://<resource>.openai.azure.com/openai/v1/",
apiKey: tokenProvider
});
聊天补全
const completion = await client.chat.completions.create({
model: "DeepSeek-V3.1", // Required: your deployment name
messages: [
{ role: "system", content: "You are a helpful assistant." },
{ role: "user", content: "What is Azure AI?" }
]
});
console.log(completion.choices[0].message.content);
流媒体
const stream = await client.chat.completions.create({
model: "DeepSeek-V3.1",
messages: [
{ role: "system", content: "You are a helpful assistant." },
{ role: "user", content: "Write a poem about Azure." }
],
stream: true
});
for await (const chunk of stream) {
if (chunk.choices[0]?.delta?.content) {
process.stdout.write(chunk.choices[0].delta.content);
}
}
嵌入
import OpenAI from "openai";
import { getBearerTokenProvider, DefaultAzureCredential } from "@azure/identity";
const tokenProvider = getBearerTokenProvider(
new DefaultAzureCredential(),
'https://cognitiveservices.azure.com/.default');
const client = new OpenAI({
baseURL: "https://<resource>.openai.azure.com/openai/v1/",
apiKey: tokenProvider
});
const embedding = await client.embeddings.create({
model: "text-embedding-3-large", // Required: your deployment name
input: "The quick brown fox jumped over the lazy dog",
encoding_format: "float",
});
console.log(embedding);
设置
将 OpenAI SDK 添加到项目。 有关最新版本和安装说明,请查看 OpenAI Java GitHub 存储库 。
对于 Microsoft Entra ID 认证,还需添加:
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-identity</artifactId>
<version>1.18.0</version>
</dependency>
客户端配置
使用 API 密钥身份验证:
import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
OpenAIClient client = OpenAIOkHttpClient.builder()
.baseUrl("https://<resource>.openai.azure.com/openai/v1/")
.apiKey(System.getenv("AZURE_OPENAI_API_KEY"))
.build();
使用 Microsoft Entra ID 身份验证:
import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.azure.identity.DefaultAzureCredential;
import com.azure.identity.DefaultAzureCredentialBuilder;
DefaultAzureCredential tokenCredential = new DefaultAzureCredentialBuilder().build();
OpenAIClient client = OpenAIOkHttpClient.builder()
.baseUrl("https://<resource>.openai.azure.com/openai/v1/")
.credential(BearerTokenCredential.create(
AuthenticationUtil.getBearerTokenSupplier(
tokenCredential,
"https://cognitiveservices.azure.com/.default"
)
))
.build();
聊天补全
import com.openai.models.chat.completions.*;
ChatCompletionCreateParams params = ChatCompletionCreateParams.builder()
.addSystemMessage("You are a helpful assistant.")
.addUserMessage("What is Azure AI?")
.model("DeepSeek-V3.1") // Required: your deployment name
.build();
ChatCompletion completion = client.chat().completions().create(params);
System.out.println(completion.choices().get(0).message().content());
流媒体
import com.openai.models.chat.completions.*;
import java.util.stream.Stream;
ChatCompletionCreateParams params = ChatCompletionCreateParams.builder()
.addSystemMessage("You are a helpful assistant.")
.addUserMessage("Write a poem about Azure.")
.model("DeepSeek-V3.1") // Required: your deployment name
.build();
Stream<ChatCompletionChunk> stream = client.chat().completions().createStreaming(params);
stream.forEach(chunk -> {
if (chunk.choices() != null && !chunk.choices().isEmpty()) {
String content = chunk.choices().get(0).delta().content();
if (content != null) {
System.out.print(content);
}
}
});
嵌入
package com.openai.example;
import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.embeddings.EmbeddingCreateParams;
import com.openai.models.embeddings.EmbeddingModel;
public final class EmbeddingsExample {
private EmbeddingsExample() {}
public static void main(String[] args) {
// Configures using one of:
// - The `OPENAI_API_KEY` environment variable
// - The `OPENAI_BASE_URL` and `AZURE_OPENAI_KEY` environment variables
OpenAIClient client = OpenAIOkHttpClient.fromEnv();
EmbeddingCreateParams createParams = EmbeddingCreateParams.builder()
.input("The quick brown fox jumped over the lazy dog")
.model(EmbeddingModel.TEXT_EMBEDDING_3_SMALL)
.build();
System.out.println(client.embeddings().create(createParams));
}
}
设置
安装 OpenAI SDK:
go get github.com/openai/openai-go/v3
为了进行Microsoft Entra ID身份验证,还安装:
go get -u github.com/Azure/azure-sdk-for-go/sdk/azidentity
客户端配置
使用 API 密钥身份验证:
import (
"github.com/openai/openai-go/v3"
"github.com/openai/openai-go/v3/option"
)
client := openai.NewClient(
option.WithBaseURL("https://<resource>.openai.azure.com/openai/v1/"),
option.WithAPIKey(os.Getenv("AZURE_OPENAI_API_KEY")),
)
使用 Microsoft Entra ID 身份验证:
import (
"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"
)
tokenCredential, err := azidentity.NewDefaultAzureCredential(nil)
if err != nil {
panic(err)
}
client := openai.NewClient(
option.WithBaseURL("https://<resource>.openai.azure.com/openai/v1/"),
azure.WithTokenCredential(tokenCredential),
)
聊天补全
import (
"context"
"fmt"
"github.com/openai/openai-go/v3"
)
chatCompletion, err := client.Chat.Completions.New(context.TODO(), openai.ChatCompletionNewParams{
Messages: []openai.ChatCompletionMessageParamUnion{
openai.SystemMessage("You are a helpful assistant."),
openai.UserMessage("What is Azure AI?"),
},
Model: "DeepSeek-V3.1", // Required: your deployment name
})
if err != nil {
panic(err.Error())
}
fmt.Println(chatCompletion.Choices[0].Message.Content)
流媒体
import (
"context"
"fmt"
"github.com/openai/openai-go/v3"
)
stream := client.Chat.Completions.NewStreaming(context.TODO(), openai.ChatCompletionNewParams{
Messages: []openai.ChatCompletionMessageParamUnion{
openai.SystemMessage("You are a helpful assistant."),
openai.UserMessage("Write a poem about Azure."),
},
Model: "DeepSeek-V3.1", // Required: your deployment name
})
for stream.Next() {
chunk := stream.Current()
if len(chunk.Choices) > 0 && chunk.Choices[0].Delta.Content != "" {
fmt.Print(chunk.Choices[0].Delta.Content)
}
}
if err := stream.Err(); err != nil {
panic(err.Error())
}
嵌入
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() {
tokenCredential, err := azidentity.NewDefaultAzureCredential(nil)
if err != nil {
log.Fatalf("Error creating credential:%s", err)
}
// Create a client with Azure OpenAI endpoint and Entra ID credentials
client := openai.NewClient(
option.WithBaseURL("https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/"),
azure.WithTokenCredential(tokenCredential),
)
inputText := "The quick brown fox jumped over the lazy dog"
// Make the embedding request synchronously
resp, err := client.Embeddings.New(context.Background(), openai.EmbeddingNewParams{
Model: openai.EmbeddingModel("text-embedding-3-large"), // Use your deployed model name on Azure
Input: openai.EmbeddingNewParamsInputUnion{
OfArrayOfStrings: []string{inputText},
},
})
if err != nil {
log.Fatalf("Failed to get embedding: %s", err)
}
if len(resp.Data) == 0 {
log.Fatalf("No embedding data returned.")
}
// Print embedding information
embedding := resp.Data[0].Embedding
fmt.Printf("Embedding Length: %d\n", len(embedding))
fmt.Println("Embedding Values:")
for _, value := range embedding {
fmt.Printf("%f, ", value)
}
fmt.Println()
}
常见迁移模式
模型参数处理
-
Azure AI 推理 SDK:对于单模型终结点,参数
model是可选的,但多模型终结点是必需的。 -
OpenAI SDK:参数
model始终是必需的,应设置为部署名称。
终结点 URL 格式
-
Azure AI 推理 SDK:使用
https://<resource>.services.ai.azure.com/models。 -
OpenAI SDK:使用
https://<resource>.openai.azure.com/openai/v1(连接到 OpenAI v1 API)。
响应结构
响应结构类似,但存在一些差异:
-
Azure AI 推理 SDK:返回包含
ChatCompletions和choices[].message.content的对象。 -
OpenAI SDK:返回一个包含
ChatCompletion的choices[].message.content对象。
这两个 SDK 都提供与响应数据类似的访问模式,包括:
- 消息内容
- 令牌使用情况
- 模型信息
- 完成原因
迁移核对清单
使用此清单确保顺利迁移:
- 安装适用于编程语言的 OpenAI SDK
- 更新身份验证代码(API 密钥或 Microsoft Entra ID)
- 将终结点 URL 从
.services.ai.azure.com/models更改为.openai.azure.com/openai/v1/ - 更新客户端初始化代码
- 始终使用部署名称指定
model参数 - 更新请求方法调用 (
complete→chat.completions.create) - 更新流代码(如果适用)
- 更新错误处理以使用 OpenAI SDK 异常
- 全面测试所有功能
- 更新文档和代码注释
Troubleshooting
身份验证失败
如果遇到身份验证失败,请按以下步骤执行:
- 验证 API 密钥是否正确且未过期
- 对于 Microsoft Entra ID,请确保应用程序具有正确的权限
- 检查凭据范围是否已设置为
https://cognitiveservices.azure.com/.default
终结点错误
如果您遇到端点错误:
- 验证终结点 URL 格式是否包含在
/openai/v1/末尾。 - 确保资源名称正确。
- 检查模型部署是否存在并且处于活动状态。
模型未找到这类错误
如果收到“找不到模型”错误:
- 验证你使用的是部署名称,而不是模型名称。
- 检查部署是否在 Microsoft Foundry 资源中处于活动状态。
- 确保部署名称完全匹配(区分大小写)。