モデルサービングエンドポイントの管理

この記事では、 Serving UI と REST APIを使用してモデルサービングエンドポイントを管理する方法について説明します。 REST API リファレンスの「エンドポイントの提供」を参照してください。

モデルサービングエンドポイントを作成するには、次のいずれかを使用します。

モデルエンドポイントの状態を取得する

Serving UI では、エンドポイントの詳細ページの上部にある [Serving endpoint state] (サービスエンドポイントの状態 ) インジケータからエンドポイントのステータスを確認できます。

REST API または MLflow Deployments SDK を使用して、エンドポイントの状態と詳細をプログラムで確認します。

REST API
MLflow Deployments SDK

Bash
GET /api/2.0/serving-endpoints/{name}

The following example creates an endpoint that serves the first version of the my-ads-model model that is registered in the Unity Catalog model registry. You must provide the full model name including parent catalog and schema such as, catalog.schema.example-model.

In the following example response, the state.ready field is “READY”, which means the endpoint is ready to receive traffic. The state.update_state field is NOT_UPDATING and pending_config is no longer returned because the update was finished successfully.

JSON
{
  "name": "unity-model-endpoint",
  "creator": "customer@example.com",
  "creation_timestamp": 1666829055000,
  "last_updated_timestamp": 1666829055000,
  "state": {
    "ready": "READY",
    "update_state": "NOT_UPDATING"
  },
  "config": {
    "served_entities": [
      {
        "name": "my-ads-model",
        "entity_name": "myCatalog.mySchema.my-ads-model",
        "entity_version": "1",
        "workload_size": "Small",
        "scale_to_zero_enabled": false,
        "state": {
          "deployment": "DEPLOYMENT_READY",
          "deployment_state_message": ""
        },
        "creator": "customer@example.com",
        "creation_timestamp": 1666829055000
      }
    ],
    "traffic_config": {
      "routes": [
        {
          "served_model_name": "my-ads-model",
          "traffic_percentage": 100
        }
      ]
    },
    "config_version": 1
  },
  "id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "permission_level": "CAN_MANAGE"
}

Python
from mlflow.deployments import get_deploy_client

client = get_deploy_client("databricks")
endpoint = client.get_endpoint(endpoint="chat")
assert endpoint == {
    "name": "chat",
    "creator": "alice@company.com",
    "creation_timestamp": 0,
    "last_updated_timestamp": 0,
    "state": {...},
    "config": {...},
    "tags": [...],
    "id": "88fd3f75a0d24b0380ddc40484d7a31b",
}

Stop a モデルサービング endpoint

モデルサービングエンドポイントを一時的に停止し、後で開始することができます。エンドポイントが停止すると、そのエンドポイントにプロビジョニングされたリソースはシャットダウンされ、エンドポイントは再度開始されるまでクエリを提供できなくなります。停止できるのは、カスタムモデルを提供し、ルート最適化されておらず、進行中の更新がないエンドポイントのみです。停止したエンドポイントは、リソースクォータにカウントされません。停止したエンドポイントに送信されたクエリは 400 エラーを返します。

エンドポイントは 、Serving UI のエンドポイントの詳細ページから停止できます。

停止するエンドポイントをクリックします。
右上隅の [ 停止 ] をクリックします。

または、次のように REST API を使用して、サービスエンドポイントをプログラムで停止することもできます。

Bash
POST /api/2.0/serving-endpoints/{name}/config:stop

停止したモデルサービングエンドポイントを開始する準備ができたら、 サービング UIのエンドポイントの詳細ページから開始できます。

開始するエンドポイントをクリックします。
右上隅の [開始 ] をクリックします。

または、次のように REST API を使用して、停止した配信エンドポイントをプログラムで開始することもできます。

Bash
POST /api/2.0/serving-endpoints/{name}/config:start

モデルサービングエンドポイントの削除

モデルの配信を無効にするには、そのモデルが配信されているエンドポイントを削除します。

エンドポイントは、Serving UI のエンドポイントの詳細ページから削除できます。

サイドバーの 「サービング 」をクリックします。
削除するエンドポイントをクリックします。
上部のケバブメニューをクリックして、[削除] を選択します。

または、REST API または MLflow デプロイ SDK を使用して、プログラムでサービスエンドポイントを削除することもできます

