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

重要

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

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

什麼是外部模型？

重要

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

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

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

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

• 建立自訂模型服務端點
• 使用基礎模型

需求

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

模型提供者

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

支援下列提供者：

• openai：適用於 OpenAI 提供的模型，以及 Azure 的整合，包括 Azure OpenAI 和使用 AAD 的 Azure OpenAI。
• anthropic：適用於 Anthropic 所提供的模型。
• cohere：適用於 Cohere 所提供的模型。
• amazon-bedrock：適用於 Amazon Bedrock 所提供的模型。
• google-cloud-vertex-ai：適用於 Google Cloud Vertex AI 所提供的模型。
• databricks-model-serving：適用於具有相容結構描述的 Mosaic AI 模型服務端點。 請參閱端點組態。
• 自定義：適用於 OpenAI API 相容但不被 Databricks 直接支援的自定義代理背後的替代供應商或模型。

若要要求此處未列出的提供者支援，請嘗試使用 自定義 提供者選項，或連絡您的 Databricks 帳戶小組。

支援的模型

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

請參閱 支援的模型。

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

支援的 Mosaic AI 模型服務端點 作為提供者，適用於 llm/v1/completions、llm/v1/chat 和 llm/v1/embeddings 端點類型。 這些端點必須接受標示為必要的標準查詢參數，而根據馬賽克 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": [
        1.0023064255,
        -0.009327292,
        .... # (1536 floats total for ada-002)
        -0.0028842222,
      ],
      "index": 0
    },
    {
      "embedding": [
        1.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/service-endpoints。

參數	說明書
name	要使用的模型名稱。 例如， gpt-3.5-turbo 針對 OpenAI 的 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_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 API 金鑰在使用 OpenAI 服務時作為純文字字串提供。 如果你偏好使用 Azure Databricks Secrets 來參考金鑰，請參閱 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 Secrets 來參考金鑰，請參閱 cohere_api_key。	你必須使用下列其中一個欄位提供 API 金鑰：cohere_api_key 或 cohere_api_key_plaintext。
cohere_api_base	Cohere 服務的基底 URL。	否

人類學的

組態參數	描述	必須	預設
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 Secrets 來參考金鑰，請參閱 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	OpenAI API 金鑰是以純文字字串形式透過 Azure 服務提供的。 如果你偏好使用 Azure Databricks Secrets 來參考金鑰，請參閱 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 令牌的預設範圍。

組態參數	描述	必須	預設
microsoft_entra_tenant_id	Microsoft Entra 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 Secrets 來參考金鑰，請參閱 microsoft_entra_client_secret。	你必須使用下列其中一個欄位提供 API 金鑰：microsoft_entra_client_secret 或 microsoft_entra_client_secret_plaintext。
openai_api_type	使用 azuread，藉由 Microsoft Entra ID 進行驗證。	是的
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 頂點 AI

組態參數	描述	必須	預設
private_key	Azure Databricks 祕密金鑰參考，供具有 Google Cloud Vertex AI 服務存取權的服務帳戶的私鑰使用。 請參閱管理服務帳戶金鑰的最佳做法。 如果你偏好直接貼上 API 金鑰，請參閱 private_key_plaintext。	你必須使用下列其中一個欄位提供 API 金鑰：private_key 或 private_key_plaintext。
private_key_plaintext	服務帳戶的私鑰以純文字秘密的形式提供，這個私鑰可以存取 Google Cloud Vertex AI 服務。 請參閱管理服務帳戶金鑰的最佳做法。 如果你偏好使用 Azure Databricks Secrets 來參考金鑰，請參閱 private_key。	你必須使用下列其中一個欄位提供 API 金鑰：private_key 或 private_key_plaintext。
region	這是 Google Cloud Vertex AI 服務區域。 請參閱支援的區域以取得詳細資訊。 一些模型僅在特定區域可用。	是的
project_id	這是服務帳戶所關聯的 Google Cloud 專案 ID。	是的

Amazon Bedrock

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

組態參數	描述	必須	預設
aws_region	要使用的 AWS 區域。 必須在那裡啟用 Bedrock。	是的
aws_access_key_id	Azure Databricks 祕密金鑰參考，用於 AWS 存取金鑰 ID，這些 ID 具有與 Bedrock 服務互動的權限。 如果你偏好直接貼上 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 Secrets 來參考金鑰，請參閱 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 Secrets 來參考金鑰，請參閱 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 Secrets 來參考金鑰，請參閱 ai21labs_api_key。	你必須使用下列其中一個欄位提供 API 金鑰：ai21labs_api_key 或 ai21labs_api_key_plaintext。

自定義提供者

組態參數	描述	必須	預設
custom_provider_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 閘道

你也可以設定端點來啟用 Mosaic AI 閘道功能，例如速率限制、使用量追蹤和護欄。

請參閱在模型服務端點上設定 AI 閘道。

查詢外部模型端點

建立外部模型端點之後，即可接收來自使用者的流量。

你可以使用 OpenAI 用戶端、REST API 或 MLflow 部署 SDK，將評分要求傳送至端點。

• 請參閱 POST /serving-endpoints/{name}/invocations中的評分請求標準查詢參數。
• 使用基礎模型

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

• tools（由 OpenAI、Anthropic 和 Amazon Bedrock 支持）。 這僅適用於聊天和完成要求。 此參數允許整合外部功能，包括供 Anthropic 使用的 電腦使用（beta） 和供 Anthropic 使用的 Amazon Bedrock。 請參閱 Azure Databricks 上的函式呼叫。

外部模型的網路連線設定支援

對於外部模型的網路連線設定（NCC）支援，包括 Azure 私人鏈接，已進入公開預覽階段。 若要參與預覽，請聯絡您的 Databricks 帳戶團隊。

限制

根據您選擇的外部模型，您的設定可能會導致數據在數據產生所在的區域之外進行處理。 請參閱模型服務限制和區域。

其他資源

• 教學課程：建立外部模型端點來查詢 OpenAI 模型。
• 使用基礎模型。