Introdução ao bloco de construção de segurança Azure OpenAI

• Um aplicativo Python Quart que usa o pacote openai e a API Responses para gerar respostas às mensagens do usuário.
• Um front-end HTML / JavaScript básico que transmite respostas do back-end usando JSON Lines em um ReadableStream.

• Um aplicativo Web Blazor que usa o Azure. IA. OpenAI pacote NuGet para gerar respostas a mensagens do usuário.

• Um aplicativo Web TypeScript que usa o pacote npm OpenAI para gerar respostas a mensagens de usuário.

Saiba mais sobre custo no repositório de exemplo.

Saiba mais sobre custo no repositório de exemplo.

Saiba mais sobre custo no repositório de exemplo.

Explorando o código de exemplo

Embora o OpenAI e o Serviço OpenAI do Azure dependam de uma biblioteca cliente Python comum, pequenas alterações de código são necessárias ao usar os pontos de extremidade do Azure OpenAI. Vamos ver como este exemplo configura a autenticação sem chave com Microsoft Entra ID e se comunica com Azure OpenAI.

Configurar a autenticação com identidade gerenciada

Neste exemplo, o arquivo src/quartapp/chat.py inicia com configurar a autenticação sem chave.

O snippet a seguir usa o módulo azure.identity.aio para criar um fluxo de autenticação assíncrono Microsoft Entra.

O snippet de código a seguir usa a AZURE_CLIENT_IDazd variável de ambiente para criar uma instância ManagedIdentityCredential capaz de autenticar por meio da identidade gerenciada atribuída pelo usuário.

user_assigned_managed_identity_credential = ManagedIdentityCredential(client_id=os.getenv("AZURE_CLIENT_ID")) 

O trecho de código a seguir usa as variáveis de ambiente de recurso AZURE_TENANT_IDazd para criar uma instância AzureDeveloperCliCredential capaz de autenticar com o locatário Microsoft Entra vigente.

azure_dev_cli_credential = AzureDeveloperCliCredential(tenant_id=os.getenv("AZURE_TENANT_ID"), process_timeout=60)  

A biblioteca de clientes do Azure Identity fornece credentials – classes públicas que implementam o protocolo TokenCredential da biblioteca do Azure Core. Uma credencial representa um fluxo de autenticação distinto para adquirir um token de acesso de Microsoft Entra ID. Essas credenciais podem ser encadeadas para formar uma sequência ordenada de mecanismos de autenticação a serem tentados.

O snippet a seguir cria um ChainedTokenCredential usando um ManagedIdentityCredential e um AzureDeveloperCliCredential.

• O ManagedIdentityCredential é usado para Azure Functions, Serviço de Aplicativo do Azure e Aplicativos de Contêiner do Azure. Há suporte para uma identidade gerenciada atribuída pelo usuário, passando o client_id para ManagedIdentityCredential.
• O AzureDeveloperCliCredential é usado para o desenvolvimento local. Ele foi definido anteriormente com base no locatário Microsoft Entra a ser usado.

azure_credential = ChainedTokenCredential(
    user_assigned_managed_identity_credential,
    azure_dev_cli_credential
)

O trecho de código a seguir obtém o provedor de token OpenAI do Azure com base na credencial Azure selecionada. Esse valor é obtido chamando o azure.identity.aio.get_bearer_token_provider com dois argumentos:

• azure_credential: A ChainedTokenCredential instância criada anteriormente para autenticar a solicitação.

• https://cognitiveservices.azure.com/.default: É necessário um ou mais escopos de token portador. No caso, o Azure Cognitive Services como ponto de extremidade.

token_provider = get_bearer_token_provider(
    azure_credential, "https://cognitiveservices.azure.com/.default"
)

As linhas a seguir verificam as variáveis de ambiente necessárias AZURE_OPENAI_ENDPOINT e AZURE_OPENAI_CHAT_DEPLOYMENT, além de duas azd que são definidas durante o processo de provisionamento. Um erro será gerado se um valor não estiver presente.

openai_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
if not openai_endpoint:
    raise ValueError("AZURE_OPENAI_ENDPOINT is required for Azure OpenAI")
if not os.getenv("AZURE_OPENAI_CHAT_DEPLOYMENT"):
    raise ValueError("AZURE_OPENAI_CHAT_DEPLOYMENT is required for Azure OpenAI")

Esse trecho inicializa o cliente OpenAI para o endpoint /openai/v1/ do Azure, passando o provedor de token como api_key. Não é necessário o uso de api_version com o endpoint v1:

bp.openai_client = AsyncOpenAI(
    base_url=f"{openai_endpoint.rstrip('/')}/openai/v1/",
    api_key=token_provider,
)

A linha a seguir define o nome de implantação do modelo Azure OpenAI para uso em chamadas à API:

bp.openai_model = os.getenv("AZURE_OPENAI_CHAT_DEPLOYMENT")

Depois que essa função for concluída, o cliente estará configurado corretamente e pronto para interagir com Azure serviços OpenAI.

Transmitir respostas usando a API de Respostas OpenAI

