モデルサービングのデバッグガイド

この記事では、モデルサービングエンドポイントを操作するときにユーザーが遭遇する可能性のある一般的な問題のデバッグ手順を示します。 一般的な問題には、エンドポイントの初期化または開始に失敗したときにユーザーが遭遇するエラー、コンテナーに関連するビルド エラー、エンドポイントでのモデルの操作または実行中の問題などがあります。

ログへのアクセスとレビュー

Databricks では、モデルサービングワークロードのデバッグとエラーのトラブルシューティングについてビルドログを確認することをお勧めします。 ログとその表示方法については、「 モデルの品質とエンドポイントの正常性の監視 」を参照してください。

注記

モデル コードで MlflowException エラーが返される場合は、応答コードが 4xx 応答にマップされることを想定してください。 Databricks では、これらのモデル コード エラーは、結果のエラー メッセージに基づいて解決できるため、顧客によるエラーと見なします。 5xx エラーコードは、Databricks に障害がある場合にエラーを伝達するために予約されています。

ワークスペース UI でモデルのイベント ログを確認し、コンテナーのビルド メッセージが成功したかどうかを確認します。 1 時間経ってもビルド メッセージが表示されない場合は、Databricks サポートにお問い合わせください。

ビルドは成功したが、他のエラーが発生した場合は、「 コンテナのビルドが成功した後のデバッグ」を参照してください。 ビルドが失敗した場合は、「 コンテナのビルド失敗後のデバッグ」を参照してください。

インストールされているライブラリパッケージのバージョン

ビルド ログでは、インストールされているパッケージのバージョンを確認できます。

• MLflowバージョンでは、バージョンが指定されていない場合、モデルサービングは最新バージョンを使用します。
• カスタム GPU サービングの場合、モデルサービングは、公開されている PyTorch と Tensorflow のドキュメントに従って、cuda と cuDNN の推奨バージョンをインストールします。

必要な記録済みモデル flash-attn

flash-attnが必要なモデルをログに記録する場合、Databricks では のカスタム ホイール バージョンを使用することをお勧めします flash-attn。そうしないと、 ModuleNotFoundError: No module named 'torch' などのビルド エラーが発生する可能性があります。

flash-attnのカスタムホイールバージョンを使用するには、すべての pip 要件をリストとして指定し、それをパラメーターとして mlflow.transformers.log_model 関数に渡します。また、 flash attnホイールで指定されているCUDAバージョンと互換性のある、PyTorch 、torch、およびtorchvisionのバージョンも指定する必要があります。

たとえば、Databricks では、CUDA 11.8 に次のバージョンとホイールを使用することをお勧めします。

• PyTorch
• Torch 2.0.1+cu118
• Torchvision 0.15.2+cu118
• Flash-Attn

Python

logged_model=mlflow.transformers.log_model(
transformers_model=test_pipeline,
       artifact_path="artifact_path",
       pip_requirements=["--extra-index-url https://download.pytorch.org/whl/cu118", "mlflow==2.13.1", "setuptools<70.0.0", "torch==2.0.1+cu118", "accelerate==0.31.0", "astunparse==1.6.3", "bcrypt==3.2.0", "boto3==1.34.39", "configparser==5.2.0", "defusedxml==0.7.1", "dill==0.3.6", "google-cloud-storage==2.10.0", "ipython==8.15.0", "lz4==4.3.2", "nvidia-ml-py==12.555.43", "optree==0.12.1", "pandas==1.5.3", "pyopenssl==23.2.0", "pytesseract==0.3.10", "scikit-learn==1.3.0", "sentencepiece==0.1.99", "torchvision==0.15.2+cu118", "transformers==4.41.2", "https://github.com/Dao-AILab/flash-attention/releases/download/v2.5.8/flash_attn-2.5.8+cu118torch2.0cxx11abiFALSE-cp311-cp311-linux_x86_64.whl"],
       input_example=input_example,
       registered_model_name=registered_model_name)

モデル展開の検証チェックの前に

Databricks では、モデルを提供する前に、このセクションのガイダンスを適用することをお勧めします。 次のパラメーターは、エンドポイントを待つ前に問題を早期にキャッチできます。 モデルをデプロイする前にモデル入力を検証するには、「 デプロイ前にモデル入力を検証する 」を参照してください。

デプロイ前に予測をテストする

