Distribuire un workflow all'endpoint online per l'inferenza in tempo reale tramite l'interfaccia della riga di comando

Questo articolo illustra come distribuire il tuo flusso in un endpoint online gestito o in un endpoint Kubernetes online per l'uso nell'inferenza in tempo reale con Azure Machine Learning v2 CLI.

Prima di iniziare, assicurarsi di aver testato correttamente il flusso e assicurarsi che sia pronto per la distribuzione nell'ambiente di produzione. Per altre informazioni sul test del flusso, vedere Testare il flusso. Dopo aver testato il flusso, si apprenderà come creare un endpoint e una distribuzione online gestiti e come usare l'endpoint per l'inferenza in tempo reale.

• Questo articolo illustra come usare l'esperienza dell'interfaccia della riga di comando.
• L'SDK di Python non è trattato in questo articolo. Guarda invece il "notebook" di esempio su GitHub. Per usare Python SDK, è necessario disporre dell'SDK di Python v2 per Azure Machine Learning. Per altre informazioni, vedere Installare Python SDK v2 per Azure Machine Learning.

Prerequisiti

• Il interfaccia della riga di comando di Azure e l'estensione Azure Machine Learning all'interfaccia della riga di comando di Azure. Per altre informazioni, vedere Installare, configurare e usare l'interfaccia della riga di comando (v2).
• Un'area di lavoro Azure Machine Learning. Se non è disponibile, seguire la procedura descritta nell'articolo Avvio rapido: Creare risorse dell'area di lavoro per crearne uno.
• I controlli degli accessi in base al ruolo di Azure vengono usati per concedere l'accesso alle operazioni in Azure Machine Learning. Per eseguire la procedura descritta in questo articolo, all'account utente deve essere assegnato il ruolo di proprietario o collaboratore per l'area di lavoro Azure Machine Learning o un ruolo personalizzato che consenta "Microsoft. MachineLearningServices/workspaces/onlineEndpoints/". Se si usa Studio per creare/gestire endpoint/distribuzioni online, è necessaria un'altra autorizzazione "Microsoft.Resources/deployments/write" richiesta dal proprietario del gruppo di risorse. Per altre informazioni, vedere Gestire l'accesso a un'area di lavoro Azure Machine Learning.

Allocazione della quota di macchine virtuali per la distribuzione

Per gli endpoint online gestiti, Azure Machine Learning riserva 20% delle risorse di calcolo per l'esecuzione degli aggiornamenti. Pertanto, se si richiede un determinato numero di istanze in una distribuzione, è necessario avere una quota per ceil(1.2 * number of instances requested for deployment) * number of cores for the VM SKU per evitare di ottenere un errore. Ad esempio, se si richiedono 10 istanze di una macchina virtuale Standard_DS3_v2 (fornita con quattro core) in una distribuzione, è necessario avere una quota per 48 core (12 istanze quattro core) disponibili. Per visualizzare l'aumento della quota di utilizzo e richiesta, vedere Visualizzare l'utilizzo e le quote nel portale di Azure.

Preparare il flusso per la distribuzione

Ogni flusso ha una cartella che contiene codici/richieste, definizione e altri artefatti del flusso. Se il flusso è stato sviluppato con l'interfaccia utente, è possibile scaricare la cartella del flusso dalla pagina dei dettagli del flusso. Se il flusso è stato sviluppato con l'interfaccia della riga di comando o l'SDK, è necessario avere già la cartella del flusso.

Questo articolo usa il flusso sample "basic-chat" come esempio per distribuire su un endpoint gestito online di Azure Machine Learning.

Impostare l'area di lavoro predefinita

Usare i comandi seguenti per impostare l'area di lavoro e il gruppo di risorse predefiniti per l'interfaccia della riga di comando.

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

Registrare il flusso come modello (facoltativo)

Nella distribuzione online è possibile fare riferimento a un modello registrato oppure specificare il percorso del modello (da cui caricare i file del modello) inline. È consigliabile registrare il modello e specificare il nome e la versione del modello nella definizione di distribuzione. Usare il modulo model:<model_name>:<version>.

Di seguito è riportato un esempio di definizione del modello per un flusso di 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

Usare az ml model create --file model.yaml per registrare il modello nell'area di lavoro.

Definire l'endpoint

Per definire un endpoint, è necessario specificare:

• Nome endpoint: Il nome dell'endpoint. Deve essere univoco nell'area Azure. Per altre informazioni sulle regole di denominazione, vedere limiti degli endpoint.
• Modalità di autenticazione: metodo di autenticazione per l'endpoint. Scegliere tra l'autenticazione basata su chiave e Azure Machine Learning l'autenticazione basata su token. Una chiave non scade, mentre un token sì. Per altre informazioni sull'autenticazione, vedere Eseguire l'autenticazione a un endpoint online. Facoltativamente, è possibile aggiungere una descrizione e tag all'endpoint.
• Facoltativamente, è possibile aggiungere una descrizione e tag all'endpoint.
• Se si vuole eseguire la distribuzione in un cluster Kubernetes (Azure Kubernetes Service (AKS) o cluster con abilitazione Arc) che è collegato alla tua area di lavoro, è possibile distribuire il flusso in un endpoint online Kubernetes.

