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

En este artículo se muestra cómo crear y usar el ejemplo de bloque de creación de seguridad de Azure OpenAI. El propósito es demostrar el aprovisionamiento de cuentas de Azure OpenAI con el control de acceso basado en rol (RBAC) para la autenticación sin claves (Id. de Microsoft Entra) en Azure OpenAI. Este ejemplo de aplicación de chat también incluye toda la infraestructura y la configuración necesarias para aprovisionar recursos de Azure OpenAI e implementar la aplicación en Azure Container Apps mediante la CLI para desarrolladores de Azure.

Siguiendo las instrucciones de este artículo, podrá:

• Implemente una aplicación de chat segura de Azure Container.
• Use la identidad administrada para el acceso a Azure OpenAI.
• Chatear con un modelo de lenguaje grande (LLM) de Azure OpenAI mediante la biblioteca de OpenAI.

Una vez finalizado este artículo, puede comenzar a modificar el nuevo proyecto con sus datos y código personalizado.

Nota:

En este artículo se usan una o varias plantillas de aplicaciones de IA como base para los ejemplos e instrucciones del artículo. Las plantillas de aplicaciones de IA le proporcionan implementaciones de referencia bien mantenidas y fáciles de implementar que le ayudan a garantizar un punto inicial de alta calidad para sus aplicaciones de IA.

Introducción a la arquitectura

En el diagrama siguiente se muestra una arquitectura sencilla de la aplicación de chat:

La aplicación de chat se ejecuta como una aplicación de contenedor de Azure. La aplicación usa la identidad administrada a través de Microsoft Entra ID para autenticarse con Azure OpenAI, en lugar de una clave de API. La aplicación de chat usa Azure OpenAI para generar respuestas a los mensajes del usuario.

La arquitectura de la aplicación se basa en los siguientes servicios y componentes:

• Azure OpenAI representa el proveedor de IA al que se envían las consultas del usuario.
• Azure Container Apps es el entorno de contenedor donde se hospeda la aplicación.
• La identidad administrada nos ayuda a garantizar la mejor seguridad de la clase y elimina el requisito de que sea un desarrollador para administrar de forma segura un secreto.
• Archivos de Bicep para aprovisionar recursos de Azure, incluidos Azure OpenAI, Azure Container Apps, Azure Container Registry, Azure Log Analytics y roles RBAC.

• Microsoft AI Chat Protocol proporciona contratos DE API estandarizados en todas las soluciones y lenguajes de IA. La aplicación de chat se ajusta al protocolo Microsoft AI Chat Protocol, que permite que la aplicación de evaluaciones se ejecute en cualquier aplicación de chat que se ajuste al protocolo.
• Un quart de Python que usa el openai paquete para generar respuestas a los mensajes del 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 usa el paquete NuGet Azure.AI.OpenAI para generar respuestas a los mensajes del usuario.

Costos

En un intento de mantener los precios tan bajos como sea posible en este ejemplo, la mayoría de los recursos usan un plan de tarifa básico o de consumo. Modifique el nivel de nivel según sea necesario en función del uso previsto. Para dejar de incurrir en cargos, elimine los recursos cuando haya terminado con el artículo.

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

Requisitos previos

Hay disponible un entorno contenedor de desarrollo con todas las dependencias necesarias para completar este artículo. Puede ejecutar el contenedor de desarrollo en GitHub Codespaces (en un navegador) o localmente utilizando Visual Studio Code.

Para usar este artículo, debe cumplir los siguientes requisitos previos:

Codespaces de GitHub (recomendado)

• Una suscripción a Azure: cree una cuenta gratuita.

• Permisos de cuenta de Azure: la cuenta de Azure debe tener Microsoft.Authorization/roleAssignments/write permisos, como administrador de acceso de usuario o propietario.

• GitHub

Visual Studio Code

• Una suscripción a Azure: cree una cuenta gratuita.

• Permisos de cuenta de Azure: la cuenta de Azure debe tener Microsoft.Authorization/roleAssignments/write permisos, como administrador de acceso de usuario o propietario.

• CLI de desarrollo de Azure

