Implante um fluxo para o 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 com a CLI do Azure Machine Learning v2.

Antes de começar, certifique-se de ter testado seu fluxo corretamente e sinta-se confiante de que ele está pronto para ser implantado na produção. Para saber mais sobre como testar seu fluxo, consulte Testar seu fluxo. Depois de testar seu fluxo, você aprenderá como criar um endpoint e uma implantação online gerenciados e como usar o endpoint para inferência em tempo real.

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

Pré-requisitos

• A CLI do Azure e a extensão do Azure Machine Learning para a CLI do Azure. Para obter mais informações, consulte Instalar, configurar e usar a CLI (v2).
• Uma área de trabalho do Azure Machine Learning. Se você não tiver um, use as etapas no artigo Guia de início rápido: criar recursos do espaço de trabalho para criar um.
• Os controlos de acesso baseado em funções (RBAC do Azure) são utilizados para conceder acesso às 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 para o espaço de trabalho 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 uma permissão adicional "Microsoft.Resources/deployments/write" do proprietário do grupo de recursos. Para obter mais informações, consulte Gerenciar o acesso a um espaço de trabalho do Azure Machine Learning.

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

Para pontos de extremidade online gerenciados, o Aprendizado de Máquina do Azure reserva 20% de seus recursos de computação 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 obter 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 e quatro núcleos) disponível. Para ver o seu uso e solicitar aumentos de cota, consulte Exibir seu uso e cotas no portal do Azure.

Prepare o fluxo para implantação

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

Este artigo usará o fluxo de exemplo "bate-papo básico" como um exemplo para implantar no ponto de extremidade online gerenciado do Azure Machine Learning.

Definir espaço de trabalho padrão

Use os comandos a seguir para definir o espaço de trabalho padrão e o grupo de recursos 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 o caminho do modelo (de onde carregar os arquivos de modelo) embutido. É recomendável registrar o modelo e especificar o nome e a versão do modelo na definição de implantação. Use o formulário model:<model_name>:<version>.

A seguir está um exemplo de definição de modelo para um fluxo de bate-papo.

$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 em seu espaço de trabalho.

Definir o ponto de extremidade

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

• Nome do ponto de extremidade: O nome do ponto de extremidade. Ele deve ser exclusivo na região do Azure. Para obter mais informações sobre as regras de nomenclatura, consulte Limites de pontos finais.
• Modo de autenticação: O método de autenticação para o ponto de extremidade. Escolha entre a autenticação baseada em chave e a autenticação baseada em token do Azure Machine Learning. 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 seu ponto de extremidade.
• Opcionalmente, você pode adicionar uma descrição e tags ao seu ponto de extremidade.
• Se você quiser implantar em um cluster Kubernetes (cluster habilitado para AKS ou Arc) que está anexado ao seu espaço de trabalho, você pode implantar o fluxo para ser um ponto de extremidade online do Kubernetes.

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

Para obter mais configurações de endpoint, consulte Esquema de ponto de extremidade online gerenciado.

Usar identidade atribuída ao usuário

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

Se desejar usar a identidade atribuída pelo usuário, você pode especificar os seguintes atributos adicionais 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 identidade atribuída pelo Client ID usuário a environment_variables deployment.yaml seguir. Você pode encontrar o Client ID no 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.

A seguir está 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 adicionais:

Implantar seu ponto de extremidade 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 nomeada blue sob o ponto de extremidade, execute o seguinte código:

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

Verificar o status do ponto de extremidade e da implantação

Para verificar o status do ponto de extremidade, 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

Invoque o ponto de extremidade para pontuar dados usando seu modelo

Você pode criar um arquivo 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 seu URI de ponto de extremidade do espaço de trabalho do Azure Machine Learning em Endpoints>Consume>Basic consumption info.

Configurações avançadas

Implante 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 chamada my_connection, você poderá substituí-la adicionando variáveis de ambiente do yaml de implantação, como a seguinte:

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

environment_variables:
  my_connection: <override_connection_name>

Se quiser substituir um campo específico da conexão, você pode substituir adicionando variáveis de ambiente com padrão <connection_name>_<field_name>de nomenclatura. 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 serviço tentará recuperar chat_deployment_name da variável de ambiente 'MY_CONNECTION_CHAT_DEPLOYMENT_NAME' por padrão. 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 mostrará como usar um contexto de compilação do docker para especificar o ambiente para sua implantação, supondo que você tenha conhecimento dos ambientes do Docker e do Azure Machine Learning.

1. Em seu ambiente local, crie uma pasta chamada image_build_with_reqirements contém os seguintes arquivos:

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

   • O requirements.txt deve ser herdado da pasta de fluxo, que foi usada para controlar as dependências do fluxo.

   • O Dockerfile conteúdo é o seguinte:

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

2. Substitua a seção 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 (visualização)

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, o mecanismo de serviço baseado em FastAPI é suportado. Você pode usar fastapi o mecanismo de serviço especificando uma variável PROMPTFLOW_SERVING_ENGINEde ambiente .

environment_variables:
  PROMPTFLOW_SERVING_ENGINE=fastapi

Configurar simultaneidade para implantação

Ao implantar seu fluxo para implantação 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.

Abaixo está 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: Este parâmetro determina o número de trabalhadores (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: Este parâmetro determina o número de threads que serão iniciados em um trabalhador. O valor predefinido é 1.

  Nota

  Ao definir PROMPTFLOW_WORKER_THREADS para um valor maior que 1, verifique se o código de fluxo está seguro para threads.

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

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

  • 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 da CPU/memória da instância desta implantação
• Não-200 respostas (4xx, 5xx)
  • Se você receber uma resposta 429, isso geralmente indica que você precisa reajustar suas configurações de simultaneidade seguindo o guia acima ou dimensionar sua implantação.
• Status do acelerador do Azure OpenAI

Monitorar pontos de extremidade

Coletar métricas gerais

Você pode visualizar métricas gerais de implantação on-line (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 espaço de trabalho adicionando uma propriedade app_insights_enabled: true no arquivo yaml de implantação. Saiba mais sobre rastreamento e métricas de implantação de fluxo de prompt.

Métricas e rastreamento específicos de fluxo de prompt podem ser especificados para 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 da seguinte maneira. Você pode encontrar a cadeia de conexão do seu Application Insights na página Visão geral no portal do Azure.

environment_variables:
  APPLICATIONINSIGHTS_CONNECTION_STRING: <connection_string>

Erros comuns

Problema de tempo limite de solicitação upstream ao consumir o ponto de extremidade

Esse erro geralmente é causado pelo tempo limite. Por padrão, o request_timeout_ms é 5000. Você pode especificar no máximo até 5 minutos, o que é 300.000 ms. A seguir está 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óximos passos

• 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 endpoints online gerenciados.
• Solucione problemas de implantações de fluxo de prompt.
• Depois de melhorar seu fluxo e quiser implantar a versão aprimorada com estratégia de distribuição segura, consulte Distribuição segura para endpoints online.
• Saiba mais sobre fluxos de implantação para outras plataformas, como um serviço de desenvolvimento local, contêiner do Docker, serviço APP do Azure, etc.