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 flusso in un endpoint online gestito o in un endpoint online Kubernetes da usare nell'inferenza in tempo reale usando l'interfaccia della riga di comando di Azure Machine Learning v2.

Prima di iniziare, assicurarsi di testare 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 usi studio per creare e gestire endpoint e distribuzioni online, hai bisogno di un'altra autorizzazione, "Microsoft.Resources/deployments/write", da parte del 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 si sviluppa il flusso usando l'interfaccia utente, è possibile scaricare la cartella del flusso dalla pagina dei dettagli del flusso. Se si sviluppa il flusso usando l'interfaccia della riga di comando o l'SDK, la cartella del flusso è già disponibile.

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 o specificare il percorso del modello (da cui caricare i file del modello) inline. Registrare il modello e specificare il nome e la versione del modello nella definizione della distribuzione. Usare il modulo model:<model_name>:<version>.

L'esempio seguente mostra una definizione di 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, specificare i valori seguenti:

• 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, aggiungi una descrizione e tag al tuo endpoint.
• Facoltativamente, aggiungi una descrizione e dei tag all'endpoint.
• Se si vuole eseguire la distribuzione in un cluster Kubernetes (servizio Azure Kubernetes o cluster con abilitazione di Arc) collegato all'area di lavoro, è possibile distribuire il flusso come endpoint online Kubernetes.

Nell'esempio seguente viene illustrata una definizione di endpoint che usa l'identità assegnata dal sistema per impostazione predefinita.

$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, il sistema genera automaticamente un'identità gestita assegnata dal sistema. È anche possibile specificare un'identità gestita assegnata dall'utente esistente per l'endpoint.

Per usare un'identità assegnata dall'utente, specificare gli attributi seguenti nel endpoint.yaml file:

identity:
  type: user_assigned
  user_assigned_identities:
    - resource_id: user_identity_ARM_id_place_holder

Specificare anche Client ID dell'identità assegnata dall'utente in environment_variables nel file deployment.yaml, come mostrato nell'esempio seguente. È possibile trovare Client ID in 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.

Nell'esempio seguente viene illustrata una definizione di distribuzione. 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, 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

Creare un sample-request.json file:

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

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

È anche possibile chiamare l'endpoint usando un client HTTP, ad esempio 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":  []}'

Ottieni la chiave dell'endpoint e l'URI dell'endpoint dall'area di lavoro di Azure Machine Learning in Endpoints>Consumo>Informazioni di base sul consumo.

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 degli ambienti Docker e Azure Machine Learning.

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

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

   • Il requirements.txt file, ereditato dalla cartella del flusso, tiene traccia delle dipendenze del flusso.

   • Oggetto Dockerfile con contenuto simile all'esempio 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 prompt flow 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 fastapi motore di gestione specificando una variabile PROMPTFLOW_SERVING_ENGINEdi ambiente .

environment_variables:
  PROMPTFLOW_SERVING_ENGINE=fastapi

Configurare la concorrenza durante la distribuzione

Quando distribuisci il flusso per la distribuzione online, configura due variabili di ambiente per l'esecuzione concorrente: PROMPTFLOW_WORKER_NUM e PROMPTFLOW_WORKER_THREADS. È anche necessario impostare il max_concurrent_requests_per_instance parametro .

Nell'esempio seguente viene illustrato come configurare queste impostazioni 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 imposta il numero di worker (processi) che vengono avviati in un container. 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 imposta il numero di thread avviati in un worker. Il valore predefinito è 1.

  Nota

  Quando si imposta PROMPTFLOW_WORKER_THREADS su un valore maggiore di 1, assicurarsi che il codice del flusso sia sicuro per quanto riguarda i thread.

• 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. Questa impostazione può migliorare il throughput complessivo consentendo ad alcune richieste di accodarsi sul server.
  • Se si inviano richieste tra aree, è possibile modificare la soglia da 200 ms a 1 s.

Durante l'ottimizzazione di questi parametri, monitorare le metriche seguenti per garantire prestazioni e stabilità ottimali:

• Utilizzo della CPU e della memoria dell'istanza per questa distribuzione
• Risposte non 200 (4xx, 5xx)
  • Se si riceve una risposta 429, questo codice di stato 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

È possibile raccogliere dati di traccia e richiedere metriche specifiche per la distribuzione del flusso (consumo di token, latenza del flusso e altro ancora) 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. Per ulteriori informazioni, vedi tracce e metriche della distribuzione di Prompt Flow.

È possibile specificare metriche e tracce specifiche di prompt flow e inviarle a un'altra istanza di Application Insights anziché a quella collegata 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 si verifica in genere a causa di un timeout. Per impostazione predefinita, il request_timeout_ms valore è 5.000 millisecondi. È possibile configurarlo fino a 5 minuti, ovvero 300.000 millisecondi. Nell'esempio seguente viene illustrato come specificare il timeout della richiesta nel file YAML di distribuzione. Per altre informazioni sullo schema di distribuzione, vedere Schema di distribuzione online gestito.

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.
• Per distribuire una versione migliorata del flusso usando 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.