• Docker Desktop: inicie Docker Desktop si no se está ejecutando ya

• Visual Studio Code

• Extensión del contenedor de desarrollo

Entorno de desarrollo abierto

Use las instrucciones siguientes para implementar un entorno de desarrollo preconfigurado que contenga todas las dependencias necesarias para completar este artículo.

Codespaces de GitHub (recomendado)

GitHub Codespaces ejecuta un contenedor de desarrollo administrado por GitHub con Visual Studio Code para la web como interfaz de usuario. Para obtener el entorno de desarrollo más sencillo, utilice Codespaces de GitHub de modo que tenga las herramientas y dependencias de desarrollador correctas preinstaladas para completar este artículo.

Importante

Todas las cuentas de GitHub pueden usar Codespaces durante un máximo de 60 horas gratis cada mes con 2 instancias principales. Para obtener más información, consulte Almacenamiento y horas de núcleo incluidas mensualmente en GitHub Codespaces.

Siga estos pasos para crear un nuevo espacio de código de GitHub en la main rama del Azure-Samples/openai-chat-app-quickstart repositorio de GitHub.

1. Haga clic con el botón derecho en el botón siguiente y seleccione Abrir vínculo en la nueva ventana. Esta acción le permite tener el entorno de desarrollo y la documentación disponible para su revisión.

2. En la página Crear espacio de códigos , revise y seleccione Crear nuevo espacio de código.

   

3. Espere a que se inicie Codespace. Este proceso de startup puede tardar unos minutos.

4. Inicie sesión en Azure con la CLI para desarrolladores de Azure en el terminal de la parte inferior de la pantalla.

   azd auth login
   

5. Copie el código del terminal y péguelo en un navegador. Siga las instrucciones para autenticarse con su cuenta Azure.

Las tareas restantes de este artículo tienen lugar en el contexto de este contenedor de desarrollo.

Visual Studio Code

La extensión de contenedores de desarrollo para Visual Studio Code requiere que Docker esté instalado en el equipo local. La extensión aloja el contenedor de desarrollo de forma local utilizando el host Docker con las herramientas y dependencias de desarrollo correctas preinstaladas para completar este artículo.

1. Cree un directorio local en el equipo para el proyecto.

   mkdir my-secure-chat-app
   

2. Vaya al directorio que creó.

   cd my-secure-chat-app
   

3. Abra Visual Studio Code en ese directorio:

   code .
   

4. Abra un nuevo terminal en Visual Studio Code.

5. Ejecute el siguiente comando AZD para traer el repositorio de GitHub a su equipo local.

   azd init -t openai-chat-app-quickstart-dotnet
   

6. Abra la paleta de comandos, busque y seleccione Dev Containers: Abrir carpeta en contenedor para abrir el proyecto en un contenedor de desarrollo. Espere hasta que se abra el contenedor de desarrollo antes de continuar.

7. Inicie sesión en Azure con la CLI para desarrolladores de Azure.

   azd auth login
   

8. Los demás ejercicios de este proyecto tienen lugar en el contexto de este contenedor de desarrollo.

Implementación y ejecución

El repositorio de ejemplo contiene todos los archivos de código y configuración para la implementación de Azure de la aplicación de chat. Los pasos siguientes le guiarán por el proceso de implementación de Azure de la aplicación de chat de ejemplo.

Implementación de la aplicación de chat en Azure

Importante

Los recursos de Azure creados en esta sección incurren en costos inmediatos. Estos recursos pueden acumular costes incluso si interrumpe el comando antes de que se ejecute por completo.

1. Ejecute el siguiente comando de la CLI para desarrolladores de Azure para el aprovisionamiento de recursos de Azure y la implementación de código fuente:

   azd up
   

2. Use la siguiente tabla para responder a las solicitudes:

   Prompt	Respuesta
   Nombre del entorno	Hágala corta y en minúsculas. Agregue su nombre o alias. Por ejemplo, secure-chat. Se usa como parte del nombre del grupo de recursos.
   Subscription	Seleccione la suscripción en la que crear los recursos.
   Ubicación (para el hospedaje)	Seleccione una ubicación cercana en la lista.
   Localización del modelo OpenAI	Seleccione una ubicación cercana en la lista. Si está disponible la misma ubicación que la primera, selecciónela.

