Mosaic AI Model Serving 中的外部模型

重要

本文中的代码示例演示如何使用公共预览版 MLflow 部署 CRUD API。

本文介绍 Mosaic AI Model Serving 中的外部模型，包括其支持的模型提供商和局限性。

什么是外部模型？

重要

现在可以在为外部模型提供服务的模型服务终结点上配置 Mosaic AI 网关。 AI 网关为这些模型服务终结点带来了治理、监视和生产就绪。 请参阅 Mosaic AI 网关。

外部模型是在 Databricks 外部托管的第三方模型。 借助 Model Serving，外部模型可以简化组织内各种大型语言模型 (LLM) 提供商（如 OpenAI 和 Anthropic）的使用和管理。 还可以使用 Mosaic AI Model Serving 作为提供商来提供自定义模型，为这些终结点提供速率限制。 作为此支持的一部分，Model Serving 提供了一个高级接口，该接口通过提供统一的终结点来处理与特定 LLM 相关的请求来简化与这些服务的交互。

此外，Azure Databricks 对外部模型的支持还提供集中式凭据管理。 通过将 API 密钥存储在一个安全位置，组织可以通过最大程度地减少公开整个系统中的敏感 API 密钥来增强其安全态势。 它还有助于防止在代码中公开这些密钥或要求最终用户安全地管理密钥。

请参阅教程：创建外部模型终结点以查询 OpenAI 模型，以获取有关使用 MLflow 部署 SDK 创建外部模型终结点和查询这些终结点提供的受支持模型的分步指南。 有关如何使用服务 UI 和 REST API 的说明，请参阅以下指南：

• 创建自定义模型服务终结点
• 查询生成 AI 模型

要求

• 模型提供程序的 API 密钥或身份验证字段。
• 外部模型支持的区域中的 Databricks 工作区。

模型提供商

Model Serving 中的外部模型可支持各种模型提供商。 提供商表示机器学习模型的来源，例如 OpenAI、Anthropic 等。 每个提供商都有其特定的特征和配置，这些特征和配置封装在外部模型终结点配置的 external_model 字段中。

支持以下提供商：

• openai：适用于 OpenAI 提供的模型，以及 Azure OpenAI 和带 AAD 的 Azure OpenAI 的 Azure 集成。
• anthropic：适用于 Anthropic 提供的模型。
• cohere：适用于 Cohere 提供的模型。
• amazon-bedrock：适用于 Amazon Bedrock 提供的模型。
• google-cloud-vertex-ai：适用于 Google Cloud Vertex AI 提供的模型。
• databricks-model-service：适用于具有兼容架构的 Mosaic AI Model Serving 终结点。 请参阅终结点配置。

若要请求支持此处未列出的提供商，请联系 Databricks 帐户团队。

支持的模型

选择的模型直接影响从 API 调用获取的响应结果。 因此，请选择符合用例要求的模型。 例如，对于生成聊天响应，可以选择聊天模型。 相反，对于生成文本嵌入，可以选择嵌入模型。

下表提供了支持的模型和相应终结点类型的非详尽列表。 给定提供商提供新发布的模型类型时，若要为这些类型配置终结点，下面列出的模型关联可用作有帮助的指南。 客户需负责确保遵守适用的模型许可条款。

注意

随着 LLM 的快速发展，不能保证此列表随时处于最新状态。