O response_stream trata a chamada de fluxo da API de Respostas na rota. O front-end envia itens na forma de Respostas input diretamente, e o back-end os encaminha para responses.stream():

async def response_stream():
    try:
        async with bp.openai_client.responses.stream(
            model=bp.openai_model,
            input=request_input,
            store=False,
        ) as openai_stream:
            async for event in openai_stream:
                yield json.dumps(event.model_dump(), ensure_ascii=False) + "\n"
    except Exception as e:
        current_app.logger.exception("Responses stream failed")
        yield json.dumps({"error": str(e)}, ensure_ascii=False) + "\n"

Explorar o código de exemplo

Aplicativos .NET dependem da biblioteca de clientes Azure.AI.OpenAI para se comunicar com os serviços OpenAI da Azure, que depende da biblioteca OpenAI. O aplicativo de exemplo configura a autenticação sem chave usando Microsoft Entra ID para se comunicar com Azure OpenAI.

Configurar autenticação e registro de serviço

Neste exemplo, a autenticação sem chave é configurada no program.cs arquivo. O snippet de código a seguir usa a AZURE_CLIENT_ID variável de ambiente definida por azd para criar uma instância ManagedIdentityCredential capaz de autenticar por meio da identidade gerenciada atribuída pelo usuário.

var userAssignedIdentityCredential = 
    new ManagedIdentityCredential(builder.Configuration.GetValue<string>("AZURE_CLIENT_ID"));

O snippet de código a seguir usa a AZURE_TENANT_ID variável de ambiente definida por azd para criar uma instância AzureDeveloperCliCredential capaz de autenticar localmente usando a conta conectada ao azd.

var azureDevCliCredential = new AzureDeveloperCliCredential(
    new AzureDeveloperCliCredentialOptions()
    { 
        TenantId = builder.Configuration.GetValue<string>("AZURE_TENANT_ID") 
    });

A biblioteca de clientes do Azure Identity fornece classes de credencial que implementam o protocolo TokenCredential da biblioteca do Azure Core. Uma credencial representa um fluxo de autenticação distinto para adquirir um token de acesso de Microsoft Entra ID. Essas credenciais podem ser encadeadas usando ChainedTokenCredential para formar uma sequência ordenada de mecanismos de autenticação a serem tentados.

O snippet a seguir registra o AzureOpenAIClient para injeção de dependência e cria um ChainedTokenCredential usando um ManagedIdentityCredential e um AzureDeveloperCliCredential.

• O ManagedIdentityCredential é usado para Azure Functions, Serviço de Aplicativo do Azure e Aplicativos de Contêiner do Azure. Há suporte para uma identidade gerenciada atribuída pelo usuário usando o AZURE_CLIENT_ID que foi fornecido ao ManagedIdentityCredential.
• O AzureDeveloperCliCredential é usado para o desenvolvimento local. Ele foi definido anteriormente com base no tenant Microsoft Entra a ser usado.

builder.Services.AddAzureClients(
    clientBuilder => {
        clientBuilder.AddClient<AzureOpenAIClient, AzureOpenAIClientOptions>((options, _, _)
            => new AzureOpenAIClient(
                new Uri(endpoint),
                new ChainedTokenCredential(
                    userAssignedIdentityCredential, azureDevCliCredential), options));
    });

Obter conclusões de chat usando o cliente Azure OpenAI

O aplicativo Web Blazor injeta o registrado AzureOpenAIClient no topo do componente Home.Razor.

@inject AzureOpenAIClient azureOpenAIClient

Quando o usuário envia o formulário, ele AzureOpenAIClient envia seu prompt ao modelo OpenAI para gerar uma conclusão:

ChatClient chatClient = azureOpenAIClient.GetChatClient("gpt-4o-mini");

messages.Add(new UserChatMessage(model.UserMessage));

ChatCompletion completion = await chatClient.CompleteChatAsync(messages);
    messages.Add(new SystemChatMessage(completion.Content[0].Text));

Explorar o código de exemplo

Embora OpenAI e o Serviço OpenAI do Azure dependam de uma openai (biblioteca de cliente JavaScript comum), pequenas alterações de código são necessárias ao usar endpoints do Azure OpenAI. Vamos ver como este exemplo configura a autenticação sem chave com Microsoft Entra ID e se comunica com Azure OpenAI.

Autenticação sem chave para cada ambiente

A biblioteca de clientes do Azure Identity fornece classes de credencial que implementam o protocolo TokenCredential da biblioteca do Azure Core. Uma credencial representa um fluxo de autenticação distinto para adquirir um token de acesso de Microsoft Entra ID. Essas credenciais podem ser encadeadas usando um ChainedTokenCredential para formar uma sequência ordenada de mecanismos de autenticação a serem tentados. Isso permite que você implante o mesmo código em ambientes de produção e desenvolvimento local.

Configurar a autenticação com identidade gerenciada

Neste exemplo, o ./src/azure-authentication.ts fornece várias funções para fornecer autenticação sem chave para Azure OpenAI.

