管理模型服务终结点

2025-10-22

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

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

获取模型终结点的状态

可以使用服务 UI 或通过 REST API、Databricks 工作区客户端或 MLflow 部署 SDK 以编程方式检查终结点的状态。

终结点状态可以是Ready、Ready (Update failed)、Not ready (Updating)或Not ready (Update failed)Not ready (Stopped)。就绪情况是指是否可以查询终结点。更新失败表示端点的最新更改未成功。已停止表明终端已停止。

UI

终结点详细信息页顶部的 “服务终结点状态 ”指示器：

使用终结点详细信息服务 UI 检查终结点状态。

使用列表终结点服务 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

单击右上角的“启动”。

使用服务 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")

调试模型服务端点

有两种类型的日志可用于帮助调试终端的问题：

模型服务器容器生成日志：在创建容器时在终结点初始化期间生成。这些日志捕获安装阶段，包括下载模型、安装依赖项和配置运行时环境。使用这些日志调试终结点在部署期间未能启动或停滞的原因。
模型服务器日志：当终结点主动提供预测时在运行时生成。这些日志捕获来自模型代码的传入请求、模型推理执行、运行时错误和应用程序级日志记录。使用这些日志来调试预测相关问题或调查查询失败情况。

这两种日志类型也可以从“日志”选项卡中的“终结点”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 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"
    }
  ]
}'

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

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

重要

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

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

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

在使用服务 UI 创建模型服务终端点时，添加无服务器预算策略。

如果拥有 MANAGE 现有终结点的权限，可以从 UI 中的 “终结点详细信息 ”页编辑和添加无服务器预算策略。

使用服务 UI 在现有模型服务终结点上编辑无服务器预算策略。

注意

如果被分配了无服务器预算策略，则现有终结点不会自动被标记为您的策略。如果要将无服务器预算策略附加到这些终结点，则必须手动更新现有终结点。

获取模型服务终结点架构

重要

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

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

若要获取模型服务终结点架构，所服务的模型必须记录有模型签名，并且终结点必须处于 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 编辑器等第三方工具可视化 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"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

反馈

此页面是否有帮助？

通过

管理模型服务终结点

获取模型终结点的状态

UI

REST API

Databricks 工作区客户端

MLflow 部署 SDK

停止模型服务终结点

停止终结点

UI

REST API

启动端点

UI

REST API

删除模型服务终结点

UI

REST API

MLflow 部署 SDK

调试模型服务端点

获取容器生成日志

获取模型服务器日志

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

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

获取模型服务终结点架构

架构响应详细信息

反馈

其他资源