模型提供商	llm/v1/completions	llm/v1/chat	llm/v1/embeddings
OpenAI**	- gpt-3.5-turbo-instruct - babbage-002 - davinci-002	- o1-preview - o1-preview-2024-09-12 - o1-mini - o1-mini-2024-09-12 - gpt-3.5-turbo - gpt-4 - gpt-4o - gpt-4o-2024-05-13 - gpt-4o-mini - gpt-3.5-turbo-0125 - gpt-3.5-turbo-1106 - gpt-4-0125-preview - gpt-4-turbo-preview - gpt-4-1106-preview	- text-embedding-ada-002 - text-embedding-3-large - text-embedding-3-small
Azure OpenAI**	- text-davinci-003 - gpt-35-turbo-instruct	- gpt-35-turbo - gpt-35-turbo-16k - gpt-4 - gpt-4-32k - gpt-4o - gpt-4o-mini	- text-embedding-ada-002 - text-embedding-3-large - text-embedding-3-small
Anthropic	- claude-1 - claude-1.3-100k - claude-2 - claude-2.1 - claude-2.0 - claude-instant-1.2	- claude-3-5-sonnet-20240620 - claude-3-haiku-20240307 - claude-3-opus-20240229 - claude-3-sonnet-20240229 - claude-2.1 - claude-2.0 - claude-instant-1.2
Cohere**	- command - command-light	- command-r-plus - command-r - command - command-light-nightly - command-light - command-nightly	- embed-english-v2.0 - embed-multilingual-v2.0 - embed-english-light-v2.0 - embed-english-v3.0 - embed-english-light-v3.0 - embed-multilingual-v3.0 - embed-multilingual-light-v3.0
Mosaic AI Model Serving	Databricks 服务终结点	Databricks 服务终结点	Databricks 服务终结点
Amazon Bedrock	Anthropic: - claude-instant-v1 - claude-v2 Cohere: - command-text-v14 - command-light-text-v14 AI21 Labs: - j2-grande-instruct - j2-jumbo-instruct - j2-mid - j2-mid-v1 - j2-ultra - j2-ultra-v1	Anthropic: - claude-v2 - claude-v2:1 - claude-3-sonnet-20240229-v1:0 - claude-3-5-sonnet-20240620-v1:0 Cohere: - command-r-plus-v1:0 - command-r-v1:0	Amazon: - titan-embed-text-v1 - titan-embed-g1-text-02 Cohere: - embed-english-v3 - embed-multilingual-v3
AI21 Labs†	- j2-mid - j2-light - j2-ultra
Google Cloud Vertex AI	text-bison	- chat-bison - gemini-pro - gemini-1.0-pro - gemini-1.5-pro - gemini-1.5-flash	textembedding-gecko

** 模型提供商支持微调的补全和聊天模型。 若要查询微调的模型，请使用你的微调模型的名称填充 external model 配置的 name 字段。

† 模型提供商支持自定义补全模型。

使用 Mosaic AI Model Serving 终结点上提供的模型

Mosaic AI Model Serving 终结点作为提供商，支持用于 llm/v1/completions、llm/v1/chat 和 llm/v1/embeddings 终结点类型。 这些终结点必须接受根据需要标记的标准查询参数，而其他参数可能会被忽略，这取决于 Mosaic AI Model Serving 终结点是否支持这些参数。

有关标准查询参数，请参阅 API 参考中的 POST /service-endpoints/{name}/invocations。

这些终结点必须以以下 OpenAI 格式生成响应。

用于完成任务：

{
"id": "123", # Not Required
"model": "test_databricks_model",
"choices": [
  {
    "text": "Hello World!",
    "index": 0,
    "logprobs": null, # Not Required
    "finish_reason": "length" # Not Required
  }
],
"usage": {
  "prompt_tokens": 8,
  "total_tokens": 8
  }
}

用于聊天任务：

{
  "id": "123", # Not Required
  "model": "test_chat_model",
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "\n\nHello there, how may I assist you today?",
    },
    "finish_reason": "stop"
  },
  {
    "index": 1,
    "message": {
      "role": "human",
      "content": "\n\nWhat is the weather in San Francisco?",
    },
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 8,
    "total_tokens": 8
  }
}

用于嵌入任务：

{
  "data": [
    {
      "embedding": [
        0.0023064255,
        -0.009327292,
        .... # (1536 floats total for ada-002)
        -0.0028842222,
      ],
      "index": 0
    },
    {
      "embedding": [
        0.0023064255,
        -0.009327292,
        .... #(1536 floats total for ada-002)
        -0.0028842222,
      ],
      "index": 0
    }
  ],
  "model": "test_embedding_model",
  "usage": {
    "prompt_tokens": 8,
    "total_tokens": 8
  }
}

