Usar ML e IA com DataFrames do BigQuery

O BigQuery DataFrames oferece recursos de ML e IA para DataFrames do BigQuery usando a biblioteca bigframes.ml.

É possível pré-processar dados, criar estimadores para treinar modelos nos DataFrames do BigQuery, criar pipelines de ML e dividir conjuntos de dados de treinamento e teste.

Funções exigidas

Para conseguir as permissões necessárias a fim de concluir as tarefas neste documento, peça ao administrador para conceder a você os seguintes papéis do IAM no projeto:

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

Locais ML

A biblioteca bigframes.ml é compatível com os mesmos locais que o BigQuery ML. A previsão do modelo do BigQuery ML e outras funções de ML são aceitas em todas as regiões do BigQuery. O suporte para treinamento de modelo varia de acordo com a região. Para mais informações, consulte Locais do BigQuery ML.

Pré-processar dados

Crie transformadores para preparar dados para uso em estimadores (modelos) usando o módulo bigframes.ml.preprocessing e o módulo bigframes.ml.compose. O DataFrames do BigQuery oferece as seguintes transformações:

  • Para agrupar dados contínuos em intervalos, use a classe KBinsDiscretizer no módulo bigframes.ml.preprocessing.

  • Para normalizar os rótulos de destino como valores inteiros, use a classe LabelEncoder no módulo bigframes.ml.preprocessing.

  • Para dimensionar cada recurso para o intervalo [-1, 1] de acordo com o valor absoluto máximo, use a classe MaxAbsScaler no módulo bigframes.ml.preprocessing.

  • Para padronizar recursos escalonando cada um para o intervalo [0, 1], use a classe MinMaxScaler no módulo bigframes.ml.preprocessing.

  • Para padronizar recursos removendo a média e dimensionando para a variância da unidade, use a classe StandardScaler no módulo bigframes.ml.preprocessing.

  • Para transformar valores categóricos em formato numérico, use a classe OneHotEncoder no módulo bigframes.ml.preprocessing.

  • Para aplicar transformadores a colunas do DataFrames, use a classe ColumnTransformer no módulo bigframes.ml.compose.

Treinar modelos

É possível criar estimadores para treinar modelos nos DataFrames do BigQuery.

Modelos de clustering

Crie estimadores para modelos de clustering usando o módulo bigframes.ml.cluster. Para criar modelos de clustering K-means, use a classe KMeans. Use esses modelos para segmentação de dados. Por exemplo, identificar segmentos de clientes. K-means é uma técnica de aprendizado não supervisionada, portanto, treinamento de modelo não requer rótulos ou dados de divisão para treinamento ou avaliação.

Use o módulo bigframes.ml.cluster para criar estimadores para modelos de clustering.

O exemplo de código a seguir mostra o uso da classe bigframes.ml.cluster KMeans para criar um modelo de clustering K-means para segmentação de dados:

from bigframes.ml.cluster import KMeans
import bigframes.pandas as bpd

# Load data from BigQuery
query_or_table = "bigquery-public-data.ml_datasets.penguins"
bq_df = bpd.read_gbq(query_or_table)

# Create the KMeans model
cluster_model = KMeans(n_clusters=10)
cluster_model.fit(bq_df["culmen_length_mm"], bq_df["sex"])

# Predict using the model
result = cluster_model.predict(bq_df)
# Score the model
score = cluster_model.score(bq_df)

Modelos de decomposição

Crie estimadores para modelos de decomposição usando o módulo bigframes.ml.decomposition. Para criar modelos de análise de componentes principais (PCA), use a classe PCA. Use esses modelos para calcular os componentes principais e usá-los para realizar uma mudança de base nos dados. Usar a classe PCA reduz a dimensionalidade, projetando cada ponto de dados apenas nos primeiros componentes principais. Assim, você consegue dados de dimensões menores, preservando o máximo possível da variação deles.

Modelos do conjunto

É possível criar estimadores para modelos de conjunto usando o módulo bigframes.ml.ensemble.

  • Para criar modelos de classificador de floresta aleatória, use a classe RandomForestClassifier. Use esses modelos para construir várias árvores de decisão de método de aprendizado para classificação.

  • Para criar modelos de regressão de floresta aleatória, use a classe RandomForestRegressor. Use esses modelos para construir várias árvores de decisão de método de aprendizado para regressão.

  • Para criar modelos de classificador de árvore otimizada com gradiente, use a classe XGBClassifier. Use esses modelos para construir aditivamente várias árvores de decisão de método de aprendizado para classificação.

  • Para criar modelos de regressão de árvore otimizada com gradiente, use a classe XGBRegressor. Use esses modelos para construir aditivamente várias árvores de decisão de método de aprendizado para regressão.

Modelos de previsão

É possível criar estimadores para modelos de previsão usando o módulo bigframes.ml.forecasting. Para criar modelos de previsão de série temporal, use a classe ARIMAPlus.

Modelos importados

É possível criar estimadores para modelos importados usando o módulo bigframes.ml.imported.

Modelos lineares

Crie estimadores para modelos lineares usando o módulo bigframes.ml.linear_model.

  • Para criar modelos de regressão linear, use a classe LinearRegression. Use esses modelos para previsão, como a previsão das vendas de um item em um determinado dia.

  • Para criar modelos de regressão logística, use a classe LogisticRegression. Use esses modelos para a classificação de dois ou mais valores possíveis, por exemplo, se uma entrada é low-value, medium-value ou high-value.

