Compartir a través de

Implementación de un flujo en un punto de conexión en línea para la inferencia en tiempo real con la CLI

  • Artículo

En este artículo, aprenderá a implementar el flujo en un punto de conexión en línea administrado o un punto de conexión en línea de Kubernetes para usarlo en inferencia en tiempo real con la CLI de Azure Machine Learning v2.

Antes de empezar, asegúrese de que ha probado el flujo correctamente y de que está listo para implementarse en producción. Para más información sobre cómo probar el flujo, consulte Prueba del flujo. Después de probar el flujo, aprenderá a crear un punto de conexión y una implementación en línea administrados y a usar el punto de conexión para la inferencia en tiempo real.

  • En este artículo se explica cómo usar la experiencia de la CLI.
  • El SDK de Python no se trata en este artículo. Vea el cuaderno de ejemplo de GitHub en su lugar. Para usar el SDK de Python, debe tener el SDK de Python v2 para Azure Machine Learning. Para más información, consulte Instalación del SDK v2 de Python para Azure Machine Learning.

Importante

Los elementos marcados (versión preliminar) en este artículo se encuentran actualmente en versión preliminar pública. Se ofrece la versión preliminar sin Acuerdo de Nivel de Servicio y no se recomienda para cargas de trabajo de producción. Es posible que algunas características no sean compatibles o que tengan sus funcionalidades limitadas. Para más información, consulte Términos de uso complementarios de las Versiones Preliminares de Microsoft Azure.

Requisitos previos

  • La CLI de Azure y la extensión de Azure Machine Learning para la CLI de Azure. Para más información, consulte Instalación, configuración y uso de la CLI v2.
  • Un área de trabajo de Azure Machine Learning. Si no tiene uno, siga los pasos descritos en el artículo Inicio rápido: Creación de recursos del área de trabajo para crear uno.
  • Los controles de acceso basado en rol de Azure (RBAC de Azure) se usan para conceder acceso a las operaciones en Azure Machine Learning. Para realizar los pasos descritos en este artículo, la cuenta de usuario debe tener asignado el rol de propietario o colaborador para el área de trabajo de Azure Machine Learning, o un rol personalizado que permita "Microsoft.MachineLearningServices/workspaces/onlineEndpoints/". Si usa Studio para crear o administrar puntos de conexión o implementaciones en línea, necesitará un permiso adicional "Microsoft.Resources/deployments/write" del propietario del grupo de recursos. Para obtener más información, consulte Administración del acceso a un área de trabajo de Azure Machine Learning.

Nota:

El punto de conexión en línea administrado solo admite la red virtual administrada. Si el área de trabajo está en una red virtual personalizada, puede implementar en el punto de conexión en línea de Kubernetes o implementar en otras plataformas como Docker.

Asignación de la cuota de máquina virtual para la implementación

En el caso de los puntos de conexión en línea administrados, Azure Machine Learning reserva el 20 % de los recursos de proceso para realizar actualizaciones. Por lo tanto, si solicita un número determinado de instancias en una implementación, debe tener una cuota para ceil(1.2 * number of instances requested for deployment) * number of cores for the VM SKU disponible para evitar errores. Por ejemplo, si solicita 10 instancias de una máquina virtual Standard_DS3_v2 (que viene con cuatro núcleos) en una implementación, debería tener disponible una cuota de 48 núcleos (12 instancias de cuatro núcleos). Para ver el uso y los aumentos de cuota de solicitud, consulte Ver el uso y las cuotas en Azure Portal.

Preparación del flujo para la implementación

Cada flujo tendrá una carpeta que contiene códigos o avisos, definición y otros artefactos del flujo. Si ha desarrollado el flujo con la interfaz de usuario, puede descargar la carpeta de flujo desde la página de detalles del flujo. Si ha desarrollado el flujo con la CLI o el SDK, debe tener la carpeta de flujo ya.

En este artículo se usará el flujo "basic-chat" como ejemplo para implementar en el punto de conexión en línea administrado de Azure Machine Learning.

Importante

Si ha usado additional_includes en el flujo, primero debe usar pf flow build --source <path-to-flow> --output <output-path> --format docker para obtener una versión resuelta de la carpeta de flujo.

Configuración del área de trabajo predeterminada