终结点配置

若要提供和查询外部模型，需要配置服务终结点。 请参阅创建外部模型服务终结点

对于为终结点提供服务的外部模型，必须在终结点配置的 served_entities 部分中包括 external_model 字段及其参数。 如果在服务终结点中配置多个外部模型，则必须提供 traffic_config 来定义每个外部模型的流量路由百分比。

external_model 字段定义了此终结点将请求转发到的模型。 指定模型时，提供商支持所请求的模型至关重要。 例如，作为提供商的 openai 支持像 text-embedding-ada-002 这样的模型，但其他提供商则可能不支持。 如果提供商不支持模型，则 Databricks 在尝试将请求路由到该模型时返回 HTTP 4xx 错误。

下表总结了 external_model 字段参数。 有关终结点配置参数，请参阅 POST /api/2.0/serving-endpoints。

参数	说明
name	要使用的模型的名称。 例如，对于 OpenAI 的 GPT-3.5-Turbo 模型，为 gpt-3.5-turbo。
provider	指定此模型的提供商的名称。 此字符串值必须与支持的外部模型 提供商 相对应。 例如，openai 对应 OpenAI 的 GPT-3.5 模型。
task	任务对应于所需的语言模型交互类型。 支持的任务有“llm/v1/completions”、“llm/v1/chat”、“llm/v1/embeddings”。
<provider>_config	包含模型所需的任何其他配置详细信息。 这包括指定 API 基 URL 和 API 密钥。 请参阅配置终结点的提供商。

下面是使用 create_endpoint() API 创建外部模型终结点的示例。 在此示例中，发送到完成终结点的请求将转发到 anthropic 提供的 claude-2 模型。

import mlflow.deployments

client = mlflow.deployments.get_deploy_client("databricks")

client.create_endpoint(
    name="anthropic-completions-endpoint",
    config={
        "served_entities": [
            {
                "name": "test",
                "external_model": {
                    "name": "claude-2",
                    "provider": "anthropic",
                    "task": "llm/v1/completions",
                    "anthropic_config": {
                        "anthropic_api_key": "{{secrets/my_anthropic_secret_scope/anthropic_api_key}}"
                    }
                }
            }
        ]
    }
)

为终结点配置提供商

创建终结点时，必须为指定的模型提供商提供所需的配置。 以下部分汇总了每个模型提供商适用的可用终结点配置参数。

注意

Databricks 会加密并安全地存储为每个模型提供程序提供的凭据。 删除关联的终结点时，会自动删除这些凭据。

OpenAI

配置参数	说明	需要	默认
openai_api_key	使用 OpenAI 服务的 OpenAI API 密钥的 Azure Databricks 密钥参考。 如果希望直接粘贴 API 密钥，请参阅 openai_api_key_plaintext。	必须使用以下字段之一来提供 API 密钥：openai_api_key 或 openai_api_key_plaintext。
openai_api_key_plaintext	使用 OpenAI 服务且以纯文本字符串形式提供的 OpenAI API 密钥。 如果希望使用 Azure Databricks 机密来引用密钥，请参阅 openai_api_key。	必须使用以下字段之一来提供 API 密钥：必须提供 openai_api_key 或 openai_api_key_plaintext。
openai_api_type	用于指定要使用的 OpenAI API 类型的可选字段。	否	openai
openai_api_base	OpenAI API 的基 URL。	否	https://api.openai.com/v1
openai_api_version	用于指定 OpenAI API 版本的可选字段。	否
openai_organization	用于指定 OpenAI 中的组织的可选字段。	否

Cohere