O exemplo de código abaixo mostra o uso de bigframes.ml para realizar as seguintes ações:

from bigframes.ml.linear_model import LinearRegression
import bigframes.pandas as bpd

# Load data from BigQuery
query_or_table = "bigquery-public-data.ml_datasets.penguins"
bq_df = bpd.read_gbq(query_or_table)

# Filter down to the data to the Adelie Penguin species
adelie_data = bq_df[bq_df.species == "Adelie Penguin (Pygoscelis adeliae)"]

# Drop the species column
adelie_data = adelie_data.drop(columns=["species"])

# Drop rows with nulls to get training data
training_data = adelie_data.dropna()

# Specify your feature (or input) columns and the label (or output) column:
feature_columns = training_data[
    ["island", "culmen_length_mm", "culmen_depth_mm", "flipper_length_mm", "sex"]
]
label_columns = training_data[["body_mass_g"]]

test_data = adelie_data[adelie_data.body_mass_g.isnull()]

# Create the linear model
model = LinearRegression()
model.fit(feature_columns, label_columns)

# Score the model
score = model.score(feature_columns, label_columns)

# Predict using the model
result = model.predict(test_data)

Modelos de linguagem grande

É possível criar estimadores para LLMs usando o módulo bigframes.ml.llm.

  • Para criar modelos geradores de texto do Gemini, use a classe GeminiTextGenerator. Use esses modelos para tarefas de geração de texto.

  • Para criar estimadores para modelos de linguagem grandes (LLMs) remotos, use o módulo bigframes.ml.llm.

O exemplo de código a seguir mostra como usar a classe bigframes.ml.llm GeminiTextGenerator para criar um modelo do Gemini para geração de código:

from bigframes.ml.llm import GeminiTextGenerator
import bigframes.pandas as bpd

# Create the Gemini LLM model
session = bpd.get_global_session()
connection = f"{PROJECT_ID}.{REGION}.{CONN_NAME}"
model = GeminiTextGenerator(
    session=session, connection_name=connection, model_name="gemini-2.0-flash-001"
)

df_api = bpd.read_csv("gs://cloud-samples-data/vertex-ai/bigframe/df.csv")

# Prepare the prompts and send them to the LLM model for prediction
df_prompt_prefix = "Generate Pandas sample code for DataFrame."
df_prompt = df_prompt_prefix + df_api["API"]

# Predict using the model
df_pred = model.predict(df_prompt.to_frame(), max_output_tokens=1024)

Modelos remotos

Para usar modelos remotos de ML do DataFrames do BigQuery (bigframes.ml.remote ou bigframes.ml.llm), ative as seguintes APIs:

Ao usar modelos remotos de ML do BigQuery DataFrames, você precisa da função de administrador do IAM do projeto (roles/resourcemanager.projectIamAdmin) se usar uma conexão padrão do BigQuery ou da função de navegador (roles/browser) se usar uma conexão pré-configurada. Para evitar esse requisito, defina a opção bigframes.pandas.options.bigquery.skip_bq_connection_check como True. Nesse caso, a conexão (padrão ou pré-configurada) será usada sem alterações, sem qualquer verificação de existência ou permissão. Se você usar a conexão pré-configurada e pular a verificação de conexão, verifique o seguinte:

  • A conexão é criada no local certo.
  • Se você usar modelos remotos de ML do DataFrames do BigQuery, a conta de serviço terá a função de usuário da Vertex AI (roles/aiplatform.user) no projeto.

A criação de um modelo remoto no DataFrames do BigQuery cria uma conexão com o BigQuery. Por padrão, uma conexão com o nome bigframes-default-connection é usada. Se preferir, use uma conexão pré-configurada do BigQuery. Nesse caso, a criação da conexão é ignorada. A conta de serviço da conexão padrão recebe o papel de usuário da Vertex AI (roles/aiplatform.user) no projeto.

Criar pipelines

É possível criar pipelines de ML usando o módulo bigframes.ml.pipeline. Os pipelines permitem montar várias etapas de ML para validação cruzada ao definir parâmetros diferentes. Isso simplifica o código e permite implantar etapas de pré-processamento de dados e um estimador juntos.

Para criar um pipeline de transformações com um estimador final, use a classe Pipeline.

Selecionar modelos

Para dividir os conjuntos de dados de treinamento e teste e selecionar os melhores modelos, use o módulo bigframes.ml.model_selection module:

  • Para dividir os dados em conjuntos de treinamento e teste (avaliação), conforme mostrado no exemplo de código a seguir, use a função train_test_split:

    X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.2)

  • Para criar conjuntos de treinamento e teste de várias dobras para treinar e avaliar modelos, conforme mostrado no exemplo de código a seguir, use a classe KFold e o método KFold.split. Esse recurso é útil para conjuntos de dados pequenos.

    kf = KFold(n_splits=5)
for i, (X_train, X_test, y_train, y_test) in enumerate(kf.split(X, y)):
# Train and evaluate models with training and testing sets

  • Para criar automaticamente conjuntos de treinamento e teste com várias dobras, treinar e avaliar o modelo e receber o resultado de cada dobra, conforme mostrado no exemplo de código a seguir, use a função cross_validate:

    scores = cross_validate(model, X, y, cv=5)

A seguir