REST API
MLflow Deployments SDK

Bash
DELETE /api/2.0/serving-endpoints/{name}

Python
from mlflow.deployments import get_deploy_client

client = get_deploy_client("databricks")
client.delete_endpoint(endpoint="chat")

モデルサービングエンドポイントのデバッグ

エンドポイントの問題をデバッグするには、次のものを取得します。

モデルサーバーコンテナのビルドログ
サーバーログのモデル化

これらのログには、 エンドポイント UI の [ログ] タブからもアクセスできます。

提供されたモデルの ビルドログ については、次の要求を使用できます。詳細については、モデルサービングのデバッグガイドを参照してください。

Bash

GET /api/2.0/serving-endpoints/{name}/served-models/{served-model-name}/build-logs
{
  “config_version”: 1  // optional
}

サーバモデルの モデルサーバ ログについては、次の要求を使用できます。

Bash

GET /api/2.0/serving-endpoints/{name}/served-models/{served-model-name}/logs

{
  “config_version”: 1  // optional
}

モデルサービングエンドポイントの権限を管理する

権限を変更するには、少なくともサービスエンドポイントに対する CAN MANAGE 権限が必要です。アクセス許可レベルの詳細については、「エンドポイント ACL の提供」を参照してください。

配信エンドポイントのアクセス許可の一覧を取得します。

Bash
databricks permissions get servingendpoints <endpoint-id>

ユーザーに jsmith@example.com 、サービスエンドポイントに対する CAN QUERY 権限を付与します。

Bash
databricks permissions update servingendpoints <endpoint-id> --json '{
  "access_control_list": [
    {
      "user_name": "jsmith@example.com",
      "permission_level": "CAN_QUERY"
    }
  ]
}'

また、Permissions API を使用して、配信エンドポイントのアクセス許可を変更することもできます。

Add a budget ポリシー for a モデルサービング endpoint

備考

プレビュー

この機能はパブリックプレビュー段階であり、外部モデルを提供するエンドポイントの提供には使用できません。

Budget ポリシーを使用すると、組織はサーバレスの使用状況にカスタムタグを適用して、詳細な請求属性を実現できます。ワークスペースで budget ポリシーを使用してサーバレスの使用状況を属性付けしている場合は、モデルサービングエンドポイントに budget ポリシーを追加できます。 Attribute サーバレス usage with budget ポリシーを参照してください。

モデルサービングエンドポイントの作成時に、サービング UI の [Budget policy] (予算ポリシー ) メニューからエンドポイントの予算ポリシーを選択できます。予算ポリシーが割り当てられている場合、[ Budget ポリシー (Budget ポリシー )] メニューからポリシーを選択しない場合でも、作成するすべてのエンドポイントにその予算ポリシーが割り当てられます。

Serving UI を使用して、モデルサービングエンドポイントの作成時に予算ポリシーを追加します。

既存のエンドポイントに対する MANAGE アクセス許可がある場合は、UI の [エンドポイントの詳細 ] ページから、そのエンドポイントの予算ポリシーを編集して追加できます。

既存のモデルサービングエンドポイントで Serving UI を使用して budget ポリシーを編集します。

注記

予算ポリシーが割り当てられている場合、既存のエンドポイントはポリシーで自動的にタグ付けされません。既存のエンドポイントに予算ポリシーをアタッチする場合は、既存のエンドポイントを手動で更新する必要があります。

モデルサービングエンドポイントスキーマを取得する

備考

プレビュー

エンドポイントクエリスキーマの提供のサポートは、パブリックプレビュー段階です。この機能は、モデルサービング地域で使用できます。

サービングエンドポイントクエリスキーマは、JSON 形式の標準 OpenAPI 仕様を使用したサッピングエンドポイントの正式な記述です。これには、エンドポイントのパス、エンドポイントのクエリの詳細 (要求と応答の本文の形式など)、各フィールドのデータ型など、エンドポイントに関する情報が含まれています。この情報は、再現性のシナリオや、エンドポイントに関する情報が必要だが、元のエンドポイントの作成者または所有者ではない場合に便利です。

モデルサービングエンドポイントスキーマを取得するには、提供されるモデルにモデル署名がログに記録され、エンドポイントが READY 状態である必要があります。

