מעבר לגרסה 2.0 של BigQuery DataFrames

גרסה 2.0 של BigQuery DataFrames כוללת שיפורים באבטחה ובביצועים של BigQuery DataFrames API, תכונות חדשות ושינויי תוכנה שעלולים לגרום לכשל. במאמר הזה מתוארים השינויים ומוסבר איך לבצע את ההעברה. אתם יכולים ליישם את ההמלצות האלה לפני שאתם מתקינים את גרסה 2.0, באמצעות הגרסה העדכנית 1.x של BigQuery DataFrames.

אלה היתרונות של גרסה 2.0 של BigQuery DataFrames:

  • כשמריצים שאילתות שמחזירות תוצאות ללקוח, השאילתות מהירות יותר ונוצרות פחות טבלאות, כי allow_large_results מוגדר כברירת מחדל ל-False. העיצוב הזה יכול להפחית את עלויות האחסון, במיוחד אם אתם משתמשים בחיוב לפי בייטים פיזיים.
  • אבטחה משופרת כברירת מחדל בפונקציות המרוחקות שנפרסות על ידי BigQuery DataFrames.

התקנת BigQuery DataFrames בגרסה 2.0

כדי למנוע שינויי תוכנה שעלולים לגרום לכשל, הצמידו לגרסה ספציפית של BigQuery DataFrames בקובץ requirements.txt (לדוגמה, bigframes==1.42.0) או בקובץ pyproject.toml (לדוגמה, dependencies = ["bigframes = 1.42.0"]). כשתהיו מוכנים לנסות את הגרסה העדכנית, תוכלו להריץ את pip install --upgrade bigframes כדי להתקין את הגרסה העדכנית של BigQuery DataFrames.

שימוש באפשרות allow_large_results

ב-BigQuery יש מגבלה על גודל התגובה המקסימלי למשימות של שאילתות. החל מגרסה 2.0 של BigQuery DataFrames, המגבלה הזו נאכפת כברירת מחדל בשיטות שמחזירות תוצאות ללקוח, כמו peek(),‏ to_pandas() ו-to_pandas_batches(). אם המשימה מחזירה תוצאות גדולות, אפשר להגדיר את allow_large_results ל-True באובייקט BigQueryOptions כדי להימנע משינוי תוכנה שעלול לגרום לכשל. האפשרות הזו מוגדרת כ-False כברירת מחדל ב-BigQuery DataFrames בגרסה 2.0.

import bigframes.pandas as bpd

bpd.options.bigquery.allow_large_results = True

אפשר לשנות את האפשרות allow_large_results באמצעות הפרמטר allow_large_results ב-to_pandas() ובשיטות אחרות. לדוגמה:

bf_df = bpd.read_gbq(query)
# ... other operations on bf_df ...
pandas_df = bf_df.to_pandas(allow_large_results=True)

שימוש במעצב @remote_function

בגרסה 2.0 של BigQuery DataFrames יש כמה שינויים בהתנהגות ברירת המחדל של ה-decorator‏ @remote_function.

ארגומנטים של מילות מפתח נאכפים על פרמטרים לא ברורים

כדי למנוע העברת ערכים לפרמטר לא מכוון, בגרסה 2.0 ואילך של BigQuery DataFrames נדרש שימוש בארגומנטים של מילות מפתח לפרמטרים הבאים:

  • bigquery_connection
  • reuse
  • name
  • packages
  • cloud_function_service_account
  • cloud_function_kms_key_name
  • cloud_function_docker_repository
  • max_batching_rows
  • cloud_function_timeout
  • cloud_function_max_instances
  • cloud_function_vpc_connector
  • cloud_function_memory_mib
  • cloud_function_ingress_settings

כשמשתמשים בפרמטרים האלה, צריך לציין את שם הפרמטר. לדוגמה:

@remote_function(
  name="my_remote_function",
  ...
)
def my_remote_function(parameter: int) -> str:
  return str(parameter)

הגדרת חשבון שירות

החל מגרסה 2.0, כברירת מחדל, BigQuery DataFrames לא משתמש יותר בחשבון השירות של Compute Engine לפונקציות Cloud Run שהוא פורס. כדי להגביל את ההרשאות של הפונקציה שאתם פורסים:

  1. יוצרים חשבון שירות עם הרשאות מינימליות.
  2. מזינים את כתובת האימייל של חשבון השירות בפרמטר cloud_function_service_account של ה-decorator‏ @remote_function.

לדוגמה:

@remote_function(
  cloud_function_service_account="my-service-account@my-project.s3ns.iam.gserviceaccount.com",
  ...
)
def my_remote_function(parameter: int) -> str:
  return str(parameter)

כדי להשתמש בחשבון השירות של Compute Engine, אפשר להגדיר את הפרמטר cloud_function_service_account של ה-decorator‏ @remote_function לערך "default". לדוגמה:

# This usage is discouraged. Use only if you have a specific reason to use the
# default Compute Engine service account.
@remote_function(cloud_function_service_account="default", ...)
def my_remote_function(parameter: int) -> str:
  return str(parameter)

קביעת הגדרות של תעבורת נתונים נכנסת (ingress)

החל מגרסה 2.0, ב-BigQuery DataFrames, הגדרות תעבורת הנתונים הנכנסת של פונקציות Cloud Run שנפרסות מוגדרות ל-"internal-only". בעבר, הגדרות תעבורת הנתונים הנכנסת (ingress) הוגדרו כ-"all" כברירת מחדל. כדי לשנות את הגדרות התעבורה הנכנסת, מגדירים את הפרמטר cloud_function_ingress_settings של ה-decorator‏ @remote_function. לדוגמה:

@remote_function(cloud_function_ingress_settings="internal-and-gclb", ...)
def my_remote_function(parameter: int) -> str:
  return str(parameter)

שימוש בנקודות קצה בהתאמה אישית

בגרסאות של BigQuery DataFrames שקודמות ל-2.0, אם אזור לא תמך בנקודות קצה אזוריות של שירות וב-bigframes.pandas.options.bigquery.use_regional_endpoints = True, BigQuery DataFrames חזר לנקודות קצה של מיקום. בגרסה 2.0 של BigQuery DataFrames, התנהגות ברירת המחדל הזו הוסרה. כדי להתחבר לנקודות קצה של מיקום בגרסה 2.0, מגדירים את האפשרות bigframes.pandas.options.bigquery.client_endpoints_override. לדוגמה:

import bigframes.pandas as bpd

bpd.options.bigquery.client_endpoints_override = {
  "bqclient": "https://LOCATION-bigquery.googleapis.com",
  "bqconnectionclient": "LOCATION-bigqueryconnection.googleapis.com",
  "bqstoragereadclient": "LOCATION-bigquerystorage.googleapis.com",
}

מחליפים את LOCATION בשם המיקום ב-BigQuery שאליו רוצים להתחבר.

שימוש במודול bigframes.ml.llm

מומלץ לספק ישירות model_name נתמך (כמו "gemini-3.5-flash") כדי למנוע תקלות אם המודל שמוגדר כברירת מחדל ישתנה בעתיד.

import bigframes.ml.llm

model = bigframes.ml.llm.GeminiTextGenerator(model_name="gemini-3.5-flash")

המאמרים הבאים