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

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

Antes de empezar, asegúrese de probar el flujo correctamente y de que esté seguro 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. Consulte el cuaderno de ejemplo 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 Instalar el SDK de Python v2 para Azure Machine Learning.

Requisitos previos

• El CLI de Azure y la extensión Azure Machine Learning al CLI de Azure. Para obtener 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 una, 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 basados en rol de Azure (Azure RBAC) 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 y administrar puntos de conexión e implementaciones en línea, necesita otro permiso "Microsoft. Resources/deployments/write" del propietario del grupo de recursos. Para obtener más información, consulte Administrar el acceso a un área de trabajo de Azure Machine Learning.

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

Para los puntos de conexión en línea administrados, Azure Machine Learning reserva 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 de Standard_DS3_v2 (que viene con cuatro núcleos) en una implementación, debe tener disponible una cuota de 48 núcleos (12 instancias de cuatro núcleos). Para ver su uso y solicitar aumentos de cuota, consulte su uso y sus cuotas en el portal de Azure.

Preparar el flujo para la implementación

Cada flujo tiene una carpeta que contiene códigos, avisos, definición y otros artefactos del flujo. Si desarrolla el flujo mediante la interfaz de usuario, puede descargar la carpeta de flujo desde la página de detalles del flujo. Si desarrolla el flujo mediante la CLI o el SDK, ya tiene la carpeta flow.

En este artículo se utiliza el flujo sample "basic-chat" como ejemplo para implementar en un endpoint en línea administrado de Azure Machine Learning.

Establecimiento 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 el despliegue online, puede hacer referencia a un modelo registrado o especificar directamente la ruta del modelo (desde donde cargar los archivos del modelo). Registre el modelo y especifique el nombre y la versión del modelo en la definición de implementación. Use el formulario model:<model_name>:<version>.

En el ejemplo siguiente se muestra una definición de modelo para un flujo de chat.

$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, especifique los valores siguientes:

• Nombre del punto de conexión: nombre del punto de conexión. Debe ser único en 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 para el punto de conexión. Elija entre la autenticación basada en claves y la autenticación basada en tokens Azure Machine Learning. Una clave no expira, pero un token expira. Para obtener más información sobre la autenticación, consulte Autenticación en un punto de conexión en línea. Opcionalmente, agregue una descripción y etiquetas al punto de conexión.
• Opcionalmente, agregue una descripción y etiquetas al punto de conexión.
• Si desea desplegar en un clúster de Kubernetes (un clúster de AKS o un clúster habilitado para Arc) que adjunte a su espacio de trabajo, puede desplegar el flujo como un punto de conexión en línea de Kubernetes.

En el ejemplo siguiente se muestra una definición de punto de conexión que usa la identidad asignada por el sistema de forma predeterminada.

$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

$schema: https://azuremlschemas.azureedge.net/latest/kubernetesOnlineEndpoint.schema.json
name: basic-chat-endpoint
compute: azureml:<Kubernetes compute name>
auth_mode: key

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

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

Uso de la identidad asignada por el usuario

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

Para usar una identidad asignada por el usuario, especifique los atributos siguientes en el endpoint.yaml archivo:

identity:
  type: user_assigned
  user_assigned_identities:
    - resource_id: user_identity_ARM_id_place_holder

Además, especifique el Client ID de la identidad asignada por el usuario en environment_variables en el archivo deployment.yaml, como se muestra en el ejemplo siguiente. Puede encontrar Client ID en Overview de la identidad administrada en el portal de Azure.

environment_variables:
  AZURE_CLIENT_ID: <client_id_of_your_user_assigned_identity>

Definición de la implementación

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

En el ejemplo siguiente se muestra una definición de implementación. La model sección 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"]'

$schema: https://azuremlschemas.azureedge.net/latest/kubernetesOnlineDeployment.schema.json
name: blue
type: kubernetes
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: <kubernetes custom instance type>
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"]'

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

Despliegue su punto de conexión online a 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 denominada blue en el punto de conexión, ejecute el código siguiente:

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

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

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

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

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

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

Invoca el punto de conexión para analizar los datos mediante tu modelo

Cree un sample-request.json archivo:

{
  "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 llamar al punto de conexión mediante un cliente HTTP, como 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":  []}'

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

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 invalidarlo agregando variables de entorno de yaml de implementación como se indica a continuación:

Opción 1: invalidar el nombre de conexión

environment_variables:
  my_connection: <override_connection_name>

Si desea sobrescribir un campo específico de la conexión, puede hacerlo 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 intenta 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, usa el valor original de la definición de flujo.

Opción 2: anulación haciendo referencia al activo

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

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, suponiendo que tenga conocimientos sobre Los entornos de Docker y Azure Machine Learning.

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

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

   • El requirements.txt archivo, heredado de la carpeta de flujo, realiza un seguimiento de las dependencias del flujo.

   • El Dockerfile con un contenido similar al del ejemplo siguiente:

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

2. Reemplace la sección de entorno del archivo YAML de definición de implementación por el siguiente contenido:

   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 mensajes usa el motor de servicio FLASK. A partir de la versión 1.10.0 del SDK de flujo de mensajes, se admite el motor de servicio basado en FastAPI. Puede usar el fastapi motor de servicio especificando una variable PROMPTFLOW_SERVING_ENGINEde entorno .

environment_variables:
  PROMPTFLOW_SERVING_ENGINE=fastapi

Configuración de la simultaneidad para la implementación

Al implementar el flujo en un despliegue online, configure dos variables de entorno para la concurrencia: PROMPTFLOW_WORKER_NUM y PROMPTFLOW_WORKER_THREADS. También debe establecer el max_concurrent_requests_per_instance parámetro .

En el ejemplo siguiente se muestra cómo configurar estas opciones en el deployment.yaml archivo.

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

• PROMPTFLOW_WORKER_NUM: este parámetro establece el número de trabajos (procesos) que se inician 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 establece el número de subprocesos que se inician en un trabajo. El valor predeterminado es 1.

  Nota

  Cuando se establece 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: 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, configure max_concurrent_requests_per_instance a 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. Esta configuración puede mejorar el rendimiento total al permitir que algunas solicitudes se ponen 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 estos parámetros, supervise las siguientes métricas para garantizar un rendimiento y una estabilidad óptimos:

• Uso de memoria y CPU de instancia para esta implementación
• Respuestas que no sea 200 (4xx, 5xx)
  • Si recibe una respuesta 429, este código de estado suele indicar que necesita volver a configurar 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 las 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

Puede recopilar datos de seguimiento y solicitar métricas específicas de implementación del flujo (consumo de tokens, latencia de flujo, etc.) durante el tiempo de inferencia en el área de trabajo vinculada a Application Insights mediante la adición de una propiedad app_insights_enabled: true en el archivo yaml de implementación. Para obtener más información, consulte trazas y métricas del despliegue de prompt flow.

Puede especificar métricas específicas de flujo de mensajes y seguimiento a otras application Insights en lugar del á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 del portal de Azure.

environment_variables:
  APPLICATIONINSIGHTS_CONNECTION_STRING: <connection_string>

Errores comunes

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

Este error suele producirse debido a un tiempo de espera. De forma predeterminada, el request_timeout_ms valor es de 5000 milisegundos. Puede configurarlo hasta 5 minutos, que es de 300 000 milisegundos. En el ejemplo siguiente se muestra cómo especificar el tiempo de espera de la solicitud en el archivo YAML de implementación. Para obtener más información sobre el esquema de implementación, consulte Esquema de implementación en línea administrado.

request_settings:
  request_timeout_ms: 300000

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

Pasos siguientes

• Obtenga más información sobre el esquema de punto de conexión en línea administrado y el esquema de implementación en línea administrado.
• Obtenga más información sobre cómo probar el punto de conexión en la interfaz de usuario y supervisar el punto de conexión.
• Obtenga más información sobre cómo solucionar problemas de puntos de conexión en línea administrados.
• Solución de problemas de las implementaciones del flujo de solicitud.
• Para implementar una versión mejorada del flujo mediante una estrategia de implementación segura, consulte Implementación segura para puntos de conexión en línea.
• Obtenga más información sobre implementar flujos en otras plataformas, como un servicio de desarrollo local, un contenedor de Docker, Azure app service, etc.