配置参数	说明	需要	默认
cohere_api_key	Cohere API 密钥的 Azure Databricks 密钥参考。 如果希望直接粘贴 API 密钥，请参阅 cohere_api_key_plaintext。	必须使用以下字段之一来提供 API 密钥：cohere_api_key 或 cohere_api_key_plaintext。
cohere_api_key_plaintext	以纯文本字符串形式提供的 Cohere API 密钥。 如果希望使用 Azure Databricks 机密来引用密钥，请参阅 cohere_api_key。	必须使用以下字段之一来提供 API 密钥：cohere_api_key 或 cohere_api_key_plaintext。
cohere_api_base	Cohere 服务的基 URL。	否

Anthropic

配置参数	说明	需要	默认
anthropic_api_key	Anthropic API 密钥的 Azure Databricks 密钥参考。 如果希望直接粘贴 API 密钥，请参阅 anthropic_api_key_plaintext。	必须使用以下字段之一来提供 API 密钥：anthropic_api_key 或 anthropic_api_key_plaintext。
anthropic_api_key_plaintext	以纯文本字符串形式提供的 Anthropic API 密钥。 如果希望使用 Azure Databricks 机密来引用密钥，请参阅 anthropic_api_key。	必须使用以下字段之一来提供 API 密钥：anthropic_api_key 或 anthropic_api_key_plaintext。

Azure OpenAI

与直接 OpenAI 服务相比，Azure OpenAI 具有不同的功能。 有关概述，请参阅比较文档。

配置参数	说明	需要	默认
openai_api_key	使用 Azure 服务的 OpenAI API 密钥的 Azure Databricks 密钥参考。 如果希望直接粘贴 API 密钥，请参阅 openai_api_key_plaintext。	必须使用以下字段之一来提供 API 密钥：openai_api_key 或 openai_api_key_plaintext。
openai_api_key_plaintext	使用 Azure 服务且以纯文本字符串形式提供的 OpenAI API 密钥。 如果希望使用 Azure Databricks 机密来引用密钥，请参阅 openai_api_key。	必须使用以下字段之一来提供 API 密钥：openai_api_key 或 openai_api_key_plaintext。
openai_api_type	要验证访问令牌，请使用 azure。	是
openai_api_base	Azure 提供的 Azure OpenAI API 服务的基 URL。	是
openai_api_version	要利用的 Azure OpenAI 服务的版本（按日期指定）。	是
openai_deployment_name	Azure OpenAI 服务的部署资源的名称。	是
openai_organization	用于指定 OpenAI 中的组织的可选字段。	否

如果要将 Azure OpenAI 与 Microsoft Entra ID 配合使用，请在终结点配置中使用以下参数。

配置参数	说明	需要	默认
microsoft_entra_tenant_id	Microsoft Entra ID 身份验证的租户 ID。	是
microsoft_entra_client_id	Microsoft Entra ID 身份验证的客户端 ID。	是
microsoft_entra_client_secret	用于 Microsoft Entra ID 身份验证的客户端密码的 Azure Databricks 密钥参考。 如果希望直接粘贴客户端密码，请参阅 microsoft_entra_client_secret_plaintext。	必须使用以下字段之一来提供 API 密钥：microsoft_entra_client_secret 或 microsoft_entra_client_secret_plaintext。
microsoft_entra_client_secret_plaintext	用于 Microsoft Entra ID 身份验证且以纯文本字符串形式提供的客户端密码。 如果希望使用 Azure Databricks 机密来引用密钥，请参阅 microsoft_entra_client_secret。	必须使用以下字段之一来提供 API 密钥：microsoft_entra_client_secret 或 microsoft_entra_client_secret_plaintext。
openai_api_type	要使用 Microsoft Entra ID 进行身份验证，请使用 azuread。	是
openai_api_base	Azure 提供的 Azure OpenAI API 服务的基 URL。	是
openai_api_version	要利用的 Azure OpenAI 服务的版本（按日期指定）。	是
openai_deployment_name	Azure OpenAI 服务的部署资源的名称。	是
openai_organization	用于指定 OpenAI 中的组织的可选字段。	否

以下示例演示如何使用 Azure OpenAI 创建终结点：

