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

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

:::tip デバッグ前に検証する 展開に問題がありますか?一般的な問題を発生前に把握するために、展開前の検証から始めます。:::

コンテナビルドをデバッグする

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

ワークスペース UI のイベント ログ ( [イベント] タブをクリック) には、コンテナー ビルドの進行状況に関する情報が含まれています。コンテナのビルドが成功すると、 SERVED_ENTITY_CONTAINER_EVENTイベント タイプとメッセージContainer image creation finished successfullyによって強調表示されます。エンドポイントを作成してから 1 時間経過してもビルド イベントまたはメッセージが表示されない場合は、Databricks サポートに問い合わせてください。

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

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

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

注記

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

依存関係がありません

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

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

モデルで 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 を提供して同時実行性の向上をリクエストしてください。

ワークスペースが並列リクエストの制限を超えました

次の 429 エラーが表示される場合があります: Exceeded max number of parallel requests. Please contact your Databricks representative to increase the limit 。この制限は、並行して送信できるリクエストの最大数に関するワークスペースの制限に達したことを示します。この制限の詳細については、 「モデルサービングの制限と地域」を参照してください。

Databricks では、この制限が削除されたルート最適化エンドポイントに移行することをお勧めします。ルート最適化エンドポイントに移動できない場合は、推論要求を送信するクライアントの数を減らすか、Databricks の担当者に連絡してクォータの増加を依頼してください。

並列リクエストが多すぎます

次の 429 エラーが表示される場合があります: Too many concurrent requests. Consider increasing the provisioned concurrency of the served entity. このエラーは、エンドポイントの現在プロビジョニングされている同時実行性が、着信トラフィックの量を処理できないことを示しています。エンドポイントでオートスケールを有効にしている場合、システムは負荷の増加に対処するために、エンドポイントに設定された制限まで追加の同時実行を自動的にプロビジョニングします。 オートスケールが有効になっていない場合は、プロビジョニングの同時実行数を手動で増やすか、オートスケールを有効にしてトラフィックのスパイクを処理することを検討してください。

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

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

OSError: [Errno 28] No space left on device

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

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

GPU の供給と可用性の制限により、GPU ビルドは次のエラーで失敗する可能性があります: Build could not start due to an internal error - please contact your Databricks representative. 。

解決するには、Databricks アカウント チームに問い合わせてください。リージョンの可用性に応じて、チームはより多くの GPU リソースをプロビジョニングできます。

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

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)