Mosaic AI 模型服務中的外部模型

重要

本文中的程式碼範例示範公開預覽版 MLflow 部署 CRUD API 的使用方式。

本文說明 Mosaic AI 模型服務中的外部模型，包括其支援的模型提供者和限制。

什麼是外部模型？

重要

你現在可以在服務外部模型的模型服務端點上設定 Mosaic AI 閘道。 AI 閘道為這些模型服務端點實現了治理、監視和生產就緒。 請參閱 Mosaic AI 閘道。

外部模型是指託管於 Databricks 外部的第三方模型。 外部模型受模型服務支援，可讓你簡化組織內各種大型語言模型 (LLM) 提供者的使用和管理，例如 OpenAI 和 Anthropic。 你也可以使用 Mosaic AI 模型作為提供者來提供自訂模型，為這些端點提供速率限制。 作為此支援的一部分，模型服務會提供高階介面，藉由提供統一端點來處理特定 LLM 相關要求，簡化與這些服務的互動。

此外，外部模型的 Azure Databricks 支援也提供了集中式認證管理。 藉由將 API 金鑰儲存在一個安全的位置，組織可以增強其安全性態勢，將整個系統內敏感性 API 金鑰的暴露風險降至最低。 它也有助於防止在程式碼中公開這些金鑰，或要求終端使用者安全地管理金鑰。

請參閱教學課程：建立外部模型端點來查詢 OpenAI 模型，以取得有關使用 MLflow 部署 SDK 建立外部模型端點以及查詢由這些端點服務的受支援模型的逐步指導。 如需如何使用服務 UI 和 REST API 的指示，請參閱下列指南：

• 建立自訂模型服務端點
• 查詢產生 AI 模型

需求

• 模型提供者的 API 金鑰或驗證欄位。
• 外部模型支援的區域中的 Databricks 工作區。

模型提供者

模型服務中的外部模型是為支援各種模型提供者而設計的。 提供者代表機器學習模型的來源，例如 OpenAI、Anthropic 等。 每個提供者都有其特定的特性和組態，這些特性和組態會封裝在外部模型端點組態的 external_model 欄位中。

支援下列提供者：

• openai：適用於 OpenAI 所提供的模型，以及使用 AAD 且適用於 Azure OpenAI 和 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 模型服務端點。 請參閱端點組態。

如果要要求此處未列出的提供者支援，請連絡你的 Databricks 帳戶團隊。

支援的模型

你選擇的模型會直接影響你從 API 呼叫取得的回覆結果。 因此，請選擇符合使用案例需求的模型。 例如，如果要產生交談式回覆，你可以選擇聊天模型。 相反地，如果要產生文字內嵌，你可以選擇內嵌模型。

下表提供所支援模型和對應端點類型的非詳盡清單。 在任何新發行的模型類型變為適用於指定供應者時為其設定端點時，下列模型關聯都可用來作為實用指南。 客戶應負責確保遵循適用的模型授權。

注意

隨著 LLM 的快速發展，不保證這份清單始終都是最新的。

模型提供者	llm/v1/completions	llm/v1/chat	llm/v1/embeddings
OpenAI**	- gpt-3.5-turbo-instruct - babbage-002 - davinci-002	- 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 - gpt-4-vision-preview - gpt-4-1106-vision-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 模型服務	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

** 模型提供者支援微調完成和聊天模型。 如果要查詢微調的模型，請使用微調模型的名稱填入 name 組態的 external model 欄位。

† 模型提供者支援自訂完成模型。

使用在 Mosaic AI 模型服務端點上提供的模型

針對 llm/v1/completions、llm/v1/chat 和 llm/v1/embeddings 端點類型，支援 Mosaic AI 模型服務端點作為提供者。 這些端點必須接受標示為必要的標準查詢參數，而根據 Mosaic AI 模型服務端點是否支援，可能會忽略其他參數。

有關標準查詢參數，請參閱 API 參考中的 POST /serving-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。

