Развертывание потока в онлайн-конечной точке для вывода в режиме реального времени с помощью CLI

В этой статье вы узнаете, как развернуть ваш поток в управляемой веб-конечной точке или онлайн-конечной точке Kubernetes для вывода в режиме реального времени с помощью CLI версии 2 Машинное обучение Azure.

Прежде чем начать, убедитесь, что вы тщательно протестировали свой поток и уверены, что он готов к развертыванию в рабочей среде. Дополнительные сведения о тестировании потока см. в статье "Тестирование потока". После тестирования потока вы узнаете, как создать управляемую конечную точку и развертывание в сети, а также как использовать конечную точку для вывода в режиме реального времени.

• В этой статье описывается использование интерфейса командной строки.
• Пакет SDK Python не рассматривается в этой статье. Вместо этого см. пример записной книжки GitHub. Чтобы использовать пакет SDK Python, необходимо использовать пакет SDK Python версии 2 для Машинное обучение Azure. Дополнительные сведения см. в статье Установка пакета SDK Python версии 2 для Машинное обучение Azure.

Необходимые условия

• CLI Azure и расширение Машинное обучение Azure для CLI Azure. Дополнительные сведения см. в разделе "Установка,настройка" и использование интерфейса командной строки (версия 2).
• Рабочая область Машинное обучение Azure. Если у вас его нет, выполните действия, описанные в статье Краткое руководство: создание ресурсов рабочей области для его создания.
• Ролевое управление доступом Azure (Azure RBAC) используется для предоставления доступа к операциям в Машинное обучение Azure. Чтобы выполнить действия, описанные в этой статье, учетная запись пользователя должна иметь роль владельца или сотрудника для рабочей области Машинное обучение Azure или настраиваемую роль, разрешающую "Microsoft.MachineLearningServices/workspaces/onlineEndpoints/". Если вы используете студию для создания и управления онлайн-конечными точками и развертываниями, вам потребуется другое разрешение "Microsoft.Resources/deployments/write" от владельца группы ресурсов. Дополнительные сведения см. в разделе Манаж доступа к рабочей области Машинное обучение Azure.

Выделение квот виртуальной машины для развертывания

Для управляемых сетевых конечных точек Машинное обучение Azure резервирует 20% вычислительных ресурсов для выполнения обновлений. Таким образом, если вы запрашиваете заданное количество экземпляров в развертывании, у вас должна быть квота для ceil(1.2 * number of instances requested for deployment) * number of cores for the VM SKU, чтобы избежать ошибки. Например, если вы запрашиваете 10 экземпляров виртуальной машины Standard_DS3_v2 (которая поставляется с четырьмя ядрами) в развертывании, у вас должна быть квота на 48 ядер (12 экземпляров четырех ядер). Чтобы просмотреть использование и запросить увеличение квоты, см. Просмотр использования и квот на портале Azure.

Подготовка потока к развертыванию

Каждый поток содержит папку, содержащую коды и запросы, определение и другие артефакты потока. Если вы разработали поток с помощью пользовательского интерфейса, вы можете скачать папку потока на странице сведений о потоке. Если вы разработали поток с помощью ИНТЕРФЕЙСА командной строки или пакета SDK, у вас уже должна быть папка потока.

В этой статье используется пример потока "basic-chat" для развертывания в управляемую сетевую конечную точку Машинное обучение Azure.

Настройка рабочей области по умолчанию

Используйте следующие команды, чтобы задать рабочую область по умолчанию и группу ресурсов для интерфейса командной строки.

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

Регистрация потока в качестве модели (необязательно)

В онлайн-развертывании вы можете либо ссылаться на зарегистрированную модель, либо указать путь к модели (откуда загружать файлы модели). Рекомендуется зарегистрировать модель и указать имя и версию модели в определении развертывания. Используйте форму model:<model_name>:<version>.

Ниже приведен пример определения модели для потока чата.

$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

Используйте az ml model create --file model.yaml, чтобы зарегистрировать модель в рабочей области.

Определение конечной точки

Чтобы определить конечную точку, необходимо указать следующее:

• Endpoint name: название конечной точки. Он должен быть уникальным в регионе Azure. Дополнительные сведения о правилах именования см. в разделе "Ограничения конечной точки".
• Режим проверки подлинности: метод проверки подлинности для конечной точки. Выберите аутентификацию на основе ключей или аутентификацию Машинное обучение Azure на основе токенов. Срок действия ключа не истекает, но срок действия маркера истекает. Дополнительные сведения о проверке подлинности см. в статье "Аутентификация в сети". При необходимости можно добавить описание и теги в конечную точку.
• При необходимости можно добавить описание и теги в конечную точку.
• Если вы хотите развертывать в кластере Kubernetes (кластер с поддержкой AKS или Arc), который подключается к рабочей области, можно развернуть поток как конечную точку онлайн Kubernetes.