Di seguito è riportato un esempio di definizione dell'endpoint che per impostazione predefinita usa l'identità assegnata dal 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

Se si crea un endpoint online Kubernetes, è necessario specificare gli attributi seguenti:

Per altre configurazioni dell'endpoint, vedere Schema di endpoint online gestito.

Usare l'identità assegnata dall'utente

Per impostazione predefinita, quando si crea un endpoint online, viene generata automaticamente un'identità gestita assegnata dal sistema. È anche possibile specificare un'identità gestita assegnata dall'utente esistente per l'endpoint.

Se si vuole usare l'identità assegnata dall'utente, è possibile specificare gli attributi seguenti in endpoint.yaml:

identity:
  type: user_assigned
  user_assigned_identities:
    - resource_id: user_identity_ARM_id_place_holder

Inoltre, è necessario specificare il Client ID dell'identità assegnata dall'utente sotto il environment_variables e il deployment.yaml come indicato di seguito. È possibile trovare il Client ID nel Overview dell'identità gestita nel portale di Azure.

environment_variables:
  AZURE_CLIENT_ID: <client_id_of_your_user_assigned_identity>

Definire la distribuzione

Una distribuzione è un set di risorse necessarie per ospitare il modello che esegue l'inferenza effettiva.

Di seguito è riportato un esempio di definizione della distribuzione, in cui la model sezione fa riferimento al modello di flusso registrato. È anche possibile specificare il percorso del modello di flusso in linea.

$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"]'

Se si crea una distribuzione online di Kubernetes, è necessario specificare gli attributi seguenti:

Implementare l'endpoint online in Azure

Per creare l'endpoint nel cloud, eseguire il codice seguente:

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

Per creare la distribuzione denominata blue sotto l'endpoint, eseguire il codice seguente:

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

Controllare lo stato dell'endpoint e della distribuzione

Per controllare lo stato dell'endpoint, eseguire il codice seguente:

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

Per controllare lo stato della distribuzione, eseguire il codice seguente:

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

Richiamare l'endpoint per assegnare un punteggio ai dati usando il modello

È possibile creare un file sample-request.json simile al seguente:

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

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

È anche possibile chiamarlo con un client HTTP, ad esempio 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":  []}'

È possibile ottenere la chiave dell'endpoint e l'URI dell'endpoint dall'area di lavoro Azure Machine Learning in Endpoints>Consume>Informazioni sull'utilizzo di base.

Configurazioni avanzate

Distribuire utilizzando connessioni diverse dallo sviluppo dei flussi

È possibile che si voglia eseguire l'override delle connessioni del flusso durante la distribuzione.

Ad esempio, se il file flow.dag.yaml usa una connessione denominata my_connection, è possibile eseguirne l'override aggiungendo variabili di ambiente dello yaml di distribuzione come segue:

Opzione 1: eseguire l'override del nome della connessione

environment_variables:
  my_connection: <override_connection_name>

Se si vuole eseguire l'override di un campo specifico della connessione, è possibile eseguire l'override aggiungendo variabili di ambiente con il modello <connection_name>_<field_name>di denominazione . Ad esempio, se il flusso usa una connessione denominata my_connection con una chiave di configurazione denominata chat_deployment_name, il back-end di servizio cerca di recuperare chat_deployment_name dalla variabile di ambiente 'MY_CONNECTION_CHAT_DEPLOYMENT_NAME' per impostazione predefinita. Se la variabile di ambiente non è impostata, usa il valore originale dalla definizione del flusso.

Opzione 2: eseguire l'override facendo riferimento all'asset

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

Eseguire la distribuzione con un ambiente personalizzato

Questa sezione illustra come usare un contesto di compilazione Docker per specificare l'ambiente per la distribuzione, presupponendo che si abbia una conoscenza di Docker e Azure Machine Learning ambienti.

1. Nell'ambiente locale creare una cartella denominata image_build_with_reqirements contenente i file seguenti:

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

   • requirements.txt dovrebbe essere ereditato dalla cartella di flusso usata per tenere traccia delle dipendenze del flusso.

   • Il Dockerfile contenuto è simile al testo seguente:

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

2. sostituire la sezione environment nel file yaml di definizione della distribuzione con il contenuto seguente:

   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
   

Usare il motore di gestione FastAPI (anteprima)

Per impostazione predefinita, la gestione del flusso di prompt usa il motore di gestione FLASK. A partire da prompt flow SDK versione 1.10.0, è supportato il motore di gestione basato su FastAPI. È possibile usare il motore di servizio fastapi specificando una variabile di ambiente PROMPTFLOW_SERVING_ENGINE.

