Implementar um fluxo num endpoint online para inferência em tempo real usando CLI

Neste artigo, aprende como implementar o seu fluxo para um endpoint online gerido ou para um endpoint online Kubernetes para utilização em inferência em tempo real, utilizando a CLI do Azure Machine Learning v2.

Antes de começar, certifique-se de testar o seu fluxo corretamente e de se sentir confiante de que está pronto para ser implementado em produção. Para saber mais sobre como testar o seu fluxo, veja testar o seu fluxo. Depois de testar o seu fluxo, aprende a criar um endpoint online gerido e a implementação, e a usar o endpoint para inferência em tempo real.

• Este artigo aborda como utilizar a experiência CLI.
• O SDK Python não é abordado neste artigo. Veja o caderno de exemplo do GitHub. Para usar o Python SDK, deve ter o Python SDK v2 para Azure Machine Learning. Para saber mais, consulte Instale o SDK Python v2 para Azure Machine Learning.

Pré-requisitos

• A CLI do Azure e a extensão Azure Machine Learning para a CLI do Azure. Para mais informações, consulte Instalar, configurar e usar a CLI (v2).
• Um espaço de trabalho de Azure Machine Learning. Se não tiver, use os passos do artigo Início Rápido: Criar recursos de espaço de trabalho para criar um.
• Os controlos de acesso baseados em papéis do Azure (Azure RBAC) são usados para conceder acesso a operações no Azure Machine Learning. Para realizar os passos deste artigo, a sua conta de utilizador deve ser atribuída ao papel de proprietário ou colaborador para o espaço de trabalho Azure Machine Learning, ou a um papel personalizado que permita "Microsoft. Serviços de Aprendizagem Automática/espaços de trabalho/Endpoints online/". Se usar o Studio para criar e gerir endpoints e implementações online, necessita de outra permissão, "Microsoft.Resources/deployments/write", concedida pelo proprietário do grupo de recursos. Para mais informações, consulte Gerenciar o acesso a um espaço de trabalho Azure Machine Learning.

Alocação de quotas de máquinas virtuais para implementação

Para endpoints online geridos, Azure Machine Learning reserva 20% dos seus recursos computacionais para realizar atualizações. Portanto, se solicitar um determinado número de instâncias numa implementação, deve ter uma quota para ceil(1.2 * number of instances requested for deployment) * number of cores for the VM SKU disponível para evitar um erro. Por exemplo, se solicitar 10 instâncias de uma VM Standard_DS3_v2 (que vem com quatro núcleos) numa implementação, deverá ter uma quota para 48 núcleos (12 instâncias quatro núcleos) disponíveis. Para ver o seu consumo e aumentar as quotas, consulte Veja o seu uso e quotas no portal Azure.

Prepare o fluxo para a implementação

Cada fluxo tem uma pasta que contém códigos, prompts, definições e outros artefactos do fluxo. Se desenvolveres o teu fluxo usando a interface, podes descarregar a pasta do fluxo a partir da página de detalhes do fluxo. Se desenvolveres o teu flow usando CLI ou SDK, já tens a pasta do flow.

Este artigo utiliza o fluxo exemplo "basic-chat" como exemplo para implementar num endpoint online gerido Azure Machine Learning.

Definir espaço de trabalho padrão

Use os seguintes comandos para definir o espaço de trabalho e o grupo de recursos predefinidos para a linha de comando.

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

Registar o fluxo como modelo (opcional)

Na implementação online, pode referir-se a um modelo registado ou especificar o caminho do modelo (de onde carregar os ficheiros do modelo) em linha. Registe o modelo e especifique o nome e a versão do modelo na definição de implementação. Use o formulário model:<model_name>:<version>.

O exemplo seguinte mostra uma definição de modelo para um fluxo 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 registar o modelo no seu espaço de trabalho.

Defina o ponto final

Para definir um ponto final, especifique os seguintes valores:

• Nome do endpoint: O nome do endpoint. Tem de ser único na região do Azure. Para mais informações sobre as regras de nomenclatura, consulte limites de ponto de extremidade.
• Modo de autenticação: O método de autenticação para o endpoint. Escolha entre autenticação baseada em chaves e autenticação baseada em tokens em Azure Machine Learning. Uma chave não expira, mas um token expira. Para mais informações sobre autenticação, consulte Autenticar para um endpoint online. Opcionalmente, adiciona uma descrição e tags ao teu endpoint.
• Opcionalmente, adiciona uma descrição e tags ao teu endpoint.
• Se pretender implementar num cluster do Kubernetes (AKS ou com o Arc ativado) que associe ao seu espaço de trabalho, pode implementar o fluxo como um ponto final online do Kubernetes.

