Introducción al bloque de construcción de seguridad de Azure OpenAI

• Una aplicación Python Quart que usa el paquete /> Responses para generar respuestas a mensajes de usuario.
• Un front-end HTML/JavaScript básico que transmite respuestas desde el back-end mediante líneas JSON a través de ReadableStream.

• Una aplicación web Blazor que utiliza el paquete NuGet Azure.AI.OpenAI para generar respuestas a los mensajes de los usuarios.

• Una aplicación web de TypeScript que usa el paquete npm de OpenAI para generar respuestas a los mensajes del usuario.

Obtenga más información sobre cost en el repositorio de ejemplo.

Obtenga más información sobre cost en el repositorio de ejemplo.

Obtenga más información sobre cost en el repositorio de ejemplo.

Exploración del código de ejemplo

Aunque OpenAI y Azure OpenAI Service dependen de una biblioteca cliente común de Python, se necesitan pequeños cambios de código al usar los puntos de conexión de Azure OpenAI. Veamos cómo este ejemplo configura la autenticación sin claves con Microsoft Entra ID y se comunica con Azure OpenAI.

Configurar la autenticación con identidad administrada

En este ejemplo, el archivo src/quartapp/chat.py comienza con la configuración de la autenticación sin claves.

En el fragmento de código siguiente se usa el módulo azure.identity.aio para crear un flujo de autenticación asincrónico Microsoft Entra.

El siguiente fragmento de código usa la variable de entorno AZURE_CLIENT_IDazd para crear una instancia de ManagedIdentityCredential capaz de autenticarse a través de una identidad administrada asignada por el usuario.

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

El siguiente fragmento de código usa AZURE_TENANT_IDazd variable de entorno de recursos para crear una instancia de AzureDeveloperCliCredential capaz de autenticarse con el inquilino de Microsoft Entra actual.

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

La biblioteca cliente de Azure Identity proporciona credenciales, clases públicas que implementan el protocolo TokenCredential de la biblioteca Azure Core. Una credencial representa un flujo de autenticación distinto para adquirir un token de acceso de Microsoft Entra ID. Estas credenciales se pueden encadenar para formar una secuencia ordenada de mecanismos de autenticación que se van a intentar.

El fragmento de código siguiente crea una ChainedTokenCredential mediante una ManagedIdentityCredential y una AzureDeveloperCliCredential:

• El ManagedIdentityCredential se usa para Azure Functions, Azure App Service y Azure Container Apps. Se admite una identidad administrada asignada por el usuario pasando el client_id a ManagedIdentityCredential.
• La AzureDeveloperCliCredential se usa para el desarrollo local. Se estableció anteriormente en función del inquilino de Microsoft Entra que se va a usar.

azure_credential = ChainedTokenCredential(
    user_assigned_managed_identity_credential,
    azure_dev_cli_credential
)

El siguiente fragmento de código obtiene el proveedor de tokens de Azure OpenAI según la credencial de Azure seleccionada. Este valor se obtiene llamando a azure.identity.aio.get_bearer_token_provider con dos argumentos:

• azure_credential: la instancia de ChainedTokenCredential creada anteriormente para autenticar la solicitud.

• https://cognitiveservices.azure.com/.default: Se requiere uno o varios ámbitos de token de portador. En este caso, el punto de conexión Azure Cognitive Services.

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

Las líneas siguientes comprueban las variables de entorno necesarias AZURE_OPENAI_ENDPOINT y AZURE_OPENAI_CHAT_DEPLOYMENT, dos variables de entorno azd que se establecen durante el aprovisionamiento azd. Si un valor no está presente, se produce un error.

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

Este fragmento de código inicializa el cliente de OpenAI en el punto de conexión de /openai/v1/ de Azure, pasando el proveedor de tokens como api_key. No api_version es necesario con el endpoint v1.

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

En la línea siguiente se establece el nombre de implementación del modelo de Azure OpenAI para su uso en llamadas a la API.

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

Una vez completada esta función, el cliente está configurado y listo para interactuar correctamente con Azure servicios de OpenAI.

Transmisión de respuestas mediante la API de respuestas de OpenAI

response_stream controla la llamada de streaming de la API de respuestas en la ruta. El frontend envía elementos con forma de Respuestasinput directamente, y el backend los reenvía a 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"

Exploración del código de ejemplo

Las aplicaciones .NET se basan en la biblioteca cliente Azure.AI.OpenAI para comunicarse con los servicios de Azure OpenAI, que depende de la biblioteca OpenAI. La aplicación de ejemplo configura la autenticación sin claves mediante Microsoft Entra ID para comunicarse con Azure OpenAI.

Configuración de la autenticación y el registro de servicios

