Примечание.
Для доступа к этой странице требуется авторизация. Вы можете попробовать войти или изменить каталоги.
Для доступа к этой странице требуется авторизация. Вы можете попробовать изменить каталоги.
Ресурс Foundry предоставляет унифицированный доступ к моделям, агентам и средствам. В этой статье объясняется, какой пакет SDK и конечная точка используются для вашего сценария.
| SDK | Для чего предназначен | Endpoint |
|---|---|---|
| Foundry SDK | Специфические для foundry возможности с интерфейсами, совместимыми с OpenAI. Включает доступ к моделям Foundry непосредственно через API ответов (в отличие от завершений чата). | https://<resource-name>.services.ai.azure.com/api/projects/<project-name> |
| OpenAI SDK | Последние модели и функции пакета SDK OpenAI с полной поверхностью API OpenAI. Модели Foundry напрямую доступны через API завершения чата (а не API ответов). | https://<resource-name>.openai.azure.com/openai/v1 |
| Пакеты SDK для средств foundry | Предварительно созданные решения (визуальное распознавание, речь, безопасность содержимого и многое другое). | Специфичные для инструмента конечные точки (зависят от сервиса). |
| Платформа агента | Многоагентная оркестрация в коде. Не зависят от облака. | Использует конечную точку проекта через SDK Foundry. |
Выберите пакет SDK:
- Используйте Foundry SDK при разработке приложений с агентами, оценками или специфичными для Foundry функциями.
- Используйте SDK OpenAI, когда требуется максимальная совместимость с OpenAI, или использование прямых моделей Foundry через функцию завершения чата
- Используйте пакеты SDK для средств Foundry при работе с определенными службами ИИ (визуальное распознавание, речь, язык и т. д.)
- Использование Agent Framework при создании многоагентных систем в коде (локальная оркестрация)
Замечание
Типы ресурсов: Ресурс Foundry предоставляет все ранее перечисленные конечные точки. Ресурс Azure OpenAI предоставляет только конечную точку /openai/v1 .
Проверки подлинности: Примеры здесь используют идентификатор Microsoft Entra (DefaultAzureCredential). Ключи API работают с /openai/v1. Передайте ключ api_key вместо поставщика токенов.
Предпосылки
-
Учетная запись Azure с активной подпиской. Если у вас его нет, создайте бесплатную учетную запись Azure, которая включает бесплатную пробную подписку.
Укажите одну из следующих ролей Azure RBAC для создания ресурсов Foundry и управления ими.
- Пользователь ИИ Azure (роль с минимальными привилегиями для разработки)
- Azure AI Project Manager (для управления проектами Foundry)
- Участник или владелец (для разрешений на уровне подписки)
Дополнительные сведения о разрешениях каждой роли см. в разделе "Управление доступом на основе ролей" для Microsoft Foundry.
Установите необходимые языковые среды выполнения, глобальные средства и расширения VS Code, как описано в разделе "Подготовка среды разработки".
Это важно
Перед началом работы убедитесь, что среда разработки готова.
В этой статье рассматриваются конкретные сценарии, такие как установка пакета SDK, проверка подлинности и выполнение примера кода.
проверка предварительных требований;
Прежде чем продолжить, подтвердите:
- [ ] Подписка Azure активна:
az account show - [ У вас есть необходимая роль RBAC: проверьте портал Azure → ресурс Foundry → управление доступом (IAM)
- [ ] Установленная среда выполнения языка:
- Python:
python --version(≥3.8) - Node.js:
node --version(≥18) - .NET:
dotnet --version(≥6.0) - Java:
java --version(≥11)
- Python:
Foundry SDK
Пакет SDK Foundry подключается к одной конечной точке проекта, которая предоставляет доступ к наиболее популярным возможностям Foundry:
https://<resource-name>.services.ai.azure.com/api/projects/<project-name>
Замечание
Если в организации используется настраиваемый поддомен, замените <resource-name> на <your-custom-subdomain> URL-адрес конечной точки.
Этот подход упрощает настройку приложения. Вместо управления несколькими конечными точками можно настроить одну.
Установите SDK
Замечание
Версии пакета SDK: Пакет SDK для предварительной версии 2.x предназначен для нового портала и API Foundry. Пакет SDK версии 1.x GA предназначен для Foundry Classic. Убедитесь, что приведенные ниже примеры соответствуют установленному пакету.
| Версия пакета SDK | Версия портала | Состояние | Пакет Python |
|---|---|---|---|
| 2.x (предварительная версия) | Литейный цех (новый) | Preview | azure-ai-projects>=2.0.0b1 --pre |
| 1.x (GA) | Классический литейный | Стабильный | azure-ai-projects==1.0.0 |
Клиентская библиотека Azure AI Projects для Python — это единая библиотека, которая позволяет использовать несколько клиентских библиотек вместе, подключаясь к одной конечной точке проекта.
Выполните эти команды, чтобы установить пакеты предварительной версии для проектов Foundry.
pip install --pre azure-ai-projects
pip install azure-identity openai
| Версия пакета SDK | Версия портала | Состояние | Пакет Java |
|---|---|---|---|
| 1.0.0-beta.3 1.0.0-beta.1 |
Литейный цех (новый) | Preview | azure-ai-projectsazure-ai-agents |
| Версия пакета SDK | Версия портала | Состояние | Пакет JavaScript |
|---|---|---|---|
| 2.0.0-beta.4 (предварительная версия) | Литейный цех (новый) | Preview | @azure/ai-projects 'prerelease' |
| 1.0.1 | Классический литейный | Стабильный | @azure/ai-projects |
| Версия пакета SDK | Версия портала | Состояние | Пакет .NET |
|---|---|---|---|
| 1.2.0-beta.5 (предварительная версия) | Литейный цех (новый) | Preview | Azure.AI.ProjectsAzure.AI.Projects.Openai |
| 1.x (GA) | Классический литейный | Стабильный | Azure.AI.Projects |
Клиентская библиотека Проектов ИИ Azure для Java (предварительная версия) — это единая библиотека, которая позволяет совместно использовать несколько клиентских библиотек, подключаясь к одной конечной точке проекта.
Это важно
Элементы, обозначенные в этой статье как (предварительная версия), сейчас предлагаются в общедоступной предварительной версии. Эта предварительная версия предоставляется без соглашения об уровне обслуживания, и мы не рекомендуем ее для рабочих нагрузок. Некоторые функции могут не поддерживаться или их возможности могут быть ограничены. Для получения дополнительной информации см. Дополнительные условия использования для предварительных версий Microsoft Azure.
Добавьте эти пакеты в установку для проектов Foundry.
package com.azure.ai.agents;
import com.azure.core.util.Configuration;
import com.azure.identity.DefaultAzureCredentialBuilder;
import com.openai.models.responses.Response;
import com.openai.models.responses.ResponseCreateParams;
Клиентская библиотека Azure AI Projects для JavaScript — это единая библиотека, которая позволяет использовать несколько клиентских библиотек вместе, подключаясь к одной конечной точке проекта.
Выполните эту команду, чтобы установить предварительные версии пакетов JavaScript для проектов Foundry.
npm install @azure/ai-projects@beta @azure/identity dotenv
Клиентская библиотека Проектов ИИ Azure для .NET — это единая библиотека, которая позволяет использовать несколько клиентских библиотек вместе, подключаясь к одной конечной точке проекта.
Выполните эту команду, чтобы добавить пакет Azure.AI.Projects в проект .NET.
dotnet add package Azure.AI.Projects --prerelease
dotnet add package Azure.AI.Projects.OpenAI --prerelease
dotnet add package Azure.Identity
Использование пакета SDK для Foundry
Пакет SDK предоставляет два типа клиентов, так как Foundry и OpenAI имеют разные формы API:
- Клиент проекта — используется для операций на основе Foundry, где OpenAI не имеет эквивалента. Примеры: перечисление подключений, получение свойств проекта, включение трассировки.
-
Клиент, совместимый с OpenAI , используется для функций Foundry, основанных на концепциях OpenAI. API ответов, оценки, агенты и дообучение используют парадигму запросов/ответов в стиле OpenAI. Этот клиент также предоставляет доступ к прямым моделям Foundry (не Azure-OpenAI моделям, размещённым в Foundry). Конечная точка проекта обслуживает этот трафик по маршруту
/openai.
Большинство приложений используют оба клиента. Используйте клиент проекта для настройки и настройки, а затем используйте клиент, совместимый с OpenAI, для выполнения агентов, вычислений и вызовов моделей (включая прямые модели Foundry).
Создайте клиент проекта:
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
project_client = AIProjectClient(
endpoint="https://<resource-name>.services.ai.azure.com/api/projects/<project-name>",
credential=DefaultAzureCredential())
Создайте клиент, совместимый с OpenAI, из проекта:
with project_client.get_openai_client() as openai_client:
response = openai_client.responses.create(
model="gpt-5.2",
input="What is the size of France in square miles?",
)
print(f"Response output: {response.output_text}")
Ожидаемые выходные данные:
Response output: France has an area of approximately 213,011 square miles (551,695 square kilometers).
Создайте клиент проекта:
import com.azure.ai.projects.ProjectsClient;
import com.azure.ai.projects.ProjectsClientBuilder;
import com.azure.identity.DefaultAzureCredentialBuilder;
String endpoint = "https://<resource-name>.services.ai.azure.com/api/projects/<project-name>";
ProjectsClient projectClient = new ProjectsClientBuilder()
.credential(new DefaultAzureCredentialBuilder().build())
.endpoint(endpoint)
.buildClient();
```**Create and use an OpenAI-compatible client from your project:**
```java
OpenAIClient openAIClient = projectClient.getOpenAIClient();
Создайте клиент проекта:
import { DefaultAzureCredential } from "@azure/identity";
import { AIProjectClient } from "@azure/ai-projects";
import "dotenv/config";
const projectEndpoint = "https://<resource-name>.services.ai.azure.com/api/projects/<project-name>";
const deploymentName = "gpt-5.2";
const project = new AIProjectClient(projectEndpoint, new DefaultAzureCredential());
Создайте клиент, совместимый с OpenAI, из проекта:
const openAIClient = await project.getOpenAIClient();
const response = await openAIClient.responses.create({
model: deploymentName,
input: "What is the size of France in square miles?",
});
console.log(`Response output: ${response.output_text}`);
Создайте клиент проекта:
using Azure.AI.Projects.OpenAI;
using Azure.Identity;
using OpenAI.Responses;
string endpoint = "https://<resource-name>.services.ai.azure.com/api/projects/<project-name>";
AIProjectClient projectClient = new(
endpoint: new Uri(endpoint),
tokenProvider: new DefaultAzureCredential());
Создайте клиент, совместимый с OpenAI, из проекта:
#pragma warning disable OPENAI001
OpenAIResponseClient responseClient = projectClient.OpenAI.GetProjectResponsesClientForModel("gpt-5.2");
OpenAIResponse response = responseClient.CreateResponse("What is the speed of light?");
Console.WriteLine(response.GetOutputText());
#pragma warning restore OPENAI001
Как использовать Foundry SDK
- Доступ к моделям Foundry, включая Azure OpenAI
- Использование службы агента Foundry
- Запуск облачных вычислений
- Включение трассировки приложений
- Точное настройка модели
- Получение конечных точек и ключей для средств Foundry, локальной оркестрации и т. д.
Устранение неполадок
Ошибки проверки подлинности
Если вы видите DefaultAzureCredential failed to retrieve a token:
Убедитесь, что Azure CLI проходит проверку подлинности:
az account show az login # if not logged inПроверьте назначение ролей RBAC:
- Убедитесь, что у вас есть по крайней мере роль пользователя ИИ Azure в проекте Foundry
- См . статью "Назначение ролей Azure"
Для управляемого удостоверения в рабочей среде:
- Убедитесь, что у управляемого удостоверения назначена соответствующая роль
- Смотрите статью "Настройка управляемых удостоверений"
Ошибки конфигурации конечной точки
Если вы видите Connection refused или 404 Not Found:
- Убедитесь, что имена ресурсов и проектов соответствуют вашему фактическому развертыванию
-
Проверьте формат URL-адреса конечной точки: должно быть
https://<resource-name>.services.ai.azure.com/api/projects/<project-name> -
Для пользовательских поддоменов: замените
<resource-name>настраиваемым поддоменом
Несоответствие версий пакета SDK
Если примеры кода завершаются ошибкой AttributeError или ModuleNotFoundError:
-
Проверьте версию пакета SDK:
pip show azure-ai-projects # Python npm list @azure/ai-projects # JavaScript dotnet list package # .NET - Проверка выравнивания моникера: для пакета SDK 2.x требуется портал Foundry, для пакета SDK 1.x требуется классическая версия Foundry
- Переустановка с правильными флагами версий: см. команды установки в каждом разделе языка выше
OpenAI SDK
Используйте пакет SDK OpenAI, если требуется полная поверхность API OpenAI и максимальная совместимость клиента. Эта конечная точка предоставляет доступ к моделям Azure OpenAI и прямым моделям Foundry (через API ответов). Он не предоставляет доступ к функциям, зависящим от Foundry, таким как агенты и оценки.
В следующем фрагменте кода показано, как напрямую использовать конечную точку Azure OpenAI /openai/v1 .
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-name>.openai.azure.com/openai/v1/",
api_key=token_provider,
)
response = client.responses.create(
model="model_deployment_name",
input= "What is the size of France in square miles?"
)
print(response.model_dump_json(indent=2))
Ожидаемые выходные данные:
{
"id": "resp_abc123",
"object": "response",
"created": 1234567890,
"model": "gpt-5.2",
"output_text": "France has an area of approximately 213,011 square miles (551,695 square kilometers)."
}
Дополнительные сведения см. в разделе Поддерживаемые языки программирования Azure OpenAI
Это важно
Элементы, обозначенные в этой статье как (предварительная версия), сейчас предлагаются в общедоступной предварительной версии. Эта предварительная версия предоставляется без соглашения об уровне обслуживания, и мы не рекомендуем ее для рабочих нагрузок. Некоторые функции могут не поддерживаться или их возможности могут быть ограничены. Для получения дополнительной информации см. Дополнительные условия использования для предварительных версий Microsoft Azure.
В следующем фрагменте кода показано, как напрямую использовать конечную точку Azure OpenAI /openai/v1 .
import com.azure.identity.AuthenticationUtil;
import com.azure.identity.DefaultAzureCredential;
import com.azure.identity.DefaultAzureCredentialBuilder;
import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.credential.BearerTokenCredential;
import java.util.function.Supplier;
DefaultAzureCredential tokenCredential = new DefaultAzureCredentialBuilder().build();
String endpoint = "https://<resource-name>.openai.azure.com/openai/v1";
String deploymentName = "gpt-5.2";
Supplier<String> bearerTokenSupplier = AuthenticationUtil.getBearerTokenSupplier(
tokenCredential, "https://cognitiveservices.azure.com/.default");
OpenAIClient openAIClient = OpenAIOkHttpClient.builder()
.baseUrl(endpoint)
.credential(BearerTokenCredential.create(bearerTokenSupplier))
.build();
ResponseCreateParams responseCreateParams = ResponseCreateParams.builder()
.input("What is the speed of light?")
.model(deploymentName)
.build();
Response response = openAIClient.responses().create(responseCreateParams);
System.out.println("Response output: " + response.getOutputText());
Дополнительные сведения об использовании пакета SDK OpenAI смотрите в разделе поддерживаемые языки программирования Azure OpenAI.
const endpoint = "https://<resource-name>.openai.azure.com/openai/v1";
const scope = "https://cognitiveservices.azure.com/.default";
const azureADTokenProvider = getBearerTokenProvider(new DefaultAzureCredential(), scope);
const client = new OpenAI({ baseURL: endpoint, apiKey: azureADTokenProvider });
const response = await client.responses.create({
model: deploymentName,
input: "What is the size of France in square miles?",
});
console.log(`Response output: ${response.output_text}`);
Дополнительные сведения об использовании пакета SDK OpenAI смотрите в разделе поддерживаемые языки программирования Azure OpenAI.
- Установите пакет OpenAI: выполните следующую команду, чтобы добавить клиентская библиотека OpenAI в проект .NET.
dotnet add package OpenAI ```When it succeeds, the .NET CLI confirms that it installed the `OpenAI` package. This snippet configures `DefaultAzureCredential`, builds `OpenAIClientOptions`, and creates a `ResponseClient` for the Azure OpenAI v1 endpoint. ```csharp using Azure.Identity; using Azure.Core; using OpenAI; using System; using System.ClientModel.Primitives; #pragma warning disable OPENAI001 const string directModelEndpoint = "https://<resource-name>.openai.azure.com/openai/v1/"; const string deploymentName = "gpt-5.2"; BearerTokenPolicy tokenPolicy = new( new DefaultAzureCredential(), "https://cognitiveservices.azure.com/.default"); OpenAIResponseClient client = new( model: deploymentName, authenticationPolicy: tokenPolicy, // To use Entra // credential: new ApiKeyCredential("<YOUR-AZURE-OPENAI-API-KEY>") // To use APIKEY options: new OpenAIClientOptions() { Endpoint = new($"{directModelEndpoint}"), }); ResponseCreationOptions options = new ResponseCreationOptions { Temperature = (float)0.7, }; OpenAIResponse modelDirectResponse = client.CreateResponse( [ ResponseItem.CreateUserMessageItem("What is the size of France in square miles?"), ], options); Console.WriteLine($"[ASSISTANT]: {modelDirectResponse.GetOutputText()}"); #pragma warning restore OPENAI001 // The ResponseClient lets you interact with models and services in your project.
Дополнительные сведения об использовании пакета SDK OpenAI смотрите в разделе поддерживаемые языки программирования Azure OpenAI.
Использование Agent Framework для локальной оркестрации
Microsoft Agent Framework — это пакет SDK с открытым кодом для создания многоагентных систем в коде (например, .NET и Python) с помощью интерфейса, не зависящем от поставщика облачных служб.
Используйте Agent Framework, если вы хотите определить и оркестрировать агентов локально. Объедините его с SDK Foundry, если вы хотите, чтобы агенты запускались на моделях Foundry или когда вы хотите, чтобы Agent Framework организовывал работу агентов, размещенных в Foundry.
Дополнительные сведения см. в обзоре Microsoft Agent Framework.
Пакеты SDK для средств литейного производства
Средства Foundry (прежнее название — службы ИИ Azure) — это предварительно созданные решения для точек с выделенными пакетами SDK. Используйте следующие конечные точки для работы с средствами Foundry.
Какую конечную точку следует использовать?
Выберите конечную точку в зависимости от ваших потребностей:
Используйте конечную точку API служб искусственного интеллекта Azure для доступа к средствам компьютерного зрения, безопасности содержимого, анализа документов, обработки языка, перевода и инструментам токенизации.
Конечная точка средств Foundry: https://<your-resource-name>.cognitiveservices.azure.com/
Замечание
Конечные точки используют имя ресурса или настраиваемый поддомен. Если ваша организация настроила настраиваемый поддомен, замените your-resource-name на your-custom-subdomain в примерах всех конечных точек.
Для средств распознавания речи и перевода используйте конечные точки в следующих таблицах. Замените заполнители сведениями о ресурсе.
Конечные точки службы "Речь"
| Инструмент Foundry | Endpoint |
|---|---|
| Речь к тексту (стандартная версия) | https://<YOUR-RESOURCE-REGION>.stt.speech.microsoft.com |
| Преобразование текста в речь (нейронное) | https://<YOUR-RESOURCE-REGION>.tts.speech.microsoft.com |
| Custom Voice | https://<YOUR-RESOURCE-NAME>.cognitiveservices.azure.com/ |
Конечные точки перевода
| Инструмент Foundry | Endpoint |
|---|---|
| Перевод текста | https://api.cognitive.microsofttranslator.com/ |
| Перевод документов | https://<YOUR-RESOURCE-NAME>.cognitiveservices.azure.com/ |
В следующих разделах содержатся ссылки на краткое руководство по пакетам SDK для средств Foundry и справочные сведения.
