Escolha um endpoint e um SDK

Concluído

A Microsoft Foundry oferece flexibilidade para desenvolver aplicações de chat de IA generativa. Antes de começar o desenvolvimento, é importante compreender as opções disponíveis e como decidir qual delas usar. Algumas considerações para desenvolver uma aplicação incluem:

• Endpoints: Os projetos Microsoft Foundry fornecem dois endpoints que pode usar para se ligar e consumir ativos do projeto, como implementações de modelos, a partir de aplicações clientes. Cada projeto tem tanto um endpoint de Project como um endpoint Azure OpenAI.
• SDK do cliente: Dependendo do endpoint que selecionar, pode optar por usar o Microsoft Foundry SDK ou o OpenAI SDK para desenvolver uma aplicação de chat de IA generativa. Ambos os SDKs suportam um objeto cliente compatível com a API OpenAI que pode submeter prompts aos modelos, mas existem algumas diferenças na funcionalidade específica disponível em cada SDK.
• Autenticação: Dependendo do endpoint e do SDK que escolher usar, existem várias formas de uma aplicação cliente ser autenticada pela Foundry para obter acesso a assets. Em geral, as aplicações de produção devem usar a autenticação Microsoft Entra ID , que exige que a aplicação esteja a correr no contexto de uma identidade específica; Mas em alguns cenários também pode usar autenticação baseada em chaves ou tokens .
• API de Chat: A API cliente OpenAI suporta duas APIs de chat: ChatCompletions e Responses. Embora a API Responses seja recomendada para a maioria dos novos projetos de desenvolvimento, a API ChatCompletions está bem estabelecida e compatível com muitos modelos e plataformas de IA generativa.

Comecemos por considerar os endpoints disponíveis, SDKs de clientes e métodos de autenticação – exploraremos mais à frente as APIs Responses e ChatCompletions.

Usando o SDK do Foundry com o endpoint do projeto

O Microsoft Foundry SDK fornece acesso programático aos recursos dos seus projetos através de uma API REST e bibliotecas clientes específicas de cada linguagem; incluindo:

• Azure Projetos de IA para Python
• Azure Projetos de IA para Microsoft .NET
• Azure Projetos de IA para JavaScript

Observação

Este módulo utiliza exemplos de código Python para tarefas comuns. Pode consultar a documentação do SDK específica para o idioma para obter código equivalente no seu idioma preferido. Cada SDK é desenvolvido e mantido de forma independente, pelo que algumas funcionalidades podem estar em diferentes fases de implementação.

Instalando o SDK

Para usar a biblioteca Azure AI Projects em Python, instale o pacote azure-ai-projects do PyPI juntamente com pacotes de suporte:

pip install azure-ai-projects azure-identity openai

Observação

Ao usar o Foundry SDK para desenvolver uma aplicação de chat, também é necessário importar o pacote OpenAI SDK – a funcionalidade do cliente de chat no Foundry SDK é derivada do OpenAI SDK.

Ligação ao endpoint do projeto

Cada projeto do Foundry tem um endpoint único que pode encontrar na página Overview do projeto no portal Foundry em https://ai.azure.com.

O endpoint do project segue este formato:

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

Use este endpoint para criar um objeto 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
)

Observação

O código usa credenciais padrão do Azure para autenticar. Para ativar esta autenticação, é necessário instalar o pacote azure-identity (mostrado anteriormente no comando de instalação).

Sugestão

Para acessar o project com sucesso, o código deve ser executado numa sessão Azure autenticada. Por exemplo, pode usar o comando Azure CLI az login para iniciar sessão antes de executar o código.

O cliente do projeto (AIProjectClient) fornece acesso a operações nativas da Foundry que não têm equivalentes OpenAI. Usar o cliente do projeto para:

• Recuperar ligações de recursos
• Configuração do projeto de acesso
• Ativar rastreamento
• Gerir conjuntos de dados e índices

Criação de um cliente de chat

Para conversar com um modelo no seu projeto Foundry, precisa de um objeto cliente compatível com OpenAI. Pode usar o método get_openai_client() do cliente do projeto para obter um, assim:

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

Pode então usar este objeto cliente de chat para submeter prompts aos modelos e devolver respostas.

A utilização do SDK OpenAI com o endpoint Azure OpenAI

