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

Advertencia

El desarrollo de la función Prompt Flow finalizó el 20 de abril de 2026. La característica se retirará completamente el 20 de abril de 2027. En la fecha de retirada, Prompt Flow entra en modo de solo lectura. Los flujos existentes seguirán funcionando hasta esa fecha.

Recommended action: Migre las cargas de trabajo de Prompt Flow a Microsoft Agent Framework antes del 20 de abril de 2027.

En este artículo, aprenderá a implementar su flujo en un punto de conexión gestionado en línea o un punto de conexión de Kubernetes en línea para realizar inferencias 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é 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.

Importante

Los elementos marcados (versión preliminar) de este artículo se encuentran actualmente en versión preliminar pública. La versión preliminar se proporciona sin un contrato de nivel de servicio y no se recomienda para cargas de trabajo de producción. Es posible que algunas características no se admitan o que tengan funcionalidades restringidas. Para obtener más información, vea Supplemental Terms of Use for Microsoft Azure Previews.

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

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 implementarla en otras plataformas, como Docker.

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 obtener un error. 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 o avisos, definiciones y otros artefactos del flujo. Si ha desarrollado su flujo con la IU, puede descargar la carpeta del flujo desde la página de detalles del flujo. Si ha desarrollado el flujo con la CLI o el SDK, ya debe tener la carpeta del flujo.

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.

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

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

A continuación se muestra un ejemplo de definición de modelo para 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, debe especificar lo siguiente:

  • Nombre del punto de conexión: nombre del punto de conexión. Debe ser único en la región de Azure. Para obtener más información sobre las reglas de nomenclatura, consulte Límites de puntos 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, 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 implementar en un clúster de Kubernetes (habilitado para AKS o Arc) que esté asociado a su área de trabajo, puede implementar el flujo como 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 forma 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) Esquema YAML. Para ver todas las opciones disponibles en el archivo YAML, puede ver el esquema en el 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. Utilice aml_token para la autenticación basada en tokens de Azure Machine Learning. Para obtener el token más reciente, use el az ml online-endpoint get-credentials comando .
property: enforce_access_to_default_secret_stores (versión preliminar) - De forma predeterminada, el punto de conexión usa la identidad asignada por el sistema. Esta propiedad solo funciona para la identidad asignada por el sistema.
- Esta propiedad significa que si tiene permiso de lector de secretos de conexión, la identidad asignada automáticamente por el sistema del punto de conexión se le asigna el rol Lector de secretos de conexión del área de trabajo de Azure Machine Learning, de modo que el punto de conexión pueda acceder correctamente a las conexiones al realizar inferencias.
- De forma predeterminada, la propiedad está deshabilitada.

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

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

Para obtener 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 Azure OpenAI usa autenticación basada en Microsoft Entra ID, debe conceder a la identidad administrada del punto de conexión el rol de Usuario de OpenAI de Cognitive Services o Colaborador de OpenAI de Cognitive Services de los recursos correspondientes de Azure OpenAI.

Uso de la identidad asignada por el usuario

De forma predeterminada, cuando se crea 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 existente para el punto de conexión.

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

identity:
  type: user_assigned
  user_assigned_identities:
    - resource_id: user_identity_ARM_id_place_holder

Además, también debe especificar la Client ID de la identidad asignada por el usuario en environment_variables la deployment.yaml de la siguiente manera. 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 pueda acceder a los recursos de Azure para realizar inferencia. Obtenga más información sobre cómo conceder permisos a la identidad del punto de conexión.

Ámbito Rol Por qué es necesario
área de trabajo de Azure Machine Learning Lector de secretos de conexión del área de trabajo de Azure Machine Learning o un rol personalizado con "Microsoft.MachineLearningServices/workspaces/connections/listsecrets/action" Obtención de conexiones del área de trabajo
Registro de contenedor del área de trabajo Extracción de ACR Imagen de contenedor de extracción
Almacenamiento predeterminado del área de trabajo Lector de datos de Storage Blob Carga del modelo desde el almacenamiento
(Opcional) área de trabajo de Azure Machine Learning 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 uso de CPU, GPU, disco o memoria, debe conceder este permiso a la identidad.

