Modelos externos no Serviço de Modelo do Databricks
Importante
Os exemplos de código neste artigo demonstram o uso da Visualização Pública API CRUD de Implantações do MLflow.
Este artigo descreve os modelos externos no Serviço de Modelo do Databricks para o Serviço de Modelo do Databricks, incluindo seus provedores de modelo com suporte e limitações.
O que são modelos externos?
Os modelos externos são modelos de terceiros hospedados fora do Databricks. Com o Serviço de Modelo, os modelos externos permitem simplificar o uso e o gerenciamento de vários provedores de modelos de linguagem grande (LLM), como o OpenAI e o Anthropic, em uma organização. Também é possível usar o Serviço de Modelo do Databricks como um provedor para fornecer modelos personalizados, o que oferece limitações de taxa para esses pontos de extremidade. Como parte desse suporte, o Serviço de Modelo oferece uma interface de alto nível que simplifica a interação com esses serviços, fornecendo um ponto de extremidade unificado para lidar com solicitações específicas relacionadas ao LLM.
Além disso, o suporte do Azure Databricks para modelos externos fornece gerenciamento centralizado de credenciais. Ao armazenar chaves de API em um local seguro, as organizações podem aprimorar sua postura de segurança minimizando a exposição de chaves de API confidenciais em todo o sistema. Também ajuda a evitar a exposição dessas chaves no código ou requer que os usuários finais gerenciem as chaves com segurança.
Veja Tutorial: Criar pontos de extremidade de modelo externo para consultar modelos OpenAI para obter orientação passo a passo sobre a criação de ponto de extremidade de modelo externo e consultar modelos suportados atendidos por esses pontos de extremidade usando o SDK de implantações do MLflow. Veja os guias a seguir para obter instruções sobre como usar a IU de serviço e a API REST:
Requisitos
- Chave de API para o provedor de modelo.
- Workspace do Databricks em regiões com suporte de modelos externos.
Fornecedores de modelos
Os modelos externos no Serviço de Modelo são projetados para dar suporte a uma variedade de provedores de modelos. Um provedor representa a origem dos modelos de aprendizado de máquina, como OpenAI, Anthropic e assim por diante. Cada provedor tem suas características e configurações específicas que são encapsuladas no campo external_model da configuração do ponto de extremidade do modelo externo.
Os seguintes provedores têm suporte:
- openai: para modelos oferecidos pelo OpenAI e as integrações do Azure para o OpenAI do Azure e o OpenAI do Azure com AAD.
- anthropic: para modelos oferecidos por Anthropic.
- cohere: para modelos oferecidos por Cohere.
- amazon-bedrock: para modelos oferecidos pela Amazon Bedrock.
- ai21labs: Para modelos oferecidos pela AI21Labs.
- google-cloud-vétex-ai: para modelos oferecidos pelo Google Cloud Vertex AI.
- databricks-model-serving: para pontos de extremidade do Serviço de Modelo do Databricks com esquemas compatíveis. Consulte Configuração do ponto de extremidade.
Para solicitar suporte para um provedor que não esteja listado aqui, entre em contato com a equipe da sua conta do Databricks.
Modelos com suporte
O modelo escolhido afeta diretamente os resultados das respostas que você obtém das chamadas à API. Portanto, escolha um modelo que se ajuste aos requisitos de seu caso de uso. Por exemplo, para gerar respostas de conversas, você pode escolher um modelo de chat. Por outro lado, para gerar inserções de texto, você pode escolher um modelo de inserção.
A tabela abaixo apresenta uma lista não exaustiva dos modelos com suporte e dos tipos de pontos de extremidade correspondentes. As associações de modelos listadas abaixo podem ser usadas como um guia útil ao configurar um ponto de extremidade para quaisquer tipos de modelos recém-lançados à medida que se tornam disponíveis em um determinado fornecedor. Os clientes são responsáveis por garantir a conformidade com as licenças de modelo aplicáveis.
Observação
Com o rápido desenvolvimento dos LLMs, não existe garantia de que esta lista esteja sempre atualizada.
| Provedor de modelos | 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-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 |
| OpenAI do Azure** | * text-davinci-003 * gpt-35-turbo-instruct |
* gpt-35-turbo * gpt-35-turbo-16k * gpt-4 * gpt-4-32k |
* 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-opus-20240229 * claude-3-sonnet-20240229 * claude-2.1 * claude-2.0 * claude-instant-1.2 |
|
| Cohere** | * 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 |
|
| Serviço de modelo do Databricks | Ponto de extremidade de serviço do Databricks | Ponto de extremidade de serviço do Databricks | Ponto de extremidade de serviço do Databricks |
| Amazon Bedrock | Anthropic: * claude-instant-v1 * claude-v1 * claude-v2 Cohere: * command-text-v14 * command-text-v14:7:4k * command-light-text-v14 * command-light-text-v14:7:4k AI21 Labs: * j2-grande-instruct * j2-jumbo-instruct * j2-mid * j2-mid-v1 * j2-ultra j2-ultra-v1 |
Anthropic: * claude-instant-v1:2:100k * claude-v2 * claude-v2:0:18k * claude-v2:0:100k * claude-v2:1 * claude-v2:1:18k * claude-v2:1:200k * claude-3-sonnet-20240229-v1:0 |
Amazon: * titan-embed-text-v1 * titan-embed-g1-text-02 * titan-embed-text-v1:2:8k |
| AI21 Labs† | * j2-mid * j2-light * j2-ultra |
||
| Google Cloud Vertex AI | text-bison | * chat-bison * gemini-pro |
textembedding-gecko |
** O provedor de modelos dá suporte a modelos de preenchimento e chat ajustados. Para consultar um modelo ajustado, preencha o campo name da configuração external model com o nome do modelo ajustado.
† O provedor de modelos dá suporte a modelos de conclusão personalizados.
Usar modelos fornecidos nos pontos de extremidade do Serviço de Modelo do Databricks
Os Pontos de extremidade de Serviço de Modelo do Databricks como provedor tem suporte para os tipos de ponto de extremidade llm/v1/completions, llm/v1/chat e llm/v1/embeddings. Esses pontos de extremidade devem aceitar os parâmetros de consulta padrão marcados como obrigatórios, enquanto outros parâmetros podem ser ignorados, dependendo se o ponto de extremidade do Serviço de Modelo do Databricks dá suporte a eles ou não.
Confira POST /serving-endpoints/{name}/invocations na referência de API para parâmetros de consulta padrão.
Esses pontos de extremidade devem produzir respostas no formato OpenAI, conforme descrito a seguir.
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 chats:
{
"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 inserção:
{
"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 do ponto de extremidade
Para servir e consultar modelos externos, você precisa configurar um ponto de extremidade de serviço. Confira Criar pontos de extremidade de serviço de modelo personalizados
Para um ponto de extremidade de modelo de serviço, você deve incluir o campo external_model e seus parâmetros na seção served_entities da configuração do ponto de extremidade.
O canpo external_model define o modelo para o qual esse ponto de extremidade encaminha solicitações. Ao especificar um modelo, é crítico que o fornecedor dê suporte para o modelo que você está solicitando. Por exemplo, openai como provedor tem suporte para modelos como text-embedding-ada-002, mas outros provedores podem não ter. Se o modelo não der suporte para o provedor, o Databricks retornará um erro HTTP 4xx ao tentar rotear solicitações para esse modelo.
A tabela abaixo resume os parâmetros de campo external_model. Confira POST /api/2.0/serving-endpoints para obter os parâmetros de configuração de ponto de extremidade.
| Parâmetro | Descrições |
|---|---|
name |
O nome do modelo a ser usado. Por exemplo, gpt-3.5-turbo para o modelo GPT-3.5-Turbo do OpenAI. |
provider |
Especifica o nome do provedor para esse modelo. Esse valor de cadeia de caracteres precisa corresponder a um provedor de modelo externo suportado. Por exemplo, openai para os modelos GPT-3.5 do OpenAI. |
task |
A tarefa corresponde ao tipo de interação do modelo de linguagem que você deseja. As tarefas com suporte são "llm/v1/completions", "llm/v1/chat", "llm/v1/embeddings". |
<provider>_config |
Contém todos os detalhes de configuração adicionais necessários para o modelo. Isso inclui a especificação da URL de base da API e da chave da API. Consulte Configurar o provedor para um ponto de extremidade. |
A seguir, um exemplo de criação de um ponto de extremidade de modelo externo usando a API de create_endpoint(). Neste exemplo, uma solicitação enviada ao ponto de extremidade de conclusão é encaminhada para o 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}}"
}
}
}
]
}
)
Configurar o provedor para um ponto de extremidade
Quando você cria um ponto de extremidade, deve fornecer as configurações necessárias para o provedor de modelo especificado. As seções a seguir resumem os pontos de extremidade disponíveis para configuração de cada provedor de modelo.
OpenAI
| Parâmetro de configuração | Descrição | Obrigatório | Padrão |
|---|---|---|---|
openai_api_key |
A chave da API para o serviço OpenAI. | Sim | |
openai_api_type |
Um campo opcional para especificar o tipo de API do OpenAI a ser usada. | Não | |
openai_api_base |
A URL de base da API do OpenAI. | Não | https://api.openai.com/v1 |
openai_api_version |
Um campo opcional para especificar a versão da API do OpenAI. | Não | |
openai_organization |
Um campo opcional para especificar a organização no OpenAI. | Não |
Cohere
| Parâmetro de configuração | Descrição | Obrigatório | Padrão |
|---|---|---|---|
cohere_api_key |
A chave da API do serviço Cohere. | Sim |
Anthropic
| Parâmetro de configuração | Descrição | Obrigatório | Padrão |
|---|---|---|---|
anthropic_api_key |
A chave da API para o serviço Anthropic. | Sim |
OpenAI do Azure
O OpenAI do Azure 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 |
|---|---|---|---|
openai_api_key |
A chave de API para o Serviço OpenAI do Azure. | Sim | |
openai_api_type |
Ajuste esse parâmetro para representar o protocolo de validação de acesso de segurança preferido. Para validação do token de acesso, use azure. Para autenticação usando o Microsoft Azure AD (Active Directory), use azuread. |
Sim | |
openai_api_base |
A URL base do serviço de API do OpenAI do Azure fornecido pelo Azure. | Sim | |
openai_api_version |
A versão do Serviço OpenAI do Azure a ser utilizada, especificada por uma data. | Sim | |
openai_deployment_name |
O nome do recurso de implantação do Serviço OpenAI do Azure. | Sim | |
openai_organization |
Um campo opcional para especificar a organização no OpenAI. | Não |
O exemplo a seguir demonstra como criar um ponto de extremidade com o OpenAI do Azure:
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
| Parâmetro de configuração | Descrição | Obrigatório | Padrão |
|---|---|---|---|
private_key |
Essa é a chave privada para a conta de serviço que tem acesso ao Serviço do Google Cloud Vertex AI. Consulte as Melhores práticas para gerenciar chaves de conta de serviço. | Yes | |
region |
Essa é a região do Serviço do Google Cloud Vertex AI. Confira as regiões com suporte para obter mais detalhes. Alguns modelos só estão disponíveis em regiões específicas. | Yes | |
project_id |
Essa é a ID do projeto do Google Cloud à qual a conta de serviço está associada. | Yes |
Amazon Bedrock
Para usar o Amazon Bedrock como provedor de modelo externo, os clientes precisam garantir que o Bedrock esteja habilitado na região especificada da AWS e que o par de chaves da AWS especificado tenha as permissões apropriadas para interagir com os serviços Bedrock. Para obter mais informações, consulte Gerenciamento de Identidades e Acesso do AWS.
| Parâmetro de configuração | Descrição | Obrigatório | Padrão |
|---|---|---|---|
aws_region |
A região do AWS a ser usada. O Bedrock tem que ser habilitado lá. | Sim | |
aws_access_key_id |
Uma ID de chave de acesso do AWS com permissões de acesso para interagir com os serviços do Bedrock. | Sim | |
aws_secret_access_key |
Uma chave de acesso secreta do AWS emparelhada com a ID da chave de acesso, com permissões de acesso para interagir com os serviços do Bedrock. | Sim | |
bedrock_provider |
O provedor subjacente no Amazon Bedrock. Os valores com suporte (sem distinção entre maiúsculas e minúsculas) incluem: Anthropic, Cohere, AI21Labs, Amazon | Sim |
O exemplo a seguir demonstra como criar um ponto de extremidade com o 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",
},
}
}
]
},
)
Se houver problemas de permissão da AWS, a Databricks recomenda que você verifique as credenciais diretamente com o API Amazon Bedrock.
AI21 Labs
| Parâmetro de configuração | Descrição | Obrigatório | Padrão |
|---|---|---|---|
ai21labs_api_key |
Esta é a chave de API do serviço AI21 Labs. | Yes |
Consultar um ponto de extremidade de modelo externo
Após criar um ponto de extremidade de modelo externo, ele está pronto para receber tráfego dos usuários.
Você pode enviar solicitações de pontuação para o ponto de extremidade usando o cliente OpenAI, a API REST ou o SDK de implantações do MLflow.
- Confira os parâmetros de consulta padrão para uma solicitação de pontuação em POST /serving-endpoints/{name}/invocations.
- Modelos de base de consulta
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 de atendimento do modelo que hospeda o modelo que você deseja consultar.
Esse exemplo usa um ponto de extremidade criado anteriormente, anthropic-completions-endpoint, configurado para acessar modelos externos do provedor de modelos Antrópico. Veja como criar pontos de extremidade de modelo externo.
Veja Modelos suportados para modelos adicionais que você pode consultar e seus fornecedores.
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
Você pode passar quaisquer parâmetros adicionais compatíveis com o provedor do ponto de extremidade como parte da sua consulta.
Por exemplo:
logit_bias(com suporte para OpenAI, Cohere).top_k(com suporte para Anthropic, Cohere).frequency_penalty(com suporte para OpenAI, Cohere).presence_penalty(com suporte para OpenAI, Cohere).stream(apoiado por OpenAI, Anthropic, Cohere, Amazon Bedrock for Anthropic). Isso só está disponível para solicitações de chats e conclusões.
Limitações
Dependendo do modelo externo escolhido, sua configuração pode fazer com que seus dados sejam processados fora da região de dados em que foram originados.
Veja Limites e regiões do serviço de modelo.