モデルをサービス エンドポイントにデプロイする前に、 mlflow.models.predictと入力例を使用して仮想環境でオフライン予測をテストします。MLflow 、デプロイメント環境をシミュレートし、変更された依存関係のテストを可能にする検証APIsを提供します。

デプロイ前の検証オプションには、 MLflow Python APIとMLflow CLI の2 つがあります。より詳細なガイダンスについては、予測のテストに関する MLflow ドキュメントを参照してください。

次の点を指定できます。

• モデルサービングにデプロイされているモデルのmodel_uri 。

• 次のいずれか一つ。

  • モデルのmlflow.pyfunc.PyFuncModel.predict()呼び出しで想定される形式のinput_data 。
  • input_pathは、 predictの呼び出しに読み込まれて使用される入力データを含むファイルを定義します。

• csvまたはjson形式のcontent_type 。

• 予測をファイルに書き込むためのオプションのoutput_path 。この問題を省略すると、予測はstdoutに出力されます。

• 環境マネージャーenv_managerは、以下を提供するための環境を構築するために使用されます。

  • デフォルトはvirtualenvです。サービング検証に推奨されます。
  • local 利用可能ですが、配信検証でエラーが発生する可能性があります。通常、迅速なデバッグにのみ使用されます。

• install_mlflowを使用して、環境内の現在のバージョンの MLflow を仮想環境にインストールするかどうか。この設定のデフォルトはFalseです。

• トラブルシューティングやデバッグのために、パッケージ依存関係の異なるバージョンを更新してテストするかどうか。オーバーライド引数pip_requirements_overrideを使用して、これを文字列依存関係のオーバーライドまたは追加のリストとして指定できます。

例えば：

Python

import mlflow

run_id = "..."
model_uri = f"runs:/{run_id}/model"

mlflow.models.predict(
  model_uri=model_uri,
  input_data={"col1": 34.2, "col2": 11.2, "col3": "green"},
  content_type="json",
  env_manager="virtualenv",
  install_mlflow=False,
  pip_requirements_override=["pillow==10.3.0", "scipy==1.13.0"],
)

モデルの依存関係を更新する

記録済みモデルで指定された依存関係に問題がある場合は、別のモデルをログに記録しなくても、 MLflow CLIまたはMLflow Python APIのmlflow.models.model.update_model_requirements()を使用して要件を更新できます。

次の例は、記録済みモデルのpip_requirements.txtインプレースで更新する方法を示しています。

指定されたパッケージ バージョンで既存の定義を更新したり、存在しない要件をpip_requirements.txtファイルに追加したりできます。このファイルは、指定されたmodel_uri場所にあるMLflowモデル アーティファクト内にあります。

Python

from mlflow.models.model import update_model_requirements

update_model_requirements(
  model_uri=model_uri,
  operation="add",
  requirement_list=["pillow==10.2.0", "scipy==1.12.0"],
)

デプロイ前にモデルの入力を検証する

モデルサービングエンドポイントは、デプロイ前にモデル入力がサービングエンドポイントで動作することを検証するために、特別な形式の json 入力を想定しています。 MLflow の validate_serving_input を使用して、このような検証を行うことができます。

以下は、モデルが有効な入力例でログに記録されている場合に、実行の [アーティファクト] タブで自動生成されるコードの例です。

Python

from mlflow.models import validate_serving_input

model_uri = 'runs:/<run_id>/<artifact_path>'

serving_payload = """{
 "messages": [
   {
     "content": "How many product categories are there?",
     "role": "user"
   }
 ]
}
"""

# Validate the serving payload works on the model
validate_serving_input(model_uri, serving_payload)

また、convert_input_example_to_serving_input API を使用して有効な JSON サービング入力を生成することにより、記録済みモデルに対して任意の入力例をテストすることもできます。

Python

from mlflow.models import validate_serving_input
from mlflow.models import convert_input_example_to_serving_input

model_uri = 'runs:/<run_id>/<artifact_path>'

# Define INPUT_EXAMPLE with your own input example to the model
# A valid input example is a data instance suitable for pyfunc prediction

serving_payload = convert_input_example_to_serving_input(INPUT_EXAMPLE)

# Validate the serving payload works on the model
validate_serving_input(model_uri, serving_payload)

コンテナのビルドが成功した後のデバッグ

コンテナが正常にビルドされた場合でも、モデルの実行時やエンドポイント自体の操作中に問題が発生する可能性があります。 次のサブセクションでは、一般的な問題と、トラブルシューティングとデバッグの方法について説明します