Use los siguientes comandos para establecer el área de trabajo y el grupo de recursos predeterminados para la CLI.

az account set --subscription <subscription ID>
az configure --defaults workspace=<Azure Machine Learning workspace name> group=<resource group>

Registro del flujo como modelo (opcional)

En la implementación en línea, puede hacer referencia a un modelo registrado o especificar la ruta de acceso del modelo insertada (desde dónde cargar los archivos del modelo). Se recomienda registrar el modelo y especificar el nombre y la versión del modelo en la definición de implementación. Utilice el formulario model:<model_name>:<version>.

A continuación se muestra un ejemplo de definición de un flujo de chat.

Nota:

Si el flujo no es un flujo de chat, no es necesario agregar estos elementos properties.

$schema: https://azuremlschemas.azureedge.net/latest/model.schema.json
name: basic-chat-model
path: ../../../../examples/flows/chat/basic-chat
description: register basic chat flow folder as a custom model
properties:
  # In AuzreML studio UI, endpoint detail UI Test tab needs this property to know it's from prompt flow
  azureml.promptflow.source_flow_id: basic-chat
  
  # Following are properties only for chat flow 
  # endpoint detail UI Test tab needs this property to know it's a chat flow
  azureml.promptflow.mode: chat
  # endpoint detail UI Test tab needs this property to know which is the input column for chat flow
  azureml.promptflow.chat_input: question
  # endpoint detail UI Test tab needs this property to know which is the output column for chat flow
  azureml.promptflow.chat_output: answer

Use az ml model create --file model.yaml para registrar el modelo en el área de trabajo.

Definición del punto de conexión

Para definir un punto de conexión, deberá especificar:

  • Nombre del punto de conexión: Nombre del punto de conexión. El valor debe ser único dentro de la región de Azure. Para más información acerca de las reglas de nomenclatura, consulte límites del punto de conexión.
  • Modo de autenticación: método de autenticación del punto de conexión. Elija entre la autenticación basada en claves y la autenticación basada en tokens de Azure Machine Learning. Una clave no expira, pero un token sí. Para más información sobre la autenticación, consulte Autenticación en un punto de conexión en línea. Opcionalmente, puede agregar una descripción y etiquetas al punto de conexión.
  • Opcionalmente, puede agregar una descripción y etiquetas al punto de conexión.
  • Si desea realizar la implementación en un clúster de Kubernetes (clúster habilitado para AKS o Arc) que está asociado al área de trabajo, puede implementar el flujo para que sea un punto de conexión en línea de Kubernetes.

A continuación se muestra un ejemplo de definición de punto de conexión que, de manera predeterminada, usa la identidad asignada por el sistema.

$schema: https://azuremlschemas.azureedge.net/latest/managedOnlineEndpoint.schema.json
name: basic-chat-endpoint
auth_mode: key
properties:
# this property only works for system-assigned identity.
# if the deploy user has access to connection secrets, 
# the endpoint system-assigned identity will be auto-assigned connection secrets reader role as well
  enforce_access_to_default_secret_stores: enabled
Clave Descripción
$schema (Opcional) El esquema de YAML. Para ver todas las opciones disponibles en el archivo YAML, puede ver el esquema del fragmento de código anterior en un explorador.
name Nombre del punto de conexión.
auth_mode Use key para la autenticación basada en claves. Use aml_token para la autenticación basada en tokens de Azure Machine Learning. Para obtener el token más reciente, use el comando az ml online-endpoint get-credentials.
property: enforce_access_to_default_secret_stores (versión preliminar) - De manera predeterminada, el punto de conexión usará la identidad asignada por el sistema. Esta propiedad solo funciona para la identidad asignada por el sistema.
- Esta propiedad significa que si tiene el permiso de lector de secretos de conexión, la identidad asignada por el sistema del punto de conexión se asignará automáticamente al rol Lector de secretos de conexión del área de trabajo de Azure Machine Learning para que el punto de conexión pueda acceder a las conexiones correctamente al realizar la inferencia.
- Esta propiedad está deshabilitada de forma predeterminada.

Si crea un punto de conexión en línea de Kubernetes, debe especificar los siguientes atributos adicionales:

