外部模型

注释

本页介绍直接在模型服务终结点上配置的外部模型。 要将外部模型提供者注册为可跨工作区查询并跟踪支出的受管控 Unity 目录对象,请参见 Databricks 外部的模型提供者。

Important

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

本文介绍 Model Services 中的外部模型,包括其支持的模型提供程序和限制。

什么是外部模型?

Important

现在,您可以在提供外部模型服务的模型服务端点上配置 AI 网关。 AI 网关为这些模型服务终结点提供治理、监视和生产就绪功能。 参见 Unity Gateway 的 AI 治理。

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

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

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

要求

模型提供商

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-serving:用于具有兼容架构定义的模型服务端点。 请参阅终结点配置。
  • custom:适用于自定义代理背后的与 OpenAI API 兼容、但 Databricks 不直接支持的备选提供商或模型。

若要请求此处未列出的提供程序的支持,请尝试使用 custom 提供程序选项或联系 Databricks 帐户团队。

支持的模型

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

请参阅 支持的模型。

使用模型服务终结点上提供的模型

、llm/v1/completions 和 llm/v1/chat 终结点类型支持将llm/v1/embeddings作为提供者。 这些终结点必须接受标记为必需的标准查询参数,而其他参数可能会忽略,具体取决于模型服务终结点是否支持它们。

有关标准查询参数,请参阅 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
  }
}

终结点配置

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

对于为终结点提供服务的外部模型,必须在终结点配置的 external_model 部分中包括 served_entities 字段及其参数。 如果在服务终结点中配置多个外部模型,则必须提供 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。 这会作为请求正文的一部分传入,其中包含相应的密钥:"model"。
provider 指定此模型的提供商的名称。 此字符串值必须与支持的外部模型 提供商 相对应。 例如,openai 对应 OpenAI 的 GPT-3.5 模型。
task 任务对应于所需的语言模型交互类型。 支持的任务有“llm/v1/completions”、“llm/v1/chat”、“llm/v1/embeddings”。
<provider>_config 包含模型所需的任何其他配置详细信息。 这包括指定 API 基 URL 和 API 密钥。 请参阅配置终结点的提供商。
如果使用 custom 提供商,请将此参数指定为 custom_provider_config。

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

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

配置参数 Description 必需 默认
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

配置参数 Description 必需 默认
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

配置参数 Description 必需 默认
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 具有不同的功能。 有关概述,请参阅比较文档。

配置参数 Description 必需 默认
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 配合使用,请在终结点配置中使用以下参数。 Databricks 传递 https://cognitiveservices.azure.com/ 作为 Microsoft Entra ID 令牌的默认作用域。

配置参数 Description 必需 默认
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"
                }
            }
        }]
    }
)

谷歌云顶点人工智能

配置参数 Description 必需 默认
private_key 可访问 Google Cloud Vertex AI Service 的服务账号的完整服务账号密钥 JSON 文件的 Azure Databricks 密钥引用。 这是从 Google Cloud 下载的 JSON 密钥文件的全部内容,而不仅仅是 private_key 字段。 请参阅管理服务帐户密钥的最佳做法。 如果希望直接粘贴密钥,请参阅 private_key_plaintext。 必须使用以下字段之一提供密钥: private_key 或 private_key_plaintext。
private_key_plaintext 有权访问 Google Cloud Vertex AI 服务的服务帐户的完整服务帐户密钥 JSON,作为纯文本机密提供。 这是从 Google Cloud 下载的 JSON 密钥文件的全部内容,而不仅仅是 private_key 字段。 请参阅管理服务帐户密钥的最佳做法。 如果希望使用 Azure Databricks 机密来引用密钥,请参阅 private_key。 必须使用以下字段之一提供密钥: private_key 或 private_key_plaintext。
region 这是 Google Cloud Vertex AI 服务的区域。 有关更多详细信息,请参阅支持的区域。 某些模型仅在特定区域中可用。 是的
project_id 这是与服务帐户关联的 Google Cloud 项目 ID。 是的

亚马逊基岩

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

配置参数 Description 必需 默认
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",
                    },
                }
            }
        ]
    },
)

注释

若要通过 AI Gateway 使用现有的 Amazon Bedrock 护栏与 Amazon Bedrock 模型搭配,可以将 X-Amzn-Bedrock-GuardrailIdentifier 标头设置为护栏 ARN 选择,并根据需要设置 X-Amzn-Bedrock-GuardrailVersion。 这些标题被转发到亚马逊贝德洛克。

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