client.create_endpoint(
    name="openai-chat-endpoint",
    config={
        "served_entities": [{
            "external_model": {
                "name": "gpt-3.5-turbo",
                "provider": "openai",
                "task": "llm/v1/chat",
                "openai_config": {
                    "openai_api_type": "azure",
                    "openai_api_key": "{{secrets/my_openai_secret_scope/openai_api_key}}",
                    "openai_api_base": "https://my-azure-openai-endpoint.openai.azure.com",
                    "openai_deployment_name": "my-gpt-35-turbo-deployment",
                    "openai_api_version": "2023-05-15"
                }
            }
        }]
    }
)

Google Cloud Vertex AI

配置参数	说明	需要	默认
private_key	有权访问 Google Cloud Vertex AI 服务的服务帐户私钥的 Azure Databricks 密钥参考。 请参阅管理服务帐户密钥的最佳做法。 如果希望直接粘贴 API 密钥，请参阅 private_key_plaintext。	必须使用以下字段之一来提供 API 密钥：private_key 或 private_key_plaintext。
private_key_plaintext	有权访问 Google Cloud Vertex AI 服务且以纯文本密钥形式提供的服务帐户私钥。 请参阅管理服务帐户密钥的最佳做法。 如果希望使用 Azure Databricks 机密来引用密钥，请参阅 private_key。	必须使用以下字段之一来提供 API 密钥：private_key 或 private_key_plaintext。
region	这是 Google Cloud Vertex AI 服务的区域。 有关更多详细信息，请参阅支持的区域。 某些模型仅在特定区域中可用。	是
project_id	这是与服务帐户关联的 Google Cloud 项目 ID。	是

Amazon Bedrock

若要将 Amazon Bedrock 用作外部模型提供商，客户需要确保在指定的 AWS 区域中启用 Bedrock，并且指定的 AWS 密钥对具有与 Bedrock 服务交互的适当权限。 有关详细信息，请参阅 AWS 标识和访问管理。

配置参数	说明	需要	默认
aws_region	要使用的 AWS 区域。 其中必须启用 Bedrock。	是
aws_access_key_id	有权与 Bedrock 服务交互的 AWS 访问密钥 ID 的 Azure Databricks 密钥参考。 如果希望直接粘贴 API 密钥，请参阅 aws_access_key_id_plaintext。	必须使用以下字段之一来提供 API 密钥：aws_access_key_id 或 aws_access_key_id_plaintext。
aws_access_key_id_plaintext	有权与 Bedrock 服务交互且以纯文本字符串形式提供的 AWS 访问密钥 ID。 如果希望使用 Azure Databricks 机密来引用密钥，请参阅 aws_access_key_id。	必须使用以下字段之一来提供 API 密钥：aws_access_key_id 或 aws_access_key_id_plaintext。
aws_secret_access_key	有权与 Bedrock 服务交互且与访问密钥 ID 配对的 AWS 机密访问密钥的 Azure Databricks 密钥参考。 如果希望直接粘贴 API 密钥，请参阅 aws_secret_access_key_plaintext。	必须使用以下字段之一来提供 API 密钥：aws_secret_access_key 或 aws_secret_access_key_plaintext。
aws_secret_access_key_plaintext	与访问密钥 ID 配对的 AWS 机密访问密钥，它有权与 Bedrock 服务交互且以纯文本字符串形式提供。 如果希望使用 Azure Databricks 机密来引用密钥，请参阅 aws_secret_access_key。	必须使用以下字段之一来提供 API 密钥：aws_secret_access_key 或 aws_secret_access_key_plaintext。
bedrock_provider	Amazon Bedrock 中的基础提供商。 支持的值（不区分大小写）包括：Anthropic、Cohere、AI21Labs、Amazon	是

以下示例演示了如何使用 Amazon Bedrock 和访问密钥创建终结点。

