databricks-model-serving

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

最初に：CLI の基本、認証、プロファイルの選択については、親の databricks-core スキルを使用してください。

ゲートウェイの境界： このスキルが扱うのは、serving-endpoints put-ai-gateway など、Model Serving エンドポイントに関連付けられたレガシーな AI Gateway の設定です。Unity Gateway / Unity AI Gateway を明示的に指定するリクエスト、および databricks ai-gateway のモデルサービス、MCP サービス、モデルプロバイダーサービスは、databricks-unity-gateway の対象です。

Model Serving は、LLM、カスタム ML モデル、外部モデルをスケーラブルな REST API として提供する、マネージドエンドポイントを提供します。エンドポイントは名前（ワークスペース内で一意）で識別されます。

エンドポイントの種類

種類	使用する場合	主な詳細
トークンごとの従量課金	Foundation Model API（Llama、GPT-5、Claude、Gemini など）	system.ai.* カタログモデルを使用します。これらはすべてのワークスペースに事前プロビジョニングされています。実行時に検出してください。詳しくは、以下のFoundation Model API エンドポイントを参照してください。
プロビジョニング済みスループット	専用 GPU 容量	スループットが保証されますが、コストは高くなります
カスタムモデル	独自の MLflow モデルまたはコンテナー	MLflow シグネチャを持つ任意のモデルをデプロイできます

エンドポイントの構造

Serving Endpoint (top-level, identified by NAME)
  ├── Config
  │     ├── Served Entities (model references + scaling config)
  │     └── Traffic Config (routing percentages across entities)
  ├── AI Gateway (rate limits, usage tracking)
  └── State (READY / NOT_READY, config_update status)

• サービング対象エンティティ：各エンティティは、スケーリングパラメーターを指定してモデル（Unity Catalog または MLflow のモデル）を参照します。get の出力にある served_entities[].name からエンティティ名を取得してください。build-logs コマンドと logs コマンドで必要になります。
• トラフィック設定：サービング対象エンティティ間でパーセンテージに基づいてリクエストを振り分けます（A/B テストやカナリアデプロイに使用します）。
• 状態：エンドポイントは、作成または設定の更新後に NOT_READY から READY へ移行します。get でポーリングして state.ready を確認してください。

CLI での確認 — 必ず最初に実行してください

コマンド構文を推測しないでください。 使用できるコマンドとその使用方法を動的に確認してください。

# List all serving-endpoints subcommands
databricks serving-endpoints -h

# Get detailed usage for any subcommand (flags, args, JSON fields)
databricks serving-endpoints <subcommand> -h

コマンドを作成する前に、databricks serving-endpoints -h を実行してください。該当サブコマンドの正確なフラグ、位置引数、JSON 仕様フィールドを確認するには、databricks serving-endpoints <subcommand> -h を実行してください。

エンドポイントの作成

作成前にエンドポイントの一覧を取得しないでください。

databricks serving-endpoints create <ENDPOINT_NAME> \
  --json '{
    "served_entities": [{
      "entity_name": "<MODEL_CATALOG_PATH>",
      "entity_version": "<VERSION>",
      "min_provisioned_throughput": 0,
      "max_provisioned_throughput": 0,
      "workload_size": "Small",
      "scale_to_zero_enabled": true
    }],
    "traffic_config": {
      "routes": [{
        "served_entity_name": "<ENTITY_NAME>",
        "traffic_percentage": 100
      }]
    }
  }' --profile <PROFILE>

• 利用可能な Foundation Model を確認するには、実行時に一覧を取得するコード例とデフォルトモデルの選択ルールについて、以下のFoundation Model API エンドポイントを参照してください。Unity Catalog の system.ai カタログを確認するか、databricks serving-endpoints list --profile <PROFILE> を実行して、ワークスペースにデプロイ済みのモデルを確認することもできます。特定のエンドポイントの API スキーマを調べるには、databricks serving-endpoints get-open-api <ENDPOINT_NAME> --profile <PROFILE> を使用してください。
• 実行時間の長い操作です。CLI はデフォルトで完了まで待機します。すぐに戻るには --no-wait を使用し、その後ポーリングしてください。

  databricks serving-endpoints get <ENDPOINT_NAME> --profile <PROFILE>
  # Check: state.ready == "READY"
  

• プロビジョニング済みスループットまたはカスタムモデルのエンドポイントでは、エンドポイントの種類に必要な JSON フィールドを確認するため、databricks serving-endpoints create -h を実行してください。

MLflow Deployments クライアント（Python の代替手段）

mlflow.deployments.get_deploy_client("databricks").create_endpoint(name=..., config={...}) は、CLI と同じ JSON 形式を受け取ります。注意点は次の 2 つです。