3. Espere hasta que se implemente la aplicación. La implementación suele tardar entre 5 y 10 minutos en completarse.

Uso de la aplicación de chat para formular preguntas al modelo de lenguaje grande

1. El terminal muestra una dirección URL después de una implementación correcta de la aplicación.

2. Seleccione esa URL etiquetada Deploying service web para abrir la aplicación de chat en un navegador.

   

3. En el explorador, escriba una pregunta como "¿Por qué es mejor la identidad administrada que las claves?".

4. La respuesta procede de Azure OpenAI y se muestra el resultado.

Exploración del código de ejemplo

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

Configuración de la autenticación con identidad administrada

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

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

El siguiente fragmento de código usa la AZURE_CLIENT_ID azd variable de entorno para crear una instancia 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")) 

Nota:

Las azd variables de entorno de recursos se aprovisionan durante la azd implementación de la aplicación.

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

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

La biblioteca cliente de identidades de Azure proporciona credenciales, clases públicas que implementan el protocolo TokenCredential de la biblioteca de 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 un ChainedTokenCredential mediante ManagedIdentityCredential y un AzureDeveloperCliCredentialobjeto :

• ManagedIdentityCredential se usa para Azure Functions y App de Azure Service. Se admite una identidad administrada asignada por el usuario pasando a client_id ManagedIdentityCredential.
• 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
)

Sugerencia

El orden de las credenciales es importante, ya que se usa el primer token de acceso válido de Microsoft Entra. Para obtener más información, consulte el artículo Información general sobre ChainedTokenCredential.

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

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

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

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

Las siguientes líneas comprueban las variables de entorno necesarias AZURE_OPENAI_ENDPOINT y AZURE_OPENAI_CHATGPT_DEPLOYMENT azd de recursos, que se aprovisionan durante la azd implementación de la aplicación. Se produce un error si un valor no está presente.

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

Este fragmento de código inicializa el cliente de Azure OpenAI, estableciendo los api_versionparámetros , azure_endpointy azure_ad_token_provider (client_args):

bp.openai_client = AsyncAzureOpenAI(
    api_version=os.getenv("AZURE_OPENAI_API_VERSION") or "2024-02-15-preview",
    azure_endpoint=os.getenv("AZURE_OPENAI_ENDPOINT"),
    azure_ad_token_provider=token_provider,
)  

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

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

Nota:

OpenAI usa el argumento de palabra clave model para especificar qué modelo se va a usar. Azure OpenAI tiene el concepto de implementaciones de modelo únicas. Al usar Azure OpenAI, model debe hacer referencia al nombre de implementación subyacente elegido durante la implementación del modelo de Azure OpenAI.

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

Flujo de respuesta mediante el cliente y el modelo de OpenAI

response_stream controla la llamada de finalización del chat en la ruta. El siguiente fragmento de código muestra cómo openai_client y model se usan.

async def response_stream():
    # This sends all messages, so API request may exceed token limits
    all_messages = [
        {"role": "system", "content": "You are a helpful assistant."},
    ] + request_messages

    chat_coroutine = bp.openai_client.chat.completions.create(
        # Azure Open AI takes the deployment name as the model name
        model=bp.openai_model,
        messages=all_messages,
        stream=True,
    )

Exploración del código de ejemplo

Las aplicaciones .NET dependen de la biblioteca cliente azure.AI.OpenAI para comunicarse con los servicios de Azure OpenAI, que depende de la biblioteca de 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 clave se configura en el program.cs archivo . El siguiente fragmento de código usa la AZURE_CLIENT_ID variable de entorno establecida por azd para crear una instancia ManagedIdentityCredential capaz de autenticarse a través de la identidad administrada asignada por el usuario.

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

Nota:

Las azd variables de entorno de recursos se aprovisionan durante la azd implementación de la aplicación.

