Servir tabelas de funcionalidades

As tabelas de características podem ser servidas de duas formas:

  • serving de modelos: Implante um modelo treinado em tabelas de características. O mesmo endpoint é usado tanto para consulta de atributos como para inferência do modelo. O endpoint consulta ou calcula automaticamente os valores das características, usando a linhagem registada quando o modelo foi registado. Utilize isto para disponibilizar previsões do modelo.
  • Feature Serving: Disponibilize um FeatureSpec que referencia tabelas de funcionalidades diretamente, sem modelo. O endpoint retorna os resultados da funcionalidade solicitada. Use isto quando uma aplicação precisa de valores de funcionalidades em vez de previsões de modelos. Se, em última análise, estiver a usar funcionalidades para inferência de modelos, o Databricks recomenda usar o serviço de modelos diretamente.

Ambas as abordagens suportam funcionalidades pré-computadas e sob demanda.

Requerimentos

  • Databricks Runtime 14.2 ML ou superior.
  • Para usar a API Python, o Feature Serving requer databricks-feature-engineering versão 0.1.2 ou superior, que está integrada no Databricks Runtime 14.2 ML. Para versões anteriores do Databricks Runtime ML, instale manualmente a versão necessária usando %pip install databricks-feature-engineering>=0.1.2. Se estiver a usar um portátil Databricks, deve então reiniciar o kernel Python executando este comando numa nova célula: dbutils.library.restartPython().
  • Para usar o SDK do Databricks, o Feature Serving requer databricks-sdk a versão 0.18.0 ou superior. Para instalar manualmente a versão necessária, use %pip install databricks-sdk>=0.18.0. Se estiver a usar um portátil Databricks, deve então reiniciar o kernel Python executando este comando numa nova célula: dbutils.library.restartPython().

O Databricks Feature Serving fornece uma interface do utilizador e várias opções programáticas para criar, atualizar, consultar e excluir endpoints. Este artigo inclui instruções para cada uma das seguintes opções:

  • Interface do usuário do Databricks
  • API REST
  • API Python
  • Databricks SDK

Para usar a API REST ou o SDK de implantações MLflow, você deve ter um token de API Databricks.

Importante

Como prática recomendada de segurança para cenários de produção, o Databricks recomenda que você use tokens OAuth máquina a máquina para autenticação durante a produção.

Para teste e desenvolvimento, o Databricks recomenda o uso de um token de acesso pessoal pertencente a entidades de serviço em vez de usuários do espaço de trabalho. Para criar tokens para entidades de serviço, consulte Gerenciar tokens para uma entidade de serviço.

Autenticação para servir funcionalidades

Para informações sobre autenticação, consulte Autorizar acesso a recursos de Azure Databricks.

Criar um FeatureSpec

Um FeatureSpec é um conjunto de recursos e funções definido pelo usuário. Você pode combinar recursos e funções em um FeatureSpec. FeatureSpecs são armazenados e gerenciados pelo Unity Catalog e aparecem no Catalog Explorer.

As tabelas especificadas em um FeatureSpec devem ser publicadas em uma loja de recursos online ou em uma loja online de terceiros. Consulte Databricks Online Feature Stores.

Você deve usar o pacote databricks-feature-engineering para criar um FeatureSpec.

Primeiro, defina a função:

from unitycatalog.ai.core.databricks import DatabricksFunctionClient

client = DatabricksFunctionClient()

CATALOG = "main"
SCHEMA = "default"

def difference(num_1: float, num_2: float) -> float:
  """
  A function that accepts two floating point numbers, subtracts the second one
  from the first, and returns the result as a float.

  Args:
      num_1 (float): The first number.
      num_2 (float): The second number.

  Returns:
      float: The resulting difference of the two input numbers.
  """
  return num_1 - num_2

client.create_python_function(
  func=difference,
  catalog=CATALOG,
  schema=SCHEMA,
  replace=True
)

