Criar endpoints de serviços personalizados de modelo

Este artigo descreve como criar pontos de extremidade de serviço de modelo que servem modelos personalizados usando o Databricks Model Serving.

O Model Serving fornece as seguintes opções para servir a criação de pontos finais:

• A Interface de Utilizador de Serviço
• API REST
• SDK de implantações MLflow

Para criar pontos de extremidade que servem modelos de IA generativos, consulte Criar modelo de base servindo pontos de extremidade.

Requerimentos

• Seu espaço de trabalho deve estar em uma região suportada.
• Se utilizar bibliotecas personalizadas ou bibliotecas de um servidor espelho privado com o seu modelo, consulte Usar bibliotecas Python personalizadas com Model Serving antes de criar o endpoint do modelo.
• Para criar endpoints usando o SDK de Deployments MLflow, deve instalar o cliente de Deployment MLflow. Para instalá-lo, execute:

import mlflow.deployments

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

Identidade e acesso

Para criar ou atualizar um endpoint de disponibilização de modelo, tanto o autor da chamada como o criador registado do endpoint têm de:

• Faz parte do espaço de trabalho.
• Mantém o workspace-access direito adquirido.

Identidade do criador

Quando cria um endpoint, o Databricks regista a identidade do autor da chamada como o criador do endpoint. Esta identidade — tipicamente um principal de serviço — é usada para aceder aos recursos do Catálogo Unity em nome do endpoint e não pode ser alterada após a criação.

Se o criador registado não tiver os privilégios necessários no Unity Catalog ou tiver sido removido do espaço de trabalho, tem de eliminar o endpoint e recriá-lo utilizando um principal de serviço que tenha as permissões necessárias e seja um membro atual do espaço de trabalho.

As atualizações da configuração e das entidades disponibilizadas reavaliam a pertença ao espaço de trabalho e as permissões concedidas do criador registado. As atualizações falham com PERMISSION_DENIED se o criador registado já não for membro do espaço de trabalho, mesmo quando o autor da chamada tem permissões válidas.

Concessões de entidades servidas

O criador registado deve deter as seguintes subvenções em cada entidade servida. As concessões validadas na criação ou atualização do endpoint fazem com que o pedido falhe se PERMISSION_DENIED estiver em falta. Os subsídios exigidos no momento da consulta não são validados antecipadamente — os subsídios em falta causam erros de execução quando o endpoint serve tráfego.

Gerir o acesso ao endpoint

Para compreender as opções de controlo de acesso para endpoints de serviço de modelo, consulte Gerenciar permissões num endpoint de serviço de modelo.

Criar um ponto de extremidade

Servindo a interface do usuário

Você pode criar um ponto de extremidade para servir modelos com a IU do Serving.

1. Clique em Serviço na barra lateral para exibir a UI de Serviço.

2. Clique em Criar ponto de extremidade de serviço.

   

Para modelos no Unity Catalog (recomendado) ou no antigo Workspace Model Registry:

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

   • Os nomes dos pontos finais não podem usar o prefixo databricks- . Esse prefixo é reservado para pontos de extremidade pré-configurados do Databricks.

2. Na secção Entidades servidas

   1. Clique no campo Entidade para abrir o formulário Selecionar entidade atendida.
   2. Selecione Meus modelos- Catálogo Unity ou Meus modelos- Registro de modelo com base em onde seu modelo está registrado. O formulário é atualizado dinamicamente com base na sua seleção.
      • Nem todos os modelos são modelos personalizados. Os modelos podem ser modelos de base ou recursos para disponibilização de funcionalidades.
   3. Selecione qual modelo e versão do modelo você deseja servir.
   4. Selecione a percentagem de tráfego a encaminhar para o seu modelo servido.
   5. Selecione o tamanho de computação a ser usado. Você pode usar cálculos de CPU ou GPU para suas cargas de trabalho. Consulte Tipo de computação para os tipos de carga de trabalho disponíveis, incluindo as CPU_MEDIUM opções e CPU_LARGE para modelos que necessitam de mais memória do que o tipo padrão CPU . Para exemplos de código GPU, veja tipos de carga de trabalho GPU.
   6. Em Expansão Horizontal de Computação, selecione o tamanho da escala de computação que corresponde ao número de solicitações que este modelo implementado pode processar ao mesmo tempo. Este número deve ser aproximadamente igual ao tempo de execução do modelo QPS x. Para configurações de computação definidas pelo cliente, consulte Limites de serviço do modelo.
      1. Os tamanhos disponíveis são Pequeno para 0-4 pedidos, Médio 8-16 pedidos e Grande para 16-64 pedidos.
   7. Especifique se o ponto de extremidade deve ser dimensionado para zero quando não estiver em uso. A escala até zero não é recomendada para pontos finais de produção, pois a capacidade não é garantida quando dimensionada para zero. Quando um ponto de extremidade é dimensionado para zero, ocorre uma latência adicional, também chamada de início a frio, quando o ponto de extremidade é redimensionado para voltar a atender solicitações.
   8. Em Configuração avançada, você pode:
      • Renomeie a entidade servida para personalizar a sua aparência no endpoint.
      • Adicione variáveis de ambiente para se conectar a recursos do seu endpoint ou registre o seu DataFrame de consulta de características na tabela de inferência do endpoint. O registo da busca de funcionalidades DataFrame requer MLflow 2.14.0 ou superior.
   9. (Opcional) Para adicionar outras entidades servidas ao seu ponto de extremidade, clique em Adicionar entidade servida e repita as etapas de configuração acima. Você pode hospedar vários modelos ou versões de modelo a partir de um único ponto de extremidade e controlar a distribuição de tráfego entre eles. Consulte servir vários modelos para obter mais informações.

