Выбор конечной точки и пакета SDK

7 мин

Подсказка

Дополнительные сведения см. на вкладке "Текст и изображения ".

Microsoft Foundry обеспечивает гибкость для разработки приложений чата искусственного интеллекта. Прежде чем начать разработку, важно понять доступные варианты и как решить, какие из них следует использовать. Ниже приведены некоторые рекомендации по разработке приложения:

Конечные точки: проекты Microsoft Foundry предоставляют две конечные точки, которые можно использовать для подключения и использования ресурсов проекта, таких как развертывания моделей, из клиентских приложений. Каждый проект имеет конечную точку проекта и конечную точку Azure OpenAI.
Клиентский SDK. В зависимости от выбранной конечной точки можно использовать Microsoft Foundry SDK или OpenAI SDK для разработки генеративного AI чат-приложения. Оба пакета SDK поддерживают совместимый клиентский объект OpenAI API, который может отправлять запросы на модели, но в каждом пакете SDK существуют некоторые различия в конкретных функциональных возможностях.
Проверка подлинности: В зависимости от конечной точки и комплекта SDK, которые вы выбираете для использования, существует несколько способов, с помощью которых клиентское приложение может пройти проверку подлинности в Foundry для предоставления доступа к ресурсам. Как правило, рабочие приложения должны использовать проверку подлинности с помощью идентификатора Microsoft Entra, которая требует, чтобы приложение выполнялось в контексте определенного удостоверения; однако в некоторых сценариях можно также использовать аутентификацию на основе ключей или токенов.
API чата: API клиента OpenAI поддерживает два API чата: ChatCompletions и Ответы. Хотя API ответов рекомендуется для большинства новых проектов разработки , API ChatCompletions хорошо установлен и совместим во многих моделях и платформах создания искусственного интеллекта.

Начнем с рассмотрения доступных эндпоинтов, клиентских SDK и методов аутентификации. Мы рассмотрим API Ответов и ChatCompletions позже.

Использование пакета SDK Foundry с конечной точкой проекта

SDK Microsoft Foundry предоставляет программный доступ к ресурсам в ваших проектах через REST API и клиентские библиотеки, специфические для языка, включая:

Замечание

В этом модуле используются примеры кода Python для распространенных задач. Вы можете обратиться к документации по пакету SDK для конкретного языка для эквивалентного кода на предпочитаемом языке. Каждый пакет SDK разрабатывается и поддерживается независимо, поэтому некоторые функции могут находиться на разных этапах реализации.

Установка пакета SDK

Чтобы использовать библиотеку проектов ИИ Azure в Python, установите пакет azure-ai-projects из PyPI вместе с вспомогательными пакетами:

pip install azure-ai-projects azure-identity openai

Замечание

При использовании пакета Foundry SDK для разработки чата-приложения также необходимо импортировать пакет OpenAI SDK. Функциональность клиента чата в пакете Foundry SDK является производной от пакета OpenAI SDK.

Подключение к конечной точке проекта

Каждый проект Foundry имеет уникальный endpoint, который можно найти на странице Overview в портале Foundry на https://ai.azure.com.

Конечная точка проекта принимает следующий формат:

https://{resource-name}.services.ai.azure.com/api/projects/<project-name>

Используйте эту конечную точку для создания объекта AIProjectClient :

from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient

project_endpoint = "https://{resource-name}.services.ai.azure.com/api/projects/<project-name>"
project_client = AIProjectClient(
    credential=DefaultAzureCredential(),
    endpoint=project_endpoint
)

Замечание

Код использует учетные данные по умолчанию Azure для проверки подлинности. Чтобы включить эту проверку подлинности, необходимо установить пакет azure-identity (показанный ранее в команде установки).

Подсказка

Чтобы успешно получить доступ к проекту, код должен выполняться в аутентифицированном сеансе Azure. Например, можно использовать команду Azure CLI az login для входа перед выполнением кода.

Клиент проекта (AIProjectClient) предоставляет доступ к операциям foundry-native, которые не имеют эквивалентов OpenAI. Используйте клиент project для:

Получение подключений к ресурсам
Доступ к конфигурации проекта
Включить трассировку
Управление наборами данных и индексами

Создание клиента чата

Чтобы общаться с моделью в проекте Foundry, вам нужен клиентский объект, совместимый с OpenAI. Чтобы получить его, можно использовать метод get_openai_client() клиента проекта:

openai_client = project_client.get_openai_client(api_version="2024-10-21")

Затем этот объект клиента чата можно использовать для отправки запросов в модели и возврата ответов.

Использование пакета SDK OpenAI с конечной точкой Azure OpenAI

Пакет SDK OpenAI — это официальная клиентская библиотека для вызова API OpenAI. Он обрабатывает HTTP-запросы, проверку подлинности, повторные попытки и синтаксический анализ ответа. Пакет SDK работает с моделями, размещенными в OpenAI, развертываниями Azure OpenAI и моделями Foundry, используя те же шаблоны.

