Usar ML e IA com BigQuery DataFrames

A biblioteca bigframes.ml no BigQuery DataFrames permite integrar recursos de IA e machine learning (ML) aos fluxos de trabalho de análise de dados. O pré-processamento de dados, o treinamento de modelos e a criação de pipelines de ML diretamente no BigQuery permitem escalonar suas análises sem extrair conjuntos de dados do data warehouse.

Funções exigidas

Para receber as permissões necessárias para realizar as tarefas neste documento, peça ao administrador para conceder a você os seguintes papéis do IAM no seu 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 oferece suporte aos 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

Criar transformadores a fim de 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 atributo 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 recurso para o intervalo [0, 1], use a classe MinMaxScaler no módulo bigframes.ml.preprocessing.

  • Para padronizar atributos removendo a média e escalonando 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 BigQuery DataFrames.

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, na sigla em inglês), use a classe PCA. Use esses modelos para calcular os componentes principais e usá-los para realizar uma alteração de base nos dados. O uso da 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 com boost de 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 com boost de 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 prever as 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 BigQuery DataFrames (bigframes.ml.remote ou bigframes.ml.llm), ative as seguintes APIs:

Ao usar modelos remotos de ML do BigQuery DataFrames, você precisa do papel de administrador do IAM do projeto (roles/resourcemanager.projectIamAdmin) se usar uma conexão padrão do BigQuery ou do papel 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 no estado em que se encontra, sem qualquer existência ou verificação de permissão. Se você usar a conexão pré-configurada e pular a verificação de conexão, verifique o seguinte:

A criação de um modelo remoto no BigQuery DataFrames 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 Agent Platform (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:

  • 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 de 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