Compartilhar via

Implantar fluxo no ponto de extremidade on-line para inferência em tempo real com CLI

  • Artigo

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, verifique se você testou seu fluxo corretamente e se sinta confiante 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 ponto de extremidade e implantação online gerenciados e como usar o ponto de extremidade para inferência em tempo real.

  • Este artigo abordará como usar a experiência da CLI.
  • O SDK do Python não é abordado neste artigo. Em vez disso, confira o notebook 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, confira Instalar o SDK do Python v2 para Azure Machine Learning.

Importante

Os itens marcados (versão prévia) neste artigo estão atualmente em versão prévia pública. A versão prévia é fornecida sem um contrato de nível de serviço e não é recomendada para cargas de trabalho de produção. Alguns recursos podem não ter suporte ou podem ter restrição de recursos. Para obter mais informações, consulte Termos de Uso Complementares de Versões Prévias do Microsoft Azure.

Pré-requisitos

  • A CLI do Azure e a extensão do Azure Machine Learning para a CLI do Azure. Para obter mais informações, confira Instalar, configurar e usar a CLI (v2).
  • Um Workspace 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.
  • O RBAC do Azure (controle de acesso baseado em função) do Azure é usado para permitir acesso a operações no Azure Machine Learning. Para executar as etapas neste artigo, sua conta de usuário deve ser atribuída com a função de proprietário ou colaborador para o workspace do Azure Machine Learning ou uma função personalizada que permita Microsoft.MachineLearningServices/workspaces/onlineEndpoints/*. Se você usar o estúdio 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 acesso a um workspace do Azure Machine Learning.

Observação

O ponto de extremidade online gerenciado dá suporte apenas à rede virtual gerenciada. Se o espaço de trabalho estiver na VNet personalizada, você poderá implantar no ponto de extremidade online do Kubernetes ou implantar em outras plataformas, como o Docker.

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

Para pontos de extremidade online gerenciados, o Azure Machine Learning reserva 20% dos 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 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, você precisa ter uma cota para 48 núcleos (12 instâncias e quatro núcleos) disponíveis. Para exibir o uso e solicitar aumentos de cota, confira Exibir seu uso e cotas no portal do Azure.

Preparar 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, poderá baixar a pasta de fluxo na página de detalhes do fluxo. Se você desenvolveu seu fluxo com a CLI ou o SDK, você já deve ter a pasta de fluxo.

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

Importante

Se você tiver usado additional_includes em seu fluxo, precisará usar pf flow build --source <path-to-flow> --output <output-path> --format docker primeiro para obter uma versão resolvida da pasta de fluxo.

Definir o 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 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 a forma model:<model_name>:<version>.

Confira a seguir um exemplo de definição de modelo para um fluxo de chat.

Observação

Se o fluxo não for um fluxo de chat, você não precisará adicionar properties.

$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 seu workspace.

Definir o ponto de extremidade

Para definir um ponto de extremidade, especifique:

  • Nome do ponto de extremidade: o nome do ponto de extremidade. O valor precisa ser exclusivo na região do Azure. Para obter mais informações sobre as regras de nomenclatura, confira Limites de pontos de extremidade.
  • 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 sim. Para obter mais informações sobre autenticação, confira Autenticação em um ponto de extremidade online. Opcionalmente, você pode adicionar uma descrição e marcas para o ponto de extremidade.
  • Opcionalmente, você pode adicionar uma descrição e marcas para o ponto de extremidade.
  • Se você quiser implantar em um cluster do Kubernetes (cluster habilitado para AKS ou Arc) que está sendo anexado ao workspace, você pode implantar o fluxo para ser um ponto de extremidade online do Kubernetes.

Confira 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
Key Descrição
$schema (Opcional) O esquema YAML. Para ver todas as opções disponíveis no arquivo YAML, você pode visualizar o esquema no exemplo anterior em um navegador.
name O nome do ponto de extremidade.
auth_mode Use key para autenticação baseada em chave. Use aml_token para autenticação baseada em chave do Azure Machine Learning. Para obter um token mais recente, use o comando az ml online-endpoint get-credentials.
property: enforce_access_to_default_secret_stores (versão prévia) – Por padrão, o ponto de extremidade usará a identidade atribuída pelo sistema. Essa propriedade funciona apenas para a identidade atribuída pelo sistema.
– Essa propriedade significa que, se você tiver a permissão de leitor de segredos de conexão, a identidade atribuída pelo sistema do ponto de extremidade será atribuída automaticamente à função Leitor de Segredos de Conexão do Workspace do Azure Machine Learning do workspace, de modo que o ponto de extremidade possa acessar conexões corretamente ao executar a inferência.
– Por padrão, essa propriedade fica "desabilitada".

Se você criar um ponto de extremidade online do Kubernetes, precisará especificar os seguintes atributos adicionais:

Key Descrição
compute O destino de computação do Kubernetes para o qual implantar o ponto de extremidade.

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

Importante

Se o fluxo usar conexões de autenticação baseadas no Microsoft Entra ID, independentemente de usar a identidade atribuída pelo sistema ou pelo usuário, você sempre precisará conceder à identidade gerenciada as funções apropriadas dos recursos correspondentes para que ela possa fazer chamadas à API para esse recurso. Por exemplo, se a conexão do OpenAI do Azure usar a autenticação baseada no Microsoft Entra ID, você precisará conceder à sua identidade gerenciada de ponto de extremidade a função Usuário OpenAI dos Serviços Cognitivos ou Colaborador OpenAI dos Serviços Cognitivos dos recursos correspondentes do OpenAI do Azure.

Use a identidade atribuída pelo usuário

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 atribuída pelo usuário existente para o ponto de extremidade.

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

environment_variables:
  AZURE_CLIENT_ID: <client_id_of_your_user_assigned_identity>

Importante

É necessário conceder as seguintes permissões à identidade atribuída pelo usuário antes de criar o ponto de extremidade para que ele possa acessar os recursos do Azure para realizar a inferência. Saiba mais sobre como conceder permissões para sua identidade do ponto de extremidade.

Escopo Função Por que ele é necessário
Workspace do Azure Machine Learning A função Leitor de Segredos de Conexão do Workspace do Azure Machine Learning OU uma função personalizada com "Microsoft.MachineLearningServices/workspaces/connections/listsecrets/action" Obter conexões do espaço de trabalho
Registro de contêiner do espaço de trabalho Pull de ACR Extração da imagem de contêiner
Armazenamento padrão do espaço de trabalho Leitor de Dados do Blob de Armazenamento Carregar modelo a partir do armazenamento
(Opcional) Workspace do Azure Machine Learning Gravador de métricas do workspace Depois de implantar o ponto de extremidade, se você quiser monitorar as métricas relacionadas ao ponto de extremidade, como utilização de CPU/GPU/Disco/Memória, precisará conceder essa permissão à identidade.

Definir a implantação

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

Veja a seguir um exemplo de definição de implantação, no qual a seção model 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"]'
Atributo Descrição
Nome O nome da implantação.
Nome do ponto de extremidade O nome do ponto de extremidade no qual criar a implantação.
Modelar O modelo a ser usado para a implantação. Esse valor pode ser uma referência a um modelo com versão existente no workspace ou uma especificação de modelo embutida.
Environment Contém os detalhes do ambiente para hospedar o modelo e o código. Ele contém:
- image
- inference_config: é usado para criar um contêiner de serviço para implantações online, incluindo liveness route, readiness_routee scoring_route.
Tipo de instância O tamanho da VM a ser usado para a implantação. Para obter a lista de tamanhos com suporte, confira Lista de SKU de pontos de extremidade online gerenciados.
Contagem de instâncias O número de instâncias a serem usadas para a implantação. Baseie o valor na carga de trabalho esperada. Para alta disponibilidade, recomendamos que você defina o valor mínimo de 3 Reservamos mais 20% para executar atualizações. Para obter mais informações, confira os limites para pontos de extremidade online.
Variáveis de ambiente As seguintes variáveis de ambiente precisam ser definidas para pontos de extremidade implantados de um fluxo:
– (obrigatório) PRT_CONFIG_OVERRIDE: para efetuar pull de conexões do workspace
- (opcional) PROMPTFLOW_RESPONSE_INCLUDED_FIELDS:: quando houver vários campos na resposta, o uso dessa variável env filtrará os campos a serem expostos na resposta.
Por exemplo, se houver duas saídas de fluxo: "answer", "context" e se você quiser apenas ter "answer" na resposta do ponto de extremidade, poderá definir essa variável env como '["answer"]'.

Importante

Se a pasta de fluxo tiver um arquivo requirements.txt que contenha as dependências necessárias para executar o fluxo, você precisará seguir a etapas de implantação com um ambiente personalizado para criar o ambiente personalizado, incluindo as dependências.

Se você criar uma implantação online do Kubernetes, precisará especificar os seguintes atributos adicionais:

Atributo Descrição
Tipo O tipo da implantação. Defina o valor como kubernetes.
Tipo de instância O tipo de instância que você criou no cluster kubernetes a ser usado para a implantação, representa o recurso de computação de solicitação/limite da implantação. Para obter mais detalhes, consulte Criar e gerenciar o tipo de instância.

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

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

Observação

Esta implantação pode levar mais de 15 minutos.

Dica

Se você preferir não bloquear o console da CLI, adicione o sinalizador --no-wait ao comando. No entanto, a exibição interativa do status da implantação será interrompida.

Importante

O sinalizador --all-traffic no az ml online-deployment create acima aloca 100% do tráfego do ponto de extremidade para a implantação azul recém-criada. Embora isso seja útil para fins de desenvolvimento e teste, para produção, talvez você queira abrir o tráfego para a nova implantação por meio de um comando explícito. Por exemplo, az ml online-endpoint update -n $ENDPOINT_NAME --traffic "blue=100".

Verificar o status do ponto de extremidade e a 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

Invocar o ponto de extremidade para pontuar os dados usando o modelo

Crie 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

Também poderá 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":  []}'

É possível obter a chave de ponto de extremidade e o URI de ponto de extremidade do workspace do Azure Machine Learning em Pontos de Extremidade>Consumo>Informações básica 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 chamada 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á substituir 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 nomeadachat_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 referindo-se ao ativo

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

Observação

Você só pode se referir a uma conexão no mesmo workspace.

Implantar com um ambiente personalizado

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

  1. No ambiente local, crie uma pasta chamada image_build_with_reqirements contendo 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 conteúdo do Dockerfile é 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 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 prompt flow usa o mecanismo de serviço FLASK. A partir do SDK de prompt flow versão 1.10.0, há suporte para o mecanismo de serviço baseado em FastAPI. Você pode usar o mecanismo de serviço fastapi especificando uma variável de ambiente PROMPTFLOW_SERVING_ENGINE.

environment_variables:
  PROMPTFLOW_SERVING_ENGINE=fastapi

Configurar a simultaneidade para a implantação

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

Abaixo está um exemplo de como configurar no arquivo deployment.yaml.

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 da CPU, e o valor máximo é o dobro do número de núcleos da CPU.

  • PROMPTFLOW_WORKER_THREADS: esse parâmetro determina o número de threads que serão iniciados em um trabalho. O valor padrão é 1.

    Observação

    Ao definir PROMPTFLOW_WORKER_THREADS como um valor maior que 1, certifique-se de que seu código de fluxo seja 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 sugerido para max_concurrent_requests_per_instance depende do seu tempo de solicitação:

    • Se o tempo da solicitação for superior a 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 dessa implantação
  • Respostas não-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 escalar 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ê também pode coletar dados de rastreamento e métricas específicas de implantação de prompt flow (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 do prompt flow.

As métricas e o rastreamento específicos do prompt flow podem ser especificados para outros Application Insights que não sejam o espaço de trabalho vinculado. Você pode especificar uma variável de ambiente no arquivo yaml de implantação como mostrado a seguir. Você pode localizar sua 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>

Observação

Caso apenas definir app_insights_enabled: true, mas seu espaço de trabalho não tiver um recurso vinculado do Application Insights, a implantação não falhará, mas não haverá coleta de dados. Caso especifique app_insights_enabled: true e a variável de ambiente acima ao mesmo tempo, os dados de rastreamento e as métricas serão enviados ao espaço de trabalho vinculado aos Application Insights. Portanto, se você quiser especificar um Application Insights diferente, só precisará manter a variável de ambiente.

Erros comuns

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

Esse erro geralmente é causado pelo tempo limite. Por padrão, o request_timeout_ms é 5.000. Você pode especificar no máximo até 5 minutos, que é de 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

Observação

O tempo limite de 300.000 ms só funciona para implantações online gerenciadas do fluxo de prompt. Você precisa ter certeza de que adicionou propriedades para o modelo como abaixo (especificação de modelo embutido no yaml de implantação ou yaml de especificação de modelo autônomo) para indicar que essa é uma implantação do fluxo de prompt.

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

Próximas etapas