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.
Um recurso do Foundry fornece acesso unificado a modelos, agentes e ferramentas. Este artigo explica qual SDK e endpoint usar para seu cenário.
| SDK | Para que serve | Ponto de Extremidade |
|---|---|---|
| Foundry SDK | Funcionalidades específicas da fábrica com interfaces compatíveis com OpenAI. Inclui acesso a modelos diretos do Foundry através da API de Respostas (não Conclusões de Chat). | https://<resource-name>.services.ai.azure.com/api/projects/<project-name> |
| OpenAI SDK | Modelos e recursos mais recentes do SDK do OpenAI com a superfície completa da API OpenAI, incluindo inserções. Modelos diretos Foundry disponíveis por meio da API de Conclusão de Chats (não Responses). | https://<resource-name>.openai.azure.com/openai/v1 |
| SDKs de Ferramentas de Fundição | 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 multiagente em código. Independente de nuvem. | Usa o endpoint do projeto por meio do SDK do Foundry. |
Escolha seu SDK:
- Usar o SDK do Foundry ao criar aplicativos com agentes, avaliações ou recursos específicos do Foundry
- Use o SDK do OpenAI quando a compatibilidade máxima do OpenAI for necessária, ao gerar inserções ou usar modelos diretos do Foundry por meio de Preenchimentos de Chat
- Use Foundry Tools SDKs ao usar serviços de IA específicos (Visão, Fala, Linguagem etc.)
- Usar o Agent Framework ao criar sistemas de vários agentes no código (orquestração local)
Nota
Tipos de recurso: Um recurso Foundry fornece todos os pontos de extremidade listados anteriormente. Um recurso do Azure OpenAI fornece apenas o endpoint /openai/v1.
Authentication: Exemplos aqui usam Microsoft Entra ID (DefaultAzureCredential). As chaves de API funcionam em /openai/v1. Passe a chave como api_key em vez de um provedor de token.
Pré-requisitos
-
Uma conta Azure com uma assinatura ativa. Se você não tiver uma, crie uma conta de Azure free, que inclui uma assinatura de avaliação gratuita.
Tenha uma das seguintes Azure funções RBAC para criar e gerenciar recursos do Foundry:
- Usuário de IA do Azure (função de privilégio mínimo para desenvolvimento)
- Azure AI Project Manager (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 Role para 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.
Importante
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.
Verificar pré-requisitos
Antes de prosseguir, confirme:
- Azure assinatura está ativa:
az account show - Você tem a função RBAC necessária: verifique Azure Portal → Recurso Foundry → [Controle de Acesso (IAM)]
- Ambiente de execução de idioma instalado.
- Python:
python --version(≥3.8)
- Python:
- Runtime de idioma instalado:
- Node.js:
node --version(≥18)
- Node.js:
- Runtime de idioma instalado:
- .NET:
dotnet --version(≥6.0)
- .NET:
- Runtime de idioma instalado:
- Java:
java --version(≥11)
- Java:
Foundry SDK
O SDK do Foundry 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>
Nota
Se sua organização usar um subdomínio personalizado, substitua <resource-name><your-custom-subdomain> na URL do ponto de extremidade.
Essa abordagem simplifica a configuração do aplicativo. Em vez de gerenciar vários pontos de extremidade, você configura um.
Instalar o SDK
| Versão do SDK | Versão do Portal | Status | Pacote Python |
|---|---|---|---|
| 2.x | Fundição (nova) | Estável | azure-ai-projects>=2.0.0 |
| 1.x | Forja (clássico) | Estável | azure-ai-projects==1.0.0 |
A biblioteca de clientes 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 para projetos do Foundry.
pip install "azure-ai-projects>=2.0.0"
| Versão do SDK | Versão do Portal | Status | Pacote Java |
|---|---|---|---|
| 2.0.0 | Foundry (novo) | Estável | azure-ai-projectsazure-ai-agents |
| Versão do SDK | Versão do Portal | Status | Pacote JavaScript |
|---|---|---|---|
| 2.0.1 | Fundição (novo) | Estável | @azure/ai-projects |
| 1.0.1 | Clássico da fundição | Estável | @azure/ai-projects |
| Versão do SDK | Versão do Portal | Status | Pacote .NET |
|---|---|---|---|
| 2.0.0 (GA) | Foundry (novo) | Estável | Azure.AI.ProjectsAzure.AI.Projects.AgentsAzure.AI.Extensions.OpenAI |
| 1.1.0 (GA) | Clássico da fundição | Estável | Azure.AI.Projects |
Importante
Não instale Azure.AI.Projects.OpenAI (versão prévia) junto com Azure.AI.Extensions.OpenAI (GA). Ambos os pacotes definem os mesmos tipos em namespaces diferentes, o que causa erros de referência ambíguos. Use apenas Azure.AI.Extensions.OpenAI para cenários de agente.
A biblioteca de clientes Azure AI Projects para Java é uma biblioteca unificada que permite que você use várias bibliotecas de cliente juntas conectando-se a um único ponto de extremidade de projeto.
Adicione esses pacotes à sua instalação para projetos do 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;
A biblioteca de clientes Azure AI Projects para JavaScript é 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 JavaScript para projetos do Foundry.
npm install @azure/ai-projects @azure/identity dotenv
A biblioteca de clientes Azure AI Projects para .NET é 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 esses comandos para adicionar os pacotes necessários ao seu projeto de .NET.
dotnet add package Azure.AI.Projects
dotnet add package Azure.AI.Projects.Agents
dotnet add package Azure.AI.Extensions.OpenAI
dotnet add package Azure.Identity
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:
- Project client – 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 Foundry que se baseia em conceitos 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 direciona 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_client = 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:
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}")
Saída esperada:
Response output: France has an area of approximately 213,011 square miles (551,695 square kilometers).
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();
```**Create and use an OpenAI-compatible client from your project:**
```java
OpenAIClient openAIClient = projectClient.getOpenAIClient();
Criar um cliente de projeto:
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());
Crie um cliente compatível com OpenAI do seu projeto:
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}`);
Criar um cliente de projeto:
using Azure.AI.Projects;
using Azure.AI.Extensions.OpenAI;
using Azure.Identity;
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:
var responseClient = projectClient.ProjectOpenAIClient.GetProjectResponsesClientForModel("gpt-5.2");
var response = responseClient.CreateResponse("What is the speed of light?");
Console.WriteLine(response.GetOutputText());
O que você pode fazer com o SDK do Foundry
- Access Foundry Models, incluindo Azure OpenAI
- Usar o Serviço do Foundry Agent
- Executar avaliações em lote
- Habilitar o rastreamento de aplicativo
- Ajustar um modelo
- Obtenha endpoints e chaves para Ferramentas Foundry, orquestração local e muito mais
Solucionando problemas
Erros de autenticação
Se você vir DefaultAzureCredential failed to retrieve a token:
Verify CLI do Azure é autenticado:
az account show az login # if not logged inVerifique a atribuição de função RBAC:
- Confirme se você tem pelo menos a função de usuário de IA Azure no projeto Foundry
- Consulte Atribuir funções do Azure
Para identidade gerenciada em produção:
- Verifique se a identidade gerenciada tem a função apropriada atribuída
- Consulte Configurar identidades gerenciadas
Erros de configuração de ponto de extremidade
Se você vir Connection refused ou 404 Not Found:
- Verificar se os nomes de recursos e projetos correspondem à sua implantação real
-
Verificar o formato da URL do ponto de extremidade: Deve ser
https://<resource-name>.services.ai.azure.com/api/projects/<project-name> -
Para subdomínios personalizados: substitua
<resource-name>pelo subdomínio personalizado
Incompatibilidades de versão do SDK
Se os exemplos de código falharem com AttributeError ou ModuleNotFoundError:
Verifique a versão do SDK:
pip show azure-ai-projects # Python npm list @azure/ai-projects # JavaScript dotnet list package # .NETReinstalar com sinalizadores de versão corretos: consulte os comandos de instalação em cada seção de idioma acima
OpenAI SDK
Use o SDK do OpenAI quando quiser toda a gama de funcionalidades da API OpenAI e a máxima compatibilidade com o cliente. Este endpoint fornece acesso a modelos do Azure OpenAI e modelos diretos do Foundry (por meio da API de Respostas), incluindo embeddings, completude de chat e geração de imagens. Ele não fornece acesso a recursos específicos do Foundry, como agentes e avaliações.
Dica
Utilize o endpoint do SDK do OpenAI para gerar embeddings. O endpoint do projeto usado pelo SDK Foundry não roteia atualmente solicitações de incorporação.
O trecho de código a seguir mostra como usar o endpoint 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://ai.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))
Saída esperada:
{
"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)."
}
Para obter mais informações, consulte Linguagens de programação com suporte do Azure OpenAI
O trecho de código a seguir mostra como usar o endpoint Azure OpenAI /openai/v1 diretamente.
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://ai.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());
Para obter mais informações sobre como usar o SDK do OpenAI, consulte Azure linguagens de programação com suporte do OpenAI
const endpoint = "https://<resource-name>.openai.azure.com/openai/v1";
const scope = "https://ai.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}`);
Para obter mais informações sobre como usar o SDK do OpenAI, consulte Azure linguagens de programação com suporte do OpenAI
- Instale o pacote OpenAI: execute este comando para adicionar a biblioteca de clientes OpenAI ao seu projeto de .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 `ResponsesClient` for the Azure OpenAI v1 endpoint. ```csharp using Azure.Identity; using OpenAI; using OpenAI.Responses; 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://ai.azure.com/.default"); OpenAIClient openAIClient = new( authenticationPolicy: tokenPolicy, options: new OpenAIClientOptions() { Endpoint = new($"{directModelEndpoint}"), }); ResponsesClient client = openAIClient.GetResponsesClient(); CreateResponseOptions options = new() { Model = deploymentName, InputItems = { ResponseItem.CreateUserMessageItem("What is the size of France in square miles?") }, Temperature = (float)0.7, }; var modelDirectResponse = client.CreateResponse(options); Console.WriteLine($"[ASSISTANT]: {modelDirectResponse.Value.GetOutputText()}"); #pragma warning restore OPENAI001
Para obter mais informações sobre como usar o SDK do OpenAI, consulte Azure linguagens de programação com suporte do OpenAI
Gerar inserções com o SDK do OpenAI
Use o mesmo /openai/v1 endpoint para gerar incorporações com um modelo de incorporação implantado.
embedding = client.embeddings.create(
model="text-embedding-3-large",
input="How do I get started with Microsoft Foundry?",
)
print(f"Embedding dimension: {len(embedding.data[0].embedding)}")
const embedding = await client.embeddings.create({
model: "text-embedding-3-large",
input: "How do I get started with Microsoft Foundry?",
});
console.log(`Embedding dimension: ${embedding.data[0].embedding.length}`);
var embeddingClient = openAIClient.GetEmbeddingClient("text-embedding-3-large");
var result = embeddingClient.GenerateEmbedding(
"How do I get started with Microsoft Foundry?");
Console.WriteLine($"Embedding dimension: {result.Value.ToFloats().Length}");
// Use the same OpenAI client created above
// Embeddings are available through the OpenAI SDK embeddings API
Para obter instruções de inserções completas, consulte Gerar inserções.
Usando a Estrutura do Agente para orquestração local
Microsoft Agent Framework é um SDK de software livre para a criação de 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 de Ferramentas de Fundição
As Ferramentas Foundry (anteriormente conhecidas como Azure AI Services) são soluções pontuais pré-construídas com SDKs dedicados. Utilize os seguintes endpoints para trabalhar com o Foundry Tools.
Qual ponto de extremidade você deve usar?
Escolha um ponto de extremidade com base em suas necessidades:
Use o endpoint dos serviços de IA do Azure para acessar Visão Computacional, Segurança de Conteúdo, Inteligência de Documentos, Linguagem, Tradução e Ferramentas de Token Foundry.
Ponto de extremidade das Ferramentas de Fundição: https://<your-resource-name>.cognitiveservices.azure.com/
Nota
Os pontos de extremidade usam seu nome de 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.
Se suas cargas de trabalho usarem recursos do Linguagem de IA do Azure que estão sendo aposentados — como análise de sentimento, extração de frases-chave, sumarização, vinculação de entidades, CLU ou CQA — planeje migrar para as alternativas da Microsoft Foundry. Para um novo desenvolvimento, considere usar o SDK do Foundry ou o endpoint compatível com OpenAI, conforme foi descrito anteriormente neste artigo. Veja Migrar do Language Studio para o Microsoft Foundry.
Para Ferramentas de Pesquisa de Fala e Tradução, use os pontos de extremidade nas tabelas a seguir. Substitua marcadores de posição pelas informações dos seus recursos.
Pontos de acesso de voz
| Ferramenta de Fundição | Ponto de Extremidade |
|---|---|
| Conversão de Fala em Texto (Padrão) | https://<YOUR-RESOURCE-REGION>.stt.speech.microsoft.com |
| Texto para 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 de Extremidade |
|---|---|
| Tradução de texto | https://api.cognitive.microsofttranslator.com/ |
| Tradução de Documento | https://<YOUR-RESOURCE-NAME>.cognitiveservices.azure.com/ |
Pontos de extremidade de linguagem
| Ferramenta de Fundição | Ponto de Extremidade |
|---|---|
| Análise de texto | https://<YOUR-RESOURCE-NAME>.cognitiveservices.azure.com |
Importante
Em 20 de março de 2027, o Azure Language Studio será desativado e migrado para Microsoft Foundry; todos os recursos e aprimoramentos futuros estarão disponíveis no Microsoft Foundry.
Em 31 de março de 2029, os seguintes recursos do Azure Language serão desativados (fim do suporte). Antes dessa data, os usuários devem migrar cargas de trabalho existentes e integrar novos projetos para modelos Microsoft Foundry para melhor compreensão da linguagem natural e integração simplificada de aplicativos:
- Extração de Frases-chave
- Análise de Sentimento e Mineração de Opiniões
- Classificação de texto personalizado
- Compreensão de Linguagem de Conversação (CLU)
- Resposta a perguntas personalizadas (CQA)
- Fluxo de trabalho de orquestração
- Resumo (extrativo e abstrativo, para documentos e conversas)
- Relacionamento de Entidades
Principais recursos com suporte contínuo: Detecção de Idioma, Detecção de Informações Pessoais Identificáveis (PII), Análise de Texto para Saúde, NER Pré-construído e NER Personalizado.
Para obter opções de migração, consulte Migrate do Language Studio para Microsoft Foundry.