Clave Descripción
compute El destino de proceso de Kubernetes en el que implementar el punto de conexión.

Para conocer más configuraciones de punto de conexión, consulte Esquema de punto de conexión en línea administrado.

Importante

Si el flujo usa conexiones de autenticación basadas en Microsoft Entra ID, independientemente de que use la identidad asignada por el sistema o la identidad asignada por el usuario, siempre debe conceder a la identidad administrada los roles adecuados de los recursos correspondientes para que pueda realizar llamadas API a ese recurso. Por ejemplo, si la conexión de Azure OpenAI usa la autenticación basada en Microsoft Entra ID, debe conceder la identidad administrada del punto de conexión Rol de colaborador de OpenAI de Cognitive Services o de OpenAI de Cognitive Services de los recursos de Azure OpenAI correspondientes.

Usar la identidad asignada por el usuario

De forma predeterminada, al crear un punto de conexión en línea, se genera automáticamente una identidad administrada asignada por el sistema. También puede especificar una identidad administrada asignada por el usuario ya existente para el punto de conexión.

Si quiere usar la identidad asignada por el usuario, puede especificar los siguientes atributos adicionales en el endpoint.yaml:

identity:
  type: user_assigned
  user_assigned_identities:
    - resource_id: user_identity_ARM_id_place_holder

Además, también debe especificar el Client ID de la identidad asignada por el usuario en environment_variables el deployment.yaml como se indica a continuación. Puede encontrar el Client ID en el Overview de la identidad administrada en Azure Portal.

environment_variables:
  AZURE_CLIENT_ID: <client_id_of_your_user_assigned_identity>

Importante

Debe conceder los siguientes permisos a la identidad asignada por el usuario antes de crear el punto de conexión para que se pueda acceder a los recursos de Azure para realizar la inferencia. Obtenga más información sobre cómo conceder permiso a la identidad del punto de conexión.

Ámbito Role Por qué se necesita
Área de trabajo de Azure Machine Learning Rol de Lector de secretos de conexión del área de trabajo de Azure Machine Learning O BIEN un rol personalizado con "Microsoft.MachineLearningServices/workspaces/connections/listsecrets/action" Obtener conexiones del área de trabajo
Registro de contenedor del área de trabajo Extracción de ACR Extracción de imagen de contenedor
Almacenamiento predeterminado del área de trabajo Lector de datos de blobs de almacenamiento Cargar el modelo desde el almacenamiento
Área de trabajo de Azure Machine Learning (opcional) Escritor de métricas del área de trabajo Después de implementar el punto de conexión, si desea supervisar las métricas relacionadas con el punto de conexión, como el uso de CPU, GPU, disco o memoria, debe conceder este permiso a la identidad.

Definir la implementación

Una implementación es un conjunto de recursos necesarios para hospedar el modelo que realiza la inferencia real.

A continuación se muestra un ejemplo de definición de implementación, en el que la sección model hace referencia al modelo de flujo registrado. También puede especificar la ruta de acceso del modelo de flujo en línea.

$schema: https://azuremlschemas.azureedge.net/latest/managedOnlineDeployment.schema.json
name: blue
endpoint_name: basic-chat-endpoint
model: azureml:basic-chat-model:1
  # You can also specify model files path inline
  # path: examples/flows/chat/basic-chat
environment: 
  image: mcr.microsoft.com/azureml/promptflow/promptflow-runtime:latest
  # inference config is used to build a serving container for online deployments
  inference_config:
    liveness_route:
      path: /health
      port: 8080
    readiness_route:
      path: /health
      port: 8080
    scoring_route:
      path: /score
      port: 8080
instance_type: Standard_E16s_v3
instance_count: 1
environment_variables:
  # for pulling connections from workspace
  PRT_CONFIG_OVERRIDE: deployment.subscription_id=<subscription_id>,deployment.resource_group=<resource_group>,deployment.workspace_name=<workspace_name>,deployment.endpoint_name=<endpoint_name>,deployment.deployment_name=<deployment_name>

  # (Optional) When there are multiple fields in the response, using this env variable will filter the fields to expose in the response.
  # For example, if there are 2 flow outputs: "answer", "context", and I only want to have "answer" in the endpoint response, I can set this env variable to '["answer"]'.
  # If you don't set this environment, by default all flow outputs will be included in the endpoint response.
  # PROMPTFLOW_RESPONSE_INCLUDED_FIELDS: '["category", "evidence"]'
