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

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

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

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

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

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

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

次の例では、 Unity Catalog モデルレジストリに登録されている my-ads-model モデルの最初のバージョンを提供するエンドポイントを作成します。親カタログとスキーマを含む完全なモデル名を指定する必要があります (例: catalog.schema.example-model)。

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

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

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 を使用して、サービスエンドポイントをプログラムで停止することもできます。

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

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

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

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

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

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

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

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

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

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

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

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
}

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

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

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

databricks permissions get servingendpoints <endpoint-id>

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

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

Permissions APIを使用して、サービス提供エンドポイントの権限を変更することもできます。

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

プレビュー

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

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

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

次の例は、 REST API使用してモデルサービングエンドポイントスキーマをプログラムで取得する方法を示しています。 Feature Servingエンドポイントスキーマについては、 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"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

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