Definición de 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 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"]'
Atributo Descripción
Nombre Nombre de la implementación.
Nombre del punto de conexión Nombre del punto de conexión en el que se va a crear la implementación.
Modelo Modelo que se va a usar para la implementación. Este valor puede ser una referencia a un modelo con versiones existentes 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 compilar un contenedor de servicio para implementaciones en línea, incluidos liveness route, readiness_routey scoring_route .
Tipo de instancia Tamaño de máquina virtual que se va a usar para la implementación. Para obtener la lista de tamaños admitidos, consulte la lista de SKU de extremos en línea administrados.
Conteo de instancias Número de instancias que se van a usar para la implementación. Base el valor en la carga de trabajo que espera. Para lograr una alta disponibilidad, se recomienda establecer el valor en al menos 3. Reservamos un adicional de 20% para realizar actualizaciones. Para obtener más información, consulte límites para los 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 filtra los campos que se van a exponer en la respuesta.
Por ejemplo, si hay dos salidas de flujo: "answer", "context" y si 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 requirements.txt archivo que contiene las dependencias necesarias para ejecutar el flujo, debe seguir los pasos de 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:

Atributo Descripción
Tipo Tipo de la implementación. Establezca el valor en kubernetes.
Tipo de instancia El tipo de instancia que ha creado en su clúster de Kubernetes para utilizar en la implementación representa los recursos computacionales de solicitud/límite de dicha implementación. Para obtener más información, consulte Creación y administración del tipo de instancia.

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

Nota

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

Propina

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

Importante

La --all-traffic marca de la anterior az ml online-deployment create asigna 100% del tráfico del punto de conexión a la implementación azul recién creada. Aunque esto resulta útil para fines de desarrollo y pruebas, para producción, es posible que desee abrir el tráfico a la nueva implementación a través de 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 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

Puede crear un archivo sample-request.json de la siguiente manera:

{
  "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 en el área de trabajo de Azure Machine Learning en Endpoints>Consumo>Información básica de consumo.

Configuraciones avanzadas

Desplegar con diferentes conexiones del desarrollo de flujo

Es posible que desee 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>}}

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, suponiendo que conoce Docker y Azure Machine Learning entornos.

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

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

    • El requirements.txt debe heredarse de la carpeta de flujo, que se ha utilizado para realizar un seguimiento de las dependencias del flujo.

    • El Dockerfile contenido 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 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 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 motor de servicio fastapi especificando una variable de entorno PROMPTFLOW_SERVING_ENGINE.

environment_variables:
  PROMPTFLOW_SERVING_ENGINE=fastapi

Configuración de la simultaneidad para la implementación

Al desplegar tu flujo para la implementación en línea, hay dos variables de entorno que configuras para la concurrencia: 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 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 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 subprocesos 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: 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. Esto 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 los parámetros anteriores, debe supervisar las siguientes métricas para garantizar un rendimiento y una estabilidad óptimos:

  • Uso de CPU/memoria de instancia de esta implementación
  • Respuestas no 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 restricciones 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

También 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 agregando una propiedad app_insights_enabled: true en el archivo yaml de implementación. Obtenga más información sobre el seguimiento y las métricas de la implementación del flujo de ejecución.

Las métricas y el seguimiento específicos del flujo de mensajes 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>

Nota

Si solo establece app_insights_enabled: true, pero su á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 envían a la área de trabajo vinculada a Application Insights. 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. Por defecto, el valor de request_timeout_ms es 5000. Puede especificar un máximo de 5 minutos, que es de 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

Importante

El tiempo de espera de 300,000 ms solo funciona para implementaciones en línea administradas desde Prompt Flow. El máximo para un punto de conexión en línea administrado sin flujo de solicitud instantánea es de 180 segundos.

Debe asegurarse de que ha agregado propiedades para su modelo como se indica a continuación (ya sea mediante la especificación de modelo insertada en el yaml de implementación o especificación del modelo en un yaml independiente) para indicar que se trata de un despliegue desde el flujo de solicitudes.

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

Pasos siguientes

  • Last updated on