El siguiente fragmento de código usa la AZURE_TENANT_ID variable de entorno 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 Identidad de Azure proporciona clases de credenciales que implementan el protocolo TokenCredential de la biblioteca de 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 mediante ChainedTokenCredential para formar una secuencia ordenada de mecanismos de autenticación que se van a intentar.

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

• ManagedIdentityCredential se usa para Azure Functions y App de Azure Service. Se admite una identidad administrada asignada por el usuario mediante el AZURE_CLIENT_ID que se proporcionó a ManagedIdentityCredential.
• AzureDeveloperCliCredential se usa para el desarrollo local. Se estableció anteriormente en función del inquilino de Microsoft Entra que se va a usar.

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

Sugerencia

El orden de las credenciales es importante, ya que se usa el primer token de acceso válido de Microsoft Entra. Para obtener más información, consulte el artículo Información general sobre ChainedTokenCredential.

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

La aplicación web blazor inserta el registrado AzureOpenAIClient en la parte superior del Home.Razor componente:

@inject AzureOpenAIClient azureOpenAIClient

Cuando el usuario envía el formulario, 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));

Otras consideraciones de seguridad

En este artículo se muestra cómo usa ChainedTokenCreadential el ejemplo para autenticarse en el servicio Azure OpenAI.

El ejemplo también tiene una acción de GitHub que examina los archivos de infraestructura como código y genera un informe que contiene los problemas detectados. Para garantizar los procedimientos recomendados continuos en su propio repositorio, se recomienda que cualquier persona que cree soluciones basadas en nuestras plantillas asegúrese de que la configuración de análisis de secretos de GitHub esté habilitada.

Considere otras medidas de seguridad, como:

• Restrinja el acceso al conjunto adecuado de usuarios de aplicaciones mediante Microsoft Entra.

• Protección de la instancia de Azure Container Apps con un firewall o una red virtual.

Limpieza de recursos

Limpieza de los recursos de Azure

Los recursos Azure creados en este artículo se facturan a su suscripción Azure. Si no espera necesitar estos recursos en el futuro, elimínelos para evitar incurrir en más gastos.

Para borrar los recursos de Azure y eliminar el código fuente, ejecute el siguiente comando de Azure Developer CLI:

azd down --purge

Limpiar GitHub Codespaces

GitHub Codespaces

La eliminación del entorno de GitHub Codespaces garantiza que pueda maximizar la cantidad de derechos de horas gratuitas por núcleo que obtiene para su cuenta.

Importante

Para obtener más información sobre los derechos de la cuenta de GitHub, consulte Almacenamiento y horas de núcleo incluidas mensualmente en GitHub Codespaces.

1. Inicie sesión en el panel de GitHub Codespaces (https://github.com/codespaces).

2. Busque los espacios de código que se ejecutan actualmente procedentes del repositorio de GitHub Azure-Samples/openai-chat-app-quickstart.

3. Abra el menú contextual del codespace y, a continuación, seleccione Eliminar.

1. Inicie sesión en el panel de GitHub Codespaces (https://github.com/codespaces).

2. Busque los espacios de código que se ejecutan actualmente procedentes del repositorio de GitHub Azure-Samples/openai-chat-app-quickstart-dotnet.

3. Abra el menú contextual del codespace y, a continuación, seleccione Eliminar.

Visual Studio Code

No es necesario limpiar el entorno local, pero puede detener el contenedor de desarrollo en ejecución y volver a ejecutar Visual Studio Code en el contexto de un área de trabajo local.

Abra la Paleta de comandos, busque los comandos de contenedores de desarrollo y, a continuación, seleccione Contenedores de desarrollo: volver a abrir la carpeta localmente.

Sugerencia

Visual Studio Code detendrá el contenedor de desarrollo en ejecución, pero el contenedor todavía existe en Docker en un estado detenido. Siempre tiene la opción de eliminar la instancia de contenedor, la imagen de contenedor y los volúmenes de Docker para liberar más espacio en la máquina local.

Obtener ayuda

Si su problema no se resuelve, regístrelo en el apartado de problemas del repositorio.

Pasos siguientes

Comience con el chat usando su propio ejemplo de datos para Python