在模型服务终结点上配置 AI 网关

本文介绍如何在模型服务终结点上配置 Mosaic AI 网关。

Requirements

• 支持模型服务的区域中的 Databricks 工作区。 请参阅 提供区域可用性的模型。
• 一个模型服务终结点。 可以在工作区上使用一个预配置的按令牌付费终结点，或者执行以下操作：
  • 若要为外部模型创建终结点，请完成 创建提供终结点的外部模型的步骤 1 和 2。
  • 若要创建预配吞吐量的终结点，请参阅 预配吞吐量基础模型 API。
  • 若要为自定义模型创建终结点，请参阅 “创建终结点”。

使用 UI 配置 AI 网关

在终结点创建页的 AI 网关 部分中，可以单独配置 AI 网关功能。 请参阅 支持的功能，了解哪些功能可用于外部模型服务端点和预配吞吐量端点。

下表总结了如何使用服务 UI 在终结点创建过程中配置 AI 网关。 如果首选以编程方式执行此操作，请参阅笔记本示例。

下图显示了一个后备方案示例，其中，

• 在模型服务终结点上提供三个服务实体。
• 请求最初路由到 服务实体 3。
• 如果请求返回 200 响应，则请求在 服务实体 3 上成功，请求及其响应将记录到终结点的使用情况跟踪和有效负载日志记录表。
• 如果请求在 服务实体 3 上返回 429 或 5xx 错误，则请求会回退到终结点上的下一个服务实体 ，即“已处理”实体 1。
  • 如果请求在 服务实体 1 上返回 429 或 5xx 错误，则请求会回退到终结点上的下一个服务实体 ，即“已处理”实体 2。
  • 如果请求在 服务实体 2 上返回 429 或 5xx 错误，则请求会失败，因为这是回退实体的最大数目。 失败的请求和响应错误将记录到使用情况跟踪和有效负载日志记录表。

在 UI 中配置 AI 护栏

下表显示了如何配置支持的护栏。

使用情况跟踪表架构

以下部分概述了用于system.serving.served_entities和system.serving.endpoint_usage系统表的使用情况跟踪表的架构。

system.serving.served_entities 使用情况跟踪表架构

system.serving.served_entities 使用情况跟踪系统表采用以下架构：

system.serving.endpoint_usage 使用情况跟踪表架构

system.serving.endpoint_usage 使用情况跟踪系统表采用以下架构：

使用 usage_context 进一步定义使用情况

在启用使用情况跟踪的情况下查询外部模型时，可以提供类型 usage_context 的 Map[String, String] 参数。 用法上下文映射显示在 usage_context 列的使用情况跟踪表中。 usage_context 映射大小不能超过 10 KiB。

{
  "messages": [
    {
      "role": "user",
      "content": "What is Databricks?"
    }
  ],
  "max_tokens": 128,
  "usage_context":
    {
      "use_case": "external",
      "project": "project1",
      "priority": "high",
      "end_user_to_charge": "abcde12345",
      "a_b_test_group": "group_a"
    }
}

如果您使用 OpenAI Python 客户端，可以通过在usage_context参数中包含extra_body来指定它。

from openai import OpenAI

client = OpenAI(
    api_key="dapi-your-databricks-token",
    base_url="https://example.staging.cloud.databricks.com/serving-endpoints"
)

response = client.chat.completions.create(
    model="databricks-claude-3-7-sonnet",
    messages=[{"role": "user", "content": "What is Databricks?"}],
    temperature=0,
    extra_body={"usage_context": {"project": "project1"}},
)
answer = response.choices[0].message.content
print("Answer:", answer)

帐户管理员可以根据用法上下文汇总不同的行，以获得见解，并且可以将此信息与有效负载日志记录表中的信息进行联接。 例如，可以将 end_user_to_charge 添加到 usage_context，以跟踪最终用户的成本归因。

监视终端使用情况

若要监视终结点使用情况，可以联接终结点的系统表和推理表。

联接系统表

此示例仅适用于外部模型和预配的吞吐量终结点。 served_entities 系统表对于按令牌付费的终结点不受支持，但你可以联接推理表和使用情况表来获取类似的详细信息。

若要联接 endpoint_usage 表和 served_entities 系统表，请使用以下 SQL：

SELECT * FROM system.serving.endpoint_usage as eu
JOIN system.serving.served_entities as se
ON eu.served_entity_id = se.served_entity_id
WHERE created_by = "\<user_email\>";

联接推理和使用情况表

下文将联接 endpoint_usage 系统表和推理表，用于按令牌付费的终端点。 必须在终结点上启用推理表和使用情况跟踪以联接这些表。

SELECT * FROM system.serving.endpoint_usage AS endpoint_usage
JOIN
  (SELECT DISTINCT(served_entity_id) AS fmapi_served_entity_id
  FROM <inference table name>) fmapi_id
ON fmapi_id.fmapi_served_entity_id = endpoint_usage.served_entity_id;

在终结点上更新 AI 网关功能

可以在以前启用 AI 网关功能和未启用该功能的模型服务终结点上更新 AI 网关功能。 应用 AI 网关配置更新大约需要 20-40 秒，但速率限制更新最长可能需要 60 秒。

下面演示了如何使用服务 UI 在模型服务终结点上更新 AI 网关功能。

在终结点页面的网关部分中，可以看到已启用的功能。 若要更新这些功能，请单击编辑 AI 网关。

笔记本示例

以下笔记本演示了如何以编程方式启用和使用 Databricks Mosaic AI 网关功能，以便管理和治理来自提供程序的模型。 有关 REST API 的详细信息，请参阅 PUT /api/2.0/service-endpoints/{name}/ai-gateway 。

启用 Databricks Mosaic AI 网关功能笔记本

Get notebook

Additional resources

• Mosaic AI 网关简介。
• 使用已启用 AI 网关的推理表监视服务的模型。