A primeira função, getChainedCredential(), retorna a primeira credencial de Azure válida encontrada na cadeia.

function getChainedCredential() {

    return new ChainedTokenCredential(
        new ManagedIdentityCredential(process.env.AZURE_CLIENT_ID!), 
        new AzureDeveloperCliCredential({
            tenantId: process.env.AZURE_TENANT_ID! ? process.env.AZURE_TENANT_ID! : undefined
          })
    );
}

• ManagedIdentityCredential é utilizado primeiro. Ele é configurado com a variável de ambiente AZURE_CLIENT_ID no runtime de produção e é capaz de autenticar por meio da identidade gerenciada atribuída pelo usuário.
• AzureDeveloperCliCredential é tentado como segunda opção. Ele é configurado quando um desenvolvedor entra com a CLI do Desenvolvedor do Azure usando azd auth login.

Obter token de portador para OpenAI

A segunda função em ./src/azure-authentication.ts é getTokenProvider(), que retorna um callback fornecendo um bearer token com escopo para o ponto de extremidade do Azure Cognitive Services.

function getTokenProvider(): () => Promise<string> {
    const credential  = getChainedCredential();
    const scope = "https://cognitiveservices.azure.com/.default";
    return getBearerTokenProvider(credential, scope);
}

O snippet de código anterior usa getBearerTokenProvider para a credencial e o escopo e, em seguida, retorna um retorno de chamada que fornece um token de autenticação.

Criar Azure cliente OpenAI autenticado

A terceira função em ./src/azure-authentication.ts é getOpenAiClient(), que retorna o cliente Azure OpenAI.

export function getOpenAiClient(): AzureOpenAI | undefined{
    try {

        if (!process.env.AZURE_OPENAI_ENDPOINT) {
            throw new Error("AZURE_OPENAI_ENDPOINT is required for Azure OpenAI");
        }
        if (!process.env.AZURE_OPENAI_CHAT_DEPLOYMENT) {
            throw new Error("AZURE_OPENAI_CHAT_DEPLOYMENT is required for Azure OpenAI");
        }

        const options = { 
            azureADTokenProvider: getTokenProvider(), 
            deployment: process.env.AZURE_OPENAI_CHAT_DEPLOYMENT!, 
            apiVersion: process.env.AZURE_OPENAI_API_VERSION! || "2024-02-15-preview",
            endpoint: process.env.AZURE_OPENAI_ENDPOINT!
        }

        // Create the Asynchronous Azure OpenAI client
        return new AzureOpenAI (options);

    } catch (error) {
        console.error('Error getting Azure OpenAI client: ', error);
    }
}

Esse código usa as opções, incluindo o token com escopo correto, e cria o AzureOpenAI cliente

Transmitir resposta de chat com Azure OpenAI

Use o seguinte manipulador de rotas do Fastify em ./src/openai-chat-api.ts para enviar uma mensagem para Azure OpenAI e transmitir a resposta.

import { FastifyReply, FastifyRequest } from 'fastify';
import { AzureOpenAI } from "openai";
import { getOpenAiClient } from './azure-authentication.js';
import { ChatCompletionChunk, ChatCompletionMessageParam } from 'openai/resources/chat/completions';

interface ChatRequestBody {
    messages: ChatCompletionMessageParam [];
  }

export async function chatRoute (request: FastifyRequest<{ Body: ChatRequestBody }>, reply: FastifyReply) {

    const requestMessages: ChatCompletionMessageParam[] = request?.body?.messages;
    const openaiClient: AzureOpenAI | undefined = getOpenAiClient();

    if (!openaiClient) {
      throw new Error("Azure OpenAI client is not configured");
    }

    const allMessages = [
      { role: "system", content: "You are a helpful assistant."},
      ...requestMessages
    ] as ChatCompletionMessageParam [];

    const chatCompletionChunks = await openaiClient.chat.completions.create({
      // Azure Open AI takes the deployment name as the model name
      model: process.env.AZURE_OPENAI_CHAT_DEPLOYMENT_MODEL || "gpt-4o-mini",
      messages: allMessages,
      stream: true

    })
    reply.raw.setHeader('Content-Type', 'text/html; charset=utf-8');
    reply.raw.setHeader('Cache-Control', 'no-cache');
    reply.raw.setHeader('Connection', 'keep-alive');
    reply.raw.flushHeaders();

    for await (const chunk of chatCompletionChunks as AsyncIterable<ChatCompletionChunk>) {
      for (const choice of chunk.choices) {
        reply.raw.write(JSON.stringify(choice) + "\n")
      }
    }

    reply.raw.end()

}

A função obtém a conversa de chat, incluindo as mensagens anteriores, e as envia para Azure OpenAI. À medida que as partes de fluxo são retornadas de Azure OpenAI, elas são enviadas para o cliente.

Se o problema não for resolvido, registre seu problema no Issues do repositório.

Próximas etapas

Se o problema não for resolvido, registre seu problema no Issues do repositório.

Se o problema não for resolvido, registre seu problema no Issues do repositório.