管理模型服务终结点

项目
02/10/2025

本文介绍如何使用服务 UI 和 REST API 管理模型服务终结点。请参阅 REST API 参考中的服务终结点。

若要创建模型服务终结点，请使用以下方法之一：

获取模型终结点的状态

在服务 UI 中，可以从终结点详细信息页顶部的“服务终结点状态”指示器检查终结点的状态。

使用 REST API 或 MLflow 部署 SDK 以编程方式检查终结点的状态和详细信息：

REST API

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

以下示例创建一个终结点，该终结点为 Unity 目录模型注册表中注册的第 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"
}

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 错误。

可从“服务”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 部署 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"
    }
  ]
}'

还可以使用权限 API 修改服务终结点权限。

为模型服务终结点添加预算策略

重要

此功能目前为公共预览版，不适用于服务外部模型的终结点。

预算策略允许组织对无服务器使用情况应用自定义标记，以实现精细计费归因。如果工作区使用预算策略来归因无服务器使用情况，则可以将预算策略添加到服务终结点的模型。请参阅使用预算策略来归因无服务器使用情况。

在创建模型服务终结点期间，可以从服务 UI 中的 预算策略 菜单中选择终结点的预算策略。如果分配了预算策略，则创建的所有终结点都会分配该预算策略，即使未从 预算策略 菜单中选择策略。

使用服务 UI 在创建模型服务终结点期间添加预算策略。

如果对现有终结点具有 MANAGE 权限，可以从 UI 中的 终结点详细信息 页编辑和添加预算策略。

使用服务 UI 在现有模型服务端点上编辑预算策略。

注意

如果已分配预算策略，则现有终结点不会自动使用你的策略进行标记。如果要将预算策略附加到现有终结点，则必须手动更新这些终结点。

获取模型服务终结点架构

重要

服务终结点查询架构支持目前为公共预览版。此功能在模型服务区域中提供。

服务终结点查询架构是使用 JSON 格式的标准 OpenAPI 规范对服务终结点进行的正式说明。它包含有关终结点的信息，包括终结点路径、查询终结点的详细信息，例如请求和响应正文的格式以及每个字段的数据类型。对于可重现性应用场景，或者当需要有关终结点的信息，但不是原始终结点的创建者或所有者时，此信息将非常有用。

若要获取模型服务终结点架构，所服务的模型必须记录有模型签名，并且终结点必须处于 READY 状态。

以下示例演示了如何使用 REST API 以编程方式获取模型服务终结点架构。有关功能服务终结点架构，请参阅什么是 Databricks 功能服务？。

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 编辑器等第三方工具可视化 OpenAPI 规范。

响应的主要字段包括：

info.title 字段显示服务终结点的名称。
servers 字段始终包含一个对象，通常是作为终结点基 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"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

通过

管理模型服务终结点

获取模型终结点的状态

REST API

MLflow 部署 SDK

停止模型服务终结点

删除模型服务终结点

REST API

MLflow 部署 SDK

调试模型服务终结点

管理模型服务终结点的权限

为模型服务终结点添加预算策略

获取模型服务终结点架构

架构响应详细信息

反馈

其他资源