モデル提供エンドポイントを管理する

  • [アーティクル]

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

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

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

Serving UI では、エンドポイントの詳細ページの上部にある [提供エンドポイントの状態] インジケーターからエンドポイントの状態を確認できます。

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

REST API

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

次の例では、モデル レジストリに登録されている ads1 モデルの最初のバージョンを提供するエンドポイントの詳細を取得します。 Unity Catalog からモデルを指定するには、catalog.schema.example-model などの親カタログとスキーマを含む完全なモデル名を指定します。

次の応答例では、state.ready フィールドは “READY” です。つまり、エンドポイントはトラフィックを受信する準備ができています。 state.update_state フィールドは NOT_UPDATING であり、更新が正常に完了したため、pending_config は返されなくなりました。

{
  "name": "workspace-model-endpoint",
  "creator": "customer@example.com",
  "creation_timestamp": 1666829055000,
  "last_updated_timestamp": 1666829055000,
  "state": {
    "ready": "READY",
    "update_state": "NOT_UPDATING"
  },
  "config": {
    "served_entities": [
      {
        "name": "ads1-1",
        "entity_name": "ads1",
        "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": "ads1-1",
          "traffic_percentage": 100
        }
      ]
    },
    "config_version": 1
  },
  "id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "permission_level": "CAN_MANAGE"
}

MLflow デプロイ SDK

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",
}

モデル提供エンドポイントを停止する

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

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

  1. 停止を実行するエンドポイントをクリックします。
  2. 右上隅にある [停止] をクリックします。

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

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

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

  1. 開始を実行するエンドポイントをクリックします。
  2. 右上隅にある [開始] をクリックします。

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

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

モデル提供エンドポイントを削除する

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

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

  1. サイドバーの [Serving] をクリックします。
  2. 削除したいエンドポイントをクリックします。
  3. 上部のケバブ メニューをクリックして [削除] を選択します。

または、REST API または MLflow デプロイ SDK を使用して、提供エンドポイントをプログラムで削除できます

REST API

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

MLflow デプロイ SDK

from mlflow.deployments import get_deploy_client

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

モデル提供エンドポイントをデバッグする

エンドポイントに関する何らかの問題をデバッグするには、次をフェッチします。

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

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

提供されたモデルのビルド ログには、次の要求を使用できます。


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

提供されたモデルのモデル サーバー ログには、次の要求を使用できます。


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

{
  “config_version”: 1  // optional
}

モデル サービス エンドポイントに対するアクセス許可を管理する

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

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

databricks permissions get servingendpoints <endpoint-id>

ユーザー jsmith@example.com に、提供エンドポイントに対するクエリ可能アクセス許可を許可します。

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

Permissions API を使って、提供エンドポイントのアクセス許可を変更することもできます。

モデル提供エンドポイント スキーマを取得する

重要

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

サービス エンドポイント クエリ スキーマは、標準の OpenAPI 仕様を JSON 形式で使用したサービス エンドポイントの正式な説明です。 これには、エンドポイント パス、要求と応答本文の形式などのエンドポイントのクエリの詳細、各フィールドのデータ型など、エンドポイントに関する情報が含まれます。 この情報は、再現性のシナリオや、エンドポイントに関する情報が必要な場合に役立ちますが、お客様は元のエンドポイント作成者または所有者ではありません。

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

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

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


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 フィールドに一覧表示されます。

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


{
  "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"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}