Criar pontos de extremidade de serviço de modelo personalizados

Este artigo descreve como criar pontos de extremidade de serviço de modelo que atendam modelos personalizados usando o Serviço de Modelo do Databricks.

O Serviço de Modelo do Databricks fornece as seguintes opções para criar os pontos de extremidade de serviço:

• A interface do usuário de serviço
• API REST
• SDK de Implantações do MLflow

Para criar pontos de extremidade que atendem a modelos de IA generativos, consulte Criar pontos de extremidade que atendem aos modelos de fundação.

Requisitos

• Seu espaço de trabalho deve estar em uma região compatível.
• Se você usar bibliotecas ou bibliotecas personalizadas de um servidor de espelho privado com o seu modelo, consulte Usar bibliotecas personalizadas do Python com o Serviço de Modelo antes de criar o ponto de extremidade do modelo.
• Para criar endpoints usando o SDK de Deployments do MLflow, você deve instalar o cliente de Deployment do MLflow. Para instalá-lo, execute:

import mlflow.deployments

client = mlflow.deployments.get_deploy_client("databricks")

Identidade e acesso

Para criar ou atualizar um ponto de extremidade de serviço de modelo, o chamador e o criador registrado do ponto de extremidade devem:

• Seja um membro do workspace.
• Manter o direito de uso de workspace-access.

Identidade do criador

Quando você cria um endpoint, o Databricks registra a identidade do chamador como o criador do endpoint. Essa identidade — geralmente um principal de serviço — é usada para acessar recursos do Unity Catalog em nome do endpoint e não pode ser alterada após a criação.

Se o criador registrado não tiver os privilégios necessários no Unity Catalog ou tiver sido removido do workspace, você deverá excluir o endpoint e recriá-lo sob uma entidade de serviço que tenha as permissões necessárias e seja um membro atual do workspace.

As atualizações de configuração e da entidade servida reavaliam a associação ao espaço de trabalho e as permissões concedidas ao criador registrado. As atualizações falham com PERMISSION_DENIED se o criador registrado não faz mais parte do espaço de trabalho, mesmo quando o solicitante tem permissões válidas.

Concessões de entidade atendidas

O criador registrado deve ter as seguintes permissões em cada entidade servida. As permissões validadas na criação ou atualização do ponto de extremidade fazem com que a solicitação falhe com PERMISSION_DENIED se estiverem ausentes. As concessões necessárias no momento da consulta não são validadas antecipadamente – as concessões ausentes causam erros de runtime quando o ponto de extremidade atende ao tráfego.

Gerenciar o acesso ao endpoint

Para entender as opções de controle de acesso para pontos de extremidade de serviço de modelo, consulte Gerenciar permissões em um ponto de extremidade de serviço de modelo.

Criar um ponto de extremidade

Interface do usuário de serviço

Você pode criar um ponto de extremidade para o serviço de modelo com a interface do usuário de Serviço.

1. Clique em Servindo na barra lateral para exibir a interface do usuário de serviço.

2. Clique em Criar endpoint de serviço.

   

Para modelos no Unity Catalog (recomendado) ou no Registro de Modelos do Workspace herdado:

1. No campo Nome, forneça um nome para o ponto de extremidade.

   • Os nomes de ponto de extremidade não podem usar o databricks- prefixo. Este prefixo é reservado para endpoints pré-configurados do Databricks.

