Implantar um fluxo no endpoint online para inferência em tempo real com a CLI

Neste artigo, você aprenderá a implantar seu fluxo em um ponto de extremidade online gerenciado ou um ponto de extremidade online Kubernetes para uso em inferência em tempo real com Azure Machine Learning CLI v2.

Antes de começar, verifique se você testou seu fluxo corretamente e tenha certeza de que ele está pronto para ser implantado na produção. Para saber mais sobre como testar seu fluxo, confira testar seu fluxo. Depois de testar seu fluxo, você aprenderá a criar pontos de extremidade e implantações online gerenciados, além de como usar o ponto de extremidade para inferência em tempo real.

• Este artigo aborda como usar a experiência da CLI.
• O SDK do Python não é abordado neste artigo. Consulte o bloco de anotações de exemplo GitHub em vez disso. Para usar o SDK do Python, você deve ter o SDK do Python v2 para Azure Machine Learning. Para saber mais, consulte Instale o SDK do Python v2 para Azure Machine Learning.

Pré-requisitos

• O CLI do Azure e a extensão Azure Machine Learning para o CLI do Azure. Para obter mais informações, consulte Instalar, configurar e usar a CLI (v2).
• Um espaço de trabalho do Azure Machine Learning. Se você não tiver um, use as etapas no artigo Início Rápido: Criar recursos do workspace para criar um.
• Os controles de acesso baseado em função do Azure (Azure RBAC) são usados para conceder acesso a operações no Azure Machine Learning. Para executar as etapas neste artigo, sua conta de usuário deve receber a função de proprietário ou colaborador no workspace do Azure Machine Learning ou uma função personalizada que permita "Microsoft.MachineLearningServices/workspaces/onlineEndpoints/". Se você usar o Studio para criar/gerenciar pontos de extremidade/implantações online, precisará de outra permissão "Microsoft.Resources/implantações/gravação" do proprietário do grupo de recursos. Para obter mais informações, consulte Gerenciar o acesso a um workspace do Azure Machine Learning.

Alocação de cota de máquina virtual para implantação

Para endpoints online gerenciados, o Azure Machine Learning reserva 20% de seus recursos computacionais para executar atualizações. Portanto, se você solicitar um determinado número de instâncias em uma implantação, deverá ter uma cota disponível para ceil(1.2 * number of instances requested for deployment) * number of cores for the VM SKU evitar receber um erro. Por exemplo, se você solicitar 10 instâncias de uma VM Standard_DS3_v2 (que vem com quatro núcleos) em uma implantação, deverá ter uma cota para 48 núcleos (12 instâncias quatro núcleos) disponíveis. Para visualizar seu uso e solicitar aumentos de cota, consulte Visualizar seu uso e quotas no portal do Azure.

Preparar o fluxo para implantação

Cada fluxo tem uma pasta que contém códigos/prompts, definição e outros artefatos do fluxo. Se você desenvolveu seu fluxo com a UI, poderá baixar a pasta do fluxo na página de detalhes. Se você desenvolveu seu fluxo com a CLI ou o SDK, você já deve ter a pasta de fluxo.

Este artigo usa o fluxo de exemplo "basic-chat" como um exemplo para implantar no ponto de extremidade online gerenciado do Azure Machine Learning.

Definir workspace padrão

Use os comandos a seguir para definir o workspace e o grupo de recursos padrão para a CLI.

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

Registrar o fluxo como um modelo (opcional)

Na implantação online, você pode consultar um modelo registrado ou especificar o caminho do modelo (de onde carregar os arquivos do modelo) diretamente. É recomendável registrar o modelo e especificar o nome do modelo e a versão na definição de implantação. Use o formulário model:<model_name>:<version>.

Veja a seguir 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 registrar o modelo no espaço de trabalho.

Definir o ponto de extremidade

Para definir um ponto de extremidade, você precisa especificar:

• Nome do endpoint: o nome do endpoint. Ele deve ser exclusivo na região Azure. Para obter mais informações sobre as regras de nomenclatura, consulte os limites de ponto de extremidade.
• Método de autenticação: o método de autenticação para o endpoint. Escolha entre a autenticação baseada em chave e Azure Machine Learning autenticação baseada em token. Uma chave não expira, mas um token expira. Para obter mais informações sobre autenticação, consulte Autenticar em um ponto de extremidade online. Opcionalmente, você pode adicionar uma descrição e tags ao endpoint.
• Opcionalmente, você pode adicionar uma descrição e tags ao endpoint.
• Se você quiser implantar em um cluster do Kubernetes (cluster habilitado para AKS ou Arc) que está sendo anexado ao seu workspace, você pode implantar o fluxo para ser um endpoint online do Kubernetes.