Atributo Description
Nombre Nombre de la implementación.
El nombre del punto de conexión El nombre del punto de conexión en el que se creará la implementación.
Modelo Modelo que se usará para la implementación. Este valor puede ser una referencia a un modelo con versiones existente en el área de trabajo o una especificación de modelo en línea.
Entorno Entorno para hospedar el modelo y el código. Contiene:
- image
- inference_config: se usa para crear un contenedor de servicios para implementaciones en línea, como liveness route, readiness_route y scoring_route.
Tipo de instancia Tamaño de máquina virtual que se usará para la implementación. Para la lista de tamaños admitidos, consulte Lista de SKU de puntos de conexión en línea administrados.
Recuento de instancias El número de instancias que se usarán para la implementación. Base el valor en la carga de trabajo esperada. Para lograr alta disponibilidad, se recomienda establecer el valor en al menos 3. Reservamos un 20 % adicional para realizar actualizaciones. Para más información, consulte Límites de puntos de conexión en línea.
Variables de entorno Las siguientes variables de entorno deben establecerse para los puntos de conexión implementados desde un flujo:
- (obligatorio) PRT_CONFIG_OVERRIDE: para extraer conexiones del área de trabajo
- (opcional) PROMPTFLOW_RESPONSE_INCLUDED_FIELDS:: cuando hay varios campos en la respuesta, el uso de esta variable env filtrará los campos que se van a exponer en la respuesta.
Por ejemplo, si hay dos salidas de flujo: "answer" y "context", y solo desea tener "answer" en la respuesta del punto de conexión, puede establecer esta variable env en '["answer"]'.

Importante

Si la carpeta de flujo tiene un archivo requirements.txt que contiene las dependencias necesarias para ejecutar el flujo, debe seguir la implementación con un entorno personalizado para compilar el entorno personalizado, incluidas las dependencias.

Si crea una implementación en línea de Kubernetes, debe especificar los siguientes atributos adicionales:

Atributo Descripción
Tipo El tipo de la implementación. Establezca el valor en kubernetes.
Tipo de instancia El tipo de instancia que ha creado en el clúster de Kubernetes que se va a usar para la implementación, representa el recurso de proceso de solicitud o límite de la implementación. Para más información, consulte Creación y administración del tipo de instancia.

Implementación del punto de conexión en línea en Azure

Para crear el punto de conexión en la nube, ejecute el código siguiente:

az ml online-endpoint create --file endpoint.yml

Para crear la implementación de nombre blue en el punto de conexión, ejecute el código siguiente:

az ml online-deployment create --file blue-deployment.yml --all-traffic

Nota:

Esta implementación puede tardar más de 15 minutos.

Sugerencia

Si prefiere no bloquear la consola de la CLI, puede agregar la marca --no-wait al comando. Sin embargo, se detendrá la presentación interactiva del estado de implementación.

Importante

La marca --all-traffic del elemento az ml online-deployment create anterior asigna el 100 % del tráfico del punto de conexión a la implementación azul creada recientemente. Aunque esto es útil para fines de desarrollo y prueba, en producción es posible que quiera abrir el tráfico a la nueva implementación mediante un comando explícito. Por ejemplo, az ml online-endpoint update -n $ENDPOINT_NAME --traffic "blue=100".

Comprobación del estado del punto de conexión y la implementación

Para comprobar el estado del punto de conexión, ejecute el siguiente código:

az ml online-endpoint show -n basic-chat-endpoint

Para comprobar el estado de la implementación, ejecute el siguiente código:

az ml online-deployment get-logs --name blue --endpoint basic-chat-endpoint

Invocación del punto de conexión para puntuar los datos con el modelo

Puede crear un archivo sample-request.json como este:

{
  "question": "What is Azure Machine Learning?",
  "chat_history":  []
}

az ml online-endpoint invoke --name basic-chat-endpoint --request-file sample-request.json

También puede llamarlo con un cliente HTTP, por ejemplo con curl:

ENDPOINT_KEY=<your-endpoint-key>
ENDPOINT_URI=<your-endpoint-uri>

