Recurso Servir pontos de extremidade

O Databricks Feature Serving disponibiliza dados na plataforma Databricks para modelos ou aplicativos implantados fora do Azure Databricks. Os pontos de extremidade do Serviço de Recursos são dimensionados automaticamente para ajustarem-se ao tráfego em tempo real e fornecerem um serviço de alta disponibilidade e baixa latência para atenderem aos recursos. Esta página descreve como configurar e usar o Feature Serving. Para um tutorial passo a passo, consulte Exemplo: implantar e consultar um ponto de extremidade de serviço de recursos.

Quando você usa o Serviço de Modelo do Mosaic AI para servir um modelo que foi criado usando recursos do Databricks, o modelo procura e transforma automaticamente os recursos para solicitações de inferência. Com o Databricks Feature Serving, você pode fornecer dados estruturados para aplicativos RAG (geração aumentada de recuperação), bem como os recursos necessários para outros aplicativos, como modelos servidos fora do Databricks ou qualquer outro aplicativo que exija recursos baseados em dados no Catálogo do Unity.

Por que usar o Feature Serving?

O Databricks Feature Serving fornece uma única interface que atende a recursos pré-materializados e sob demanda. Ele também inclui os seguintes benefícios:

• Simplicidade. O Databricks manipula a infraestrutura. Com uma única chamada à API, o Databricks cria um ambiente de serviço pronto para produção.
• Alta disponibilidade e escalabilidade. Os pontos de extremidade do Serviço de Recursos são escalados e reduzidos automaticamente para ajustarem-se ao volume de solicitações de serviço.
• Segurança. Os pontos de extremidade são implantados em um limite de rede seguro e usam computação dedicada que termina quando o ponto de extremidade é excluído ou dimensionado para zero.

Requisitos

• Databricks Runtime 14.2 ML ou superior.
• Para usar a API do Python, o Feature Serving requer a versão 0.1.2 ou superior do databricks-feature-engineering, 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, deverá reiniciar o kernel do Python executando este 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, deverá reiniciar o kernel do Python executando este 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 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 Autorizar o acesso aos recursos do 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 renomeada usando o rename_outputs parâmetro, default_values deverá usar os nomes de recursos renomeado.

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

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 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 Serviço de Modelo do Mosaic AI, consulte Serviço de Modelo do Mosaic AI.

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 obter informações sobre tabelas de inferência, consulte tabelas de inferência para modelos de monitoramento e depuração.

Obter um ponto de extremidade

Você pode usar o SDK do Databricks ou a API do 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 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 de navegação do lado esquerdo do workspace do Azure Databricks, clique em Serviços.

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 Ponto de extremidade de consulta inclui códigos de exemplo gerados no 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 de navegação do lado esquerdo do workspace do Azure Databricks, clique em Serviços.
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 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 de navegação do lado esquerdo do workspace do Azure Databricks, clique em Serviços.
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 Serviço de Funcionalidade, consulte Gerenciar permissões em um ponto de extremidade de serviço de funcionalidade.

Caderno de exemplo

Esse notebook ilustra como usar o SDK do Databricks para criar um ponto de extremidade do Feature Serving usando tabelas online do Databricks.

Notebook de exemplo do Serviço de Recursos com tabelas online

Obter notebook