Veja a seguir um exemplo de definição de ponto de extremidade que, por padrão, usa a 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 você criar um ponto de extremidade online do Kubernetes, precisará especificar os seguintes atributos:

Para obter mais configurações do ponto de extremidade, consulte o esquema de ponto de extremidade online gerenciado.

Usar a identidade atribuída pelo usuário

Por padrão, quando você cria um ponto de extremidade online, uma identidade gerenciada atribuída pelo sistema é gerada automaticamente para você. Você também pode especificar uma identidade gerenciada já existente atribuída pelo usuário para o ponto de extremidade.

Se você quiser usar a identidade atribuída pelo usuário, poderá 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, você também precisa especificar a Client ID da identidade atribuída pelo usuário sob environment_variables o deployment.yaml como segue. Você pode encontrar o Client ID no Overview da identidade gerenciada no portal Azure.

environment_variables:
  AZURE_CLIENT_ID: <client_id_of_your_user_assigned_identity>

Definir a implantação

Uma implantação é um conjunto de recursos necessários para hospedar o modelo que faz a inferência real.

Veja a seguir um exemplo de definição de implantação, no qual a model seção se refere ao modelo de fluxo registrado. Você também pode especificar o caminho do modelo de fluxo na 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 você criar uma implantação online do Kubernetes, precisará especificar os seguintes atributos:

Implantar seu endpoint online no Azure

Para criar o ponto de extremidade na nuvem, execute o seguinte código:

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

Para criar a implantação com o nome blue no endpoint, execute o seguinte código:

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

Verificar o status do endpoint e da implantação

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

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

Para verificar o status da implantação, execute o seguinte código:

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

Invocar o endpoint para pontuar os dados usando seu modelo

Você pode criar um arquivo de sample-request.json como este:

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

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

Você 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":  []}'

Você pode obter sua chave de ponto de extremidade e o URI do ponto de extremidade no workspace do Azure Machine Learning em Endpoints>Consumo>Informações básicas de consumo.

Configurações avançadas

Implantar usando conexões diferentes das utilizadas no desenvolvimento do fluxo

Talvez você queira substituir as conexões do fluxo durante a implantação.

Por exemplo, se o arquivo flow.dag.yaml usar uma conexão nomeada my_connection, você poderá substituí-la adicionando variáveis de ambiente do yaml de implantação da seguinte maneira:

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

environment_variables:
  my_connection: <override_connection_name>

Se você quiser substituir um campo específico da conexão, poderá fazê-lo adicionando variáveis de ambiente com o padrão de nomenclatura <connection_name>_<field_name>. Por exemplo, se o fluxo usar uma conexão nomeada my_connection com uma chave de configuração chamada chat_deployment_name, o back-end de atendimento tentará, por padrão, recuperar chat_deployment_name da variável de ambiente 'MY_CONNECTION_CHAT_DEPLOYMENT_NAME'. Se a variável de ambiente não estiver definida, ela usará o valor original da definição de fluxo.

Opção 2: substituir referindo-se ao ativo

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

Implantar com um ambiente personalizado

Esta seção mostra como usar um contexto de build do Docker para especificar o ambiente para sua implantação, supondo que você tenha conhecimento de ambientes Docker e Azure Machine Learning.

1. Em seu ambiente local, crie uma pasta nomeada image_build_with_reqirements que contenha os seguintes arquivos:

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

   • O requirements.txt deve ser herdado da pasta de fluxo, que foi 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 seção de ambiente no arquivo yaml de definição de implantaçã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 mecanismo de serviço FastAPI (versão prévia)

Por padrão, o serviço de fluxo de prompt usa o mecanismo de serviço FLASK. A partir do SDK de fluxo de prompt versão 1.10.0, há suporte ao motor de atendimento baseado no FastAPI. Você pode usar o fastapi motor de serviço especificando uma variável de ambiente PROMPTFLOW_SERVING_ENGINE.

environment_variables:
  PROMPTFLOW_SERVING_ENGINE=fastapi

Configurar simultaneidade para implantação