• tags= は最上位のキーワード引数です。config 内のフィールドではありません。serving-endpoints patch --add-tags と同じ [{key, value}] 形式です。
• traffic_config.routes[].served_model_name = "<model>-<version>"（例："turbine_failure-3"）。API はこれをエンティティから自動導出しますが、traffic_config では正確な文字列を指定する必要があります。形式を間違えると、ルートが一致しなくても通知されません。

ダウンタイムなしのバージョン切り替え

エンドポイントを新しいモデルバージョンに切り替えるには、エイリアスを新しいバージョンに向けるとともに、新しい served_entities と対応する traffic_config を指定して update_endpoint を呼び出します。どちらか一方だけにするのがよくあるミスです。エイリアスだけではエンドポイントは更新されず、update_endpoint だけではエイリアスが古いバージョンを指したままになります。

from mlflow.tracking import MlflowClient
from mlflow.deployments import get_deploy_client

registry = MlflowClient(registry_uri="databricks-uc")
deploy   = get_deploy_client("databricks")

registry.set_registered_model_alias(FULL_NAME, "prod", new_version)
deploy.update_endpoint(endpoint=ENDPOINT_NAME, config={
    "served_entities": [{"entity_name": FULL_NAME, "entity_version": new_version,
                         "workload_size": "Small", "scale_to_zero_enabled": True}],
    "traffic_config": {"routes": [
        {"served_model_name": f"{NAME}-{new_version}", "traffic_percentage": 100}
    ]},
})

CLI では databricks serving-endpoints update-config <NAME> --json '...' を実行します。いずれの場合も、その後 state.ready と state.config_update の両方をポーリングしてください。詳しくは、以下の「エンドポイントの準備状況」を参照してください。

エンドポイントの準備状況

create または update-config の実行後、エンドポイントはコンピュートリソースをプロビジョニングし、モデルを読み込みます。準備が完了するまで、エンドポイントにクエリを送信しないでください。 重要な状態フィールドは2つあり、それぞれ意味が異なります。

• state.ready — エンドポイントに動作可能な設定があると READY になります。バージョン切り替え中も READY のままです。
• state.config_update — 現在の 設定更新が完了すると NOT_UPDATING になり、バージョン切り替え中は IN_PROGRESS になります。

state.ready だけを監視するループでは、バージョン切り替え中に旧バージョンがまだリクエストを処理しているにもかかわらず、「準備完了」と判定してしまいます。両方をポーリングしてください。

databricks serving-endpoints get <ENDPOINT_NAME> --profile <PROFILE> \
  | jq '{ready: .state.ready, config_update: .state.config_update}'
# Fully ready when ready == "READY" AND config_update == "NOT_UPDATING"

プロビジョニングには数分かかることがあります。プロビジョンドスループットエンドポイントは、GPU の割り当てがあるため最も時間がかかります。まだ READY ではないエンドポイントへのクエリは、404 または 503 を返します。

エンドポイントにクエリを送信する

チャット／エージェントエンドポイントでは、messages 配列を使用します。

databricks serving-endpoints query <ENDPOINT_NAME> \
  --json '{"messages": [{"role": "user", "content": "Hello"}]}' --profile <PROFILE>

従来型の ML エンドポイントでは、dataframe_records を使用します（行ごとに1つのレコード）。

databricks serving-endpoints query <ENDPOINT_NAME> \
  --json '{"dataframe_records": [{"vibration": 0.42, "rpm": 18.3, "temp_c": 71.2}]}'

• チャットエンドポイントでストリーミング応答を使用するには、--stream を指定します。
• 埋め込みやその他のカスタムスキーマの場合は、まず get-open-api <ENDPOINT_NAME> を使用して、リクエスト／レスポンスの形式を確認します。

エンドポイントのスキーマを取得する（OpenAPI）

各サービングモデルが受け付ける内容と返す内容を記述した、OpenAPI 3.1 の JSON スキーマを返します。エンドポイントにクエリを送信する前に、入力／出力の形式を把握するために使用してください。

databricks serving-endpoints get-open-api <ENDPOINT_NAME> --profile <PROFILE>

スキーマには、各サービングモデルのパス（例：/served-models/<model-name>/invocations）が、パラメーター型、列挙値、null 許容フィールドを含む完全なリクエスト／レスポンス定義とともに表示されます。

その他のコマンド

使用方法の詳細は、databricks serving-endpoints <subcommand> -h を実行してください。

タスク	コマンド	備考
すべてのエンドポイントを一覧表示	list
エンドポイントの詳細を取得	get <NAME>	状態、設定、サービングエンティティを表示します
エンドポイントを削除	delete <NAME>
サービングエンティティまたはトラフィックを更新	update-config <NAME> --json '...'	ダウンタイムなし：新しい設定の準備が完了するまで、古い設定でリクエストを処理します
レート制限と使用状況の追跡	put-ai-gateway <NAME> --json '...'
タグを更新	patch <NAME> --json '...'
ビルドログ	build-logs <NAME> <SERVED_MODEL>	get の出力にある served_entities[].name から SERVED_MODEL を取得します
ランタイムログ	logs <NAME> <SERVED_MODEL>
メトリクス（Prometheus 形式）	export-metrics <NAME>
アクセス許可	get-permissions <ENDPOINT_ID>	⚠️ エンドポイントの名前ではなく、エンドポイントの ID（16進文字列）を使用します。ID は get で確認してください。

