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

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

Antes de começar, certifique-se de que testou corretamente o seu fluxo e sinta-se 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-se a criar endpoints online geridos e implementações, 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 utilizar o Studio para criar/gerir endpoints/implementações online, necessitará 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ção e outros artefactos do fluxo. Se desenvolveu o seu fluxo com a interface de utilizador, pode descarregar a pasta do fluxo a partir da página de detalhes do fluxo. Se desenvolveu o seu fluxo com CLI ou SDK, já deve ter a pasta de fluxo.

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 consultar um modelo registado ou especificar o caminho do modelo (de onde carregar os ficheiros do modelo) inline. Recomenda-se registar o modelo e especificar o nome e a versão do modelo na definição de implementação. Use o formulário model:<model_name>:<version>.

Segue-se um exemplo de 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 endpoint, é necessário especificar:

• 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, pode adicionar uma descrição e tags ao seu endpoint.
• Opcionalmente, pode adicionar uma descrição e tags ao seu endpoint.
• Se quiseres implementar para um cluster Kubernetes (cluster com AKS ou Arc) que se liga ao teu espaço de trabalho, podes implementar o fluxo para ser um endpoint online Kubernetes.

Segue-se um exemplo de definição de endpoint que, por defeito, utiliza identidade atribuída ao 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, uma identidade gerida pelo sistema é gerada automaticamente para si. Também pode especificar uma identidade gerida atribuída pelo utilizador para o endpoint.

Se quiser usar a identidade atribuída pelo utilizador, pode especificar os seguintes atributos no endpoint.yaml:

identity:
  type: user_assigned
  user_assigned_identities:
    - resource_id: user_identity_ARM_id_place_holder

Além disso, também precisa de especificar a Client ID identidade atribuída pelo utilizador sob a environment_variablesdeployment.yaml como se segue. 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.

Segue-se um exemplo de definição de implantação, em que a model secção se refere ao modelo de fluxo 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, precisa de especificar 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

Pode criar um ficheiro sample-request.json assim:

{
  "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 chamá-lo com um cliente HTTP, por exemplo com 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":  []}'

Podes obter a chave do endpoint e o URI do endpoint no espaço de trabalho Azure Machine Learning em Endpoints>Consume>Informação básica de consumo.

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 da tua implementação, assumindo que tens conhecimento dos ambientes Docker e Azure Machine Learning.

1. No seu ambiente local, crie uma pasta com o nome image_build_with_reqirements que contém os seguintes ficheiros:

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

   • A requirements.txt deve ser herdada da pasta de fluxo, que tem sido usada para acompanhar as dependências do fluxo.

   • O Dockerfile conteúdo é semelhante ao seguinte texto:

     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 padrão, o serviço de fluxo de prompts utiliza o motor de serviço FLASK. A partir da versão 1.10.0 do SDK de fluxo de prompts, é suportado um motor de serviço baseado em FastAPI. Pode usar o motor de servir fastapi especificando uma variável de ambiente PROMPTFLOW_SERVING_ENGINE.

environment_variables:
  PROMPTFLOW_SERVING_ENGINE=fastapi

Configurar concorrência para implementação

Quando envia o seu fluxo para implementação online, há duas variáveis de ambiente que configura para operação simultânea: PROMPTFLOW_WORKER_NUM e PROMPTFLOW_WORKER_THREADS. Além disso, também terás de definir o max_concurrent_requests_per_instance parâmetro.

Abaixo está um exemplo de como configurar 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 determina o número de trabalhadores (processos) que serão iniciados 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 determina o número de threads que serão iniciadas num worker. O valor padrão é 1.

  Nota

  Ao definir PROMPTFLOW_WORKER_THREADS para um valor superior a 1, certifique-se de que o seu código de execução é thread-safe.

• 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. Isto pode melhorar o throughput total ao permitir que alguns pedidos sejam colocados 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 acima dos parâmetros, é necessário monitorizar as seguintes métricas para garantir desempenho e estabilidade ótimos:

• Utilização de CPU/Memória de instância desta implementação
• Respostas não-200 (4xx, 5xx)
  • Se receber uma resposta 429, isto normalmente indica que precisa de reajustar as suas definições de concorrência seguindo o guia acima ou escalar a 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

Também pode recolher dados de rastreamento e indicar métricas específicas de implementação de fluxo (consumo de tokens, latência de fluxo, etc.) durante o tempo de inferência para o Application Insights ligado ao workspace, adicionando uma propriedade app_insights_enabled: true no ficheiro yaml de implementação. Saiba mais sobre rastreamento e métricas de implementação rápida de fluxo.

Métricas e rastreamentos específicos do fluxo de prompts podem ser especificados para outros Application Insights além do associado ao workspace. 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 é geralmente causado pelo timeout. O parâmetro request_timeout_ms é, por defeito, 5000. Podes especificar no máximo até 5 minutos, o que corresponde a 300.000 ms. Segue-se um exemplo que mostra como especificar o timeout do pedido no ficheiro yaml de implementação. Saiba mais sobre o esquema de implementação aqui.

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.
• Uma vez que tenha melhorado o seu fluxo e quiser desdobrar a versão melhorada com uma estratégia de lançamento 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.