O exemplo seguinte mostra uma definição de endpoint que usa, por predefinição, uma identidade atribuída pelo 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 criar um endpoint online Kubernetes, precisa de especificar os seguintes atributos:

Para mais configurações de endpoint, consulte esquema de endpoint online gerido.

Use a identidade atribuída pelo utilizador

Por predefinição, quando cria um endpoint online, o sistema gera automaticamente uma identidade gerida atribuída pelo sistema. Também pode especificar uma identidade gerida atribuída pelo utilizador para o endpoint.

Para usar uma identidade atribuída pelo utilizador, especifique os seguintes atributos no endpoint.yaml ficheiro:

identity:
  type: user_assigned
  user_assigned_identities:
    - resource_id: user_identity_ARM_id_place_holder

Além disso, especifique o Client ID da identidade atribuída pelo utilizador em environment_variables no ficheiro deployment.yaml, conforme mostrado no exemplo seguinte. Pode encontrar o Client ID no Overview da identidade gerida no portal do Azure.

environment_variables:
  AZURE_CLIENT_ID: <client_id_of_your_user_assigned_identity>

Defina a implementação

Uma implementação é um conjunto de recursos necessários para alojar o modelo que faz a inferência propriamente dita.

O exemplo seguinte mostra uma definição de implementação. A model secção refere-se ao modelo de escoamento registado. Também pode especificar o percurso do modelo de fluxo em linha.

$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 criar uma implementação online do Kubernetes, especifique os seguintes atributos:

Implemente o seu endpoint online no Azure

Para criar o endpoint na cloud, execute o seguinte código:

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

Para criar a implementação nomeada blue no endpoint, execute o seguinte código:

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

Verificar o estado do endpoint e da implementação

Para verificar o estado do endpoint, execute o seguinte código:

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

Para verificar o estado da implementação, execute o seguinte código:

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

Chama o endpoint para avaliar dados usando o seu modelo

Crie um ficheiro sample-request.json:

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

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

Também pode chamar o endpoint usando um 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":  []}'

Obtenha a chave do ponto final e o URI do ponto final a partir do espaço de trabalho do Azure Machine Learning em Endpoints>Consume>Basic consumption info.

Configurações avançadas

Implementar com diferentes ligações do desenvolvimento de fluxos

Poderás querer sobrepor as ligações do fluxo durante a implementação.

Por exemplo, se o seu ficheiro flow.dag.yaml usar uma ligação chamada my_connection, pode sobrepê-la adicionando variáveis de ambiente do yaml de implementação, como segue:

Opção 1: substituir o nome da ligação

environment_variables:
  my_connection: <override_connection_name>

Se quiseres sobrescrever um campo específico da ligação, podes fazê-lo adicionando variáveis de ambiente com o padrão de nomenclatura <connection_name>_<field_name>. Por exemplo, se o seu fluxo utilizar uma ligação chamada my_connection com uma chave de configuração chamada chat_deployment_name, o servidor backend tenta recuperar chat_deployment_name da variável de ambiente 'MY_CONNECTION_CHAT_DEPLOYMENT_NAME' por defeito. Se a variável de ambiente não estiver definida, utiliza o valor original da definição de fluxo.

Opção 2: sobrescrever ao referir-se a um recurso

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

Implementar com um ambiente personalizado

Esta secção mostra-te como usar um contexto de build Docker para especificar o ambiente para a tua implementação, assumindo que tens conhecimento dos ambientes Docker e Azure Machine Learning.

1. No seu ambiente local, crie uma pasta chamada image_build_with_reqirements que contenha os seguintes ficheiros:

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

   • O requirements.txt ficheiro, herdado da pasta do fluxo, regista as dependências do fluxo.

   • O Dockerfile com conteúdo semelhante ao exemplo seguinte:

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

2. Substitua a secção de ambiente no ficheiro YAML de definição de implementação pelo seguinte conteúdo:

   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
   

Usar o motor de serviço FastAPI (pré-visualização)

Por predefinição, o serviço de prompt flow utiliza o motor de serviço FLASK. A partir da versão 1.10.0 do SDK de fluxo de prompts, é suportado o motor de serviço baseado em FastAPI. Pode usar o fastapi motor de serviço especificando uma variável PROMPTFLOW_SERVING_ENGINEde ambiente .

environment_variables:
  PROMPTFLOW_SERVING_ENGINE=fastapi

