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 em um ponto de extremidade online do Kubernetes para uso em inferência em tempo real usando Azure Machine Learning CLI v2.

Antes de começar, certifique-se de testar seu fluxo corretamente e de que ele está pronto para ser implantado em produção. Para saber mais sobre como testar seu fluxo, confira testar seu fluxo. Depois de testar seu fluxo, você aprenderá como criar um ponto de extremidade online gerenciado e uma implantação, e 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 do artigo Início Rápido: criar recursos de workspace para criar.
• 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 realizar as etapas deste artigo, sua conta de usuário precisa ser atribuída com 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 e gerenciar pontos de extremidade online e implantações, será necessária outra permissão, "Microsoft.Resources/deployments/write", 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 para ceil(1.2 * number of instances requested for deployment) * number of cores for the VM SKU disponível para 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ê desenvolver seu fluxo usando a interface do usuário, poderá baixar a pasta de fluxo na página de detalhes do fluxo. Se você desenvolver seu fluxo usando a CLI ou o SDK, você já terá a pasta de fluxo.

Este artigo usa o fluxo de exemplo "basic-chat" como exemplo de implantação 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 fazer referência a um modelo registrado ou especificar diretamente o caminho para o modelo (de onde os arquivos do modelo serão carregados). Registre o modelo e especifique o nome do modelo e a versão na definição de implantação. Use o formulário model:<model_name>:<version>.

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

Definir o ponto de extremidade

Para definir um ponto de extremidade, especifique os seguintes valores:

• 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, confira Autenticação em um ponto de extremidade online. Opcionalmente, adicione uma descrição e tags ao seu endpoint.
• Opcionalmente, adicione uma descrição e tags ao seu endpoint.
• Se você quiser implantar em um cluster do Kubernetes (AKS ou cluster habilitado para Arc) que anexou ao seu workspace, poderá implantar o fluxo como um endpoint online do Kubernetes.

O exemplo a seguir mostra uma definição de ponto de extremidade que usa a identidade atribuída pelo sistema por padrão.

$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 endpoint online, o sistema gera automaticamente uma identidade gerenciada atribuída pelo sistema. Você também pode especificar uma identidade gerenciada atribuída pelo usuário existente para o ponto de extremidade.

Para usar uma identidade atribuída pelo usuário, especifique os seguintes atributos no endpoint.yaml arquivo:

identity:
  type: user_assigned
  user_assigned_identities:
    - resource_id: user_identity_ARM_id_place_holder

Além disso, especifique também o(a) Client ID da identidade atribuída pelo usuário em environment_variables, no arquivo deployment.yaml, conforme mostrado no exemplo a seguir. Você pode encontrar o Client ID nos Overview da identidade gerenciada no portal do 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.

O exemplo a seguir mostra uma definição de implantação. A model seção refere-se 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, especifique 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

Crie um sample-request.json arquivo:

{
  "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 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 endpoint e o URI do endpoint no workspace do Azure Machine Learning em Endpoints>Consumir>Informações básicas de consumo.

Configurações avançadas

Implantar com conexões diferentes do desenvolvimento de 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 por referência 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 do Docker e Azure Machine Learning ambientes.

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 arquivo, herdado da pasta de fluxo, rastreia as dependências do fluxo.

   • O Dockerfile com conteúdo semelhante ao do exemplo a seguir:

     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 do Prompt Flow usa o mecanismo de serviço FLASK. A partir da versão 1.10.0 do SDK do Prompt Flow, há suporte ao mecanismo de disponibilização baseado em FastAPI. Você pode usar o fastapi mecanismo de serviço especificando uma variável PROMPTFLOW_SERVING_ENGINEde ambiente.

environment_variables:
  PROMPTFLOW_SERVING_ENGINE=fastapi

Configurar a simultaneidade para a implantação

Ao implantar seu fluxo para implantação online, configure duas variáveis de ambiente para concorrência: PROMPTFLOW_WORKER_NUM e PROMPTFLOW_WORKER_THREADS. Você também precisa definir o max_concurrent_requests_per_instance parâmetro.

O exemplo a seguir mostra como definir essas configurações 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 define o número de trabalhos (processos) que começam 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: Este parâmetro define o número de threads iniciadas em um worker. O valor padrão é 1.

  Nota

  Quando você definir PROMPTFLOW_WORKER_THREADS como 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. Essa configuração pode melhorar a taxa de transferência total ao permitir que algumas solicitações fiquem na fila no servidor.
  • Se você estiver enviando solicitações entre regiões, poderá alterar o limite de 200 ms para 1 s.

Ao ajustar esses parâmetros, monitore as seguintes métricas para garantir o desempenho e a estabilidade ideais:

• Utilização de CPU e memória da instância para essa implantação
• Respostas não-200 (4xx, 5xx)
  • Se você receber uma resposta 429, esse código de status normalmente indica que você precisa reajustar suas configurações de simultaneidade seguindo o guia anterior ou dimensionar sua implantação.
• Status da limitação do OpenAI do Azure

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ê pode coletar dados de rastreamento e métricas específicas da implantação do Prompt Flow (consumo de tokens, latência do fluxo e muito mais) durante a inferência no Application Insights vinculado ao workspace adicionando uma propriedade app_insights_enabled: true no arquivo YAML da implantação. Para obter mais informações, consulte rastreamento e métricas da implantação do prompt flow.

Você pode especificar métricas específicas do Prompt Flow e enviar rastreamentos para outros recursos do Application Insights, em vez daquele vinculado ao espaço de trabalho. 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 ao consumir o ponto de extremidade

Esse erro geralmente ocorre por causa de um timeout. Por padrão, o request_timeout_ms valor é 5.000 milissegundos. Você pode configurá-lo até 5 minutos, o que é 300.000 milissegundos. O exemplo a seguir mostra como especificar o tempo limite da solicitação no arquivo YAML de implantação. Para obter mais informações sobre o esquema de implantação, consulte o esquema de implantação online gerenciado.

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 Depurar e solucionar os pontos de extremidade online gerenciados.
• Solucionar problemas de implantações de fluxo de prompts.
• Para implantar uma versão aprimorada do seu fluxo usando uma estratégia de distribuição segura, consulte a distribuição segura para pontos de extremidade 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.