Então você pode usar a função em um FeatureSpec:

from databricks.feature_engineering import (
  FeatureFunction,
  FeatureLookup,
  FeatureEngineeringClient,
)

fe = FeatureEngineeringClient()

features = [
  # Lookup column `average_yearly_spend` and `country` from a table in UC by the input `user_id`.
  FeatureLookup(
    table_name="main.default.customer_profile",
    lookup_key="user_id",
    feature_names=["average_yearly_spend", "country"]
  ),
  # Calculate a new feature called `spending_gap` - the difference between `ytd_spend` and `average_yearly_spend`.
  FeatureFunction(
    udf_name="main.default.difference",
    output_name="spending_gap",
    # Bind the function parameter with input from other features or from request.
    # The function calculates num_1 - num_2.
    input_bindings={"num_1": "ytd_spend", "num_2": "average_yearly_spend"},
  ),
]

# Create a `FeatureSpec` with the features defined above.
# The `FeatureSpec` can be accessed in Unity Catalog as a function.
fe.create_feature_spec(
  name="main.default.customer_features",
  features=features,
)

Especificar valores padrão

Para especificar valores padrão para recursos, use o default_values parâmetro no FeatureLookup. Veja o seguinte exemplo:

feature_lookups = [
    FeatureLookup(
        table_name="ml.recommender_system.customer_features",
        feature_names=[
            "membership_tier",
            "age",
            "page_views_count_30days",
        ],
        lookup_key="customer_id",
        default_values={
          "age": 18,
          "membership_tier": "bronze"
        },
    ),
]

Se as colunas de recursos forem renomeadas usando o rename_outputs parâmetro, default_values deverão usar os nomes de recursos renomeados.

FeatureLookup(
  table_name = 'main.default.table',
  feature_names = ['materialized_feature_value'],
  lookup_key = 'id',
  rename_outputs={"materialized_feature_value": "feature_value"},
  default_values={
    "feature_value": 0
  }
)

Adicionar dependências de Python

Se uma função definida pelo utilizador (UDF) importar pacotes Python, declare-os quando criar o FeatureSpec. O extra_pip_requirements parâmetro requer databricks-feature-engineering a versão 0.17.0 ou superior. O Feature Serving instala o MLflow e databricks-feature-lookup os pacotes automaticamente.

Por exemplo, se um UDF na sua especificação importar NumPy, adicione o requisito à especificação:

fe.create_feature_spec(
    name="main.default.customer_features_with_dependencies",
    features=features,
    extra_pip_requirements=["numpy==1.26.4"],
)

Use main.default.customer_features_with_dependencies como nome da especificação ao criar o endpoint.

Cada entrada em extra_pip_requirements deve ser uma cadeia de requisitos PyPI, como numpy==1.26.4, ou um caminho para um .whl ficheiro num volume do Unity Catalog. Por exemplo, use /Volumes/main/libraries/wheels/custom_features-1.0.0-py3-none-any.whl uma roda que tenha carregado. O criador do endpoint deve ter READ VOLUME no volume e USE CATALOGUSE SCHEMA no seu catálogo pai e esquema.

Para pacotes de um repositório privado, configure o repositório de pacotes predefinido do workspace. Não coloque opções de comando pip, como --index-url, em extra_pip_requirements.

Dependências numa cláusula UDF ENVIRONMENT do Unity Catalog aplicam-se à execução offline de SQL. O Feature Serving não as copia automaticamente. Declare todos os pacotes necessários pelos UDFs, incluindo os UDFs em funcionalidades a montante, nos requisitos da especificação de funcionalidades.

Se a implementação no endpoint falhar, inspecione os registos de compilação para erros de instalação de pacotes, conflitos de versões ou falhas de acesso na roda. Consulte Monitorar a qualidade do modelo e a integridade do ponto final.