environment_variables:
  PROMPTFLOW_SERVING_ENGINE=fastapi

Configurare la concorrenza durante la distribuzione

Quando si distribuisce il flusso per la distribuzione online, sono presenti due variabili di ambiente, che si configurano per la concorrenza: PROMPTFLOW_WORKER_NUM e PROMPTFLOW_WORKER_THREADS. Inoltre, è anche necessario impostare il max_concurrent_requests_per_instance parametro .

Di seguito è riportato un esempio di come configurare nel deployment.yaml file.

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

• PROMPTFLOW_WORKER_NUM: questo parametro determina il numero di worker (processi) che verranno avviati in un unico contenitore. Il valore predefinito è uguale al numero di core CPU e il valore massimo è due volte il numero di core CPU.

• PROMPTFLOW_WORKER_THREADS: questo parametro determina il numero di thread che verranno avviati in un ruolo di lavoro. Il valore predefinito è 1.

  Nota

  Quando si imposta PROMPTFLOW_WORKER_THREADS su un valore maggiore di 1, assicurarsi che il codice di flusso sia thread-safe.

• max_concurrent_requests_per_instance: numero massimo di richieste simultanee per istanza consentite per la distribuzione. Il valore predefinito è 10.

  Il valore suggerito per max_concurrent_requests_per_instance dipende dal tempo della richiesta:

  • Se il tempo della richiesta è maggiore di 200 ms, impostare max_concurrent_requests_per_instance su PROMPTFLOW_WORKER_NUM * PROMPTFLOW_WORKER_THREADS.
  • Se il tempo della richiesta è minore o uguale a 200 ms, impostare su max_concurrent_requests_per_instance(1.5-2) * PROMPTFLOW_WORKER_NUM * PROMPTFLOW_WORKER_THREADS. Ciò può migliorare la velocità effettiva totale consentendo la coda di alcune richieste sul lato server.
  • Se si inviano richieste tra aree, è possibile modificare la soglia da 200 ms a 1 s.

Durante l'ottimizzazione dei parametri precedenti, è necessario monitorare le metriche seguenti per garantire prestazioni e stabilità ottimali:

• Utilizzo CPU/memoria dell'istanza di questa distribuzione
• Risposte non 200 (4xx, 5xx)
  • Se si riceve una risposta 429, questo indica in genere che è necessario ripristinare le impostazioni di concorrenza seguendo la guida precedente o ridimensionare la distribuzione.
• Stato di limitazione di Azure OpenAI

Monitorare gli endpoint

Raccogliere metriche generali

È possibile visualizzare le metriche generali della distribuzione online (numeri di richiesta, latenza delle richieste, byte di rete, UTILIZZO CPU/GPU/disco/memoria e altro ancora).

Raccogliere i dati di traccia e le metriche di sistema durante il tempo di inferenza

È anche possibile raccogliere dati di traccia e richiedere metriche specifiche per la distribuzione del flusso (consumo di token, latenza del flusso e così via) durante il tempo di inferenza nell'area di lavoro collegata ad Application Insights aggiungendo una proprietà app_insights_enabled: true nel file yaml di distribuzione. Maggiori informazioni su tracce e metriche della distribuzione del prompt flow.

Le metriche e la traccia specifiche del flusso dei prompt possono essere specificate in altri Application Insights diversi da quello collegato all'area di lavoro. È possibile specificare una variabile di ambiente nel file yaml di distribuzione come indicato di seguito. È possibile trovare la stringa di connessione di Application Insights nella pagina Panoramica nel portale di Azure.

environment_variables:
  APPLICATIONINSIGHTS_CONNECTION_STRING: <connection_string>

Errori comuni

Problema di timeout della richiesta upstream durante l'utilizzo dell'endpoint

Questo errore è in genere causato dal timeout. Per impostazione predefinita, il valore di request_timeout_ms è 5000. È possibile specificare fino a 5 minuti, ovvero 300.000 ms. Di seguito è riportato un esempio che illustra come specificare il timeout della richiesta nel file yaml di distribuzione. Altre informazioni sullo schema di distribuzione sono disponibili qui.

request_settings:
  request_timeout_ms: 300000

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

Passaggi successivi

• Altre informazioni sullo schema di endpoint online gestito e sullo schema di distribuzione online gestito.
• Altre informazioni su come testare l'endpoint nell'interfaccia utente e monitorare l'endpoint.
• Altre informazioni su come risolvere i problemi relativi agli endpoint online gestiti.
• Risolvere i problemi relativi alle distribuzioni del prompt flow.
• Dopo aver migliorato il flusso e si vuole distribuire la versione migliorata con una strategia di implementazione sicura, vedere Implementazione sicura per gli endpoint online.
• Scopri di più sui flussi di deploy su altre piattaforme, ad esempio un servizio di sviluppo locale, un contenitore Docker, un servizio APP di Azure e così via.