次の例は、 REST APIを使用してモデルサービングエンドポイントスキーマをプログラムで取得する方法を示しています。 Feature Servingエンドポイントスキーマについては、「Databricks Feature Servingとは」を参照してください。

API によって返されるスキーマは、OpenAPI 仕様に準拠した JSON オブジェクトの形式です。

Bash

ACCESS_TOKEN="<endpoint-token>"
ENDPOINT_NAME="<endpoint name>"

curl "https://example.databricks.com/api/2.0/serving-endpoints/$ENDPOINT_NAME/openapi" -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json"

スキーマ応答の詳細

応答は JSON 形式の OpenAPI 仕様であり、通常は、 openapi、 info、 servers 、 pathsなどのフィールドが含まれます。スキーマ応答は JSON オブジェクトであるため、一般的なプログラミング言語を使用して解析し、サードパーティのツールを使用して仕様からクライアントコードを生成できます。また、Swagger Editor などのサードパーティツールを使用して OpenAPI 仕様を視覚化することもできます。

応答の主なフィールドは次のとおりです。

info.title フィールドには、サービスエンドポイントの名前が表示されます。
servers フィールドには常に1つのオブジェクトが含まれます。通常は、エンドポイントのベースURLである url フィールドです。
応答の paths オブジェクトには、エンドポイントでサポートされるすべてのパスが含まれています。オブジェクトのキーはパスのURLです。各 path は複数の入力形式をサポートできます。これらの入力は oneOf フィールドに記載されています。

エンドポイントスキーマのレスポンスの例を次に示します。

JSON
{
  "openapi": "3.1.0",
  "info": {
    "title": "example-endpoint",
    "version": "2"
  },
  "servers": [{ "url": "https://example.databricks.com/serving-endpoints/example-endpoint" }],
  "paths": {
    "/served-models/vanilla_simple_model-2/invocations": {
      "post": {
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "type": "object",
                    "properties": {
                      "dataframe_split": {
                        "type": "object",
                        "properties": {
                          "columns": {
                            "description": "required fields: int_col",
                            "type": "array",
                            "items": {
                              "type": "string",
                              "enum": ["int_col", "float_col", "string_col"]
                            }
                          },
                          "data": {
                            "type": "array",
                            "items": {
                              "type": "array",
                              "prefixItems": [
                                {
                                  "type": "integer",
                                  "format": "int64"
                                },
                                {
                                  "type": "number",
                                  "format": "double"
                                },
                                {
                                  "type": "string"
                                }
                              ]
                            }
                          }
                        }
                      },
                      "params": {
                        "type": "object",
                        "properties": {
                          "sentiment": {
                            "type": "number",
                            "format": "double",
                            "default": "0.5"
                          }
                        }
                      }
                    },
                    "examples": [
                      {
                        "columns": ["int_col", "float_col", "string_col"],
                        "data": [
                          [3, 10.4, "abc"],
                          [2, 20.4, "xyz"]
                        ]
                      }
                    ]
                  },
                  {
                    "type": "object",
                    "properties": {
                      "dataframe_records": {
                        "type": "array",
                        "items": {
                          "required": ["int_col", "float_col", "string_col"],
                          "type": "object",
                          "properties": {
                            "int_col": {
                              "type": "integer",
                              "format": "int64"
                            },
                            "float_col": {
                              "type": "number",
                              "format": "double"
                            },
                            "string_col": {
                              "type": "string"
                            },
                            "becx_col": {
                              "type": "object",
                              "format": "unknown"
                            }
                          }
                        }
                      },
                      "params": {
                        "type": "object",
                        "properties": {
                          "sentiment": {
                            "type": "number",
                            "format": "double",
                            "default": "0.5"
                          }
                        }
                      }
                    }
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful operation",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "predictions": {
                      "type": "array",
                      "items": {
                        "type": "number",
                        "format": "double"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

モデル エンドポイントの状態を取得する​

Stop a モデルサービング endpoint​

モデルサービングエンドポイントの削除​

モデルサービングエンドポイントのデバッグ​

モデルサービングエンドポイントの権限を管理する​

Add a budget ポリシー for a モデルサービング endpoint​

モデルサービング エンドポイント スキーマを取得する​

スキーマ応答の詳細​