Tabelas de recursos do Serve

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

• Implantação de modelos: Implante um modelo que foi treinado em tabelas de atributos. O mesmo endpoint é usado tanto para consulta de features quanto para inferência de modelo. O endpoint pesquisa ou calcula automaticamente os valores dos atributos, usando a linhagem rastreada quando o modelo foi registrado. Use isso para atender a previsões de modelo.
• Feature Serving: Implante um FeatureSpec que faz referência a tabelas de features diretamente, sem um modelo. O endpoint retorna as saídas de recursos solicitadas. Use isso quando um aplicativo precisar de valores de recurso em vez de previsões de modelo. Se você estiver usando atributos para inferência de modelos, a Databricks recomenda usar model serving diretamente.

Ambas as abordagens suportam recursos pré-computados e sob demanda.

Requisitos

• Databricks Runtime 14.2 ML ou superior.
• Para usar a API Python, o Serviço de Recursos requer databricks-feature-engineering versão 0.1.2 ou superior, que é integrada ao Databricks Runtime 14.2 ML. Para versões anteriores do Databricks Runtime ML, instale manualmente a versão necessária usando o %pip install databricks-feature-engineering>=0.1.2. Se você estiver usando um notebook do Databricks, reinicie o kernel Python executando esse comando em uma nova célula: dbutils.library.restartPython().
• Para usar o SDK do Databricks, o Feature Serving requer a versão 0.18.0 ou superior do databricks-sdk. Para instalar manualmente a versão necessária, use %pip install databricks-sdk>=0.18.0. Se você estiver usando um notebook do Databricks, reinicie o kernel Python executando esse comando em uma nova célula: dbutils.library.restartPython().

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

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

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

Autenticação do Serviço de Recursos

Para obter informações sobre autenticação, consulte Authorize o acesso aos recursos Azure Databricks.

Criar um FeatureSpec

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

As tabelas especificadas em um repositório FeatureSpec de recursos online devem ser publicadas ou em um repositório online de terceiros. Consulte repositórios de recursos do Databricks Online.

Você precisa usar o pacote do 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
)

Em seguida, 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. Consulte 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 recurso forem renomeadas usando o rename_outputs parâmetro, default_values deverá 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 usuário (UDF) importar pacotes Python, declare-os ao 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 de recurso importar o 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 string de requisitos PyPI, como numpy==1.26.4, ou um caminho para um .whl arquivo em um volume do Unity Catalog. Por exemplo, use /Volumes/main/libraries/wheels/custom_features-1.0.0-py3-none-any.whl para uma roda que você carregou. O criador do endpoint deve ter READ VOLUME no volume e USE CATALOGUSE SCHEMA em seu catálogo pai e esquema.

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

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

Se a implantação no endpoint falhar, inspecione os logs de compilação em busca de erros na instalação de pacotes, conflitos de versão ou falhas de acesso na roda. Consulte Monitorar a qualidade do modelo e a integridade do ponto de extremidade.

Para um exemplo com CustomUDF e FeatureViewSource, veja características do Serve CustomUDF e suas dependências. Para dependências de servidor de modelos, veja Dependências UDF personalizadas.

Criar um ponto de extremidade

O FeatureSpecdefine o ponto de extremidade. Para obter mais informações, consulte Criar pontos de extremidade de serviço de modelo personalizados, a documentação da API do Python ou a documentação do SDK do Databricks para obter mais detalhes.

SDK do 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 de 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 Servir na barra lateral esquerda da interface do usuário do Databricks. Quando o estado estiver Pronto, o ponto de extremidade estará pronto para responder às consultas. Para saber mais sobre o Model Serving, consulte Model Serving.

Salvar o DataFrame aumentado na tabela de inferência

Para pontos de extremidade criados a partir de fevereiro de 2025, você pode configurar o ponto de extremidade do serviço de modelo para registrar o DataFrame aumentado que contém os valores de recurso pesquisados e os valores de retorno da função. O DataFrame é salvo na tabela de inferência do modelo servido.

Para obter instruções sobre como definir essa configuração, confira Registrar DataFrames de pesquisa de recursos em tabelas de inferência.

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

Obter um ponto de extremidade

Você pode usar o SDK do Databricks ou a API Python para obter os metadados e o status de um ponto de extremidade.

SDK do Databricks – Python

from databricks.sdk import WorkspaceClient
workspace = WorkspaceClient()

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

API de 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 obter mais informações sobre o esquema do ponto de extremidade, consulte Obter um esquema do ponto de extremidade de serviço de modelo.

SDK do 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 do MLflow ou a Interface do Usuário de Serviços para consultar um ponto de extremidade.

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

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

  # Set up the client
  import mlflow.deployments

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

Consultar um ponto de extremidade usando APIs

Essa seção inclui exemplos de consulta de um ponto de extremidade usando a API REST ou o SDK de Implantações do MLflow.

SDK de Implantaçõ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 ponto de extremidade usando a interface do usuário

Você pode consultar um ponto de extremidade de serviços diretamente a partir da Interface do Usuário de Serviços. A interface do usuário inclui exemplos de código gerado que você pode usar para consultar o ponto de extremidade.

1. Na barra lateral esquerda do workspace Azure Databricks, clique em Serving.

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

3. No canto superior direito da tela, 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 }
  ]
}

A caixa de diálogo Query endpoint inclui códigos de exemplo gerados em curl, Python e SQL. Clique nas guias para exibir 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 ponto de extremidade

Você pode atualizar um ponto de extremidade usando a API REST, o SDK do Databricks ou a Interface do Usuário de Serviços.

Atualizar um ponto de extremidade usando as APIs

SDK do 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
        }
    ]'

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

Siga as etapas abaixo para usar a Interface do Usuário de Serviços.

1. Na barra lateral esquerda do workspace Azure Databricks, clique em Serving.
2. Na tabela, clique no nome do ponto de extremidade que você quer atualizar. A tela do ponto de extremidade é exibida.
3. No canto superior direito da tela, clique em Editar ponto de extremidade.
4. Na caixa de diálogo Editar ponto de extremidade de serviços, edite as configurações do ponto de extremidade conforme necessário.
5. Clique em Atualizar para salvar suas alterações.

Excluir um ponto de extremidade

Você pode excluir um ponto de extremidade usando a API REST, o SDK do Databricks, a API do Python ou a Interface do Usuário de Serviços.

Excluir um ponto de extremidade usando APIs

SDK do Databricks – Python

from databricks.sdk import WorkspaceClient
workspace = WorkspaceClient()

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

API de 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 as etapas abaixo para excluir um ponto de extremidade usando a Interface do Usuário de Serviços:

1. Na barra lateral esquerda do workspace Azure Databricks, clique em Serving.
2. Na tabela, clique no nome do ponto de extremidade que você quer excluir. A tela do ponto de extremidade é exibida.
3. No canto superior direito da tela, clique no e selecione Excluir.

Monitorar a integridade de um ponto de extremidade

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

Controle de acesso

Para obter informações sobre permissões em pontos de extremidade de Feature Serving, consulte Gerenciar permissões em um ponto de extremidade de Serviço de Modelo.

Caderno de exemplo

Esse notebook ilustra como usar o SDK do Databricks para criar um ponto de extremidade do Feature Serving usando o Repositório de Recursos do Databricks Online.

Notebook de exemplo do Feature Serving com repositório online

Obter notebook