Para um exemplo com CustomUDF e FeatureViewSource, veja características do Servir CustomUDF e as suas dependências. Para dependências para disponibilização de modelos, consulte Dependências de UDF personalizadas.

Criar um ponto final

O FeatureSpec define o ponto de extremidade. Para mais informações, consulte Create custom model serving endpoints, the Python API documentation, ou a documentação do SDK Databricks para detalhes.

Nota

Para cargas de trabalho sensíveis à latência ou que exigem altas taxas de consultas por segundo, o Model Serving oferece otimização de rota nos endpoints de serviço de modelo personalizado, consulte Otimização de rota nos endpoints de serviço.

SDK Databricks - Python

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

workspace = WorkspaceClient()

# Create endpoint
workspace.serving_endpoints.create(
  name="my-serving-endpoint",
  config = EndpointCoreConfigInput(
    served_entities=[
    ServedEntityInput(
        entity_name="main.default.customer_features",
        scale_to_zero_enabled=True,
        workload_size="Small"
      )
    ]
  )
)

API Python

from databricks.feature_engineering.entities.feature_serving_endpoint import (
  ServedEntity,
  EndpointCoreConfig,
)

fe.create_feature_serving_endpoint(
  name="customer-features",
    config=EndpointCoreConfig(
    served_entities=ServedEntity(
      feature_spec_name="main.default.customer_features",
             workload_size="Small",
             scale_to_zero_enabled=True,
             instance_profile_arn=None,
    )
  )
)

API REST

curl -X POST -u token:$DATABRICKS_API_TOKEN ${WORKSPACE_URL}/api/2.0/serving-endpoints \
    -H 'Content-Type: application/json' \
    -d '"name": "customer-features",
   "config": {
       "served_entities": [
           {
               "entity_name": "main.default.customer_features",
               "workload_size": "Small",
               "scale_to_zero_enabled": true
           }
       ]
   }'

Para ver o ponto de extremidade, clique em Serviços na barra lateral esquerda da interface de utilizador do Databricks. Quando o estado estiver Pronto, o ponto de extremidade estará pronto para responder a consultas. Para saber mais sobre o Model Serving, consulte Model Serving.

Salve o DataFrame aumentado na tabela de inferência

Para terminais criados a partir de fevereiro de 2025, pode-se configurar o terminal de serviço de modelo para registar o DataFrame aumentado que contém os valores de características pesquisadas e os valores de retorno da função. O DataFrame é salvo na tabela de inferência para o modelo servido.

Para obter instruções sobre como definir esta configuração, consulte Registar DataFrames de consulta de funcionalidades em tabelas de inferência.

Para informações sobre tabelas de inferência, veja Pedidos de registo e respostas para endpoints de serviço (legado).

Obtenha um ponto de extremidade

Podes usar o Databricks SDK ou a API Python para obter os metadados e o estado de um endpoint.

SDK Databricks - Python

from databricks.sdk import WorkspaceClient
workspace = WorkspaceClient()

endpoint = workspace.serving_endpoints.get(name="customer-features")
# print(endpoint)

API Python

endpoint = fe.get_feature_serving_endpoint(name="customer-features")
# print(endpoint)

Obter o esquema de um ponto de extremidade

Você pode usar o SDK do Databricks ou a API REST para obter o esquema de um ponto de extremidade. Para mais informações sobre o esquema do ponto de extremidade, consulte Obter um esquema de ponto de extremidade de serviço de modelo.

SDK Databricks - Python

from databricks.sdk import WorkspaceClient
workspace = WorkspaceClient()

# Create endpoint
endpoint = workspace.serving_endpoints.get_open_api(name="customer-features")

API REST

ACCESS_TOKEN=<token>
ENDPOINT_NAME=<endpoint name>

curl "https://example.databricks.com/api/2.0/serving-endpoints/$ENDPOINT_NAME/openapi" -H "Authorization: Bearer $ACCESS_TOKEN" -H "Content-Type: application/json"

