Pular para o conteúdo principal
Última atualização em

Disponibilizar tabelas de recursos

As tabelas de recursos podem ser disponibilizadas de duas maneiras:

  • servindo modelo : implante um modelo que foi treinado em tabelas de recursos. O mesmo endpoint é usado para a pesquisa de recursos e para a inferência de modelos. O endpoint busca ou computa valores de recursos automaticamente, usando a linhagem rastreada quando o modelo foi registrado. Use isto para servir previsões de modelos.
  • Feature Serving : implante um FeatureSpec que faça referência a tabelas de recursos diretamente, sem um modelo. O endpoint retorna as saídas de recursos solicitadas. Use isto quando um aplicativo precisar de valores de recursos em vez de previsões de modelo. Se você estiver usando recursos para inferência de modelo, o Databricks recomenda usar o servindo modelo diretamente.

Ambas as abordagens oferecem suporte a recursos pré-computados e sob demanda.

Requisitos​

  • Databricks Runtime 14.2 ML ou acima.
  • Para usar a API do Python, o Feature Serving requer o site databricks-feature-engineering versão 0.1.2 ou acima, que está incorporado 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 usando um notebook Databricks, o senhor deverá reiniciar o kernel Python executando este comando em uma nova célula: dbutils.library.restartPython().
  • Para usar o Databricks SDK, Feature Serving requer databricks-sdk versão 0.18.0 ou acima. Para instalar manualmente a versão necessária, use %pip install databricks-sdk>=0.18.0. Se estiver usando um notebook Databricks, o senhor deverá reiniciar o kernel Python executando este comando em uma nova célula: dbutils.library.restartPython().

Databricks Feature Serving fornece uma interface de 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 opções a seguir:

  • IU da Databricks
  • API REST
  • API do Python
  • SDK da Databricks

Para usar o REST API ou MLflow Deployments SDK, o senhor deve ter um token Databricks API .

Autenticação para Feature Serving​

Para obter informações sobre autenticação, consulte Autorizar acesso ao recurso Databricks.

Crie um FeatureSpec​

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

As tabelas especificadas em um FeatureSpec devem ser publicadas em uma loja de recursos on-line ou em um armazenamento on-line de terceiros. Consulte Databricks Online recurso Stores.

O senhor deve usar o pacote databricks-feature-engineering para criar um FeatureSpec.

Primeiro, defina a função:

Python
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:

Python
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,
)

Especifique os valores d default​

Para especificar valores de default para recurso, utilize o parâmetro default_values em FeatureLookup. Veja o exemplo a seguir:

Python
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 parâmetro " rename_outputs ", o comando " default_values " deverá utilizar os nomes renomeados dos recursos.

Python
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 do Python​

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

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

Python
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 o nome da especificação quando você criar o endpoint.

Cada entrada em extra_pip_requirements deve ser uma string de requisito do PyPI, como numpy==1.26.4, ou o caminho para um arquivo .whl em um volume do Unity Catalog. Por exemplo, use /Volumes/main/libraries/wheels/custom_features-1.0.0-py3-none-any.whl para uma wheel que você tenha feito upload. O criador do endpoint deve ter READ VOLUME no volume e USE CATALOG e USE SCHEMA em seu catálogo pai e esquema.

Para pacotes de um repository privado, configure o repository de pacotes default do Workspace. Não coloque opções de comando do pip, como --index-url, em extra_pip_requirements.

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

Se a implantação do endpoint falhar, inspecione os logs de compilação em busca de erros de instalação de pacote, conflitos de versão ou falhas de acesso ao wheel. Consulte Monitorar a qualidade do modelo e a integridade do endpoint.

Para ver um exemplo com CustomUDF e FeatureViewSource, consulte Disponibilizar recursos CustomUDF e suas dependências. Para obter dependências de servindo modelo, consulte Dependências de UDF personalizada.

Criar um endpoint​

O FeatureSpec define o endpoint. Para obter mais informações, consulte Create custom servindo modelo endpoint, a documentação Python API ou a documentaçãoDatabricks SDK para obter detalhes.

nota

Para cargas de trabalho que são sensíveis à latência ou que exigem altas consultas por segundo, a servindo modelo oferece otimização de rota no endpoint personalizado da servindo modelo, consulte Otimização de rota no endpoint da servindo.

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

Para visualizar o endpoint, clique em "Serving" na barra lateral esquerda da interface do Databricks. Quando o estado for Pronto , o endpoint estará pronto para responder a consultas. Para saber mais sobre modelo de atividade, consulte modelo de atividade.

Obter um endpoint​