2. Na seção Entidades atendidas

   1. Clique no campo Entidade para abrir o formulário Selecionar entidade atendida.
   2. Selecione Meus modelos– Catálogo do Unity ou Meus modelos – Registro de Modelo com base no local em que seu modelo está registrado. O formulário é atualizado dinamicamente com base em sua seleção.
      • Nem todos os modelos são modelos personalizados. Os modelos podem ser modelos de base ou recursos para serviço.
   3. Selecione qual modelo e versão de modelo você deseja atender.
   4. Selecione o percentual de tráfego a ser roteado para o modelo atendido.
   5. Selecione o tamanho de computação a ser usado. Você pode usar cálculos de CPU ou GPU nas suas cargas de trabalho. Consulte Tipo de computação para ver os tipos de carga de trabalho disponíveis, incluindo as opções CPU_MEDIUM e CPU_LARGE para modelos que precisam de mais memória do que o tipo padrão CPU. Para obter exemplos de código gpu, consulte os tipos de carga de trabalho de GPU.
   6. Em Expansão de computação, selecione o tamanho da escala horizontal de computação que corresponde ao número de solicitações que esse modelo servido pode processar ao mesmo tempo. Esse número deve ser aproximadamente igual ao tempo de execução do QPS x modelo. Para configurações de computação definidas pelo cliente, consulte os limites de serviço do modelo.
      1. Os tamanhos disponíveis são Pequeno para 0-4 solicitações, Médio para 8 a 16 solicitações e Grande para 16 a 64 solicitações.
   7. Especifique se o endpoint deve escalar para zero quando não estiver em uso. A escala para zero não é recomendada para pontos de extremidade de produção, pois a capacidade não é garantida quando dimensionada para zero. Quando um ponto de extremidade é escalado como zero, há latência adicional, também conhecida como um início frio, quando o ponto de extremidade é escalado novamente para atender às solicitações.
   8. Em Configuração avançada, você pode:
      • Renomeie a entidade servida para personalizar sua aparência no endpoint.
      • Adicione variáveis de ambiente para se conectar aos recursos de seu ponto de extremidade ou registre seu DataFrame de consulta de recursos na tabela de inferência do ponto de extremidade. O registro em log do DataFrame de pesquisa de recursos requer o MLflow 2.14.0 ou superior.
   9. (Opcional) Para adicionar outras entidades atendidas ao ponto de extremidade, clique em Adicionar entidade atendida e repita as etapas de configuração acima. Você pode fornecer vários modelos ou versões de modelo de um único ponto de extremidade e controlar a divisão de tráfego entre eles. Consulte servir vários modelos para mais informações.

3. Na seção Otimização de Rotas, você pode habilitar a otimização de rotas para o seu ponto de extremidade. A otimização de rota é sugerida para terminais com altos requisitos de QPS e largura de banda. Otimização de rota em pontos de extremidade do serviço.

4. Na seção Gateway de IA, você pode selecionar quais recursos de governança habilitar em seu endpoint. Consulte a governança de IA com o Unity AI Gateway.

5. Clique em Criar. A página Pontos de extremidade de serviço é exibida com o Estado do ponto de extremidade de serviço mostrado como Não Pronto.

   

API REST

Você pode criar endpoints usando a API REST. Consulte POST /api/2.0/serving-endpoints para obter os parâmetros de configuração dos pontos de extremidade.

O exemplo a seguir cria um ponto de extremidade que atende à primeira versão do modelo my-ads-model que é registrado no registro de modelo do Catálogo do Unity. Para especificar um modelo do Catálogo do Unity, forneça o nome completo do modelo, incluindo o catálogo pai e o esquema, como catalog.schema.example-model. Este exemplo usa simultaneidade definida sob medida com min_provisioned_concurrency e max_provisioned_concurrency. Os valores de concorrência devem ser múltiplos de 4.

POST /api/2.0/serving-endpoints

{
  "name": "uc-model-endpoint",
  "config":
  {
    "served_entities": [
      {
        "name": "ads-entity",
        "entity_name": "catalog.schema.my-ads-model",
        "entity_version": "3",
        "min_provisioned_concurrency": 4,
        "max_provisioned_concurrency": 12,
        "scale_to_zero_enabled": false
      }
    ]
  }
}

A seguir, um exemplo de resposta. O estado do ponto de extremidade config_update é NOT_UPDATING e o modelo servido está em um estado READY.

{
  "name": "uc-model-endpoint",
  "creator": "user@email.com",
  "creation_timestamp": 1700089637000,
  "last_updated_timestamp": 1700089760000,
  "state": {
    "ready": "READY",
    "config_update": "NOT_UPDATING"
  },
  "config": {
    "served_entities": [
      {
        "name": "ads-entity",
        "entity_name": "catalog.schema.my-ads-model",
        "entity_version": "3",
        "min_provisioned_concurrency": 4,
        "max_provisioned_concurrency": 12,
        "scale_to_zero_enabled": false,
        "workload_type": "CPU",
        "state": {
          "deployment": "DEPLOYMENT_READY",
          "deployment_state_message": ""
        },
        "creator": "user@email.com",
        "creation_timestamp": 1700089760000
      }
    ],
    "config_version": 1
  },
  "tags": [
    {
      "key": "team",
      "value": "data science"
    }
  ],
  "id": "e3bd3e471d6045d6b75f384279e4b6ab",
  "permission_level": "CAN_MANAGE",
  "route_optimized": false
}

SDK de Implantações do MLflow

Implantações de MLflow fornece uma API para tarefas de criação, atualização e exclusão. As APIs para essas tarefas aceitam os mesmos parâmetros que a API REST para endpoints de serviço. Consulte POST /api/2.0/serving-endpoints para obter os parâmetros de configuração dos pontos de extremidade.