client.create_endpoint(
    name="bedrock-anthropic-completions-endpoint",
    config={
        "served_entities": [
            {
                "external_model": {
                    "name": "claude-v2",
                    "provider": "amazon-bedrock",
                    "task": "llm/v1/completions",
                    "amazon_bedrock_config": {
                        "aws_region": "<YOUR_AWS_REGION>",
                        "aws_access_key_id": "{{secrets/my_amazon_bedrock_secret_scope/aws_access_key_id}}",
                        "aws_secret_access_key": "{{secrets/my_amazon_bedrock_secret_scope/aws_secret_access_key}}",
                        "bedrock_provider": "anthropic",
                    },
                }
            }
        ]
    },
)

如果存在 AWS 权限问题，Databricks 建议使用 Amazon Bedrock API 直接验证凭据。

AI21 Labs

配置参数	说明	需要	默认
ai21labs_api_key	AI21 Labs API 密钥的 Azure Databricks 密钥参考。 如果希望直接粘贴 API 密钥，请参阅 ai21labs_api_key_plaintext。	必须使用以下字段之一来提供 API 密钥：ai21labs_api_key 或 ai21labs_api_key_plaintext。
ai21labs_api_key_plaintext	以纯文本字符串形式提供的 AI21 Labs API 密钥。 如果希望使用 Azure Databricks 机密来引用密钥，请参阅 ai21labs_api_key。	必须使用以下字段之一来提供 API 密钥：ai21labs_api_key 或 ai21labs_api_key_plaintext。

在终结点上配置 AI 网关

还可以配置终结点以启用 Mosaic AI 网关 功能，例如速率限制、使用情况跟踪和防护措施。

请参阅在模型服务终结点上配置 AI 网关。

查询外部模型终结点

创建外部模型终结点后，即可接收来自用户的流量。

可以使用 OpenAI 客户端、REST API 或 MLflow 部署 SDK 向终结点发送评分请求。

• 请参阅 POST /serving-endpoints/{name}/invocations 中评分请求的标准查询参数。
• 查询生成 AI 模型

以下示例使用 OpenAI 客户端查询由 Anthropic 托管的 claude-2 完成模型。 若要使用 OpenAI 客户端，请在 model 字段中填充托管着你要查询的模型的模型服务终结点的名称。

此示例使用以前创建的终结点 anthropic-completions-endpoint，该终结点是为访问 Anthropic 模型提供商提供的外部模型而配置的。 了解如何创建外部模型终结点。

有关你可以查询的其他模型及其提供商，请参阅支持的模型。

import os
import openai
from openai import OpenAI

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

completion = client.completions.create(
  model="anthropic-completions-endpoint",
  prompt="what is databricks",
  temperature=1.0
)
print(completion)

预期的输出响应格式：

{
"id": "123", # Not Required
"model": "anthropic-completions-endpoint",
"choices": [
  {
    "text": "Hello World!",
    "index": 0,
    "logprobs": null, # Not Required
    "finish_reason": "length" # Not Required
  }
],
"usage": {
  "prompt_tokens": 8,
  "total_tokens": 8
  }
}

其他查询参数

作为查询的一部分，可以传递终结点的提供商支持的任何其他参数。

例如：

• logit_bias（受 OpenAI、Cohere 支持）。
• top_k（受 Anthropic、Cohere 支持）。
• frequency_penalty（受 OpenAI、Cohere 支持）。
• presence_penalty（受 OpenAI、Cohere 支持）。
• stream（受 OpenAI、Anthropic、Cohere、Amazon Bedrock for Anthropic 支持）。 这仅适用于聊天和补全请求。

外部模型的网络连接配置支持

对 外部模型（包括 Azure 专用链接）的网络连接配置（NCC） 的支持目前为 专用预览版。 请联系你的 Databricks 帐户团队以参与预览版。

限制

根据你选择的外部模型，配置可能会导致在数据来源区域外处理数据。 请参阅模型服务限制和区域。

其他资源

• 教程：创建外部模型终结点以查询 OpenAI 模型。
• 查询生成 AI 模型。