依存関係がありません

An error occurred while loading the model. No module named <module-name>.のようなエラーが表示される場合があります。このエラーは、依存関係がコンテナーに存在しないことを示している可能性があります。 コンテナのビルドに含める必要があるすべての依存関係を適切に示していることを確認します。 カスタムライブラリに特に注意を払い、 .whl ファイルがアーティファクトとして含まれていることを確認してください。

サービスログのループ

コンテナのビルドが失敗した場合は、サービスログをチェックして、エンドポイントがモデルを読み込もうとしたときにループしているかどうかを確認します。 この動作が見られる場合は、次の手順を試してください。

1. ノートブックを開き、機械学習用のDatabricks Runtimeではなく、Databricks Runtimeバージョンを使用する汎用クラスターにアタッチします。
2. MLflow を使用してモデルを読み込み、そこからデバッグを試みます。

また、モデルをPCにローカルに読み込み、そこからデバッグすることもできます。 以下を使用してモデルをローカルに読み込みます。

Python

import os
import mlflow

os.environ["MLFLOW_TRACKING_URI"] = "databricks://PROFILE"

ARTIFACT_URI = "model_uri"
if '.' in ARTIFACT_URI:
    mlflow.set_registry_uri('databricks-uc')
local_path = mlflow.artifacts.download_artifacts(ARTIFACT_URI)
print(local_path)

conda env create -f local_path/artifact_path/conda.yaml
conda activate mlflow-env

mlflow.pyfunc.load_model(local_path/artifact_path)

要求がエンドポイントに送信されるとモデルが失敗するか、タイムアウトする

モデルで predict() が呼び出されると、Encountered an unexpected error while evaluating the model. Verify that the input is compatible with the model for inference. のようなエラーが表示される場合があります。

predict()関数にコードの問題があります。Databricks では、MLflow からモデルをノートブックに読み込んで呼び出すことをお勧めします。 これにより、 predict() 関数の問題が強調表示され、メソッド内のどこでエラーが発生しているかを確認できます。

失敗した要求の根本原因分析

エンドポイントへのリクエストが失敗した場合は、推論テーブルを使用して根本原因分析を実行できます。推論テーブルは、エンドポイントに対するすべての要求と応答を Unity Catalog テーブルに自動的に記録し、クエリを実行できるようにします。

• 外部モデル、プロビジョニングされたスループットエンドポイント、AI エージェントについては、「 AI Gateway 対応推論テーブルを使用して提供されたモデルを監視する」を参照してください。

• カスタムモデルについては、 モニタリングモデルとデバッグモデルの推論テーブルを参照してください。

推論テーブルをクエリするには:

1. ワークスペースで、 サービング タブに移動し、エンドポイント名を選択します。

2. [ 推論テーブル ] セクションで、推論テーブルの完全修飾名を見つけます。たとえば、 my-catalog.my-schema.my-table.

3. Databricks ノートブックで次のコマンドを実行します。

   Python

   %sql
   SELECT * FROM my-catalog.my-schema.my-table

4. request、response、request_time、status_codeなどの列を表示してフィルタリングし、リクエストを理解し、結果を絞り込みます。

   Python

   %sql
   SELECT * FROM my-catalog.my-schema.my-table
   WHERE status_code != 200

5. AI エージェントのエージェントトレースを有効にした場合は、[ レスポンス ] 列を参照して詳細なトレースを表示します。AI エージェントの推論テーブルを有効にするを参照してください。

ワークスペースがプロビジョニングされた同時実行数を超えています

Workspace exceeded provisioned concurrency quotaエラーが表示される場合があります。

コンカレンシーは、リージョンの可用性に応じて増やすことができます。 Databricks アカウント チームに連絡し、ワークスペース ID を提供して、コンカレンシーの増加をリクエストしてください。

コンテナのビルド失敗後のデバッグ

このセクションでは、ビルドが失敗したときに発生する可能性のある問題について詳しく説明します。

OSError: [Errno 28] No space left on device

No space leftエラーは、モデルと一緒に記録される大きなアーティファクトが不必要に多すぎることが原因である可能性があります。無関係なアーティファクトがモデルと一緒にログに記録されていないことを確認し MLflow 、スリム化されたパッケージを再デプロイしてみてください。

GPU の可用性不足によるビルドの失敗

Build could not start due to an internal error - please contact your Databricks representative. というエラーが表示されるかもしれません。

Databricksアカウントチームに連絡して解決してください。