この記事では、Serving UI と REST API を使ってモデル サービング エンドポイントを管理する方法について説明します。 REST API リファレンスの「提供エンドポイント」を参照してください。
モデル サービング エンドポイントを作成するには、次のいずれかを使用します。
モデル エンドポイントの状態を取得する
サービス UI を使用するか、REST API、Databricks Workspace Client、または MLflow Deployments SDK を使用して、エンドポイントの状態を確認できます。
エンドポイントの状態は、 Ready、 Ready (Update failed)、 Not ready (Updating)、 Not ready (Update failed)、または Not ready (Stopped)できます。 準備とは、エンドポイントを照会できるかどうかを指します。 更新失敗は、エンドポイントへの最新の変更が失敗したことを示します。 停止とは、エンドポイントが停止されたことを意味します。
UI
エンドポイントの詳細ページの上部にあるサービス エンドポイントの 状態 インジケーター:
REST API
GET /api/2.0/serving-endpoints/{name}
次の応答例では、 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"
}
Databricks ワークスペース クライアント
from databricks.sdk import WorkspaceClient
w = WorkspaceClient()
endpoint = w.serving_endpoints.get(name="my-endpoint")
print(f"Endpoint state: {endpoint.state.ready}")
print(f"Update state: {endpoint.state.config_update}")
MLflow デプロイ SDK
from mlflow.deployments import get_deploy_client
client = get_deploy_client("databricks")
endpoint = client.get_endpoint(endpoint="my-endpoint")
print(f"Endpoint state: {endpoint['state']}")
print(f"Endpoint config: {endpoint['config']}")
モデル サービング エンドポイントを停止する
エンドポイントを提供するモデルを一時的に停止し、後で再開することができます。 エンドポイントが停止した場合:
- プロビジョニングされたリソースは停止されています。
- エンドポイントは、再度開始されるまでクエリを処理できません。
- 停止できるのは、 カスタム モデル を提供し、進行中の更新がないエンドポイントのみです。
- 停止したエンドポイントはリソースクォータにカウントされません。
- 停止したエンドポイントに送信されたクエリは、400エラーを返します。
エンドポイントを停止する
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
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")
エンドポイントを提供するモデルをデバッグする
エンドポイントに関する問題のデバッグに役立つ 2 種類のログを使用できます。
- モデル サーバー コンテナーのビルド ログ: コンテナーの作成時にエンドポイントの初期化中に生成されます。 これらのログは、モデルのダウンロード、依存関係のインストール、ランタイム環境の構成など、セットアップ フェーズをキャプチャします。 これらのログを使用して、デプロイ中にエンドポイントの起動に失敗した、またはスタックした理由をデバッグします。
- モデル サーバー ログ: エンドポイントが予測をアクティブに処理しているときに実行時に生成されます。 これらのログは、受信要求、モデル推論の実行、ランタイム エラー、およびモデル コードからのアプリケーション レベルのログをキャプチャします。 これらのログを使用して、予測に関する問題をデバッグしたり、クエリエラーを調査したりします。
どちらのログの種類も、[ログ] タブの [エンドポイント] UI からアクセスできます。
コンテナービルドログを取得する
build ログの場合提供されるモデルの場合は、次の要求を使用できます。 詳細については、 モデル サービスのDebugging ガイド を参照してください。
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 の提供」を参照してください。
提供エンドポイントのアクセス許可の一覧を取得します。
UI
UI の右上にある [アクセス許可] ボタンをクリックします。
Databricks コマンドラインインターフェース (CLI)
databricks permissions get serving-endpoints <endpoint-id>
ユーザー jsmith@example.com に、提供エンドポイントに対するクエリ可能アクセス許可を許可します。
databricks permissions update serving-endpoints <endpoint-id> --json '{
"access_control_list": [
{
"user_name": "jsmith@example.com",
"permission_level": "CAN_QUERY"
}
]
}'
Permissions API を使って、提供エンドポイントのアクセス許可を変更することもできます。
エンドポイントを提供するモデルのサーバーレス予算ポリシーを追加する
重要
この機能はパブリック プレビュー であり、外部モデルにサービスを提供するエンドポイントには使用できません。
サーバーレス予算ポリシーを使用すると、組織はサーバーレス使用量にカスタム タグを適用して、詳細な課金属性を設定できます。 ワークスペースでサーバーレス予算ポリシーを使用してサーバーレス使用量を属性付けする場合は、エンドポイントを提供するモデルにサーバーレス予算ポリシーを追加できます。 サーバーレス予算ポリシーでの属性の使用に関する説明を参照してください。
モデル サービス エンドポイントの作成中に、サービス UI の [予算ポリシー] メニューからエンドポイントのサーバーレス 予算ポリシー を選択できます。 サーバーレス予算ポリシーが割り当てられている場合は、[予算ポリシー] メニューからポリシーを選択しない場合でも、作成するすべてのエンドポイントにそのサーバーレス 予算ポリシー が割り当てられます。
既存のエンドポイントに対する MANAGE アクセス許可がある場合は、UI の [エンドポイント の詳細 ] ページからサーバーレス予算ポリシーを編集し、そのエンドポイントに追加できます。
注
サーバーレス予算ポリシーが割り当てられている場合、既存のエンドポイントにはポリシーが自動的にタグ付けされません。 サーバーレス予算ポリシーをアタッチする場合は、既存のエンドポイントを手動で更新する必要があります。
モデル サービング エンドポイント スキーマを取得する
重要
エンドポイント クエリ スキーマの提供のサポートはパブリック プレビュー段階にあります。 この機能は、モデル サービス リージョンで使用できます。
サービス エンドポイント クエリ スキーマは、標準の OpenAPI 仕様を JSON 形式で使用したサービス エンドポイントの正式な説明です。 これには、エンドポイント パス、要求と応答本文の形式などのエンドポイントのクエリの詳細、各フィールドのデータ型など、エンドポイントに関する情報が含まれます。 この情報は、再現性のシナリオや、エンドポイントに関する情報が必要な場合に役立ちますが、お客様は元のエンドポイント作成者または所有者ではありません。
モデル サービング エンドポイント スキーマを取得するには、提供されるモデルにおいてモデル署名がログに記録され、エンドポイントが READY 状態である必要があります。
次の例では、REST API を使用して、エンドポイント スキーマを提供するモデルをプログラムで取得する方法を示します。 エンドポイント スキーマを提供する機能については、「 機能サービス エンドポイント」を参照してください。
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"
}
}
}
}
}
}
}
}
}
}
}
}