Habilitar tabelas de inferência nos endpoints de serviço de modelo na API

Artigo
01/23/2025

Importante

Esta funcionalidade está em Pré-visualização Pública.

Importante

Este artigo descreve tópicos que se aplicam a tabelas de inferência para modelos personalizados . Para modelos externos ou cargas de trabalho de taxa de transferência provisionadas, use as tabelas de inferência compatíveis com o AI Gateway.

Este artigo explica como usar a API Databricks para habilitar tabelas de inferência para um modelo de que servede ponto de extremidade . Para obter informações gerais sobre como usar tabelas de inferência, incluindo como habilitá-las usando a interface do usuário do Databricks, consulte tabelas de inferência para monitorar e depurar modelos.

Você pode habilitar tabelas de inferência ao criar um novo ponto de extremidade ou em um ponto de extremidade existente. O Databricks recomenda que você crie o ponto de extremidade com uma entidade de serviço para que a tabela de inferência não seja afetada se o usuário que criou o ponto de extremidade for removido do espaço de trabalho.

O proprietário das tabelas de inferência é o usuário que criou o ponto de extremidade. Todas as listas de controle de acesso (ACLs) na tabela seguem as permissões padrão do Catálogo Unity e podem ser modificadas pelo proprietário da tabela.

Requerimentos

Seu espaço de trabalho deve ter o Unity Catalog habilitado.
Tanto o criador do ponto de extremidade quanto o modificador devem ter a permissão Pode gerenciar no ponto de extremidade. Consulte Listas de controle de acesso.
Tanto o criador do endpoint quanto o modificador devem ter as seguintes permissões no Unity Catalog.
- USE CATALOG permissões no catálogo especificado.
- USE SCHEMA permissões no esquema especificado.
- CREATE TABLE permissões no esquema.

Ativar tabelas de inferência ao criar pontos finais usando a API

Você pode habilitar tabelas de inferência para um ponto de extremidade durante a criação do ponto de extremidade usando a API. Para obter instruções sobre como criar um ponto de extremidade, consulte Criar ponto de extremidade de serviço de modelo personalizado.

Na API, o corpo da solicitação tem um auto_capture_config para especificar:

O Catálogo Unity: cadeia de caracteres que representa o catálogo para armazenar a tabela
O esquema do Unity Catalog: string que representa o esquema para armazenar a tabela
(opcional) prefixo da tabela: string usada como um prefixo para o nome da tabela de inferência. Se isso não for especificado, o nome do ponto de extremidade será usado.
(opcional) habilitado: valor booleano usado para habilitar ou desabilitar tabelas de inferência. Isso é verdade por padrão.

Depois de especificar um catálogo, esquema e, opcionalmente, prefixo de tabela, uma tabela é criada em <catalog>.<schema>.<table_prefix>_payload. Esta tabela cria automaticamente uma tabela gerenciada Unity Catalog. O proprietário da tabela é o utilizador que cria o ponto final.

Nota

Não há suporte para a especificação de uma tabela existente, pois a tabela de inferência é sempre criada automaticamente quando da criação de pontos de extremidade ou em atualizações de pontos de extremidade.

Aviso

A tabela de inferência pode ficar corrompida se você fizer o seguinte:

Altere o esquema da tabela.
Altere o nome da tabela.
Exclua a tabela.
Perde permissões para o catálogo ou esquema do Unity Catalog.

Nesse caso, o auto_capture_config do estado do ponto final mostra um estado FAILED para a tabela de carga útil. Se isso acontecer, você deverá criar um novo ponto de extremidade para continuar usando tabelas de inferência.

O exemplo a seguir demonstra como habilitar tabelas de inferência durante a criação do ponto de extremidade.

POST /api/2.0/serving-endpoints

{
  "name": "feed-ads",
  "config":
  {
    "served_entities": [
      {
       "entity_name": "ads1",
       "entity_version": "1",
       "workload_size": "Small",
       "scale_to_zero_enabled": true
      }
    ],
    "auto_capture_config":
    {
       "catalog_name": "ml",
       "schema_name": "ads",
       "table_name_prefix": "feed-ads-prod"
    }
  }
}

A resposta é semelhante a:

{
  "name": "feed-ads",
  "creator": "customer@example.com",
  "creation_timestamp": 1666829055000,
  "last_updated_timestamp": 1666829055000,
  "state": {
    "ready": "NOT_READY",
    "config_update": "IN_PROGRESS"
  },
  "pending_config": {
    "start_time": 1666718879000,
    "served_entities": [
      {
        "name": "ads1-1",
        "entity_name": "ads1",
        "entity_version": "1",
        "workload_size": "Small",
        "scale_to_zero_enabled": true,
        "state": {
          "deployment": "DEPLOYMENT_CREATING",
          "deployment_state_message": "Creating"
        },
        "creator": "customer@example.com",
        "creation_timestamp": 1666829055000
    }
   ],
   "config_version": 1,
   "traffic_config": {
     "routes": [
       {
         "served_model_name": "ads1-1",
         "traffic_percentage": 100
       }
      ]
   },
   "auto_capture_config": {
     "catalog_name": "ml",
     "schema_name": "ads",
     "table_name_prefix": "feed-ads-prod",
     "state": {
       "payload_table": {
         "name": "feed-ads-prod_payload"
       }
     },
     "enabled": true
   }
  },
  "id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "permission_level": "CAN_MANAGE"
}

Depois que o registro em tabelas de inferência tiver sido habilitado, aguarde até que seu ponto de extremidade esteja pronto. Então você pode começar a chamá-lo.

Depois de criar uma tabela de inferência, a evolução do esquema e a adição de dados devem ser tratadas pelo sistema.

As seguintes operações não afetam a integridade da tabela:

Executando OPTIMIZE, ANALYZE e VACUUM na tabela.
Eliminação de dados antigos não utilizados.

Se você não especificar um auto_capture_config, por padrão, a configuração de definições da versão de configuração anterior será reutilizada. Por exemplo, se as tabelas de inferência já estavam habilitadas, as mesmas configurações são usadas na próxima atualização de ponto de extremidade ou se as tabelas de inferência foram desabilitadas, elas continuam sendo desabilitadas.

{
  "served_entities": [
    {
      "name":"current",
      "entity_name":"model-A",
      "entity_version":"1",
      "workload_size":"Small",
      "scale_to_zero_enabled":true
    }
  ],
  "auto_capture_config": {
    "enabled": false
  }
}

Habilitar tabelas de inferência em um ponto de extremidade existente usando a API

Você também pode habilitar tabelas de inferência em um ponto de extremidade existente usando a API. Depois que as tabelas de inferência estiverem habilitadas, continue especificando o mesmo corpo auto_capture_config em futuras chamadas de API para o endpoint de atualização, a fim de continuar usando as tabelas de inferência.

Nota

Não há suporte para alterar o local da tabela depois de habilitar as tabelas de inferência.

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

{
  "served_entities": [
    {
      "name":"current",
      "entity_name":"model-A",
      "entity_version":"1",
      "workload_size":"Small",
      "scale_to_zero_enabled":true
    },
    {
      "name":"challenger",
      "entity_name":"model-B",
      "entity_version":"1",
      "workload_size":"Small",
      "scale_to_zero_enabled":true
    }
  ],
  "traffic_config":{
    "routes": [
      {
        "served_model_name":"current",
        "traffic_percentage":"50"
      },
      {
        "served_model_name":"challenger",
        "traffic_percentage":"50"
      }
    ]
  },
  "auto_capture_config":{
   "catalog_name": "catalog",
   "schema_name": "schema",
   "table_name_prefix": "my-endpoint"
  }
}

Desativar tabelas de inferência

Ao desativar tabelas de inferência, não é necessário especificar catálogo, esquema ou prefixo de tabela. O único campo obrigatório é enabled: false.

POST /api/2.0/serving-endpoints

{
  "name": "feed-ads",
  "config":{
    "served_entities": [
      {
       "entity_name": "ads1",
       "entity_version": "1",
       "workload_size": "Small",
       "scale_to_zero_enabled": true
      }
    ],
    "auto_capture_config":{
       "enabled": false
    }
  }
}

Para reativar uma tabela de inferência desabilitada, siga as instruções em Habilitar tabelas de inferência em um ponto de extremidade existente. Você pode usar a mesma tabela ou especificar uma nova tabela.

Próximos passos

Depois de ativar as tabelas de inferência, pode monitorizar os modelos servidos no seu endpoint de serviço de modelos com o Databricks Lakehouse Monitoring. Para obter detalhes, consulte Fluxo de trabalho: monitorar o desempenho do modelo usando tabelas de inferência.

Partilhar via