3. Na seção Otimização de rota , você pode habilitar a otimização de rota para seu ponto de extremidade. A otimização de rotas é recomendada para endpoints com altos requisitos de QPS e taxa de transferência. Consulte Otimização de rotas em pontos de extremidade de serviço.

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

5. Clique em Criar. A página Pontos de Extremidade de Serviço aparece 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 do ponto final.

O exemplo a seguir cria um endpoint que disponibiliza a terceira versão do modelo my-ads-model registado no registo de modelos do Unity Catalog. Para especificar um modelo do Unity Catalog, forneça o nome completo do modelo, incluindo o catálogo pai e o esquema, tal como no exemplo catalog.schema.example-model. Este exemplo usa simultaneidade personalizada com min_provisioned_concurrency e max_provisioned_concurrency. Os valores de simultaneidade 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
      }
    ]
  }
}

Segue-se um exemplo de resposta. O estado do ponto de extremidade config_update é NOT_UPDATING e o modelo servido está num 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 MLflow

MLflow Deployments 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 pontos finais de serviço. Consulte POST /api/2.0/serving-endpoints para obter os parâmetros de configuração do ponto final.

O exemplo a seguir cria um endpoint que disponibiliza a terceira versão do modelo my-ads-model registado no registo de modelos do Unity Catalog. Você deve fornecer o nome completo do modelo, incluindo o catálogo pai e o esquema, como, por exemplo, catalog.schema.example-model. Este exemplo usa simultaneidade personalizada com min_provisioned_concurrency e max_provisioned_concurrency. Os valores de simultaneidade 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 Databricks Workspace Client SDK.

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 pode:

• Habilite tabelas de inferência para capturar automaticamente solicitações recebidas e respostas enviadas para os endpoints de disponibilização de modelo.
• Se tiver tabelas de inferência habilitadas no seu ponto de extremidade, pode registar o seu DataFrame de consulta de características na tabela de inferência.

Você também pode adicionar variáveis de ambiente para armazenar credenciais para servir o modelo. Consulte Configurar o acesso a recursos a partir de endpoints de serviço de modelo

Tipos de carga de trabalho GPU

A implantação da 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 o seu ponto de extremidade para cargas de trabalho de GPU com a interface de utilizador do Serving, selecione o tipo de GPU desejado no menu drop-down Tipo de Computação ao criar o seu 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 os 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 MLflow

O exemplo a seguir mostra como criar um endpoint de GPU usando o SDK de implantação 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 GPU usando o Databricks Workspace Client SDK.

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 disponíveis da GPU dependem do seu fornecedor de cloud, conforme resumido na tabela seguinte.

Nos endpoints da GPU, o valor de concorrência determina o número de réplicas alocadas para servir o seu modelo. O número de réplicas é igual ao valor de concorrência dividido por 4. Por exemplo, definir min_provisioned_concurrency como 12 aprovisiona 3 réplicas.

Modificar um ponto de extremidade de modelo personalizado

Após ativar um ponto de extremidade de modelo personalizado, poderá atualizar a configuração de cálculo 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 um papel fundamental nos recursos alocados para atender ao seu modelo.

Até que a nova configuração esteja pronta, a configuração antiga continua servindo o tráfego de previsão. Embora haja uma atualização em andamento, outra atualização não pode ser feita. No entanto, pode cancelar uma atualização em curso na interface de atualizaçã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 seu ponto de extremidade.

Você pode alterar a maioria dos aspetos da configuração do ponto de extremidade, exceto o nome do ponto de extremidade e certas 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

Segue 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 MLflow

O SDK de implantações 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 exemplo de código a seguir usa um modelo do registro de modelo do Unity Catalog:

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
            }
        ]
    }
  }
)

Avaliação de um ponto de extremidade do modelo

Para avaliar o seu modelo, envie solicitações para o terminal de serviço de modelo.

• Consulte Pontos de extremidade de serviço de consulta para modelos personalizados.
• Consulte Usar modelos de fundação.

Recursos adicionais

• Gerencie o modelo de pontos de extremidade de serviço.
• Modelos externos em Serviço de Modelos.
• Caso prefiras usar Python, podes utilizar o SDK de serviço em tempo real Python da Databricks.

Exemplos de blocos de notas

Os cadernos a seguir incluem diferentes modelos registados no Databricks que pode utilizar para começar a trabalhar com endpoints de serviço de modelos. Para obter exemplos adicionais, consulte Tutorial: Implantar e consultar um modelo personalizado.

Os exemplos de modelo podem ser importados para o espaço de trabalho seguindo as instruções em Importar um bloco de anotações. Depois de escolher e criar um modelo a partir de um dos exemplos, registe-o no Unity Cataloge, em seguida, siga as etapas do fluxo de trabalho da interface de utilizador para disponibilizar o modelo.

Treine e registe um modelo scikit-learn para servimento de modelo em notebook

Obter bloco de notas

Treine e registe um modelo HuggingFace para a execução de modelos num notebook

Obter bloco de notas