Consultar um ponto de extremidade

Você pode usar a API REST, o SDK de implantações MLflow ou a interface de utilizador do serviço para consultar um endpoint.

O código a seguir mostra como configurar credenciais e criar o cliente ao usar o SDK de implantações MLflow.

  # Set up credentials
  export DATABRICKS_HOST=...
  export DATABRICKS_TOKEN=...

  # Set up the client
  import mlflow.deployments

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

Nota

Como prática recomendada de segurança, quando você se autentica com ferramentas, sistemas, scripts e aplicativos automatizados, o Databricks recomenda que você use tokens de acesso pessoal pertencentes a entidades de serviço em vez de usuários do espaço de trabalho. Para criar tokens para entidades de serviço, consulte Gerenciar tokens para uma entidade de serviço.

Fazer uma consulta a um endpoint usando APIs

Esta seção inclui exemplos de consulta a um endpoint usando a API REST ou o SDK de implantações do MLflow.

SDK de Implementações do MLflow

Importante

O exemplo a seguir usa a predict() API do MLflow Deployments SDK. Esta API é Experimental e a definição da API pode mudar.

import mlflow.deployments

client = mlflow.deployments.get_deploy_client("databricks")
response = client.predict(
    endpoint="test-feature-endpoint",
    inputs={
        "dataframe_records": [
            {"user_id": 1, "ytd_spend": 598},
            {"user_id": 2, "ytd_spend": 280},
        ]
    },
)

API REST

curl -X POST -u token:$DATABRICKS_API_TOKEN $ENDPOINT_INVOCATION_URL \
  -H 'Content-Type: application/json' \
  -d '{"dataframe_records": [
          {"user_id": 1, "ytd_spend": 598},
          {"user_id": 2, "ytd_spend": 280}
      ]}'

Consultar um endpoint usando a interface do utilizador

Você pode consultar diretamente um endpoint a partir da interface de serviço. A interface do utilizador inclui exemplos de código gerado que pode usar para consultar o endpoint.

  1. Na barra lateral esquerda do espaço de trabalho Azure Databricks, clique em Serving.

  2. Clique no ponto de extremidade que você deseja consultar.

  3. No canto superior direito do ecrã, clique em Ponto de extremidade de consulta.

    Botão Consultar Ponto Final

  4. Na caixa Solicitação , digite o corpo da solicitação no formato JSON.

  5. Clique em Enviar solicitação.

// Example of a request body.
{
  "dataframe_records": [
    { "user_id": 1, "ytd_spend": 598 },
    { "user_id": 2, "ytd_spend": 280 }
  ]
}

O diálogo Query endpoint inclui código de exemplo gerado em curl, Python e SQL. Clique nas guias para visualizar e copiar o código de exemplo.

caixa de diálogo do ponto de acesso da consulta

Para copiar o código, clique no ícone de cópia no canto superior direito da caixa de texto.

botão copiar na caixa de diálogo de endpoint de consulta

Atualizar um endpoint

Importante

Para modificar a configuração de um endpoint Feature Serving (como alterar a FeatureSpec ou o tamanho da carga de trabalho), use sempre as APIs de atualização descritas nesta secção. Não apague nem recrie o endpoint para aplicar alterações. Eliminar um endpoint ativo causa tempo de inatividade imediato e interrompe todas as aplicações que o consultam.

Você pode atualizar um endpoint usando a API REST, o SDK do Databricks ou a interface de serviço.

Atualizar um endpoint usando APIs

SDK Databricks - Python

from databricks.sdk import WorkspaceClient
workspace = WorkspaceClient()

workspace.serving_endpoints.update_config(
  name="my-serving-endpoint",
  served_entities=[
    ServedEntityInput(
      entity_name="main.default.customer_features",
      scale_to_zero_enabled=True,
      workload_size="Small"
    )
  ]
)

API REST

