Observação
O acesso a essa página exige autorização. Você pode tentar entrar ou alterar diretórios.
O acesso a essa página exige autorização. Você pode tentar alterar os diretórios.
Note
Este documento refere-se ao portal do Microsoft Foundry (clássico ).
🔄 Alterne para a documentação nova do Microsoft Foundry se você estiver usando o novo portal.
Note
Este documento refere-se ao portal do Microsoft Foundry (novo ).
A criação de um recurso do Foundry desbloqueia o acesso a modelos, agentes e ferramentas por meio de um conjunto unificado de SDKs e pontos de extremidade. Este artigo aborda para que serve cada SDK e para qual ponto de extremidade usar.
| SDK | Para que serve | Ponto final |
|---|---|---|
| Foundry SDK | Capacidades específicas de fundição com interfaces compatíveis com OpenAI. Inclui acesso aos modelos diretos do Foundry por meio da API de Respostas (não Conclusões de Chat). | https://<resource-name>.services.ai.azure.com/api/projects/<project-name> |
| SDK de OpenAI | Modelos e recursos mais recentes do SDK do OpenAI com a superfície completa da API OpenAI. Os modelos Foundry Direct estão disponíveis através da API Chat Completions (não Responses). | https://<resource-name>.openai.azure.com/openai/v1 |
| Foundry Tools SDKs | Soluções predefinidas (Visão, Fala, Segurança de Conteúdo e muito mais). | Pontos de extremidade específicos da ferramenta (varia de acordo com o serviço). |
| Estrutura do Agente | Orquestração de multiagentes em código. Independente de nuvem. | Usa o endpoint do projeto por meio do SDK do Foundry. |
Note
Tipos de recurso: Um recurso do Foundry fornece todos os pontos de extremidade listados anteriormente. Um recurso do Azure OpenAI fornece apenas o /openai/v1 endpoint.
Autenticação: Os exemplos aqui usam a ID do Microsoft Entra (DefaultAzureCredential). As chaves de API funcionam em /openai/v1. Passe a chave como api_key em vez de um provedor de token.
Prerequisites
-
Uma conta do Azure com uma assinatura ativa. Se você não tiver uma, crie uma conta gratuita do Azure, que inclui uma assinatura de avaliação gratuita.
Tenha uma das seguintes funções RBAC do Azure para criar e gerenciar recursos do Foundry no Azure.
- Usuário de IA do Azure (função de privilégio mínimo para desenvolvimento)
- Gerenciador de Projetos de IA do Azure (para gerenciar projetos do Foundry)
- Colaborador ou Proprietário (para permissões no nível da assinatura)
Para obter detalhes sobre as permissões de cada função, consulte o controle de acesso baseado em função para o Microsoft Foundry.
Instale os runtimes de idioma necessários, as ferramentas globais e as extensões do VS Code, conforme descrito em Preparar seu ambiente de desenvolvimento.
Important
Antes de começar, verifique se o ambiente de desenvolvimento está pronto.
Este artigo se concentra em etapas específicas do cenário , como instalação do SDK, autenticação e execução de código de exemplo.
Foundry SDK
O Foundry SDK conecta-se a um único endpoint de projeto que fornece acesso às funcionalidades mais populares do Foundry:
https://<resource-name>.services.ai.azure.com/api/projects/<project-name>
Note
Se sua organização usar um subdomínio personalizado, substitua <resource-name><your-custom-subdomain> na URL do ponto de extremidade.
Isso simplifica a configuração do aplicativo. Em vez de gerenciar vários pontos de extremidade, você configura apenas um.
Instalar o SDK
Note
Este artigo se aplica a um projeto do Foundry. O código mostrado aqui não funciona para um projeto baseado em hub. Para obter mais informações, confira Tipos de projetos.
Note
Versões do SDK: O SDK de versão prévia 2.x tem como destino o novo portal do Foundry e a API. O SDK 1.x GA tem como destino o Foundry Classic. Verifique se os exemplos a seguir correspondem ao pacote instalado.
A biblioteca de clientes do Azure AI Projects para Python é uma biblioteca unificada que permite que você use várias bibliotecas de cliente juntas conectando-se a um único ponto de extremidade de projeto.
Execute este comando para instalar os pacotes estáveis para projetos clássicos do Foundry.
pip install azure-ai-projects azure-identity openai
Execute esses comandos para instalar os pacotes de visualização para projetos do Foundry.
pip install --pre azure-ai-projects
pip install azure-identity openai
A biblioteca de clientes do Azure AI Projects para Java (versão prévia) é uma biblioteca unificada que permite que você use várias bibliotecas de cliente juntas conectando-se a um único ponto de extremidade de projeto.
Important
Os itens marcados (versão prévia) neste artigo estão atualmente em versão prévia pública. Essa versão prévia é fornecida sem um contrato de nível de serviço e não recomendamos isso para cargas de trabalho de produção. Alguns recursos podem não ter suporte ou podem ter restrição de recursos. Para obter mais informações, consulte Termos de Uso Complementares para Versões Prévias do Microsoft Azure.
Adicione estes pacotes à sua instalação:
com.azure.ai.projectscom.azure.core
A biblioteca de clientes do Azure AI Projects para JavaScript é uma biblioteca unificada que permite que você use várias bibliotecas de clientes juntas conectando-se a um único ponto de extremidade de projeto.
Execute este comando para instalar os pacotes JavaScript atuais para projetos clássicos do Foundry.
npm install @azure/ai-projects @azure/identity
Execute este comando para instalar os pacotes JavaScript de visualização para projetos do Foundry.
npm install @azure/ai-projects@beta @azure/identity
A biblioteca de clientes do Azure AI Projects para .NET é uma biblioteca unificada que permite que você use várias bibliotecas de cliente juntas conectando-se a um único ponto de extremidade de projeto.
Execute este comando para adicionar o pacote Azure.AI.Projects ao seu projeto .NET.
dotnet add package Azure.AI.Projects --version 1.2
Usando o SDK do Foundry
O SDK expõe dois tipos de cliente porque o Foundry e o OpenAI têm formas de API diferentes:
- Cliente do projeto – Use para operações nativas do Foundry em que o OpenAI não tem equivalente. Exemplos: listar conexões, recuperar propriedades do projeto, habilitar o rastreamento.
-
Cliente compatível com OpenAI – Use a funcionalidade da Foundry que se baseia em conceitos do OpenAI. A API de Respostas, agentes, avaliações e ajuste fino usam padrões de solicitação/resposta no estilo OpenAI. Esse cliente também fornece acesso aos modelos diretos do Foundry (modelos nãoAzure-OpenAI hospedados na Foundry). O endpoint do projeto atende a esse tráfego na rota
/openai.
A maioria dos aplicativos usa os dois clientes. Use o cliente do projeto para configuração e configuração e use o cliente compatível com OpenAI para executar agentes, avaliações e modelos de chamada (incluindo modelos diretos do Foundry).
Criar um cliente de projeto:
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
project = AIProjectClient(
endpoint="https://<resource-name>.services.ai.azure.com/api/projects/<project-name>",
credential=DefaultAzureCredential())
Crie um cliente compatível com OpenAI do seu projeto:
openai_client = project.inference.get_azure_openai_client(api_version="2024-10-21")
response = openai_client.responses.create(
model="gpt-5.2",
input="What is the speed of light?",
)
print(response.output_text)
Criar um cliente de projeto:
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();
Crie um cliente compatível com OpenAI do seu projeto:
OpenAIClient openAIClient = projectClient.getOpenAIClient();
Criar um cliente de projeto:
import { AIProjectClient } from '@azure/ai-projects';
import { DefaultAzureCredential } from '@azure/identity';
const endpoint = "https://<resource-name>.services.ai.azure.com/api/projects/<project-name>";
const project = new AIProjectClient(endpoint, new DefaultAzureCredential());
Crie um cliente compatível com OpenAI do seu projeto:
const openAIClient = await project.getOpenAIClient();
Criar um cliente de projeto:
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());
Crie um cliente compatível com OpenAI do seu projeto:
#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
O que você pode fazer com o SDK do Foundry
- Acessar modelos do Foundry, incluindo o Azure OpenAI
- Usar o Serviço do Foundry Agent
- Executar avaliações de nuvem
- Habilitar o rastreamento de aplicativo
- Ajustar um modelo
- Obtenha pontos de extremidade e chaves para Foundry Tools, orquestração local e muito mais
SDK de OpenAI
Utilize o SDK do OpenAI quando quiser a superfície completa da API OpenAI e a compatibilidade máxima do cliente. Este endpoint fornece acesso a modelos do Azure OpenAI e modelos diretos do Foundry (por meio da API de Completações de Chat). Ele não fornece acesso a recursos específicos do Foundry, como agentes e avaliações.
Criar um cliente OpenAI do seu projeto
Este trecho de código usa o AIProjectClient para solicitar um cliente OpenAI com escopo limitado ao seu projeto.
# Use the AIProjectClient to create an OpenAI client for your project
openai_client = project.get_openai_client(api_version="2024-10-21")
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}")
O trecho de código a seguir mostra como usar o endpoint do Azure OpenAI /openai/v1 diretamente.
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))
Para obter mais informações, consulte as linguagens de programação compatíveis com o Azure OpenAI.
Este trecho usa o AIProjectClient para solicitar um cliente OpenAI do projeto Foundry.
# Use the AIProjectClient to create an OpenAI client for your project
openai_client = project.get_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}")
O trecho de código a seguir mostra como usar diretamente o endpoint do 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))
Para obter mais informações, consulte as linguagens de programação compatíveis com o Azure OpenAI
Important
Os itens marcados (versão prévia) neste artigo estão atualmente em versão prévia pública. Essa versão prévia é fornecida sem um contrato de nível de serviço e não recomendamos isso para cargas de trabalho de produção. Alguns recursos podem não ter suporte ou podem ter restrição de recursos. Para obter mais informações, consulte Termos de Uso Complementares para Versões Prévias do Microsoft Azure.
Este snippet recupera um OpenAIClient do ProjectsClient para que você possa enviar solicitações OpenAI por meio do Foundry.
OpenAIClient openAIClient = projectClient.getOpenAIClient();
Para obter mais informações sobre como usar o SDK do OpenAI, consulte as linguagens de programação compatíveis com o Azure OpenAI.
Para obter mais informações sobre como usar o SDK do OpenAI, consulte as linguagens de programação compatíveis com o Azure OpenAI
Esse snippet usa o cliente do projeto para criar um cliente OpenAI que você pode reutilizar entre solicitações.
// Use the AIProjectClient to create an OpenAI client for your project
const openAIClient = await project.getOpenAIClient();
Para obter mais informações sobre como usar o SDK do OpenAI, consulte as linguagens de programação compatíveis com o Azure OpenAI.
Para obter mais informações sobre como usar o SDK do OpenAI, consulte as linguagens de programação compatíveis com o Azure OpenAI
Instale o pacote OpenAI:
Execute este comando para adicionar a biblioteca de clientes OpenAI ao seu projeto .NET.
dotnet add package OpenAI
Quando ele for bem-sucedido, a CLI do .NET confirmará que instalou o OpenAI pacote.
O snippet de código seguinte demonstra como criar o cliente OpenAI diretamente usando o endpoint Azure OpenAI v1.
Este trecho de código configura
DefaultAzureCredential, compilaOpenAIClientOptions, e cria um ponto de extremidadeResponseClientpara o Azure OpenAI v1.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.
Para obter mais informações sobre como usar o SDK do OpenAI, consulte as linguagens de programação compatíveis com o Azure OpenAI.
Para obter mais informações sobre como usar o SDK do OpenAI, consulte as linguagens de programação compatíveis com o Azure OpenAI
Usando a Estrutura do Agente para orquestração local
O Microsoft Agent Framework é um SDK de software livre para criar sistemas de vários agentes em código (por exemplo, .NET e Python) com uma interface independente do provedor de nuvem.
Use o Agent Framework quando quiser definir e orquestrar agentes localmente. Emparelhe-o com o SDK do Foundry quando quiser que esses agentes sejam executados em modelos do Foundry ou quando desejar que o Agent Framework orquestrá agentes hospedados no Foundry.
Para obter mais informações, consulte a visão geral do Microsoft Agent Framework.
SDKs do Foundry Tools
O Foundry Tools (anteriormente Serviços de IA do Azure) são soluções pontuais pré-construídas com SDKs dedicados. Utilize os seguintes pontos de extremidade para trabalhar com o Foundry Tools.
Qual endpoint você deve usar?
Escolha um ponto de extremidade com base em suas necessidades:
Use o ponto de extremidade dos Serviços de IA do Azure para acessar a Pesquisa Visual Computacional, a Segurança de Conteúdo, a Inteligência de Documentos, a Linguagem, a Tradução e as Ferramentas de Fundimento de Token.
Ponto de extremidade do Foundry Tools: https://<your-resource-name>.cognitiveservices.azure.com/
Note
Os pontos de extremidade usam o nome do recurso ou um subdomínio personalizado. Se sua organização configurou um subdomínio personalizado, substitua your-resource-name por your-custom-subdomain em todos os exemplos de ponto de extremidade.
Para Foundry Tools de Fala e Tradução, use os pontos de extremidade nas tabelas a seguir. Substitua os espaços reservados pelas informações do seu recurso.
Pontos de Extremidade de Fala
| Ferramenta de Fundição | Ponto final |
|---|---|
| Conversão de Fala em Texto (Padrão) | https://<YOUR-RESOURCE-REGION>.stt.speech.microsoft.com |
| Conversão de Texto em Fala (Neural) | https://<YOUR-RESOURCE-REGION>.tts.speech.microsoft.com |
| Voz Personalizada | https://<YOUR-RESOURCE-NAME>.cognitiveservices.azure.com/ |
Pontos de Extremidade de Tradução
| Ferramenta de Fundição | Ponto final |
|---|---|
| Tradução de texto | https://api.cognitive.microsofttranslator.com/ |
| Tradução de Documento | https://<YOUR-RESOURCE-NAME>.cognitiveservices.azure.com/ |
As seções a seguir incluem links de início rápido para os SDKs do Foundry Tools e informações de referência sobre os SDKs.
