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.

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.

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")

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

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.

   

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.

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

Atualizar um endpoint

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.

Excluir um ponto de extremidade

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 selecione Excluir.

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