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

从 Azure AI 推理 SDK 迁移到 OpenAI SDK

注释

本文档引用 Microsoft Foundry (经典) 门户。

🔍 查看 Microsoft Foundry (new) 文档 ,了解新门户。

本文提供有关将应用程序从 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:返回包含ChatCompletionschoices[].message.content的对象。
  • OpenAI SDK:返回一个包含ChatCompletionchoices[].message.content对象。

这两个 SDK 都提供与响应数据类似的访问模式,包括:

  • 消息内容
  • 令牌使用情况
  • 模型信息
  • 完成原因

迁移核对清单

使用此清单确保顺利迁移:

  • 安装适用于编程语言的 OpenAI SDK
  • 更新身份验证代码(API 密钥或 Microsoft Entra ID)
  • 将终结点 URL 从 .services.ai.azure.com/models 更改为 .openai.azure.com/openai/v1/
  • 更新客户端初始化代码
  • 始终使用部署名称指定 model 参数
  • 更新请求方法调用 (completechat.completions.create
  • 更新流代码(如果适用)
  • 更新错误处理以使用 OpenAI SDK 异常
  • 全面测试所有功能
  • 更新文档和代码注释

Troubleshooting

身份验证失败

如果遇到身份验证失败,请按以下步骤执行:

  • 验证 API 密钥是否正确且未过期
  • 对于 Microsoft Entra ID,请确保应用程序具有正确的权限
  • 检查凭据范围是否已设置为 https://cognitiveservices.azure.com/.default

终结点错误

如果您遇到端点错误:

  • 验证终结点 URL 格式是否包含在 /openai/v1/ 末尾。
  • 确保资源名称正确。
  • 检查模型部署是否存在并且处于活动状态。

模型未找到这类错误

如果收到“找不到模型”错误:

  • 验证你使用的是部署名称,而不是模型名称。
  • 检查部署是否在 Microsoft Foundry 资源中处于活动状态。
  • 确保部署名称完全匹配(区分大小写)。