O exemplo a seguir cria um ponto de extremidade que atende à primeira versão do modelo my-ads-model que é registrado no registro de modelo do Catálogo do Unity. Você deve fornecer o nome completo do modelo, incluindo o catálogo pai e o esquema, como, catalog.schema.example-model. Este exemplo usa simultaneidade definida sob medida com min_provisioned_concurrency e max_provisioned_concurrency. Os valores de concorrência devem ser múltiplos de 4.

import mlflow
from mlflow.deployments import get_deploy_client

mlflow.set_registry_uri("databricks-uc")
client = get_deploy_client("databricks")

endpoint = client.create_endpoint(
    name="unity-catalog-model-endpoint",
    config={
        "served_entities": [
            {
                "name": "ads-entity",
                "entity_name": "catalog.schema.my-ads-model",
                "entity_version": "3",
                "min_provisioned_concurrency": 4,
                "max_provisioned_concurrency": 12,
                "scale_to_zero_enabled": False
            }
        ]
    }
)

Cliente de workspace

O exemplo a seguir mostra como criar um endpoint usando o SDK do Client do Databricks Workspace.

from databricks.sdk import WorkspaceClient
from databricks.sdk.service.serving import EndpointCoreConfigInput, ServedEntityInput

w = WorkspaceClient()

w.serving_endpoints.create(
    name="uc-model-endpoint",
    config=EndpointCoreConfigInput(
        served_entities=[
            ServedEntityInput(
                name="ads-entity",
                entity_name="catalog.schema.my-ads-model",
                entity_version="3",
                workload_size="Small",
                scale_to_zero_enabled=False
            )
        ]
    )
)

Também é possível:

• Habilite tabelas de inferência para capturar automaticamente as solicitações recebidas e as respostas enviadas dos endpoints de serviço do modelo.
• Se você tiver tabelas de inferência habilitadas no seu ponto de extremidade, poderá registrar seu DataFrame de pesquisa de recursos na tabela de inferência.

Você também pode adicionar variáveis de ambiente para armazenar credenciais para o serviço de modelo. Consulte Configurar o acesso aos recursos dos pontos de extremidade do serviço de modelo

Tipos de cargas de trabalho GPU

A implantação de GPU é compatível com as seguintes versões de pacote:

• PyTorch 1.13.0 – 2.0.1
• TensorFlow 2.5.0 – 2.13.0
• MLflow 2.4.0 e superior

Os exemplos a seguir mostram como criar pontos de extremidade de GPU usando métodos diferentes.

Interface do usuário de serviço

Para configurar seu ponto de extremidade para cargas de trabalho de GPU com a interface de Serviço, selecione o tipo de GPU desejado na lista suspensa Tipo de Computação durante a criação do ponto de extremidade. Siga as mesmas etapas em Criar um ponto de extremidade, mas selecione um tipo de carga de trabalho de GPU em vez de CPU.

API REST

Para implantar seus modelos usando GPUs, inclua o campo workload_type na configuração do endpoint.

POST /api/2.0/serving-endpoints

{
  "name": "gpu-model-endpoint",
  "config": {
    "served_entities": [{
      "entity_name": "catalog.schema.my-gpu-model",
      "entity_version": "1",
      "workload_type": "GPU_SMALL",
      "workload_size": "Small",
      "scale_to_zero_enabled": false
    }]
  }
}

SDK de Implantações do MLflow

O exemplo a seguir mostra como criar um ponto de extremidade de GPU usando o SDK de Implantações do MLflow.

import mlflow
from mlflow.deployments import get_deploy_client

mlflow.set_registry_uri("databricks-uc")
client = get_deploy_client("databricks")

endpoint = client.create_endpoint(
    name="gpu-model-endpoint",
    config={
        "served_entities": [{
            "entity_name": "catalog.schema.my-gpu-model",
            "entity_version": "1",
            "workload_type": "GPU_SMALL",
            "workload_size": "Small",
            "scale_to_zero_enabled": False
        }]
    }
)

Cliente de workspace

O exemplo a seguir mostra como criar um ponto de extremidade de GPU usando o SDK do Cliente do Workspace do Databricks.

from databricks.sdk import WorkspaceClient
from databricks.sdk.service.serving import EndpointCoreConfigInput, ServedEntityInput

w = WorkspaceClient()

w.serving_endpoints.create(
    name="gpu-model-endpoint",
    config=EndpointCoreConfigInput(
        served_entities=[
            ServedEntityInput(
                entity_name="catalog.schema.my-gpu-model",
                entity_version="1",
                workload_type="GPU_SMALL",
                workload_size="Small",
                scale_to_zero_enabled=False
            )
        ]
    )
)