Ниже приведен пример определения конечной точки, который по умолчанию использует назначаемое системой удостоверение.

$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

Если вы создаете конечную точку Kubernetes online, необходимо указать следующие атрибуты:

Дополнительные конфигурации конечной точки см. в схеме управляемых сетевых конечных точек.

Использование назначаемого пользователем удостоверения

По умолчанию при создании онлайн-конечной точки для вас автоматически создается управляемое удостоверение, назначаемое системой. Вы также можете указать существующее управляемое удостоверение, назначаемое пользователем для конечной точки.

Если вы хотите использовать пользовательскую назначаемую идентичность, можно указать следующие атрибуты в endpoint.yaml:

identity:
  type: user_assigned
  user_assigned_identities:
    - resource_id: user_identity_ARM_id_place_holder

Кроме того, необходимо также указать Client ID идентификатор, назначаемый пользователем, под environment_variablesdeployment.yaml, как показано ниже. Вы можете найти Client ID в Overview управляемого удостоверения на портале Azure.

environment_variables:
  AZURE_CLIENT_ID: <client_id_of_your_user_assigned_identity>

Определение развертывания

Развертывание — это набор ресурсов, необходимых для размещения модели, которая выполняет фактическое инференсирование.

Ниже приведен пример определения развертывания, в котором model раздел ссылается на зарегистрированную модель потока. Можно также указать путь модели потока в строке.

$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"]'

При создании сетевого развертывания Kubernetes необходимо указать следующие атрибуты:

Развертывание веб-конечной точки в Azure

Чтобы создать конечную точку в облаке, выполните следующий код:

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

Чтобы создать развертывание с именем blue под конечной точкой, выполните следующий код:

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

Проверка состояния конечной точки и развертывания

Чтобы проверить состояние конечной точки, выполните следующий код:

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

Чтобы проверить состояние развертывания, выполните следующий код:

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

Вызов конечной точки для оценки данных с помощью модели

Вы можете создать файл sample-request.json следующим образом:

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

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

Можно также вызвать его с помощью HTTP-клиента, например с помощью 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":  []}'

Ключ конечной точки и URI конечной точки можно получить из рабочей области Машинное обучение Azure в Endpoints>Потребление>Основная информация о потреблении.

Дополнительные конфигурации

Развертывание с различными подключениями от разработки потока

Во время развертывания может потребоваться переопределить подключения потока.

Например, если файл flow.dag.yaml использует соединение с именем my_connection, его можно переопределить, добавив переменные среды для yaml развертывания следующим образом:

Вариант 1: Переопределение имени подключения

environment_variables:
  my_connection: <override_connection_name>

Если вы хотите переопределить определенное поле подключения, можно переопределить, добавив переменные среды с шаблоном <connection_name>_<field_name> именования. Например, если поток использует соединение my_connection с ключом конфигурации, под названием chat_deployment_name, бэкенд сервиса пытается извлечь chat_deployment_name из переменной среды "MY_CONNECTION_CHAT_DEPLOYMENT_NAME" по умолчанию. Если переменная среды не задана, она использует исходное значение из определения потока.

Вариант 2: переопределение путем ссылки на актив

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

Развертывание с помощью пользовательской среды

В этом разделе показано, как использовать контекст сборки Docker для указания среды для развертывания, при условии, что вы знакомы с Docker и средами Машинное обучение Azure.

1. В локальной среде создайте папку с именем image_build_with_reqirements , содержащую следующие файлы:

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

   • requirements.txt должны наследоваться из папки потока, которая использовалась для отслеживания зависимостей потока.

   • Содержимое Dockerfile похоже на следующий текст:

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

2. Замените раздел среды в файле yaml определения развертывания следующим содержимым:

   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
   

Использование обработчика обслуживания FastAPI (предварительная версия)

По умолчанию в потоке подсказок используется движок обслуживания FLASK. Начиная с пакета SDK потока запросов версии 1.10.0, поддерживается подсистема обслуживания на основе FastAPI. Можно использовать движок обслуживания fastapi, указав переменную среды PROMPTFLOW_SERVING_ENGINE.