AI21 实验室

配置参数 Description 必需 默认
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。

自定义提供程序

Important

若要使用自定义提供程序模型,它必须兼容 OpenAI API。

配置参数 Description 必需 默认
custom_provider_url 自定义提供商的模型所在位置的 URL。 URL 必须指向特定的 API 终结点;例如, https://api.provider.com/chat/completions. 是的
bearer_token_auth 如果自定义提供程序使用持有者令牌身份验证,请指定必填字段。 必须使用以下字段之一提供身份验证方法:bearer_token_auth 或 api_key_auth。
token 用于持有者身份验证的令牌的 Azure Databricks 密钥参考。 此参数必须嵌套在 bearer_token_auth 下。 如果希望直接粘贴 API 密钥,请参阅 token_plaintext。 如果使用持有者身份验证,则必须使用以下字段之一提供 API 密钥:token 或 token_plaintext。
token_plaintext 持有者身份验证的令牌作为纯文本字符串提供。 此参数必须嵌套在 bearer_token_auth 下。 如果希望使用 Azure Databricks 机密来引用密钥,请参阅 token。 如果使用持有者身份验证,则必须使用以下字段之一提供 API 密钥:token 或 token_plaintext。
api_key_auth 如果自定义提供程序使用 API 密钥身份验证,请指定必填字段。 必须使用以下字段之一提供身份验证方法:bearer_token_auth 或 api_key_auth。
key API 密钥身份验证的密钥。 此参数必须嵌套在 api_key_auth 下 是,使用 API 密钥身份验证时。
value 用于 API 密钥身份验证的值的 Azure Databricks 密钥参考。 如果希望直接粘贴 API 密钥,请参阅 value_plaintext。 如果使用 API 密钥身份验证,则必须使用以下字段之一提供 API 密钥:value 或 value_plaintext。
value_plaintext API 密钥身份验证的值作为纯文本字符串提供。 如果希望使用 Azure Databricks 机密来引用密钥,请参阅 value。 如果使用 API 密钥身份验证,则必须使用以下字段之一提供 API 密钥:value 或 value_plaintext。

以下示例演示如何使用“持有者身份验证”创建具有自定义提供商的终结点:

client.create_endpoint(
    name="custom-provider-completions-endpoint",
    config={
        "served_entities": [
            {
                "external_model": {
                    "name": "custom-provider-model",
                    "provider": "custom",
                    "task": "llm/v1/chat",
                    "custom_provider_config": {
                        "custom_provider_url": "https://api.provider.com/chat/completions",
                        "bearer_token_auth": {
                            "token": "{{secrets/my_custom_provider_secret_scope/custom_provider_token}}"
                        }
                    }
                }
            }
        ]
    },
)

以下示例演示如何使用“API 密钥身份验证”创建具有自定义提供商的终结点:

client.create_endpoint(
    name="custom-provider-completions-endpoint",
    config={
        "served_entities": [
            {
                "external_model": {
                    "name": "custom-provider-model",
                    "provider": "custom",
                    "task": "llm/v1/chat",
                    "custom_provider_config": {
                        "custom_provider_url": "https://my-custom-provider.com",
                        "api_key_auth": {
                            "key": "X-API-KEY",
                            "value": "{{secrets/my_custom_provider_secret_scope/custom_provider_api_key}}"
                        }
                    }
                }
            }
        ]
    },
)

在终结点上配置 AI 网关

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

参见 配置模型服务端点治理(旧版)。

查询外部模型终结点

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

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

以下示例使用 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 支持)。 这仅适用于聊天和补全请求。
  • tools(由 OpenAI、Anthropic 和 Amazon Bedrock for Anthropic 支持)。 这仅适用于聊天和补全请求。 此参数允许集成外部功能,包括 Computer Use (beta) for Anthropic 和 Amazon Bedrock for Anthropic。 请参阅 在 Azure Databricks 上调用函数。

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

外部模型(包括 Azure 专用链接)对网络连接配置(NCC)的支持处于公开预览阶段。 要通过 Azure 专用链接 连接到外部模型提供商,请配置一个带有私有端点的 NCC,并将其附加到你的工作区。 请参阅 配置与 Azure 资源的专用连接。

Limitations

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

其他资源