En este ejemplo, la autenticación sin claves se configura en el archivo program.cs. El siguiente fragmento de código usa la variable de entorno AZURE_CLIENT_ID establecida por azd para crear una instancia de ManagedIdentityCredential capaz de autenticarse a través de una identidad administrada asignada por el usuario.

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

El siguiente fragmento de código usa la variable de entorno AZURE_TENANT_ID establecida por azd para crear una instancia de AzureDeveloperCliCredential capaz de autenticarse localmente mediante la cuenta que inició sesión en azd.

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

La biblioteca cliente de Azure Identity proporciona clases de credenciales que implementan el protocolo TokenCredential de la biblioteca Azure Core. Una credencial representa un flujo de autenticación distinto para adquirir un token de acceso de Microsoft Entra ID. Estas credenciales se pueden encadenar con ChainedTokenCredential para formar una secuencia ordenada de mecanismos de autenticación que se van a intentar.

El fragmento de código siguiente registra el AzureOpenAIClient para la inyección de dependencias y crea una ChainedTokenCredential mediante una ManagedIdentityCredential y una AzureDeveloperCliCredential:

• El ManagedIdentityCredential se usa para Azure Functions, Azure App Service y Azure Container Apps. Se admite una identidad administrada asignada por el usuario utilizando el AZURE_CLIENT_ID que fue proporcionado a ManagedIdentityCredential.
• La AzureDeveloperCliCredential se usa para el desarrollo local. Se estableció previamente en función de la entidad de Microsoft Entra que se está usando.

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

Obtención de finalizaciones de chat mediante el cliente de OpenAI de Azure

La aplicación web de Blazor inyecta el AzureOpenAIClient registrado en la parte superior del componente Home.Razor:

@inject AzureOpenAIClient azureOpenAIClient

Cuando el usuario envía el formulario, el AzureOpenAIClient envía su solicitud al modelo de OpenAI para generar una finalización:

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));

Exploración del código de ejemplo

Aunque OpenAI y el servicio Azure OpenAI dependen de una openai (biblioteca cliente común de JavaScript), se necesitan pequeños cambios de código al usar los puntos de conexión de Azure OpenAI. Veamos cómo este ejemplo configura la autenticación sin claves con Microsoft Entra ID y se comunica con Azure OpenAI.

Autenticación sin claves para cada entorno

La biblioteca cliente de Azure Identity proporciona clases de credenciales que implementan el protocolo de Azure Core library TokenCredential. Una credencial representa un flujo de autenticación distinto para adquirir un token de acceso de Microsoft Entra ID. Estas credenciales se pueden encadenar mediante chainedTokenCredential para formar una secuencia ordenada de mecanismos de autenticación que se van a intentar. Esto le permite implementar el mismo código en entornos de producción y desarrollo local.

Configurar la autenticación con identidad administrada

En este ejemplo, el ./src/azure-authentication.ts proporciona varias funciones para proporcionar autenticación sin claves para Azure OpenAI.

La primera función, getChainedCredential(), devuelve la primera credencial Azure válida que se encuentra en la cadena.

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 se prueba primero. Se configura con la variable de entorno AZURE_CLIENT_ID en tiempo de ejecución de producción y es capaz de autenticarse a través de la identidad administrada asignada por el usuario.
• AzureDeveloperCliCredential se intenta en segundo lugar. Se configura cuando un desarrollador inicia sesión con la CLI para desarrolladores de Azure mediante azd auth login.

Obtención del token de portador para OpenAI

La segunda función de ./src/azure-authentication.ts es getTokenProvider(), que devuelve un callback que proporciona un token de portador con alcance en el punto de conexión de Azure Cognitive Services.

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

El fragmento de código anterior usa getBearerTokenProvider para tomar la credencial y el ámbito, y luego devuelve una devolución de llamada que proporciona un token portador.

Creación de un cliente de OpenAI autenticado Azure

La tercera función de ./src/azure-authentication.ts es getOpenAiClient(), que devuelve el cliente openAI de Azure.

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);
    }
}

Este código toma las opciones, incluido el token con ámbito correcto, y crea el cliente de AzureOpenAI.

Transmisión de respuesta de chat con Azure OpenAI

Use el siguiente controlador de rutas fastify en ./src/openai-chat-api.ts para enviar un mensaje a Azure OpenAI y transmitir la respuesta.

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()

}

La función obtiene la conversación de chat, incluidos los mensajes anteriores, y los envía a Azure OpenAI. A medida que los fragmentos de flujo se devuelven de Azure OpenAI, se envían al cliente.

Si no se soluciona el problema, registre su problema en el repositorio Issues.

Pasos siguientes

Si no se soluciona el problema, registre su problema en el repositorio Issues.

Si no se soluciona el problema, registre su problema en el repositorio Issues.