environment_variables:
  PROMPTFLOW_SERVING_ENGINE=fastapi

Настройка параллелизма для развертывания

При развертывании потока в онлайн-среду существует две переменные среды, которые настраиваются для параллельного выполнения: PROMPTFLOW_WORKER_NUM и PROMPTFLOW_WORKER_THREADS. Кроме того, необходимо также задать max_concurrent_requests_per_instance параметр.

Ниже приведен пример настройки в deployment.yaml файле.

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

• PROMPTFLOW_WORKER_NUM. Этот параметр определяет количество рабочих (процессов), которые будут запущены в одном контейнере. Значение по умолчанию равно числу ядер ЦП, а максимальное значение — в два раза больше ядер ЦП.

• PROMPTFLOW_WORKER_THREADS. Этот параметр определяет количество потоков, которые будут запущены в одном рабочем процессе. Значение по умолчанию — 1.

  Примечание

  Если задать PROMPTFLOW_WORKER_THREADS значение больше 1, убедитесь, что код является потокобезопасным.

• max_concurrent_requests_per_instance. Максимальное количество одновременных запросов на экземпляр, разрешенных для развертывания. Значение по умолчанию — 10.

  Рекомендуемое значение max_concurrent_requests_per_instance зависит от времени запроса:

  • Если время запроса больше 200 мс, установите значение max_concurrent_requests_per_instancePROMPTFLOW_WORKER_NUM * PROMPTFLOW_WORKER_THREADS.
  • Если время запроса меньше или равно 200 мс, установите значение max_concurrent_requests_per_instance(1.5-2) * PROMPTFLOW_WORKER_NUM * PROMPTFLOW_WORKER_THREADS. Это может повысить общую пропускную способность, позволяя некоторым запросам быть в очереди на стороне сервера.
  • Если вы отправляете запросы между регионами, можно изменить пороговое значение с 200 мс на 1.

При настройке указанных выше параметров необходимо отслеживать следующие метрики, чтобы обеспечить оптимальную производительность и стабильность.

• Использование ЦП и памяти экземпляра для этого развертывания
• Ответы, отличные от 200 (4xx, 5xx)
  • Если вы получите ответ 429, обычно это означает, что необходимо повторно настроить параметры параллелизма после приведенного выше руководства или масштабирования развертывания.
• Состояние управления нагрузкой Azure OpenAI

Мониторинг конечных точек

Сбор общих метрик

Вы можете просмотреть общие метрики развертывания в онлайн-среде (количество запросов, задержка запросов, сетевые байты, использование процессора/GPU/диска/памяти и многое другое).

Сбор данных трассировки и системных метрик во время инференса

Вы также можете собирать данные трассировки и метрики развертывания потока запроса (потребление токенов, задержку потока и т. д.) во время выполнения вывода на связанную рабочую область Application Insights, добавив свойство app_insights_enabled: true в файл yaml развертывания. Узнайте больше о трассировках и метриках развертывания потока вызовов.

Специфичные для потока метрики и трассировки могут быть указаны в других Application Insights, отличных от тех, что связаны с рабочей областью. Вы можете указать переменную среды в файле yaml развертывания, как показано ниже. Строку подключения для Application Insights можно найти на странице обзора портала Azure.

environment_variables:
  APPLICATIONINSIGHTS_CONNECTION_STRING: <connection_string>

Распространенные ошибки

Проблема тайм-аута при обращении к конечной точке во время обработки исходящего запроса

Такая ошибка обычно вызвана временем ожидания. По умолчанию request_timeout_ms значение равно 5000. Можно указать не более 5 минут, что составляет 300 000 мс. Ниже показано, как указать время ожидания запроса в yaml-файле развертывания. Дополнительные сведения о схеме развертывания см. здесь.

request_settings:
  request_timeout_ms: 300000

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

Дальнейшие действия

• Дополнительные сведения о схеме управляемой конечной точки в Интернете и схеме управляемого сетевого развертывания.
• Узнайте больше о том, как протестировать конечную точку в пользовательском интерфейсе и отслеживать конечную точку.
• Узнайте больше об устранении неполадок с управляемыми сетевыми конечными точками.
• Устранение неполадок при развертывании потока запросов.
• После улучшения потока и развертывания улучшенной версии с помощью стратегии безопасного развертывания см. раздел "Безопасный выпуск" для сетевых конечных точек.
• Узнайте больше о развёртывании потоков на другие платформы, такие как локальная служба разработки, контейнер Docker, служба приложений Azure и т. д.