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

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

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

• В этой статье описывается использование интерфейса командной строки.
• Пакет 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 Azure Machine Learning studio, the endpoint Test tab uses this property to identify a 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_variables файла deployment.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 в разделе Конечные точки>Использование>Основные сведения о потреблении.

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

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

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

Например, если файл 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.

Образы среды выполнения Prompt flow заморожены и больше не получают обновлений безопасности или обновлений пакетов. Тег latest в следующем примере не указывает, что изображение получает обновления. Используйте этот пример только для поддержания существующего развертывания во время планирования миграции.

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

|--image_build_with_requirements
  |  |--requirements.txt
  |  |--Dockerfile
  ```
  - The `requirements.txt` file, inherited from the flow folder, tracks the dependencies of the flow. 

  - The `Dockerfile` with content similar to the following example: 

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

1. Replace the environment section in the deployment definition YAML file with the following content:

  ```yaml
  environment: 
    build:
      path: image_build_with_requirements
      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
  ```

### Use FastAPI serving engine (preview)

By default, prompt flow serving uses the Flask serving engine. Starting from prompt flow SDK version 1.10.0, FastAPI-based serving engine is supported. You can use the `fastapi` serving engine by specifying an environment variable `PROMPTFLOW_SERVING_ENGINE`.

```yaml
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/диска/памяти и многое другое).

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

Вы можете собирать данные трассировки и метрики, относящиеся к развертыванию Prompt Flow (потребление токенов, задержка потока и многое другое), во время инференса в Application Insights, связанную с рабочей областью, добавив свойство app_insights_enabled: true в файл YAML развертывания. Дополнительные сведения см. в разделе трассировка и метрики развертывания Prompt flow.

Вы можете указать метрики и трассировку, относящиеся к prompt flow, для другого ресурса 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 и т. д.