Os tipos de carga de trabalho de GPU disponíveis dependem do provedor de nuvem, conforme resumido na tabela a seguir.

Para pontos de extremidade de GPU, o valor de simultaneidade determina o número de réplicas alocadas para atender ao seu modelo. O número de réplicas é igual ao valor de simultaneidade dividido por 4. Por exemplo, definir min_provisioned_concurrency como 12 provisiona 3 réplicas.

Modificar um endpoint de modelo personalizado

Após habilitar um endpoint de modelo personalizado, você pode atualizar a configuração de computação conforme desejado. Essa configuração é particularmente útil se você precisar de recursos adicionais para seu modelo. O tamanho da carga de trabalho e a configuração de computação desempenham uma função fundamenta em quais os recursos são alocados para servir seu modelo.

Até que a nova configuração esteja pronta, a configuração antiga continuará atendendo ao tráfego de previsão. Embora haja uma atualização em andamento, outra atualização não pode ser feita. No entanto, você pode cancelar uma atualização em andamento na interface de usuário do Serving.

Interface do usuário de serviço

Depois de habilitar um ponto de extremidade de modelo, selecione Editar ponto de extremidade para modificar a configuração de computação do ponto de extremidade.

Você pode alterar a maioria dos aspectos da configuração do ponto de extremidade, exceto o nome do ponto de extremidade e determinadas propriedades imutáveis.

Você pode cancelar uma atualização de configuração em andamento selecionando Cancelar atualização na página de detalhes do ponto de extremidade.

API REST

A seguir, um exemplo de atualização da configuração de um endpoint usando a API REST. Consulte PUT /api/2.0/serving-endpoints/{name}/config.

PUT /api/2.0/serving-endpoints/{name}/config

{
  "name": "unity-catalog-model-endpoint",
  "config":
  {
    "served_entities": [
      {
        "entity_name": "catalog.schema.my-ads-model",
        "entity_version": "5",
        "workload_size": "Small",
        "scale_to_zero_enabled": true
      }
    ],
    "traffic_config":
    {
      "routes": [
        {
          "served_model_name": "my-ads-model-5",
          "traffic_percentage": 100
        }
      ]
    }
  }
}

SDK de Implantações do MLflow

O SDK de Implantações do MLflow usa os mesmos parâmetros que a API REST. Consulte PUT /api/2.0/serving-endpoints/{name}/config para obter detalhes do esquema de solicitação e resposta.

O seguinte exemplo de código usa um modelo do registro de modelo do Catálogo do Unity:

import mlflow
from mlflow.deployments import get_deploy_client

mlflow.set_registry_uri("databricks-uc")
client = get_deploy_client("databricks")

endpoint = client.update_endpoint_config(
  endpoint=f"{endpointname}",
  config={
    "served_entities": [
        {
            "entity_name": f"{catalog}.{schema}.{model_name}",
            "entity_version": "1",
            "workload_size": "Small",
            "scale_to_zero_enabled": True
        }
    ],
    "traffic_config": {
        "routes": [
            {
                "served_model_name": f"{model_name}-1",
                "traffic_percentage": 100
            }
        ]
    }
  }
)

Pontuar um ponto de extremidade de modelo

Para pontuar seu modelo, envie solicitações para o ponto de extremidade de serviço do modelo.

• Confira Pontos de extremidade de serviço de consulta para modelos personalizados.
• Consulte Usar modelos de base.

Recursos adicionais

• Gerenciar os pontos de extremidade do serviço de modelo.
• Modelos externos no Model Serving.
• Se você preferir usar o Python, poderá usar o Databricks de serviço em tempo real do SDK do Python.

Exemplos de notebook

Os notebooks a seguir incluem diferentes modelos registrados do Databricks que você pode usar para começar a executar os pontos de extremidade do serviço de modelo. Para obter exemplos adicionais, consulte Tutorial: Implantar e consultar um modelo personalizado.

Importe os exemplos de modelos para o workspace seguindo as instruções em Importar um notebook. Depois de escolher e criar um modelo de um dos exemplos, registre-o no Unity Catalog e siga as etapas do fluxo de trabalho de interface do usuário para a disponibilização do modelo.

Treinar e registrar um modelo do Scikit-learn no notebook de serviço de modelo

Obter notebook

Treinar e registrar um modelo do HuggingFace para o notebook de fornecimento de modelo

Obter notebook