curl --request POST "$ENDPOINT_URI" --header "Authorization: Bearer $ENDPOINT_KEY" --header 'Content-Type: application/json' --data '{"question": "What is Azure Machine Learning?", "chat_history":  []}'

Puede obtener la clave de punto de conexión y el URI del punto de conexión desde el área de trabajo de Azure Machine Learning en Puntos de conexión>Consumir>información de consumo básica.

Configuraciones avanzadas

Implementación con otras conexiones del desarrollo de flujo

Es posible que quiera invalidar las conexiones del flujo durante la implementación.

Por ejemplo, si el archivo flow.dag.yaml usa una conexión denominada my_connection, puede invalidarla si agrega variables de entorno del archivo yaml de implementación como se indica a continuación:

Opción 1: invalidación del nombre de conexión

environment_variables:
  my_connection: <override_connection_name>

Si desea invalidar un campo específico de la conexión, puede invalidar agregando variables de entorno con el patrón de nomenclatura <connection_name>_<field_name>. Por ejemplo, si el flujo usa una conexión denominada my_connection con una clave de configuración denominada chat_deployment_name, el back-end de servicio intentará recuperar chat_deployment_name de la variable de entorno "MY_CONNECTION_CHAT_DEPLOYMENT_NAME" de forma predeterminada. Si no se establece la variable de entorno, usará el valor original de la definición de flujo.

Opción 2: invalidación haciendo referencia al recurso

