Миграция из пакета SDK для вывода Azure ИИ в пакет SDK OpenAI

В этой статье приводятся рекомендации по миграции ваших приложений с Azure AI Inference SDK на OpenAI SDK. Пакет SDK OpenAI обеспечивает более широкую совместимость, доступ к новейшим функциям OpenAI и упрощенному коду с унифицированными шаблонами в Azure OpenAI и Foundry Models.

Примечание

Пакет SDK OpenAI ссылается на клиентские библиотеки (например, пакет Python openai или пакет JavaScript openai npm), которые подключаются к конечным точкам API OpenAI версии 1. Эти SDK имеют собственное управление версиями, независимое от API. Например, SDK Go OpenAI в настоящее время находится на версии 3, но по-прежнему подключается к конечным точкам API OpenAI версии 1 с /openai/v1/ в пути URL.

Преимущества миграции

Миграция на пакет SDK OpenAI обеспечивает несколько преимуществ:

  • поддержка модели Broader: работает с Azure OpenAI в модели Foundry и других моделях Foundry от поставщиков, таких как DeepSeek и Grok.
  • Unified API: использует те же библиотеки и клиенты SDK для конечных точек OpenAI и Azure OpenAI.
  • функции Последние: доступ к новейшим функциям OpenAI без ожидания обновлений Azure
  • Simplified authentication: встроенная поддержка как ключа API, так и проверки подлинности Microsoft Entra ID
  • Неявное управление версиями API: API версии 1 устраняет необходимость часто обновлять api-version параметры

Основные различия

В следующей таблице показаны основные различия между двумя пакетами SDK:

Аспект пакет SDK для вывода Azure ИИ OpenAI SDK
Класс клиента ChatCompletionsClient OpenAI
Формат конечной точки https://<resource>.services.ai.azure.com/models https://<resource>.openai.azure.com/openai/v1/
Версия API Обязательный в URL-адресе или параметре Не требуется (используется API версии 1)
Параметр модели Необязательно (для конечных точек с несколькими моделями) Обязательный (имя развертывания)
Проверки подлинности только учетные данные Azure Ключ API или учетные данные Azure

Установка

Установите пакет SDK OpenAI:

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://ai.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://ai.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)

Установка

Установите пакет SDK OpenAI:

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://ai.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())}]");

Установка

Установите пакет SDK OpenAI:

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://ai.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://ai.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);

Установка

Добавьте пакет SDK OpenAI в проект. Проверьте репозиторий 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://ai.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));
    }
}

Установка

Установите пакет SDK OpenAI:

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 Inference SDK: параметр model необязателен для конечных точек с одной моделью, но требуется для многомодельных конечных точек.
  • Пакет SDK OpenAI: model параметр всегда обязателен и должен быть установлен как имя вашего развертывания.

Формат URL-адреса конечной точки

  • SDK для инференса Azure AI: использует https://<resource>.services.ai.azure.com/models.
  • Пакет SDK OpenAI: использует https://<resource>.openai.azure.com/openai/v1 (подключается к API OpenAI версии 1).

Структура ответа

Структура отклика аналогична, но имеет некоторые отличия:

  • Azure AI Inference SDK: возвращает объект ChatCompletions с choices[].message.content.
  • Пакет SDK OpenAI: возвращает объект ChatCompletion с choices[].message.content.

Оба пакета SDK предоставляют аналогичные шаблоны доступа к данным ответа, в том числе:

  • Содержимое сообщения
  • Использование токена
  • Сведения о модели
  • Причина завершения

Контрольный список миграции

Используйте этот контрольный список для обеспечения плавной миграции:

  • Установка пакета SDK OpenAI для языка программирования
  • Обновление кода проверки подлинности (ключ API или Microsoft Entra ID)
  • Измените URL-адреса конечной точки с .services.ai.azure.com/models на .openai.azure.com/openai/v1/
  • Измените область учетных данных с https://cognitiveservices.azure.com/.default на https://ai.azure.com/.default
  • Обновление кода инициализации клиента
  • Всегда задавайте параметр model с названием вашего развертывания.
  • Обновление вызовов метода запроса (completechat.completions.create)
  • Обновление кода потоковой передачи при необходимости
  • Обновите обработку ошибок для использования исключений OpenAI SDK
  • Тщательно протестируйте все функциональные возможности
  • Обновление документации и комментариев кода

Устранение неполадок

Сбои проверки подлинности

Если возникают сбои проверки подлинности:

  • Убедитесь, что ключ API является правильным и не истекает
  • Для Microsoft Entra ID убедитесь, что приложение имеет правильные разрешения
  • Убедитесь, что для области учетных данных задано значение https://ai.azure.com/.default

Ошибки конечной точки

Если вы сталкиваетесь с ошибками конечного узла:

  • Убедитесь, что формат URL-адреса конечной точки включает /openai/v1/ в конце.
  • Убедитесь, что имя ресурса правильно.
  • Убедитесь, что развертывание модели существует и активно.

Ошибки модели не найдены

Если вы получаете ошибку "модель не найдена":

  • Убедитесь, что вы используете имя развертывания, а не имя модели.
  • Убедитесь, что развертывание активно в вашем ресурсе Microsoft Foundry.
  • Убедитесь, что имя развертывания совпадает точно (с учетом регистра).