curl -X PUT -u token:$DATABRICKS_API_TOKEN ${WORKSPACE_URL}/api/2.0/serving-endpoints/<endpoint_name>/config \
  -H 'Content-Type: application/json' \
  -d '"served_entities": [
        {
            "name": "customer-features",
            "entity_name": "main.default.customer_features_new",
            "workload_size": "Small",
            "scale_to_zero_enabled": True
        }
    ]'

Atualize um endpoint usando a interface do usuário

Siga estes passos para usar a interface de serviço:

  1. Na barra lateral esquerda do espaço de trabalho Azure Databricks, clique em Serving.
  2. Na tabela, clique no nome do ponto de extremidade que você deseja atualizar. O ecrã do endpoint aparece.
  3. No canto superior direito do ecrã, clique em Editar ponto de extremidade.
  4. Na caixa de diálogo Editar ponto de extremidade de serviço , edite as configurações do ponto de extremidade conforme necessário.
  5. Clique em Atualizar para salvar as alterações.

Atualizar um ponto de extremidade

Atualizar dependências de um endpoint de Feature Serving em funcionamento

Um endpoint de Feature Serving resolve as suas dependências quando é construído e implementado pela primeira vez: os privilégios que o seu principal de serviço precisa para ler a tabela online (USE CATALOG, USE SCHEMA e SELECT), e EXECUTE no Unity Catalog UDF descrito no seu FeatureSpec. O endpoint fixa estas permissões em tempo de compilação e não as resolve novamente numa simples nova implementação ou reinício. Se recriar a tabela online ou a UDF, o endpoint perde a permissão sobre esta. Se atualizares o UDF diretamente, o endpoint continua a correr a versão original. As consultas de funcionalidades podem falhar, ou usar silenciosamente a antiga lógica UDF, mesmo enquanto o endpoint continua a reportar Pronto.

Para tabelas online e UDFs on-demand, a Databricks recomenda uma migração versionada: criar uma nova versão da dependência, criar um novo endpoint para essa versão e migrar o tráfego para o novo endpoint. Isto ajuda-o a evitar interrupções e os modos de falha descritos nesta secção.

Recriar uma tabela online

Aviso

Não apague nem recrie uma tabela online no local de um endpoint de Feature Serving em funcionamento.

Quando cria um endpoint, o Model Serving concede ao principal de serviço do endpoint USE CATALOG sobre o catálogo da tabela online, USE SCHEMA sobre o seu esquema e SELECT sobre a tabela online. Eliminar e recriar a tabela, mesmo com o mesmo nome, cria um novo securável no Unity Catalog, pelo que a SELECT concessão não é mantida. O principal do serviço perde o acesso à tabela, a emissão de tokens OAuth falha e a ligação à loja online volta à autenticação por palavra-passe e falha. As pesquisas de funcionalidades falham depois com erros como KeyError: 'OAUTH_TOKEN' ou password authentication failed.

Estas falhas são fáceis de ignorar: o endpoint continua a reportar Pronto e o pipeline de sincronização continua a mostrar execuções bem-sucedidas, enquanto as consultas falham. Alterar o modo de sincronização de uma tabela online (por exemplo, entre CONTINUOUS e SNAPSHOT) não pode ser feito no local e requer recriar a tabela, o que também pode desencadear este problema.

Um endpoint não lê uma tabela online específica. Consulta funcionalidades através da tabela offline nomeada no seu FeatureSpec, e quando uma tabela de funcionalidades é publicada em mais do que uma tabela online, o endpoint usa a mais antiga. Publicar a mesma tabela de funcionalidades numa segunda tabela online não move um endpoint para a nova tabela online. Consulte as limitações da Feature Store online.