Configurar concorrência para implementação

Quando fizer a implementação do seu fluxo numa implementação online, configure duas variáveis de ambiente para concorrência: PROMPTFLOW_WORKER_NUM e PROMPTFLOW_WORKER_THREADS. Também precisas de definir o max_concurrent_requests_per_instance parâmetro.

O exemplo seguinte mostra como configurar estas definições no deployment.yaml ficheiro.

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

• PROMPTFLOW_WORKER_NUM: Este parâmetro define o número de trabalhadores (processos) que começam num contentor. O valor padrão é igual ao número de núcleos de CPU, e o valor máximo é o dobro do número de núcleos de CPU.

• PROMPTFLOW_WORKER_THREADS: Este parâmetro define o número de threads iniciadas por um worker. O valor padrão é 1.

  Nota

  Quando definir PROMPTFLOW_WORKER_THREADS um valor superior a 1, certifique-se de que o seu código de fluxo é seguro para threads.

• max_concurrent_requests_per_instance: O número máximo de pedidos concorrentes por instância permitido para a implementação. O valor padrão é 10.

  O valor sugerido para max_concurrent_requests_per_instance depende do tempo do seu pedido:

  • Se o seu tempo de pedido for superior a 200 ms, defina max_concurrent_requests_per_instance para PROMPTFLOW_WORKER_NUM * PROMPTFLOW_WORKER_THREADS.
  • Se o seu tempo de pedido for inferior ou igual a 200 ms, defina max_concurrent_requests_per_instance para (1.5-2) * PROMPTFLOW_WORKER_NUM * PROMPTFLOW_WORKER_THREADS. Esta configuração pode melhorar o throughput total ao permitir que alguns pedidos entrem em fila do lado do servidor.
  • Se estiveres a enviar pedidos entre regiões, podes alterar o limite de 200 ms para 1 s.

Ao ajustar estes parâmetros, monitorize as seguintes métricas para garantir desempenho e estabilidade ótimos:

• Utilização de CPU e memória de instância para esta implementação
• Respostas não-200 (4xx, 5xx)
  • Se receber um código de resposta 429, este código de estado indica normalmente que precisa de ajustar as suas definições de simultaneidade de acordo com o guia anterior ou aumentar a escala da sua implementação.
• Azure OpenAI estado de limitação

Monitorizar endpoints

Recolha de métricas gerais

Pode consultar métricas gerais de implementação online (números de pedido, latência de pedido, bytes de rede, utilização de CPU/GPU/Disco/Memória e mais).

Recolha de dados de rastreio e métricas do sistema durante o tempo de inferência

Pode recolher dados de rastreio e métricas específicas da implementação do prompt flow (consumo de tokens, latência do fluxo, entre outras) durante a inferência no Application Insights associado ao workspace, adicionando uma propriedade app_insights_enabled: true no ficheiro YAML da implementação. Para mais informações, consulte rastreio e métricas da implementação do prompt flow.

Pode especificar métricas específicas do prompt flow e enviar os rastreios para outras instâncias do Application Insights, em vez da instância associada à área de trabalho. Pode especificar uma variável de ambiente no ficheiro yaml de implementação da seguinte forma. Pode encontrar a cadeia de ligação do seu Application Insights na página de Visão Geral do portal do Azure.

environment_variables:
  APPLICATIONINSIGHTS_CONNECTION_STRING: <connection_string>

Erros comuns

Problema de tempo limite em requisições upstream ao consumir o endpoint

Este erro normalmente acontece devido a um timeout. Por predefinição, o valor de request_timeout_ms é 5 000 milissegundos. Podes configurar para 5 minutos, que são 300.000 milissegundos. O exemplo seguinte mostra como especificar o timeout do pedido no ficheiro YAML de implementação. Para mais informações sobre o esquema de implementação, consulte Esquema de implementação online gerida.

request_settings:
  request_timeout_ms: 300000

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

Próximos passos

• Saiba mais sobre o esquema de endpoint online gerido e o esquema de implementação online gerida.
• Saiba mais sobre como testar o endpoint na UI e monitorizar o endpoint.
• Saiba mais sobre como resolver problemas com endpoints online geridos.
• Solucionar problemas em implementações de fluxo de avisos.
• Para implementar uma versão melhorada do seu fluxo utilizando uma estratégia de implementação segura, consulte Implementação segura para endpoints online.
• Saiba mais sobre o desenvolvimento de fluxos para outras plataformas, como um serviço de desenvolvimento local, contentor Docker, serviço Azure APP, etc.