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 a criação de 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 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 pontos de extremidade usando o SDK de Implantações do MLflow, você deve instalar o cliente de Implantação do MLflow. Para instalá-lo, execute:

import mlflow.deployments

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

Controle de acesso

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

A identidade sob a qual um modelo que serve o ponto de extremidade é executado está vinculada ao criador original do ponto de extremidade. Após a criação do ponto de extremidade, a identidade associada não pode ser alterada ou atualizada no ponto de extremidade. Essa identidade e suas permissões associadas são usadas para acessar recursos do Catálogo do Unity para implantações. Se a identidade não tiver as permissões apropriadas para acessar os recursos necessários do Unity Catalog, você deverá excluir o endpoint e recriá-lo em uma conta de usuário ou de entidade de serviço que possa acessar esses recursos do Unity Catalog.

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

Criar um ponto de extremidade

Servindo a interface do usuário

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 ponto de extremidade de serviço.

   

Para modelos registrados no registro de modelo de workspace ou modelos no Catálogo do Unity:

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 características para o fornecimento de características.
   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 qual tamanho a computação usar. Você pode usar cálculos de CPU ou GPU nas suas cargas de trabalho. Consulte Tipos de carga de trabalho de GPU para obter mais informações sobre as computações de GPU disponíveis.
   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 ponto de extremidade deve reduzir 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 introdução ao Gateway o Mosaic AI.

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

   

API REST

Você pode criar pontos de extremidade 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 config_update extremidade é NOT_UPDATING e o modelo servido está em um READY estado.

{
  "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 fornecem 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 pontos de extremidade 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, catalog.schema.example-modelcomo . 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 solicitações de entrada e respostas de saída dos seus pontos de extremidade de serviço de 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.

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.

Servindo a interface do usuário

Para configurar seu ponto de extremidade para cargas de trabalho de GPU com a interface do usuário de Serving, 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
            )
        ]
    )
)

A tabela a seguir resume os tipos de carga de trabalho de GPU disponíveis e com suporte.

Modificar um ponto de extremidade de modelo personalizado

Após habilitar um ponto de extremidade 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 de serviço.

Servindo a interface do usuário

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 ponto de extremidade 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.create_endpoint(
  name=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
            }
        ]
    }
  }
)

Pontuando um ponto de extremidade de modelo

Para pontuar o 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 pontos de extremidade de serviço de modelo.
• Modelos externos no Mosaic AI 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 Catálogo do Unity e siga as etapas do fluxo de trabalho da interface do usuário para o serviço de modelo.

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

Obter notebook

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

Obter notebook