參數	Description
name	模型要使用的的名稱。 例如，gpt-3.5-turbo 對應 OpenAI 的 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 建立外部模型端點的範例。 在此範例中，傳送至完成端點的要求會轉寄至 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

組態參數	描述	是必要欄位	預設
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 類型。	No	openai
openai_api_base	OpenAI API 的基底 URL。	No	https://api.openai.com/v1
openai_api_version	選用欄位，指定 OpenAI API 版本。	No
openai_organization	選用欄位，指定 OpenAI 中的組織。	No

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。	No

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 進行存取權杖驗證。	Yes
openai_api_base	Azure 提供的 Azure OpenAI API 服務的基底 URL。	Yes
openai_api_version	要利用的 Azure OpenAI 服務版本，按日期指定。	Yes
openai_deployment_name	Azure OpenAI 服務的部署資源名稱。	Yes
openai_organization	選用欄位，指定 OpenAI 中的組織。	No

如果你搭配 Microsoft Entra ID 使用 Azure OpenAI，請在端點組態中使用下列參數。

組態參數	描述	是必要欄位	預設
microsoft_entra_tenant_id	Microsoft Entra ID 驗證的租用戶 ID。	Yes
microsoft_entra_client_id	Microsoft Entra ID 驗證的用戶端 ID。	Yes
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	使用 azuread，藉由 Microsoft Entra ID 進行驗證。	Yes
openai_api_base	Azure 提供的 Azure OpenAI API 服務的基底 URL。	Yes
openai_api_version	要利用的 Azure OpenAI 服務版本，按日期指定。	Yes
openai_deployment_name	Azure OpenAI 服務的部署資源名稱。	Yes
openai_organization	選用欄位，指定 OpenAI 中的組織。	No

下列範例示範如何使用 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 服務區域。 請參閱支援的區域以取得詳細資訊。 一些模型僅在特定區域可用。	Yes
project_id	這是服務帳戶所關聯的 Google Cloud 專案 ID。	Yes

Amazon Bedrock

如果要使用 Amazon Bedrock 作為外部模型提供者，客戶必須確定 Bedrock 已在指定的 AWS 區域中啟用，而且指定的 AWS 金鑰組具有適當的權限與 Bedrock 服務互動。 如需詳細資訊，請參閱 AWS 身分識別和存取權管理。

組態參數	描述	是必要欄位	預設
aws_region	要使用的 AWS 區域。 Bedrock 必須在那裡啟用。	Yes
aws_access_key_id	AWS 存取金鑰 ID (具有與 Bedrock 服務互動的權限) 的 Azure Databricks 祕密金鑰參考。 如果你偏好直接貼上 API 金鑰，請參閱 aws_access_key_id_plaintext。	你必須使用下列其中一個欄位提供 API 金鑰：aws_access_key_id 或 aws_access_key_id_plaintext。
aws_access_key_id_plaintext	AWS 存取金鑰 ID，其具有與以純文字字串形式提供的 Bedrock 服務互動的權限。 如果你偏好使用 Azure Databricks 祕密來參考金鑰，請參閱 aws_access_key_id。	你必須使用下列其中一個欄位提供 API 金鑰：aws_access_key_id 或 aws_access_key_id_plaintext。
aws_secret_access_key	與存取金鑰 ID 配對之 AWS 祕密存取金鑰 (具有與 Bedrock 服務互動的權限) 的 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	Yes

下列範例示範如何使用存取金鑰在 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 模型提供者的外部模型而設定的端點 anthropic-completions-endpoint。 請參閱如何建立外部模型端點。

如需你可以查詢的其他模型及其提供者，請參閱支援的模型 。

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 支援)。 這僅適用於聊天和完成要求。

限制

根據你選擇的外部模型，你的設定可能會導致資料在資料發源區域之外進行處理。 請參閱模型服務限制和區域。

其他資源

• 教學課程：建立外部模型端點來查詢 OpenAI 模型。
• 查詢產生 AI 模型。