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 su flujo en un punto de conexión en línea gestionado o un punto de conexión en línea de Kubernetes para su uso en la 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. 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 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 basados en roles de Azure (Azure RBAC) se utilizan para conceder acceso a las operaciones de 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, 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 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 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 solicitar aumentos de cuota, consulte Ver el uso y las cuotas en el portal de Azure.

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 utiliza el flujo de muestra "basic-chat" como ejemplo para su implementación en el punto de conexión administrado en línea de Azure Machine Learning.

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 (desde donde cargar los archivos del modelo) directamente. 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.

$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. 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 del 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 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

$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 siguientes atributos:

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

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

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 la misma 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, debe especificar los siguientes atributos:

Despliegue su endpoint 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

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

Invocar el punto de conexión para puntuar los datos utilizando tu 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 desde el área de trabajo de Azure Machine Learning en Endpoints>Consume>Información básica de consumo.

Configuraciones avanzadas

Desplegar con diferentes conexiones desde el 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: sobrescribir 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 conoce Docker y Azure Machine Learning entornos.

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, utilizada para hacer seguimiento de las dependencias del flujo.

   • El contenido Dockerfile es similar al texto 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 hilos que se iniciarán en un trabajador. 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 del portal de Azure.

environment_variables:
  APPLICATIONINSIGHTS_CONNECTION_STRING: <connection_string>

Errores comunes

Problema de tiempo de espera de solicitud hacia el servidor al consumir el endpoint

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

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 administrados en línea.
• Solución de problemas de implementaciones de flujo de avisos
• Una vez que haya mejorado el flujo y desee implementar la versión mejorada con 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.