O Microsoft Foundry Models fornece acesso a uma ampla variedade de modelos de vários provedores por meio de um único endpoint e conjunto de credenciais. Essa funcionalidade permite alternar entre modelos e usá-los em seu aplicativo sem fazer alterações de código.
Este artigo explica como os serviços Foundry organizam modelos e como usar o endpoint de inferência para acessá-los.
Pré-requisitos
Implantações
O Foundry usa implantações como aliases para acessar modelos. Uma implantação fornece a um modelo um nome e um conjunto de configurações. Você acessa um modelo usando seu nome de implantação em suas solicitações.
Uma implantação define:
- Um nome do modelo
- Uma versão do modelo
- Um tipo de provisionamento ou capacidade1
- Uma configuração de filtragem de conteúdo1
- Uma configuração de limitação de taxa1
1 Essas configurações podem ser alteradas dependendo do modelo selecionado.
Um recurso Foundry pode ter muitas implantações de modelo. Você paga apenas pela inferência executada em implantações de modelo. As implantações são recursos do Azure, portanto, estão sujeitas às políticas do Azure.
Para obter mais informações sobre como criar implantações, consulte Adicionar e configurar implantações de modelo.
Ponto de extremidade de inferência do OpenAI do Azure
A API Azure OpenAI expõe todos os recursos de modelos OpenAI e dá suporte a mais recursos como assistentes, threads, arquivos e inferência em lote. Você também pode usá-lo para acessar modelos não OpenAI.
Os endpoints do Azure OpenAI são formatados como https://<resource-name>.openai.azure.com. Pontos de extremidade correspondem a implantações, e cada implantação tem sua própria URL associada. No entanto, você pode usar o mesmo mecanismo de autenticação para acessar mais de uma implantação. Para obter mais informações, consulte a página de referência para Azure API OpenAI.
As URLs de implantação são formadas concatenando a URL base do Azure OpenAI e a rota/deployments/<model-deployment-name>. Ao usar a API OpenAI v1, chame a rota /openai/v1/ na URL base https://<resource-name>.openai.azure.com/openai/v1/ e passe o nome da implantação no campo model da solicitação. A rota /openai/v1/ usa controle de versão implícito, portanto, você não fornece um api-version.
Os exemplos a seguir usam a API de Respostas, que dá suporte aos recursos de inferência mais recentes.
Note
A API de Respostas funciona com modelos do Azure OpenAI e com Modelos do Foundry vendidos pelo Azure que oferecem suporte à API, como os modelos DeepSeek, Llama e Grok. Se uma implantação não der suporte à API de Respostas, a solicitação retornará 400 Model not supported. Nesse caso, use a API de Conclusões de Chat chamando client.chat.completions.create em vez disso.
Usar autenticação de chave de API
Você pode autenticar solicitações de inferência com uma chave de API do recurso foundry. As chaves de API são rápidas de configurar, mas concedem acesso total ao recurso, são difíceis de definir o escopo para usuários ou ações específicos e exigem rotação manual para se manterem seguras. Para cargas de trabalho de produção, use a autenticação sem chave com Microsoft Entra ID em vez disso.
No exemplo a seguir, deepseek-v3-0324 é o nome de uma implantação de modelo no recurso Microsoft Foundry. Substitua-o pelo seu próprio nome de implantação e armazene sua chave de API na variável de AZURE_INFERENCE_CREDENTIAL ambiente.
Instale o openai pacote usando pip:
pip install openai --upgrade
Crie um cliente que aponte para o endpoint do Azure OpenAI v1 e gere uma resposta. A rota /openai/v1/ usa controle de versão implícito, portanto, você não fornece um api-version. Insira o nome da implantação no campo model:
import os
from openai import OpenAI
client = OpenAI(
base_url="https://<resource>.openai.azure.com/openai/v1/",
api_key=os.environ["AZURE_INFERENCE_CREDENTIAL"],
)
response = client.responses.create(
model="deepseek-v3-0324", # Replace with your model deployment name.
input="Explain the Riemann hypothesis in one paragraph.",
)
print(response.output_text)
Instale o openai pacote usando o npm:
npm install openai
Crie um cliente que aponte para o endpoint do Azure OpenAI v1 e, em seguida, gere uma resposta:
import OpenAI from "openai";
const client = new OpenAI({
baseURL: "https://<resource>.openai.azure.com/openai/v1/",
apiKey: process.env.AZURE_INFERENCE_CREDENTIAL,
});
const response = await client.responses.create({
model: "deepseek-v3-0324", // Replace with your model deployment name.
input: "Explain the Riemann hypothesis in one paragraph.",
});
console.log(response.output_text);
Instale a biblioteca OpenAI:
dotnet add package OpenAI
Crie um cliente que aponte para o endpoint do Azure OpenAI v1 e, em seguida, gere uma resposta:
using System.ClientModel;
using OpenAI;
using OpenAI.Responses;
OpenAIClient client = new(
new ApiKeyCredential(Environment.GetEnvironmentVariable("AZURE_INFERENCE_CREDENTIAL")),
new OpenAIClientOptions
{
Endpoint = new Uri("https://<resource>.openai.azure.com/openai/v1/")
});
OpenAIResponseClient responseClient = client.GetResponsesClient("deepseek-v3-0324");
OpenAIResponse response = responseClient.CreateResponse(
"Explain the Riemann hypothesis in one paragraph.");
Console.WriteLine(response.GetOutputText());
Adicione o SDK de Java do OpenAI ao seu projeto. Verifique o repositório Java OpenAI para obter a versão mais recente.
Crie um cliente que aponte para o endpoint do Azure OpenAI v1 e, em seguida, gere uma resposta:
import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.models.responses.Response;
import com.openai.models.responses.ResponseCreateParams;
OpenAIClient client = OpenAIOkHttpClient.builder()
.baseUrl("https://<resource>.openai.azure.com/openai/v1/")
.apiKey(System.getenv("AZURE_INFERENCE_CREDENTIAL"))
.build();
Response response = client.responses().create(
ResponseCreateParams.builder()
.model("deepseek-v3-0324") // Replace with your model deployment name.
.input("Explain the Riemann hypothesis in one paragraph.")
.build());
// The Responses API has no single output-text accessor; concatenate the output items.
response.output().stream()
.flatMap(item -> item.message().stream())
.flatMap(message -> message.content().stream())
.flatMap(content -> content.outputText().stream())
.forEach(outputText -> System.out.println(outputText.text()));
Enviar solicitações diretamente para a rota v1. O caminho /openai/v1/ usa versionamento implícito, portanto você não inclui um parâmetro de consulta api-version. Passe sua chave no cabeçalho Authorization como um token de portador:
curl -X POST https://<resource>.openai.azure.com/openai/v1/responses \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $AZURE_INFERENCE_CREDENTIAL" \
-d '{
"model": "deepseek-v3-0324",
"input": "Explain the Riemann hypothesis in one paragraph."
}'
Para obter mais informações sobre como usar o endpoint do Azure OpenAI, consulte suporte a idiomas do SDK do Azure OpenAI.
Usar autenticação sem chave
Os modelos do Foundry implantados dão suporte à autorização sem uso de chave com o Microsoft Entra ID. A autorização sem chave aprimora a segurança, simplifica a experiência do usuário, reduz a complexidade operacional e fornece suporte robusto à conformidade. Use a autorização sem chave se sua organização usar soluções de gerenciamento de identidade seguras e escalonáveis.
Para usar a autenticação sem chave, configure seu recurso e conceda acesso aos usuários para executar a inferência. Depois de configurar o recurso e conceder acesso, autentique da seguinte maneira:
Instale o SDK do OpenAI usando um gerenciador de pacotes como pip:
pip install openai
Para Microsoft Entra ID autenticação, instale também:
pip install azure-identity
Use o pacote para consumir o modelo. O exemplo a seguir mostra como criar um cliente e fazer uma chamada de teste para a API de Respostas usando Microsoft Entra ID e sua implantação de modelo.
Substitua <resource> pelo nome do recurso Foundry. Localize-o no portal do Azure ou executando az cognitiveservices account list. Substitua deepseek-v3-0324 pelo nome da implantação real.
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,
)
response = client.responses.create(
model="deepseek-v3-0324", # Replace with your model deployment name.
input="What is Azure AI?",
)
print(response.output_text)
Saída esperada
Azure AI is a comprehensive suite of artificial intelligence services and tools from Microsoft that enables developers to build intelligent applications. It includes services for natural language processing, computer vision, speech recognition, and machine learning capabilities.
Referência: OpenAI Python SDK e classeDefaultAzureCredential.
Instale o SDK do OpenAI:
dotnet add package OpenAI
Para Microsoft Entra ID autenticação, instale também o pacote Azure.Identity:
dotnet add package Azure.Identity
Em seguida, use o pacote para consumir o modelo. O exemplo a seguir mostra como criar um cliente e fazer uma chamada de teste para a API de Respostas usando Microsoft Entra ID e sua implantação de modelo.
Substitua <resource> pelo nome do recurso Foundry (localize-o no portal Azure). Substitua deepseek-v3-0324 pelo nome da implantação real.
using Azure.Identity;
using OpenAI;
using OpenAI.Responses;
using System.ClientModel.Primitives;
#pragma warning disable OPENAI001
BearerTokenPolicy tokenPolicy = new(
new DefaultAzureCredential(),
"https://ai.azure.com/.default"
);
OpenAIResponseClient client = new(
model: "deepseek-v3-0324", // Replace with your model deployment name.
authenticationPolicy: tokenPolicy,
options: new OpenAIClientOptions()
{
Endpoint = new Uri("https://<resource>.openai.azure.com/openai/v1/")
}
);
OpenAIResponse response = client.CreateResponse("What is Azure AI?");
Console.WriteLine(response.GetOutputText());
Saída esperada:
Azure AI is a comprehensive suite of artificial intelligence services and tools from Microsoft that enables developers to build intelligent applications. It includes services for natural language processing, computer vision, speech recognition, and machine learning capabilities.
Referência: OpenAI .NET SDK e classe DefaultAzureCredential.
Instale o SDK do OpenAI com npm:
npm install openai
Para Microsoft Entra ID autenticação, instale também:
npm install @azure/identity
Em seguida, use o pacote para consumir o modelo. O exemplo a seguir mostra como criar um cliente e fazer uma chamada de teste para a API de Respostas usando Microsoft Entra ID e sua implantação de modelo.
Substitua <resource> pelo nome do recurso Foundry (localize-o no portal do Azure ou executando az cognitiveservices account list). Substitua deepseek-v3-0324 pelo nome da implantação real.
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 response = await client.responses.create({
model: "deepseek-v3-0324", // Replace with your model deployment name.
input: "What is Azure AI?"
});
console.log(response.output_text);
Saída esperada:
Azure AI is a comprehensive suite of artificial intelligence services and tools from Microsoft that enables developers to build intelligent applications. It includes services for natural language processing, computer vision, speech recognition, and machine learning capabilities.
Referência: OpenAI Node.js classe SDK e DefaultAzureCredential.
Adicione o SDK do OpenAI ao seu projeto. Verifique o OpenAI Java GitHub repositório para obter as instruções de versão e instalação mais recentes.
Para a autenticação do Microsoft Entra ID, além disso, adicione:
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-identity</artifactId>
<version>1.18.0</version>
</dependency>
Em seguida, use o pacote para consumir o modelo. O exemplo a seguir mostra como criar um cliente e fazer uma chamada de teste para a API de Respostas usando Microsoft Entra ID e sua implantação de modelo.
Substitua <resource> pelo nome do recurso Foundry (localize-o no portal Azure). Substitua deepseek-v3-0324 pelo nome da implantação real.
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 com.openai.models.responses.Response;
import com.openai.models.responses.ResponseCreateParams;
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();
ResponseCreateParams params = ResponseCreateParams.builder()
.model("deepseek-v3-0324") // Replace with your model deployment name.
.input("What is Azure AI?")
.build();
Response response = client.responses().create(params);
// The Responses API has no single output-text accessor; concatenate the output items.
response.output().stream()
.flatMap(item -> item.message().stream())
.flatMap(message -> message.content().stream())
.flatMap(content -> content.outputText().stream())
.forEach(outputText -> System.out.println(outputText.text()));
Saída esperada:
Azure AI is a comprehensive suite of artificial intelligence services and tools from Microsoft that enables developers to build intelligent applications. It includes services for natural language processing, computer vision, speech recognition, and machine learning capabilities.
Referência: OpenAI Java SDK e classeDefaultAzureCredential.
Explore o design da API na seção de referência para ver quais parâmetros estão disponíveis. Insira o token de autenticação (bearer) no cabeçalho Authorization.
Por exemplo, a seção de referência da API de Respostas detalha como usar a /responses rota para gerar previsões. O caminho /openai/v1/ está incluído na raiz da URL:
Solicitação
Substitua <resource> pelo nome do recurso Foundry (localize-o no portal do Azure ou executando az cognitiveservices account list). Substitua deepseek-v3-0324 pelo nome da implantação real.
A URL base aceita ambos os formatos https://<resource>.services.ai.azure.com/openai/v1/ e https://<resource>.openai.azure.com/openai/v1/.
curl -X POST https://<resource>.openai.azure.com/openai/v1/responses \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $AZURE_OPENAI_AUTH_TOKEN" \
-d '{
"model": "deepseek-v3-0324",
"input": "Explain what the bitter lesson is?"
}'
Resposta
Se a autenticação for bem-sucedida, você receberá uma 200 OK resposta com os resultados da resposta no corpo da resposta:
{
"id": "resp_...",
"object": "response",
"created_at": 1738368234,
"model": "deepseek-v3-0324",
"status": "completed",
"output": [
{
"type": "message",
"role": "assistant",
"content": [
{
"type": "output_text",
"text": "The bitter lesson refers to a key insight in AI research that emphasizes the importance of general-purpose learning methods that leverage computation, rather than human-designed domain-specific approaches. It suggests that methods which scale with increased computation tend to be more effective in the long run."
}
]
}
],
"usage": {
"input_tokens": 28,
"output_tokens": 52,
"total_tokens": 80
}
}
Os tokens devem ser emitidos com escopo https://ai.azure.com/.default.
Para fins de teste, a maneira mais fácil de obter um token válido para sua conta de usuário é usar o CLI do Azure. Em um console, entre e solicite um token executando os seguintes comandos de CLI do Azure:
az login
az account get-access-token --resource https://ai.azure.com --query "accessToken" --output tsv
Esse comando gera um token de acesso que você pode armazenar na variável de $AZURE_OPENAI_AUTH_TOKEN ambiente.
Referência: API de respostas
Conteúdo relacionado