Para minimizar o tempo de inatividade, controle a versão da tabela de funcionalidades offline, assim como da tabela online:

  1. Crie uma nova tabela de funcionalidades offline e inclua a versão no seu nome (por exemplo, customer_features_v2).
  2. Publique a nova tabela de funcionalidades numa nova tabela online. Consulte Publicar uma tabela de funcionalidades.
  3. Crie um novo FeatureSpec que use a nova feature table e crie um novo endpoint de Feature Serving que o sirva.
  4. Migrar o tráfego para o novo endpoint. Depois de o endpoint antigo deixar de receber tráfego, elimine-o e a sua tabela online.

Atualizar um UDF on-demand

Aviso

Não modifiquem um UDF do Unity Catalog usado por um FeatureSpec in-place.

O UDF on-demand do A FeatureSpec está integrado no endpoint de serviço no momento da implementação. Um simples refresh ou redeploy reutiliza o mesmo UDF nessa imagem de serviço. Uma atualização no local do UDF com o mesmo nome não entra em vigor. Se eliminares e recriares o UDF, o endpoint também fica sem EXECUTE, por isso as pesquisas que usam o UDF falham.

FeatureSpecs e UDFs não têm campo de versão, por isso, faça o versionamento pelo nome: criar um novo UDF e um novo FeatureSpec, criar um novo endpoint que use o novo FeatureSpec e migrar tráfego para ele. Consulte um FeatureSpec.

Veja Cálculo de funcionalidade a pedido.

Recuperar um endpoint após uma alteração no próprio endpoint

Se já alteraste uma dependência no local, reconstrói o endpoint para que ele resolva novamente as dependências. Crie um novo FeatureSpec endpoint (ou, para um endpoint Model Serving, registe uma nova versão do modelo) e atualize o endpoint para o servir. Alterar o que o endpoint serve reconstrói o endpoint, que aprovisiona uma nova entidade de serviço e reexecuta a configuração de permissões. Nenhuma destas reconstrói o endpoint de forma fiável: pará-lo e iniciá-lo, uma simples reimplantação ou alterar uma variável de ambiente.

Excluir um ponto de extremidade

Aviso

Esta ação é irreversível. Eliminar um endpoint de Feature Serving causa um tempo de inatividade imediato para qualquer aplicação que o consulte. Se quiser alterar a configuração do endpoint, use Atualizar um endpoint em vez de apagar e recriar o endpoint.

Pode eliminar um endpoint usando a API REST, o SDK Databricks, a API Python ou a interface de serviço.

Excluir um ponto de extremidade usando APIs

SDK Databricks - Python

from databricks.sdk import WorkspaceClient
workspace = WorkspaceClient()

workspace.serving_endpoints.delete(name="customer-features")

API Python

fe.delete_feature_serving_endpoint(name="customer-features")

API REST

curl -X DELETE -u token:$DATABRICKS_API_TOKEN ${WORKSPACE_URL}/api/2.0/serving-endpoints/<endpoint_name>

Excluir um ponto de extremidade usando a interface do usuário

Siga estas etapas para excluir um ponto de extremidade usando a interface de serviço:

  1. Na barra lateral esquerda do espaço de trabalho Azure Databricks, clique em Serving.
  2. Na tabela, clique no nome do ponto de extremidade que você deseja excluir. O ecrã do endpoint aparece.
  3. No canto superior direito da tela, clique no ícone do menu kebab Kebab e selecione Excluir.

Excluir um ponto de extremidade

Monitorizar a saúde de um ponto de extremidade

Para obter informações sobre os logs e métricas disponíveis para pontos de extremidade de serviço de funcionalidades, consulte Monitorizar a qualidade do modelo e a integridade do ponto de extremidade.

Controlo de acesso

Para obter informações sobre permissões nos endpoints de serviço de funcionalidade, consulte Gerir permissões em um endpoint de serviço de modelo.

Bloco de notas de exemplo

Este caderno ilustra como usar o Databricks SDK para criar um endpoint de Feature Serving usando a Databricks Online Feature Store.

Exemplo de caderno de Feature Serving com loja online

Obter bloco de notas

  • Última atualização a