O senhor pode usar o SDK da Databricks ou a API do Python para obter os metadados e o status de um endpoint.

Python
from databricks.sdk import WorkspaceClient
workspace = WorkspaceClient()

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

Obter o esquema de um endpoint​

É possível utilizar o Databricks SDK ou o REST API para obter o esquema de um endpoint. Para obter mais informações sobre o esquema endpoint, consulte Obter um modelo de serviço do esquema endpoint.

Python
from databricks.sdk import WorkspaceClient
workspace = WorkspaceClient()

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

Consultar um endpoint​

O senhor pode usar a REST API, o MLflow Deployments SDK ou a Serving UI para consultar um endpoint.

O código a seguir mostra como configurar as credenciais e criar o cliente ao usar o SDK do MLflow Deployments.

  # Set up credentials
  export DATABRICKS_HOST=...
  export DATABRICKS_TOKEN=...
Python
  # Set up the client
  import mlflow.deployments

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

Como prática recomendada de segurança, ao autenticar 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 workspace. Para criar tokens para entidades de serviço, consulte Gerenciar tokens para uma entidade de serviço.

Consultar um site endpoint usando APIs​

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

importante

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

Python
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},
        ]
    },
)

Consultar um endpoint usando a UI​

O senhor pode consultar um serviço endpoint diretamente da Serving UI. A interface do usuário inclui exemplos de códigos gerados que o senhor pode usar para consultar o endpoint.

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

  2. Clique no endpoint que o senhor deseja consultar.

  3. No canto superior direito da tela, clique em Query endpoint (Consultar ponto de extremidade ).

    Consultar o botão endpoint

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

  5. Clique em Enviar solicitação .

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

A caixa de diálogo do endpoint Query inclui um código de exemplo gerado em curl, Python e SQL. Clique na guia view e copie o código de exemplo.

consulta endpoint diálogo

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

botão de cópia na caixa de diálogo da consulta endpoint

Atualizar e endpoint​

importante

Para modificar a configuração de um endpoint Feature Serving (como alterar o FeatureSpec ou o tamanho da carga de trabalho), use sempre as APIs de atualização descritas nesta seção. Não exclua e recrie o endpoint para aplicar as alterações. A exclusão de um endpoint ativo causa indisponibilidade imediata e interrompe todos os aplicativos que o consultam.

O senhor pode atualizar um endpoint usando a REST API, o Databricks SDK ou a Serving UI.

Atualize o site endpoint usando APIs​

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

Atualizar um endpoint usando a UI​

Siga estas etapas para usar a Serving UI:

  1. Na barra lateral esquerda do site Databricks workspace, clique em Serving .
  2. Na tabela, clique no nome do endpoint que o senhor deseja atualizar. A tela do endpoint é exibida.
  3. No canto superior direito da tela, clique em Editar endpoint .
  4. Na caixa de diálogo Edit serving endpoint (Editar endpoint de serviço ), edite as configurações do endpoint conforme necessário.
  5. Clique em Atualizar para salvar suas alterações.

atualizar e endpoint

Atualizar dependências de um endpoint de Feature Serving ativo​

Um endpoint de Feature Serving resolve suas dependências quando é construído e implantado pela primeira vez: os privilégios que seu service principal precisa para ler a tabela online (USE CATALOG, USE SCHEMA e SELECT) e EXECUTE no UDF do Unity Catalog descrito em seu FeatureSpec. O endpoint corrige essas permissões no momento da construção e não as resolve novamente em uma reimplementação ou reinicialização simples. Se você recriar a tabela online ou o UDF, o endpoint perderá a permissão nela. Se você atualizar o UDF no local, o endpoint continuará executando a versão original. As pesquisas de recursos podem falhar ou usar silenciosamente a lógica UDF antiga, mesmo enquanto o endpoint continua relatando Pronto .

Tanto para tabelas online quanto para UDFs sob demanda, o Databricks recomenda uma migração versionada: crie uma nova versão da dependência, crie um novo endpoint para ela e migre o tráfego para o novo endpoint. Isso ajuda você a evitar o tempo de inatividade e os modos de falha descritos nesta seção.

Recriar uma tabela online​

atenção

Não exclua e recrie uma tabela online no local sob um endpoint de Feature Serving ativo.

Quando você cria um endpoint, o Model Serving concede ao service principal do endpoint USE CATALOG no catálogo da tabela online, USE SCHEMA em seu esquema e SELECT na tabela online. Excluir e recriar a tabela, mesmo com o mesmo nome, cria um novo objeto protegível no Unity Catalog, portanto, a concessão SELECT não será transferida. O service principal perde acesso à tabela, a geração de tokens OAuth falha e a conexão com o armazenamento online falha e volta para a autenticação por senha. As pesquisas de recursos falham com erros como KeyError: 'OAUTH_TOKEN' ou password authentication failed.