Quando você implanta seu fluxo no ambiente online, há duas variáveis de ambiente que você configura para simultaneidade: PROMPTFLOW_WORKER_NUM e PROMPTFLOW_WORKER_THREADS. Além disso, você também precisará definir o max_concurrent_requests_per_instance parâmetro.

Veja abaixo um exemplo de como configurar no deployment.yaml arquivo.

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

• PROMPTFLOW_WORKER_NUM: esse parâmetro determina o número de trabalhos (processos) que serão iniciados em um contêiner. 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: esse parâmetro determina o número de threads que serão iniciados em um worker. O valor padrão é 1.

  Nota

  Ao definir PROMPTFLOW_WORKER_THREADS para um valor maior que 1, verifique se o código de fluxo é thread-safe.

• max_concurrent_requests_per_instance: o número máximo de solicitações simultâneas por instância permitidas para a implantação. O valor padrão é 10.

  O valor max_concurrent_requests_per_instance sugerido depende do tempo de solicitação:

  • Se o tempo de solicitação for maior que 200 ms, defina max_concurrent_requests_per_instance como PROMPTFLOW_WORKER_NUM * PROMPTFLOW_WORKER_THREADS.
  • Se o tempo de solicitação for menor ou igual a 200 ms, defina max_concurrent_requests_per_instance como (1.5-2) * PROMPTFLOW_WORKER_NUM * PROMPTFLOW_WORKER_THREADS. Isso pode melhorar a taxa de transferência total permitindo que algumas solicitações sejam enfileiradas no lado do servidor.
  • Se você estiver enviando solicitações entre regiões, poderá alterar o limite de 200 ms para 1 s.

Ao ajustar os parâmetros acima, você precisa monitorar as seguintes métricas para garantir o desempenho e a estabilidade ideais:

• Utilização de CPU/Memória da instância nesta implantação
• Respostas HTTP diferentes de 200 (4xx, 5xx)
  • Se você receber uma resposta 429, isso normalmente indica que você precisa reajustar suas configurações de simultaneidade seguindo o guia acima ou dimensionar sua implantação.
• Status de limitação do Azure OpenAI

Monitorar pontos de extremidade

Coletar métricas gerais

Você pode exibir métricas gerais de implantação online (números de solicitação, latência de solicitação, bytes de rede, utilização de CPU/GPU/Disco/Memória e muito mais).

Coletar dados de rastreamento e métricas do sistema durante o tempo de inferência

Você também pode coletar dados de rastreamento e métricas específicas de implantação de fluxo de prompt (consumo de token, latência de fluxo etc.) durante o tempo de inferência para o Application Insights vinculado ao workspace adicionando uma propriedade app_insights_enabled: true no arquivo yaml de implantação. Saiba mais sobre métricas e rastreamento na implantação de fluxo de comandos.

As métricas e o rastreamento específicos do fluxo de prompt podem ser especificados em outros Application Insights além do espaço de trabalho vinculado. Você pode especificar uma variável de ambiente no arquivo yaml de implantação como a seguir. Você pode encontrar a cadeia de conexão do Application Insights na página de Visão geral no portal do Azure.

environment_variables:
  APPLICATIONINSIGHTS_CONNECTION_STRING: <connection_string>

Erros comuns

Problema de tempo limite da solicitação upstream no consumo do endpoint

Esse erro geralmente é causado por timeout. Por padrão, o request_timeout_ms valor é 5000. Você pode especificar no máximo 5 minutos, que é 300.000 ms. Veja a seguir um exemplo mostrando como especificar o tempo limite da solicitação no arquivo yaml de implantação. Saiba mais sobre o esquema de implantação aqui.

request_settings:
  request_timeout_ms: 300000

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

Próximas etapas

• Saiba mais sobre o esquema de ponto de extremidade online gerenciado e o esquema de implantação online gerenciado.
• Saiba mais sobre como testar o ponto de extremidade na interface do usuário e monitorar o ponto de extremidade.
• Saiba mais sobre como solucionar problemas de pontos de extremidade online gerenciados.
• Diagnosticar problemas nas implementações de fluxo de prompt.
• Depois de melhorar seu fluxo e desejar implantar a versão aprimorada com uma estratégia de implantação segura, consulte Distribuição segura para endpoints online.
• Saiba mais sobre como implantar fluxos em outras plataformas, como um serviço de desenvolvimento local, contêiner do Docker, serviço de aplicativos do Azure, etc.