Wdróż przepływ do punktu końcowego online na potrzeby wnioskowania w czasie rzeczywistym przy użyciu interfejsu wiersza polecenia (CLI)

Z tego artykułu dowiesz się, jak wdrożyć przepływ w zarządzanym punkcie końcowym online lub punkcie końcowym online platformy Kubernetes do użycia w wnioskowaniu w czasie rzeczywistym przy użyciu interfejsu wiersza polecenia platformy Azure Machine Learning w wersji 2.

Przed rozpoczęciem upewnij się, że przepływ jest prawidłowo testowany i upewnij się, że jest gotowy do wdrożenia w środowisku produkcyjnym. Aby dowiedzieć się więcej na temat testowania przepływu, zobacz Testowanie przepływu. Po przetestowaniu przepływu dowiesz się, jak utworzyć zarządzany punkt końcowy online i wdrożenie oraz jak używać punktu końcowego do wnioskowania w czasie rzeczywistym.

• W tym artykule opisano, jak korzystać z doświadczenia CLI.
• Zestaw SDK Python nie został omówiony w tym artykule. Zamiast tego zobacz przykładowy notes GitHub. Aby użyć zestawu SDK Python, musisz mieć zestaw SDK Python w wersji 2 dla Azure Machine Learning. Aby dowiedzieć się więcej, zobacz Install the Python SDK v2 for Azure Machine Learning (Instalowanie zestawu SDK Python w wersji 2 dla Azure Machine Learning.

Wymagania wstępne

• Azure CLI i rozszerzenie Azure Machine Learning do Azure CLI. Aby uzyskać więcej informacji, zobacz Instalowanie, konfigurowanie i używanie interfejsu wiersza polecenia (wersja 2).
• Obszar roboczy Azure Machine Learning. Jeśli go nie masz, wykonaj kroki opisane w artykule Szybki start: tworzenie zasobów obszaru roboczego , aby je utworzyć.
• Azure kontrole dostępu oparte na rolach (Azure RBAC) służą do udzielania dostępu do operacji w Azure Machine Learning. Aby wykonać kroki opisane w tym artykule, konto użytkownika musi mieć przypisaną rolę właściciela lub współautora dla obszaru roboczego Azure Machine Learning lub rolę niestandardową zezwalającą na "Microsoft. MachineLearningServices/workspaces/onlineEndpoints/". Jeśli używasz Studio do tworzenia punktów końcowych online i wdrożeń oraz zarządzania nimi, potrzebujesz dodatkowego uprawnienia „Microsoft.Resources/deployments/write” od właściciela grupy zasobów. Aby uzyskać więcej informacji, zobacz Zarządzanie dostępem do obszaru roboczego Azure Machine Learning.

Alokacja przydziału maszyny wirtualnej na potrzeby wdrożenia

W przypadku zarządzanych punktów końcowych online Azure Machine Learning rezerwuje 20% zasobów obliczeniowych na potrzeby przeprowadzania uaktualnień. W związku z tym, jeśli zażądasz określonej liczby wystąpień we wdrożeniu, musisz mieć limit przydziału ceil(1.2 * number of instances requested for deployment) * number of cores for the VM SKU , aby uniknąć wystąpienia błędu. Jeśli na przykład zażądasz 10 wystąpień maszyny wirtualnej Standard_DS3_v2 (która jest dostarczana z czterema rdzeniami) we wdrożeniu, musisz mieć limit przydziału dla 48 rdzeni (12 wystąpień z czterema rdzeniami). Aby wyświetlić swoje użycie i poprosić o zwiększenie przydziału, zobacz Przeglądaj użycie i limity przydziału w portalu Azure.

Przygotowanie przepływu do wdrożenia

Każdy przepływ ma folder, który zawiera kody, podpowiedzi, definicję i inne artefakty przepływu. Jeśli tworzysz przepływ przy użyciu interfejsu użytkownika, możesz pobrać folder przepływu ze strony szczegółów przepływu. Jeśli tworzysz przepływ przy użyciu interfejsu wiersza polecenia lub zestawu SDK, masz już folder przepływu.

W tym artykule użyto przepływu pracy sample "basic-chat" jako przykład do wdrożenia w zarządzanym punkcie końcowym usługi Azure Machine Learning.

Ustawianie domyślnego obszaru roboczego

Użyj następujących poleceń, aby ustawić domyślny obszar roboczy i grupę zasobów dla interfejsu wiersza polecenia.

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

Rejestrowanie przepływu jako modelu (opcjonalnie)

We wdrożeniu online można albo odwołać się do zarejestrowanego modelu, albo bezpośrednio podać ścieżkę do modelu (skąd przesłać pliki modelu). Zarejestruj model i określ nazwę i wersję modelu w definicji wdrożenia. Użyj formularza model:<model_name>:<version>.

W poniższym przykładzie przedstawiono definicję modelu przepływu czatu.

$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

Użyj polecenia az ml model create --file model.yaml, aby zarejestrować model w twoim obszarze roboczym.

Definiowanie punktu końcowego

Aby zdefiniować punkt końcowy, określ następujące wartości:

• Nazwa punktu końcowego: nazwa punktu końcowego. Musi być unikatowy w regionie Azure. Aby uzyskać więcej informacji na temat reguł nazewnictwa, zobacz Limity punktów końcowych.
• Tryb uwierzytelniania: metoda uwierzytelniania dla punktu końcowego. Wybierz uwierzytelnianie oparte na kluczach i Azure Machine Learning uwierzytelnianie oparte na tokenach. Klucz nie wygasa, ale token wygasa. Aby uzyskać więcej informacji na temat uwierzytelniania, zobacz Uwierzytelnianie w punkcie końcowym online.
• Opcjonalnie dodaj opis i tagi do punktu końcowego.
• Jeśli chcesz wdrożyć do klastra Kubernetes (klastra AKS lub klastra z obsługą usługi Arc), który dołączasz do obszaru roboczego, możesz wdrożyć przepływ jako internetowy punkt końcowy Kubernetes.

W poniższym przykładzie przedstawiono definicję punktu końcowego, która domyślnie używa tożsamości przypisanej przez system.

$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

Jeśli tworzysz punkt końcowy online platformy Kubernetes, musisz określić następujące atrybuty:

Aby uzyskać więcej konfiguracji punktu końcowego, zobacz Zarządzany schemat punktu końcowego online.

Korzystanie z tożsamości przypisanej przez użytkownika

Domyślnie podczas tworzenia punktu końcowego online system automatycznie generuje tożsamość zarządzaną przypisaną przez system. Możesz również określić istniejącą tożsamość zarządzaną przypisaną przez użytkownika dla punktu końcowego.

Aby użyć tożsamości przypisanej przez użytkownika, określ następujące atrybuty w endpoint.yaml pliku:

identity:
  type: user_assigned
  user_assigned_identities:
    - resource_id: user_identity_ARM_id_place_holder

Ponadto określ Client ID tożsamości przypisanej przez użytkownika w obszarze environment_variables w pliku deployment.yaml, jak pokazano w poniższym przykładzie. Element Client ID można znaleźć w elemencie Overview tożsamości zarządzanej w portalu Azure.

environment_variables:
  AZURE_CLIENT_ID: <client_id_of_your_user_assigned_identity>

Definiowanie wdrożenia

Wdrożenie to zestaw zasobów wymaganych do hostowania modelu, który wykonuje rzeczywiste wnioskowanie.

W poniższym przykładzie przedstawiono definicję wdrożenia. Sekcja model dotyczy zarejestrowanego modelu przepływu. Możesz również określić ścieżkę modelu przepływu w wierszu.

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

Jeśli tworzysz wdrożenie online platformy Kubernetes, określ następujące atrybuty:

Wdrażanie punktu końcowego online w Azure

Aby utworzyć punkt końcowy w chmurze, uruchom następujący kod:

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

Aby utworzyć wdrożenie o nazwie blue w punkcie końcowym, uruchom następujący kod:

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

Sprawdzanie stanu punktu końcowego i wdrożenia

Aby sprawdzić stan punktu końcowego, uruchom następujący kod:

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

Aby sprawdzić stan wdrożenia, uruchom następujący kod:

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

Wywoływanie punktu końcowego w celu oceny danych przy użyciu modelu

sample-request.json Utwórz plik:

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

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

Punkt końcowy można również wywołać przy użyciu klienta HTTP, takiego jak 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":  []}'

Pobierz klucz punktu końcowego i adres URI punktu końcowego z obszaru roboczego Azure Machine Learning w sekcji Punkty końcowe>Używanie>Podstawowe informacje o użyciu.

Konfiguracje zaawansowane

Wdrażanie przy użyciu różnych połączeń z programowania przepływów

Podczas wdrażania, możesz chcieć nadpisać połączenia przepływu.

Jeśli na przykład plik flow.dag.yaml używa połączenia o nazwie my_connection, możesz go zastąpić, dodając zmienne środowiskowe pliku yaml wdrożenia w następujący sposób:

Opcja 1: Zastąp nazwę połączenia

environment_variables:
  my_connection: <override_connection_name>

Jeśli chcesz nadpisać określone pole połączenia, możesz to zrobić, dodając zmienne środowiskowe o wzorze nazewnictwa <connection_name>_<field_name>. Jeśli na przykład przepływ używa połączenia o nazwie my_connection z kluczem konfiguracji o nazwie chat_deployment_name, zaplecze obsługujące próbuje domyślnie pobrać chat_deployment_name z zmiennej środowiskowej "MY_CONNECTION_CHAT_DEPLOYMENT_NAME". Jeśli zmienna środowiskowa nie jest ustawiona, używa oryginalnej wartości z definicji przepływu.

Opcja 2: nadpisanie za pomocą odwołania do zasobu

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

Wdrażanie przy użyciu środowiska niestandardowego

W tej sekcji dowiesz się, jak używać kontekstu kompilacji Docker do określenia środowiska wdrożenia, zakładając, że znasz platformę Docker i środowiska Azure Machine Learning.

Obrazy środowiska uruchomieniowego Prompt flow są zamrożone i nie otrzymują już aktualizacji zabezpieczeń ani aktualizacji pakietów oprogramowania. Tag latest w poniższym przykładzie nie wskazuje, że obraz odbiera aktualizacje. Użyj tego przykładu tylko do utrzymania istniejącego wdrożenia podczas planowania migracji.

1. W środowisku lokalnym utwórz folder o nazwie image_build_with_requirements zawierający następujące pliki:

|--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

Konfigurowanie współbieżności na potrzeby wdrożenia

Podczas wdrażania przepływu w trybie online skonfiguruj dwie zmienne środowiskowe dla współbieżności: PROMPTFLOW_WORKER_NUM i PROMPTFLOW_WORKER_THREADS. Należy również ustawić max_concurrent_requests_per_instance parametr .

W poniższym przykładzie pokazano, jak skonfigurować te ustawienia w deployment.yaml pliku.

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

• PROMPTFLOW_WORKER_NUM: Ten parametr określa liczbę procesów roboczych uruchamianych w ramach jednego kontenera. Wartość domyślna jest równa liczbie rdzeni procesora CPU, a maksymalna wartość jest dwukrotnie większa niż liczba rdzeni procesora CPU.

• PROMPTFLOW_WORKER_THREADS: Ten parametr określa liczbę wątków uruchamianych w jednym procesie roboczym. Wartość domyślna to 1.

  Uwaga

  Gdy ustawisz PROMPTFLOW_WORKER_THREADS na wartość większą niż 1, upewnij się, że kod przepływu jest bezpieczny dla wątków.

• max_concurrent_requests_per_instance: maksymalna liczba współbieżnych żądań na wystąpienie dozwolone dla wdrożenia. Wartość domyślna to 10.

  Sugerowana wartość parametru max_concurrent_requests_per_instance zależy od czasu żądania:

  • Jeśli czas żądania jest większy niż 200 ms, ustaw wartość max_concurrent_requests_per_instancePROMPTFLOW_WORKER_NUM * PROMPTFLOW_WORKER_THREADS.
  • Jeśli czas żądania jest krótszy lub równy 200 ms, ustaw wartość max_concurrent_requests_per_instance(1.5-2) * PROMPTFLOW_WORKER_NUM * PROMPTFLOW_WORKER_THREADS. To ustawienie może zwiększyć łączną przepływność, zezwalając niektórym żądaniom na kolejkowanie po stronie serwera.
  • Jeśli wysyłasz żądania między regionami, możesz zmienić próg z 200 ms na 1 s.

Podczas dostrajania tych parametrów monitoruj następujące metryki, aby zapewnić optymalną wydajność i stabilność:

• Wykorzystanie procesora i pamięci wystąpienia dla tego wdrożenia
• Odpowiedzi inne niż 200 (4xx, 5xx)
  • Jeśli otrzymasz odpowiedź 429, ten kod stanu zwykle wskazuje, że należy ponownie dostroić ustawienia współbieżności zgodnie z poprzednim przewodnikiem lub przeskalować wdrożenie.
• Azure stan limitowania usługi OpenAI

Monitorowanie punktów końcowych

Zbieranie ogólnych metryk

Możesz wyświetlić ogólne metryki wdrożenia online (numery żądań, opóźnienie żądań, bajty sieciowe, procesor CPU/procesor GPU/dysk/pamięć itp.).

Zbieranie danych śledzenia i metryk systemowych podczas wnioskowania

Możesz zbierać dane śledzenia oraz metryki specyficzne dla wdrożenia przepływu promptów (zużycie tokenów, opóźnienie przepływu i inne) podczas inferencji w usłudze Application Insights połączonej z obszarem roboczym, dodając właściwość app_insights_enabled: true w pliku YAML wdrożenia. Aby uzyskać więcej informacji, zobacz śledzenie i metryki wdrożenia usługi Prompt Flow.

Możesz określić metryki i ślady specyficzne dla Prompt flow dla innej usługi Application Insights zamiast tej połączonej z obszarem roboczym. Zmienną środowiskową można określić w pliku yaml wdrożenia w następujący sposób. Connection string usługi Application Insights można znaleźć na stronie Przegląd w portalu Azure.

environment_variables:
  APPLICATIONINSIGHTS_CONNECTION_STRING: <connection_string>

Typowe błędy

Problem z przekroczeniem limitu czasu żądania nadrzędnego podczas korzystania z punktu końcowego

Ten błąd zwykle występuje z powodu przekroczenia limitu czasu. Domyślnie wartość parametru request_timeout_ms wynosi 5000 milisekund. Można go skonfigurować do 5 minut, czyli 300 000 milisekund. W poniższym przykładzie pokazano, jak określić limit czasu żądania w pliku YAML wdrożenia. Aby uzyskać więcej informacji na temat schematu wdrażania, zobacz Zarządzany schemat wdrażania online.

request_settings:
  request_timeout_ms: 300000

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

Następne kroki

• Dowiedz się więcej o zarządzanym schemacie punktu końcowego online i zarządzanym schemacie wdrażania online.
• Dowiedz się więcej na temat testowania punktu końcowego w interfejsie użytkownika i monitorowania punktu końcowego.
• Dowiedz się więcej o rozwiązywaniu problemów z zarządzanymi punktami końcowymi online.
• Rozwiązywanie problemów z wdrożeniami przepływu komunikatów.
• Aby wdrożyć ulepszoną wersję przepływu przy użyciu bezpiecznej strategii wdrażania, zobacz Bezpieczne wdrażanie punktów końcowych online.
• Dowiedz się więcej o przepływach wdrażania na innych platformach, takich jak lokalna usługa programistyczna, kontener Docker, usługa Azure App Service itp.