Essas falhas são fáceis de perder: o endpoint ainda informa Pronto e o pipeline de sincronização ainda mostra execuções bem-sucedidas, enquanto as pesquisas falham. Alterar o modo de sincronização de uma tabela online (por exemplo, entre CONTINUOUS e SNAPSHOT) não pode ser feito in-place e requer a recriação da tabela, o que também pode desencadear esse problema.

Um endpoint não lê uma tabela online específica. Ele pesquisa recursos por meio da tabela de recursos offline nomeada em seu FeatureSpec e, quando uma tabela de recursos é publicada em mais de uma tabela online, o endpoint usa a mais antiga. Publicar a mesma tabela de recursos em uma segunda tabela online não move um endpoint para a nova tabela online. Consulte Limitações do Online Feature Store.

Para minimizar o tempo de inatividade, versione a tabela de recursos offline e a tabela online:

  1. Crie uma nova tabela de recursos offline e inclua a versão em seu nome (por exemplo, customer_features_v2).
  2. Publique a nova tabela de recursos em uma nova tabela online. Consulte Publicar uma tabela de recursos.
  3. Crie um novo FeatureSpec que use a nova tabela de recursos e crie um novo endpoint de Feature Serving que o disponibilize.
  4. Migre o tráfego para o novo endpoint. Depois que o endpoint antigo não receber mais tráfego, exclua-o e sua tabela online.

Atualizar um UDF sob demanda​

atenção

Não modifique uma UDF do Unity Catalog usada por um FeatureSpec no local.

A UDF sob demanda de um FeatureSpec é incorporada ao endpoint de disponibilização no momento da implantação. Um refresh simples ou uma reimplementação reutiliza a mesma UDF nessa imagem de disponibilização. Uma atualização no local da UDF com o mesmo nome não entra em vigor. Se você soltar e recriar a UDF, o endpoint também perderá EXECUTE nela, de modo que as pesquisas que usam a UDF falharão.

FeatureSpecs e UDFs não têm um campo de versão, portanto, versionam por nome: crie um novo UDF e um novo FeatureSpec, crie um novo endpoint que use o novo FeatureSpec e migre o tráfego para ele. Consulte Criar um FeatureSpec.

Consulte Cálculo de recursos sob demanda.

Recuperar um endpoint após uma alteração in-place​

Se você já alterou uma dependência no local, reconstrua o endpoint para que ele resolva novamente suas dependências. Crie um novo FeatureSpec (ou, para um endpoint de Model Serving, registre uma nova versão do modelo) e atualize o endpoint para servir a ele. Alterar o que o Endpoint serve reconstrói o Endpoint, o que faz o provisionamento de um novo Service Principal e faz novamente a execução da configuração de permissão. Nenhum desses métodos reconstrói o endpoint de forma confiável: pará-lo e iniciá-lo, uma redeplantação simples ou alterar uma variável de ambiente.

Excluir um endpoint​

atenção

Essa ação é irreversível. A exclusão de um endpoint do Feature Serving causa indisponibilidade imediata para quaisquer aplicativos que o consultem. Se você deseja alterar a configuração do endpoint, use "Atualizar um endpoint" em vez de excluir e recriar o endpoint.

O senhor pode excluir um endpoint usando a REST API, o Databricks SDK, a Python API ou a Serving UI.

Excluir um endpoint usando APIs​

Python
from databricks.sdk import WorkspaceClient
workspace = WorkspaceClient()

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

Excluir um endpoint usando a interface do usuário​

Siga estas etapas para excluir um endpoint usando a Serving UI:

  1. Na barra lateral esquerda do site Databricks workspace, clique em Serving .
  2. Na tabela, clique no nome do endpoint que o senhor deseja excluir. A tela do endpoint é exibida.
  3. No canto superior direito da tela, clique no menu de kebab Ícone do menu Kebab. e selecione Excluir.

excluir um endpoint

Monitorar a integridade de um endpoint​

Para obter informações sobre o logs e as métricas disponíveis para o endpoint Feature Serving, consulte Monitorar a qualidade do modelo e a saúde do endpoint.

Controle de acesso​

Para obter informações sobre permissões no endpoint Feature Serving , consulte gerenciar permissões em um modelo endpointopcional.

Exemplo de notebook​

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

Exemplo Feature Serving : Notebook com funcionalidade online

Abrir notebook em uma nova abaOpen in Databricks
Nesta página