Modelos externos no Model Serving
Experimente a nova Unity AI Gateway Beta
Uma nova experiência do Unity AI Gateway está disponível em Beta. O novo Unity AI Gateway é o plano de controle corporativo para governar o endpoint LLM e os agentes de codificação com recurso aprimorado. Consulte governança de AI com o Unity AI Gateway.
Os exemplos de código neste artigo demonstram o uso da API CRUD de Implantações do MLflow em visualização pública.
Este artigo descreve modelos externos no Model Serving, incluindo seus provedores de modelo compatíveis e limitações.
O que são modelos externos?
Agora você pode configurar o AI Gateway em endpoints de servindo modelo que servem modelos externos. O AI Gateway traz governança, monitoramento e prontidão para produção para esses endpoints de servindo modelo. Consulte Governança de AI com Unity AI Gateway.
Modelos externos são modelos de terceiros hospedados fora do Databricks. Apoiados pelo Model Serving, os modelos externos permitem otimizar o uso e o gerenciamento de vários provedores de modelos de linguagem grandes (LLM), como OpenAI e Anthropic, dentro de uma organização. Você também pode usar o Model Serving como um provedor para disponibilizar modelos personalizados, o que oferece limites de taxa para esses endpoints. Como parte deste suporte, o Model Serving oferece uma interface de alto nível que simplifica a interação com esses serviços, fornecendo um endpoint unificado para lidar com solicitações específicas relacionadas a LLM.
Além disso, o suporte do Databricks para modelos externos oferece gerenciamento centralizado de credenciais. Ao armazenar chaves API em um local seguro, as organizações podem aprimorar sua postura de segurança, minimizando a exposição de chaves API sensíveis em todo o sistema. Também ajuda a evitar a exposição dessas key no código ou exigir que os usuários finais gerenciar as key com segurança.
Consulte Tutorial: Crie endpoints de modelo externo para consultar modelos do OpenAI para obter orientações passo a passo sobre a criação de endpoints de modelo externo e a consulta de modelos suportados que são veiculados por esses endpoints usando o SDK de Implantações do MLflow. Consulte os seguintes guias para obter instruções sobre como usar a IU de veiculação e a API REST:
Requisitos
- API key ou campos de autenticação para o provedor do modelo.
- Workspace do Databricks em regiões compatíveis com modelos externos.
Provedores de modelos
Modelos externos no Model Serving são projetados para suportar uma variedade de provedores de modelos. Um provedor representa a origem dos modelos do machine learning, como OpenAI, Anthropic e assim por diante. Cada provedor possui suas características e configurações específicas que são encapsuladas no campo external_model da configuração de endpoint de modelo externo.
Os seguintes provedores são compatíveis:
- OpenAI : para modelos oferecidos por OpenAI e as integrações do Azure para Azure OpenAI e Azure OpenAI com AAD.
- Anthropic : Para modelos oferecidos pela Anthropic.
- cohere : Para modelos oferecidos por Cohere.
- amazon-bedrock : Para modelos oferecidos por Amazon Bedrock.
- google-cloud-vertex-ai : Para modelos oferecidos pelo Google Cloud Vertex AI.
- databricks-model-serving : Para endpoints de servindo modelo com esquemas compatíveis. Consulte Configuração de endpoint.
- personalizado : Para provedores alternativos ou modelos por trás de proxies personalizados que são compatíveis com a API da OpenAI, mas não são suportados diretamente pelo Databricks.
Para solicitar suporte para um provedor não listado aqui, tente usar a opção de provedor **personalizado** ou entre em contato com sua equipe de account Databricks.
Modelos compatíveis
O modelo que você escolher afeta diretamente os resultados das respostas que você obtém das chamadas da API. Portanto, escolha um modelo que se ajuste aos requisitos do seu caso de uso. Por exemplo, para gerar respostas conversacionais, você pode escolher um modelo de chat. Por outro lado, para gerar incorporações de texto, você pode escolher um modelo de incorporação.
Consulte Modelos compatíveis.
Utilize modelos servidos em endpoints de Model Serving
Endpoints de Model Serving como provedor são suportados para os tipos de endpoint llm/v1/completions, llm/v1/chat e llm/v1/embeddings. Esses endpoints devem aceitar os parâmetros de query padrão marcados como obrigatórios, enquanto outros parâmetros podem ser ignorados dependendo se o endpoint de Model Serving os suporta ou não.
Consulte POST /serving-endpoint/{name}/invocations na referência da API para parâmetros de consulta padrão.
Estes endpoints devem produzir respostas no seguinte formato OpenAI.
Para tarefas de conclusão:
{
"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
}
}
Para tarefas de chat:
{
"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
}
}
Para tarefas de incorporações:
{
"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
}
}
Configuração de endpoint
Para disponibilizar e consultar modelos externos, é preciso configurar um endpoint de disponibilização de modelo. Consulte Criar um endpoint de servindo modelo externo
Para um endpoint de servindo modelo externo, você deve incluir o campo external_model e seus parâmetros na seção served_entities da configuração do endpoint. Se você configurar vários modelos externos em um endpoint de serviço, deverá fornecer um traffic_config para definir a porcentagem de roteamento de tráfego para cada modelo externo.
O campo external_model define o modelo para o qual este endpoint encaminha as solicitações. Ao especificar um modelo, é fundamental que o provedor seja compatível com o modelo que você está solicitando. Por exemplo, openai como provedor é compatível com modelos como text-embedding-ada-002, mas outros provedores podem não ser. Se o modelo não for compatível com o provedor, o Databricks retornará um erro HTTP 4xx ao tentar rotear as solicitações para esse modelo.
A tabela abaixo resume os parâmetros do campo external_model. Veja POST /api/2.0/serving-endpoints para parâmetros de configuração de endpoint.
Parâmetro | Descrições |
|---|---|
| O nome do modelo a ser usado. Por exemplo, |
| Especifica o nome do provedor para este modelo. Este valor de strings deve corresponder a um provedor de modelo externo compatível. Por exemplo, |
| A tarefa corresponde ao tipo de interação do modelo de linguagem desejada. As tarefas suportadas são “llm/v1/completions”, “llm/v1/chat”, “llm/v1/embeddings”. |
| Contém quaisquer detalhes de configuração adicionais necessários para o modelo. Isso inclui especificar a URL base da API e a key de API. Consulte Configurar o provedor para um endpoint. Se estiver utilizando o provedor |
A seguir, um exemplo de criação de um endpoint de modelo externo usando a API create_endpoint(). Neste exemplo, uma solicitação enviada ao endpoint de conclusão é encaminhada ao modelo claude-2 fornecido por 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}}"
}
}
}
]
}
)
Configure o provedor para um endpoint
Ao criar um endpoint, você deve fornecer as configurações necessárias para o provedor de modelo especificado. As seções a seguir resumem os parâmetros de configuração de endpoint disponíveis para cada provedor de modelo.
A Databricks criptografa e armazena com segurança as credenciais fornecidas para cada provedor de modelo. Essas credenciais são excluídas automaticamente quando seu endpoint associado é excluído.
OpenAI
Parâmetro de Configuração | Descrição | Obrigatório | Padrão |
|---|---|---|---|
| A referência da chave secreta do Databricks para uma chave API OpenAI que usa o serviço OpenAI. Se preferir colar sua key API diretamente, consulte | Você deve fornecer uma key de API usando um dos seguintes campos: | |
| A key API da OpenAI usando o serviço da OpenAI fornecida como uma strings de texto simples. Se preferir referenciar sua chave usando Databricks Secrets, consulte | Você deve fornecer uma key de API usando um dos seguintes campos: | |
| Um campo opcional para especificar o tipo de API do OpenAI a ser usado. | Não |
|
| A URL base para a API da OpenAI. | Não |
|
| Um campo opcional para especificar a versão da API OpenAI. | Não | |
| Um campo opcional para especificar a organização na OpenAI. | Não |
Cohere
Parâmetro de Configuração | Descrição | Obrigatório | Padrão |
|---|---|---|---|
| A referência da chave secreta do Databricks para uma API key Cohere. Se preferir colar sua key API diretamente, consulte | Você deve fornecer uma key de API usando um dos seguintes campos: | |
| A key da API Cohere fornecida como uma strings de texto simples. Se preferir referenciar sua chave usando Databricks Secrets, consulte | Você deve fornecer uma key de API usando um dos seguintes campos: | |
| A URL base para o serviço Cohere. | Não |
Anthropic
Parâmetro de Configuração | Descrição | Obrigatório | Padrão |
|---|---|---|---|
| A referência de chave secreta Databricks para uma API key Anthropic. Se preferir colar sua key de API diretamente, consulte | Você deve fornecer uma key de API usando um dos seguintes campos: | |
| A chave da API do Anthropic fornecida como uma string de texto simples. Se preferir referenciar sua chave usando Databricks Secrets, consulte | Você deve fornecer uma key de API usando um dos seguintes campos: |
Azure OpenAI
O Azure OpenAI tem recursos distintos em comparação com o serviço OpenAI direto. Para obter uma visão geral, consulte a documentação de comparação.
Parâmetro de Configuração | Descrição | Obrigatório | Padrão |
|---|---|---|---|
| A referência de chave secreta do Databricks para uma key de API OpenAI usando o serviço Azure. Se preferir colar sua key API diretamente, consulte | Você deve fornecer uma key de API usando um dos seguintes campos: | |
| A key da API do OpenAI usando o serviço do Azure fornecida como uma strings de texto simples. Se preferir referenciar sua chave usando Databricks Secrets, consulte | Você deve fornecer uma key de API usando um dos seguintes campos: | |
| Utilize | Sim | |
| A URL base para o serviço da API OpenAI do Azure. | Sim | |
| A versão do serviço OpenAI do Azure a utilizar, especificada por uma data. | Sim | |
| O nome do recurso de implantação para o serviço Azure OpenAI. | Sim | |
| Um campo opcional para especificar a organização na OpenAI. | Não |
Se estiver usando o Azure OpenAI com o Microsoft Entra ID, use os seguintes parâmetros na configuração do seu endpoint. O Databricks passa https://cognitiveservices.azure.com/ como o escopo default para o token do Microsoft Entra ID.
Parâmetro de Configuração | Descrição | Obrigatório | Padrão |
|---|---|---|---|
| O ID do tenant para autenticação do Microsoft Entra ID. | Sim | |
| O ID do cliente para autenticação do Microsoft Entra ID. | Sim | |
| A referência da chave secreta do Databricks para um segredo de cliente utilizada para autenticação do Microsoft Entra ID. Caso prefira colar o seu segredo de cliente diretamente, consulte | Você deve fornecer uma key de API usando um dos seguintes campos: | |
| O segredo do cliente usado para a autenticação do Microsoft Entra ID fornecido como uma strings de texto simples. Se preferir referenciar sua chave usando Databricks Secrets, consulte | Você deve fornecer uma key de API usando um dos seguintes campos: | |
| Use | Sim | |
| A URL base para o serviço da API OpenAI do Azure. | Sim | |
| A versão do serviço OpenAI do Azure a utilizar, especificada por uma data. | Sim | |
| O nome do recurso de implantação para o serviço Azure OpenAI. | Sim | |
| Um campo opcional para especificar a organização na OpenAI. | Não |
O exemplo a seguir demonstra como criar um endpoint com 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"
}
}
}]
}
)
Vertex AI do Google Cloud
Parâmetro de Configuração | Descrição | Obrigatório | Padrão |
|---|---|---|---|
| A referência de chave secreta do Databricks para o arquivo JSON completo da service account key do serviço account que tem acesso ao serviço Google Cloud Vertex AI. Este é todo o conteúdo do arquivo JSON key baixado do Google Cloud, não apenas o campo | Você deve fornecer uma key utilizando um dos seguintes campos: | |
| O JSON completo da chave da account de serviço que tem acesso ao Serviço Vertex AI do Google Cloud, fornecido como um segredo de texto simples. Este é todo o conteúdo do arquivo JSON key baixado do Google Cloud, não apenas o campo | Você deve fornecer uma key utilizando um dos seguintes campos: | |
| Esta é a região para o serviço do Google Cloud Vertex AI. Consulte regiões compatíveis para mais detalhes. Alguns modelos estão disponíveis apenas em regiões específicas. | Sim | |
| Este é o ID do projeto do Google cloud ao qual a account de serviço está associada. | Sim |
Amazon Bedrock
Para usar o Amazon Bedrock como um provedor de modelo externo, os clientes precisam garantir que o Bedrock esteja habilitado na região AWS especificada, e que o par de chaves AWS especificado tenha as permissões apropriadas para interagir com os serviços do Bedrock. Para mais informações, consulte AWS Identity and Access Management.
O Amazon Bedrock suporta vários mecanismos de autenticação. Exatamente um dos seguintes deve ser fornecido:
- Uma Unity Catalog credencial de serviço que faz referência a uma AWS IAM role
- Um **instance profile** da AWS
- Chaves de acesso da AWS (usando Databricks Secrets ou texto simples)
Se as chaves de acesso forem usadas, **ambos** um ID da chave de acesso e uma chave de acesso secreta são necessários.
Parâmetro de configuração | Descrição | Obrigatório | Padrão |
|---|---|---|---|
| A região da AWS a ser usada. O Amazon Bedrock deve ser habilitado nesta região. | Sim | |
| Referência a uma credencial de serviço do Unity Catalog usada pela entidade atendida para acessar recursos da AWS. A credencial deve fazer referência a um IAM role da AWS. | Não | |
| Nome do Recurso da Amazon (ARN) do instance profile usado pela entidade servida para acessar recursos da AWS. | Não | |
| ID da key de acesso da AWS usado pela entidade servida para acessar recursos da AWS, fornecido usando uma referência secreta do Databricks. | Não | |
| ID da key de acesso da AWS usado pela entidade servida para acessar recurso da AWS, fornecido como uma string de texto simples. | Não | |
| Key de acesso secreta da AWS usada pela entidade servida para acessar recurso da AWS, associada ao ID da key de acesso e fornecida usando uma referência secreta do Databricks. | Não | |
| Key de acesso secreta da AWS usada pela entidade servida para acessar recurso da AWS, emparelhada com o ID da key de acesso e fornecida como uma strings de texto simples. | Não | |
| O fornecedor subjacente no Amazon Bedrock. Valores compatíveis (não diferenciam maiúsculas de minúsculas): Anthropic, Cohere, AI21Labs, Amazon. | Sim |
O exemplo a seguir demonstra como criar um endpoint com Amazon Bedrock usando um instance profile. Se preferir usar key de acesso, use aws_access_key_id e aws_secret_access_key. Se preferir usar uma credencial de serviço, use uc_service_credential_name.
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>",
"uc_service_credential_name": "<YOUR_UC_SERVICE_CREDENTIAL_NAME>", ## Remove if using other authentication methods
# "instance_profile_arn": "<YOUR_AWS_INSTANCE_PROFILE_ARN>",
# "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",
},
}
}
]
},
)
Para usar as proteções existentes do Amazon Bedrock com modelos do Amazon Bedrock através do AI Gateway, pode definir o cabeçalho X-Amzn-Bedrock-GuardrailIdentifier para o ARN da proteção de sua escolha e definir X-Amzn-Bedrock-GuardrailVersion conforme necessário. Estes cabeçalhos são encaminhados para o Amazon Bedrock.
Se houver problemas de permissão da AWS, o Databricks recomenda que você verifique as credenciais diretamente com a API do Amazon Bedrock.
AI21 Labs
Parâmetro de Configuração | Descrição | Obrigatório | Padrão |
|---|---|---|---|
| A referência da chave secreta Databricks para uma key API da AI21 Labs. Se preferir colar sua key API diretamente, consulte | Você deve fornecer uma key de API usando um dos seguintes campos: | |
| Uma key de API da AI21 Labs fornecida como uma strings de texto simples. Se preferir referenciar sua chave usando Databricks Secrets, consulte | Você deve fornecer uma key de API usando um dos seguintes campos: |
Provedor personalizado
Para usar um modelo de provedor personalizado, ele deve ser compatível com a API OpenAI.
Parâmetro de Configuração | Descrição | Obrigatório | Padrão |
|---|---|---|---|
| O URL onde o modelo do provedor personalizado reside. O URL deve apontar para um endpoint de API específico; por exemplo, | Sim | |
| Se o provedor personalizado utilizar a autenticação por tokens, especifique os campos necessários. | Você deve fornecer um método de autenticação usando um dos seguintes campos: | |
| A referência da chave secreta do Databricks para os tokens para autenticação de portador. Este parâmetro deve estar aninhado em | Se estiver usando autenticação de portador, você deve fornecer uma key de API usando um dos seguintes campos: | |
| Os tokens para autenticação de portador fornecido como uma strings de texto simples. Este parâmetro deve estar aninhado em | Se estiver usando autenticação de portador, você deve fornecer uma key de API usando um dos seguintes campos: | |
| Se o provedor personalizado utilizar autenticação de key de API, especifique os campos obrigatórios. | Você deve fornecer um método de autenticação usando um dos seguintes campos: | |
| A key para autenticação da key de API. Este parâmetro deve ser aninhado em | Sim, ao usar a autenticação de API key. | |
| A referência da chave secreta do Databricks para o valor de autenticação da API key. Se preferir colar sua key de API diretamente, consulte | Se estiver usando autenticação de chave de API, você deve fornecer uma chave de API usando um dos seguintes campos: | |
| O valor para autenticação de API key fornecido como uma strings de texto simples. Se preferir referenciar sua key usando os segredos do Databricks, consulte | Se estiver usando autenticação de chave de API, você deve fornecer uma chave de API usando um dos seguintes campos: |
O exemplo a seguir demonstra como criar um endpoint com um provedor personalizado usando **autenticação de portador**:
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}}"
}
}
}
}
]
},
)
O exemplo a seguir demonstra como criar um endpoint com um provedor personalizado usando **autenticação de key de 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}}"
}
}
}
}
]
},
)
Configurar o AI Gateway em um endpoint
Você também pode configurar seu endpoint para habilitar recursos do AI Gateway, como limitação de taxa, acompanhamento de uso e guardrails.
Consulte Configurar o AI Gateway em endpoints de servindo modelo.
Consultar um endpoint de modelo externo
Após criar um endpoint de modelo externo, ele estará pronto para receber tráfego de usuários.
Você pode enviar solicitações de pontuação para o endpoint usando o cliente OpenAI, a API REST ou o SDK de Implantações MLflow.
- Consulte os parâmetros de consulta padrão para uma solicitação de pontuação em POST /serving-endpoint/{name}/invocations.
- Use modelos de fundação
O exemplo a seguir consulta o modelo de conclusões claude-2 hospedado pela Anthropic usando o cliente OpenAI. Para usar o cliente OpenAI, preencha o campo model com o nome do endpoint servindo modelo que hospeda o modelo que você deseja consultar.
Este exemplo usa um endpoint criado anteriormente, anthropic-completions-endpoint, configurado para acessar modelos externos do provedor de modelos Anthropic. Consulte como criar endpoint de modelo externo.
Consulte Modelos compatíveis para modelos adicionais que você pode consultar e seus provedores.
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)
Formato de resposta de saída esperado:
{
"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
}
}
Parâmetros de consulta adicionais
É possível passar quaisquer parâmetros adicionais compatíveis com o provedor do endpoint como parte da sua consulta.
Por exemplo:
-
logit_bias(compatível com OpenAI, Cohere). -
top_k(suportado por Anthropic, Cohere). -
frequency_penalty(compatível com OpenAI, Cohere). -
presence_penalty(compatível com OpenAI, Cohere). -
stream(suportado por OpenAI, Anthropic, Cohere, Amazon Bedrock para Anthropic). Isto está disponível apenas para solicitações de bate-papo e conclusões. -
tools(com suporte de OpenAI, Anthropic, Amazon Bedrock para Anthropic). Este está disponível apenas para solicitações de bate-papo e de conclusão. Este parâmetro permite a integração de funcionalidades externas, incluindo Uso de Computador (beta) para Anthropic e Amazon Bedrock para Anthropic. Consulte Chamada de função no Databricks.
Suporte para configurações de conectividade de rede para modelos externos
O suporte para Configurações de conectividade de rede (NCCs) para modelos externos, incluindo o AWS PrivateLink, está atualmente em prévia pública. Entre em contato com a equipe da sua account Databricks para participar da prévia.
Limitações
Dependendo do modelo externo escolhido, sua configuração pode fazer com que seus dados sejam processados fora da região de origem. Consulte Limites e regiões do Model Serving.