environment_variables:
  my_connection: ${{azureml://connections/<override_connection_name>}}

Nota:

Solo puede hacer referencia a una conexión dentro del mismo área de trabajo.

Implementación con un entorno personalizado

En esta sección se muestra cómo usar un contexto de compilación de Docker para especificar el entorno de la implementación, siempre que tenga conocimientos de Docker y de entornos de Azure Machine Learning.

  1. En el entorno local, cree una carpeta denominada image_build_with_reqirements con los siguientes archivos:

    |--image_build_with_reqirements
|  |--requirements.txt
|  |--Dockerfile

    • requirements.txt se debe heredar de la carpeta de flujo, que se ha usado para realizar el seguimiento de las dependencias del flujo.

    • El contenido de Dockerfile es el siguiente:

      FROM mcr.microsoft.com/azureml/promptflow/promptflow-runtime:latest
COPY ./requirements.txt .
RUN pip install -r requirements.txt

  2. reemplace la sección environment del archivo yaml de definición de implementación por el contenido siguiente:

    environment: 
  build:
    path: image_build_with_reqirements
    dockerfile_path: Dockerfile
  # deploy prompt flow is BYOC, so we need to specify the inference config
  inference_config:
    liveness_route:
      path: /health
      port: 8080
    readiness_route:
      path: /health
      port: 8080
    scoring_route:
      path: /score
      port: 8080

Uso del motor de servicio de FastAPI (versión preliminar)

De forma predeterminada, el servicio de flujo de avisos usa el motor de servicio FLASK. A partir de la versión 1.10.0 del SDK de flujo de avisos, se admite el motor de servicio basado en FastAPI. Puede usar fastapi motor de servicio especificando una variable de entorno PROMPTFLOW_SERVING_ENGINE.

environment_variables:
  PROMPTFLOW_SERVING_ENGINE=fastapi

Configuración de la simultaneidad para la implementación

Al implementar el flujo en la implementación en línea, hay dos variables de entorno que se configuran para la simultaneidad: PROMPTFLOW_WORKER_NUM y PROMPTFLOW_WORKER_THREADS. Además, también tendrá que establecer el parámetro max_concurrent_requests_per_instance.

A continuación se muestra un ejemplo de cómo configurar en el archivo deployment.yaml.

request_settings:
  max_concurrent_requests_per_instance: 10
environment_variables:
  PROMPTFLOW_WORKER_NUM: 4
  PROMPTFLOW_WORKER_THREADS: 1

  • PROMPTFLOW_WORKER_NUM: este parámetro determina el número de trabajos (procesos) que se iniciarán en un contenedor. El valor predeterminado es igual al número de núcleos de CPU y el valor máximo es el doble del número de núcleos de CPU.

  • PROMPTFLOW_WORKER_THREADS: este parámetro determina el número de conversaciones que se iniciarán en un trabajo. El valor predeterminado es 1.

    Nota:

    Al establecer PROMPTFLOW_WORKER_THREADS en un valor mayor que 1, asegúrese de que el código de flujo sea seguro para subprocesos.

  • max_concurrent_requests_per_instance: el número máximo de solicitudes simultáneas por instancia permitidas para la implementación. El valor predeterminado es 10.

    El valor sugerido para max_concurrent_requests_per_instance depende del tiempo de solicitud:

    • Si el tiempo de solicitud es mayor que 200 ms, establezca max_concurrent_requests_per_instance en PROMPTFLOW_WORKER_NUM * PROMPTFLOW_WORKER_THREADS.
    • Si el tiempo de solicitud es menor o igual que 200 ms, establezca max_concurrent_requests_per_instance en (1.5-2) * PROMPTFLOW_WORKER_NUM * PROMPTFLOW_WORKER_THREADS. Esto puede mejorar el rendimiento total al permitir que algunas solicitudes se pongan en cola en el lado servidor.
    • Si va a enviar solicitudes entre regiones, puede cambiar el umbral de 200 ms a 1 s.

Al ajustar los parámetros anteriores, debe supervisar las siguientes métricas para garantizar un rendimiento y una estabilidad óptimos:

  • Uso de CPU o memoria de instancia de esta implementación
  • Respuestas que no sea 200 (4xx, 5xx)
    • Si recibe una respuesta 429, normalmente indica que necesita volver a usar la configuración de simultaneidad siguiendo la guía anterior o escalar la implementación.
  • Estado de limitación de Azure OpenAI

Supervisión de puntos de conexión

Recopilación de métricas generales

Puede ver métricas generales de implementación en línea (números de solicitud, latencia de solicitud, bytes de red, USO de CPU/GPU/disco/memoria, etc.).

Recopilación de datos de seguimiento y métricas del sistema durante el tiempo de inferencia

También puede recopilar datos de seguimiento y solicitar métricas específicas de implementación del flujo de avisos (consumo de tokens, latencia de flujo, etc.) durante el tiempo de inferencia en el área de trabajo vinculada a Application Insights agregando una propiedad app_insights_enabled: true en el archivo yaml de implementación. Obtenga más información sobre seguimiento y métricas de la implementación del flujo de avisos.

Las métricas y el seguimiento específicos del flujo de avisos se pueden especificar en otras instancias de Application Insights que no sean el área de trabajo vinculada. Puede especificar una variable de entorno en el archivo yaml de implementación como se indica a continuación. Puede encontrar la cadena de conexión de Application Insights en la página Información general de Azure Portal.

environment_variables:
  APPLICATIONINSIGHTS_CONNECTION_STRING: <connection_string>

Nota:

Si solo establece app_insights_enabled: true pero el área de trabajo no tiene una instancia de Application Insights vinculada, la implementación no producirá un error, pero no se recopilarán datos. Si especifica tanto app_insights_enabled: true como la variable de entorno anterior al mismo tiempo, los datos de seguimiento y las métricas se enviarán a la instancia de Application Insights vinculada al área de trabajo. Por lo tanto, si desea especificar otra instancia de Application Insights, solo debe mantener la variable de entorno.

Errores comunes

Problema de tiempo de espera de solicitud ascendente al consumir el punto de conexión

Este error suele deberse a un tiempo de espera. De manera predeterminada, el request_timeout_ms es 5000. Puede especificar un máximo de 5 minutos, que son 300 000 ms. A continuación se muestra cómo especificar el tiempo de espera de la solicitud en el archivo yaml de implementación. Obtenga más información sobre el esquema de implementación aquí.

request_settings:
  request_timeout_ms: 300000

Nota:

El tiempo de espera de 300 000 ms solo funciona para las implementaciones en línea modificadas desde el flujo de solicitud. Debe asegurarse de que ha agregado propiedades para el modelo como se indica a continuación (ya sea la especificación del modelo insertado en la especificación de yaml de implementación o yaml de modelo independiente) para indicar que se trata de una implementación desde el flujo de solicitud.

properties:
  # indicate a deployment from prompt flow
  azureml.promptflow.source_flow_id: <value>

Pasos siguientes