O SDK OpenAI é a biblioteca cliente oficial para chamar a API OpenAI. Trata de pedidos HTTP, autenticação, tentativas e análise de respostas. O SDK funciona com modelos alojados em OpenAI, implementações Azure OpenAI e modelos Foundry usando os mesmos padrões.

Instalando o SDK

Para usar a biblioteca OpenAI em Python, instale o pacote openAI do PyPI juntamente com os pacotes de suporte:

pip install openai azure-identity

Observação

O pacote Azure-identity é necessário se pretender usar autenticação baseada em token para se ligar ao endpoint usando credenciais Microsoft Entra ID.

Ligação ao endpoint Azure OpenAI

Cada projeto Foundry inclui um endpoint Azure OpenAI que pode encontrar na página de Visão Geral do projeto no portal Foundry em https://ai.azure.com.

O endpoint Azure OpenAI segue este formato:

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

Crie um cliente OpenAI com o seu endpoint e credenciais 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,
)

Além do Microsoft Entra ID (recomendado), pode autenticar usando uma chave API ou variáveis de ambiente.

Autenticação da chave 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/"
)

Importante

Use chaves de API com cuidado. Guarde-os de forma segura no Azure Key Vault e nunca os inclua diretamente no seu código.

Variáveis de ambiente:

Se definir as variáveis de ambiente OPENAI_BASE_URL e OPENAI_API_KEY, o cliente usa-as automaticamente.

from openai import OpenAI

openai_client = OpenAI()  # Uses environment variables

Independentemente da forma como escolhas autenticar, o cliente OpenAI trata das operações de inferência de modelos. Utilize-o para:

• Gerar respostas com a API Respostas
• Conclusão de chat e geração de imagens
• Aceder aos modelos diretos Foundry (modelos não-Azure OpenAI)

Utilização de um objeto cliente AzureOpenAI

Deves geralmente usar o objeto cliente OpenAI para conversar com modelos através do endpoint Azure OpenAI v1. No entanto, também tem a opção de criar um objeto cliente AzureOpenAI se precisar de usar funcionalidades de uma versão específica da API Azure OpenAI. Para criar um objeto cliente AzureOpenAI , deve especificar a versão da API e o endpoint Azure, desta forma:

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

Escolher entre o SDK Foundry e o SDK OpenAI

O Microsoft Foundry suporta duas abordagens para construir aplicações de IA. Cada um serve propósitos diferentes, e saber quando usar cada um ajuda-o a construir a solução certa.

Quando usar o SDK Foundry

Use o SDK do Foundry quando a sua aplicação precisar de capacidades específicas da Foundry:

• Serviço de Agentes da Fundição para construção e gestão de agentes de IA
• Fluxos de trabalho de invocação e aprovação de ferramentas
• Avaliações na cloud para testar e validar respostas de IA
• Rastreamento e observabilidade para monitorizar o comportamento da aplicação
• Modelos diretos da Foundry (modelos OpenAI não-Azure disponíveis através do catálogo de modelos)
• Metadados do projeto, ligações e funcionalidades de governação

A Microsoft recomenda o SDK do Foundry ao criar aplicações com agentes, avaliações ou funcionalidades específicas do Foundry.

Quando usar o SDK OpenAI

Use o SDK OpenAI quando precisar de máxima compatibilidade com a API OpenAI:

• Compatibilidade total com a API OpenAI para código e ferramentas existentes
• Portabilidade entre as implementações OpenAI e Azure OpenAI
• Conclusão, Respostas e Imagens do Chat APIs
• Dependência mínima de conceitos específicos da Foundry

O SDK OpenAI é ideal para cargas de inferência de modelos onde se quer que o código OpenAI existente funcione com alterações mínimas. No entanto, esta abordagem não fornece funcionalidades específicas da Foundry, como agentes ou avaliações.

O Microsoft Foundry dá-lhe flexibilidade na forma como constrói aplicações de IA. Usa o SDK do Foundry com AIProjectClient quando precisar de funcionalidades de nível de projeto, como agentes, avaliações, rastreamento e ligações. Use o SDK OpenAI quando precisar de inferência direta de modelos com máxima compatibilidade OpenAI. Ambos os SDKs funcionam com o endpoint do seu projeto Foundry, por isso pode combiná-los conforme necessário nas suas aplicações. Também pode usar ambos os SDKs em conjunto na mesma aplicação — o SDK Foundry para funcionalidades do projeto e o SDK OpenAI para inferência de modelos.