Установка пакета SDK

Чтобы использовать библиотеку OpenAI в Python, установите пакет openai из PyPI вместе с вспомогательными пакетами:

pip install openai azure-identity

Замечание

Пакет azure-identity требуется, если вы планируете использовать проверку подлинности на основе маркеров для подключения к конечной точке с помощью учетных данных идентификатора Microsoft Entra.

Подключение к конечной точке Azure OpenAI

Каждый проект Foundry включает конечную точку Azure OpenAI, которую можно найти на странице обзора проекта на портале https://ai.azure.comFoundry.

Конечная точка Azure OpenAI соответствует этому формату:

https://{resource-name}.openai.azure.com/openai/v1

Создайте клиент OpenAI с помощью конечной точки и учетных данных Azure:

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

openai_client = OpenAI(  
  base_url = "https://{resource-name}.openai.azure.com/openai/v1/",  
  api_key=token_provider,
)

Помимо идентификатора Microsoft Entra (рекомендуется), вы можете пройти проверку подлинности с помощью ключа API или переменных среды.

Проверка подлинности ключа API:

import os
from openai import OpenAI

openai_client = OpenAI(
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),
    base_url="https://{resource-name}.openai.azure.com/openai/v1/"
)

Это важно

Используйте ключи API с осторожностью. Безопасно храните их в Azure Key Vault и никогда не включайте их непосредственно в код.

Переменные среды:

Если заданы OPENAI_BASE_URL и OPENAI_API_KEY переменные среды, клиент автоматически использует их:

from openai import OpenAI

openai_client = OpenAI()  # Uses environment variables

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

Создание ответов с помощью API ответов
Завершение чата и создание образа
Доступ к прямым моделям Foundry (модели, отличные от Azure OpenAI)

Использование клиентского объекта AzureOpenAI

Как правило, для чата с моделями следует использовать объект клиента OpenAI через конечную точку Azure OpenAI версии 1. Однако у вас также есть возможность создать клиентский объект AzureOpenAI , если необходимо использовать функциональные возможности из определенной версии API Azure OpenAI. Чтобы создать клиентский объект AzureOpenAI , необходимо указать версию API и конечную точку Azure, как показано ниже.

import os
from openai import AzureOpenAI

openai_client = AzureOpenAI(
    azure_endpoint = "https://{resource-name}.openai.azure.com"
    api_key=os.getenv("AZURE_OPENAI_KEY"),  
    api_version="2024-10-21",
)

Выбор между пакетом SDK Foundry и пакетом SDK OpenAI

Microsoft Foundry поддерживает два подхода к созданию приложений ИИ. Каждое из них служит разным целям, и понимание того, когда следует использовать каждое, помогает создать правильное решение.

Когда следует использовать пакет SDK Для Foundry

Используйте пакет SDK Foundry, если приложению нужны возможности Foundry:

Служба Foundry Agent для разработки и управления агентами ИИ
Рабочие процессы запуска и утверждения инструмента
Облачные оценки для тестирования и проверки ответов ИИ
Трассировка и наблюдаемость для мониторинга поведения приложений
Прямые модели Foundry (модели, отличные от Azure OpenAI, доступные в каталоге моделей)
Метаданные проекта, подключения и функции управления

Корпорация Майкрософт рекомендует пакет SDK Foundry при создании приложений с помощью агентов, вычислений или функций Foundry.

Когда следует использовать пакет SDK OpenAI

Используйте пакет SDK OpenAI, если требуется максимальная совместимость с API OpenAI:

Полная совместимость API OpenAI для существующего кода и инструментов
Переносимость между развертываниями OpenAI и Azure OpenAI
Завершение чата, ответы и изображения Api
Минимальная зависимость от специфичных для Foundry концепций

Пакет SDK OpenAI идеально подходит для рабочих нагрузок вывода модели, в которых требуется, чтобы существующий код OpenAI работал с минимальными изменениями. Однако этот подход не предоставляет функций, специфичных для Foundry, таких как агенты или оценки.

Microsoft Foundry обеспечивает гибкость в создании приложений искусственного интеллекта. Используйте Foundry SDK с AIProjectClient, когда вам нужны функции уровня проекта, такие как агенты, оценивание, трассировка и подключения. Используйте пакет SDK OpenAI, если требуется простой вывод модели с максимальной совместимостью с OpenAI. Оба пакета SDK работают с конечной точкой проекта Foundry, поэтому их можно объединить по мере необходимости в приложениях. Вы также можете использовать оба пакета SDK вместе в одном приложении — пакет SDK Foundry для функций проекта и пакет SDK OpenAI для вывода модели.

Обратная связь

Были ли сведения на этой странице полезными?