次のステップ

Databricks App と統合する

サービングエンドポイントを作成したら、Databricks App に接続します。

ステップ1 — AppKit テンプレートで serving プラグインが利用可能か確認する

databricks apps manifest --profile <PROFILE>

出力に serving プラグインが含まれている場合は、次のコマンドでスキャフォールドを作成します。

databricks apps init --name <APP_NAME> \
  --features serving \
  --set "serving.serving-endpoint.name=<ENDPOINT_NAME>" \
  --run none --profile <PROFILE>

ステップ2 — serving プラグインがない場合は、既存のアプリの databricks.yml にエンドポイントリソースを手動で追加します。

resources:
  apps:
    my_app:
      resources:
        - name: my-model-endpoint
          serving_endpoint:
            name: <ENDPOINT_NAME>
            permission: CAN_QUERY

また、app.yaml で環境変数としてエンドポイント名を設定します。

env:
  - name: SERVING_ENDPOINT
    valueFrom: serving-endpoint

その後、serving() プラグインまたは onPluginsReady のカスタムルートを使って、エンドポイントをアプリに接続します。アプリ統合の全体的なパターンについては、databricks-apps スキルを使用し、モデルサービングガイドを参照してください。

新しいモデルを開発してデプロイする

このスキルは運用に重点を置いており、既存のエンドポイントを管理します。トレーニング、MLflow のトラッキング、UC への登録、カスタム PyFunc の作成、手動で記述する ResponsesAgent コードなど、開発側の手順については、databricks-ml-training（実験的）を参照してください。

Foundation Model API エンドポイント

従量課金制で、すべてのワークスペースに事前にプロビジョニングされています。新しいモデルは定期的に追加され、静的なスキルリストはすぐに古くなるため、名前をハードコードせず、必ず実行時に一覧を取得してください。databricks- という名前のプレフィックスで絞り込み、さらに提供エンティティが system.ai.* 内にあることを確認してください（databricks-app-template-serving など、同じプレフィックスを持つ他のエンドポイントは FM API エンドポイントではありません）。Foundation Model エンドポイントへのアクセス管理には、Databricks Unity Gateway（databricks-unity-gateway）を使用してください。レガシー AI Gateway の databricks-model-serving は使用しないでください。

# FM API endpoints in this workspace, grouped by task (chat / embeddings / etc.)
databricks serving-endpoints list \
  | jq -r '.[]
      | select(.name | startswith("databricks-"))
      | select((.config.served_entities[0].entity_name // "") | startswith("system.ai."))
      | "\(.task)\t\(.name)"' \
  | sort

ユーザーが指定しない場合のデフォルト：エージェントには番号が最も大きい Claude Sonnet、コードには番号が最も大きい -codex-max、埋め込みには databricks-gte-large-en を選び、実際の名前は上記のライブリストから解決してください。

Databricks 外でのストリーミング

Databricks Apps 以外（Vercel、AWS、スタンドアロンの Node.js）にデプロイされたアプリで、Vercel AI SDK v6 を使用して Databricks レガシー AI Gateway に接続する場合は、references/off-platform-streaming.md を参照してください。Databricks 外のアプリは、Databricks Unity Gateway（databricks-unity-gateway）に接続するよう更新してください。AppKit ベースのアプリでは、代わりに databricks-apps スキルに組み込まれたサービングプラグインを使用してください。

トラブルシューティング

エラー	解決策
cannot configure default credentials	--profile フラグを使用するか、先に認証してください
PERMISSION_DENIED	ワークスペースの権限を確認してください。アプリの場合は、serving_endpoint リソースが CAN_QUERY 付きで宣言されていることを確認してください
エンドポイントが NOT_READY のままになる	プロビジョニング済みスループットの場合、最大 30 分お待ちください。ビルドログを確認します：build-logs <NAME> <ENTITY_NAME>（エンティティ名は get の出力 → served_entities[].name から取得してください）
RESOURCE_DOES_NOT_EXIST	list でエンドポイント名を確認してください
クエリが 404 を返す	エンドポイントのプロビジョニング中である可能性があります。get で state.ready を確認してください
RATE_LIMIT_EXCEEDED（429）	AI Gateway のレート制限です。put-ai-gateway の設定を確認するか、バックオフ後に再試行してください
デプロイ後、Serving UI にエンドポイントが表示されない	UI のフィルターはデフォルトで「自分が所有」に設定されています。デプロイジョブはサービスプリンシパルとして実行されるため、「すべて」に切り替えるまでエンドポイントは表示されません。databricks serving-endpoints list では常に表示されます。