שמירת נתונים במטמון בהקשר ב-BigQuery: AI גנרטיבי מהיר, חסכוני ומבוסס ל-Big Data

1. מבוא

פונקציות ה-AI הגנרטיבי של BigQuery מאפשרות לכם להשתמש ב-SQL כדי להסיק מסקנות לגבי הנתונים שלכם באמצעות מודלים גדולים של שפה (LLM). אתם יכולים לנתח את הסנטימנט, ליצור סיכומים ולתת כתוביות לתמונות במיליוני שורות בלי להעביר את הנתונים.

אבל מה קורה אם ההנחיה שלכם צריכה כמות גדולה של הקשר (כמו מדיניות, מדריכים או סרטון) כדי לקבל תוצאות מדויקות ומהימנות?

שמירת ההקשר ב-Gemini במטמון פותרת את הבעיה הזו על ידי אחסון ההקשר הגדול הזה במטמון. בהנחיות הבאות, המערכת מתייחסת למטמון במקום לעבד את התוכן המלא בכל פעם, וכך היא מציעה חביון נמוך יותר והנחה של עד 90% על אסימוני קלט.

בשיעור Codelab הזה תיצרו כלי לבדיקת מדיניות החזרת מוצרים שמשתמש במטמון הקשר המפורש כדי לנתח בקשות של לקוחות להחזרת מוצרים בהשוואה למסמך מדיניות החזרת מוצרים סטטי ומקיף ב-BigQuery.

הפעולות שתבצעו:

• יוצרים מערך נתונים ב-BigQuery ומאכלסים אותו בבקשות לדוגמה להחזרת מוצרים.
• יוצרים מטמון הקשר בפלטפורמת הסוכנים של Gemini Enterprise (לשעבר Vertex AI), שמפנה למסמך מדיניות החזרת מוצרים שמאוחסן ב-Cloud Storage.
• מריצים שאילתה באמצעות AI.GENERATE שמפנה למטמון כדי להעריך את הבקשות בצורה יעילה, שורה אחר שורה.

הדרישות

• דפדפן אינטרנט כמו Chrome
• פרויקט ב-Google Cloud שהחיוב בו מופעל
• גישה ל-Google Cloud Shell

שיעור ה-Codelab הזה מיועד למפתחים בכל הרמות, כולל מתחילים.

העלות של המשאבים שנוצרו ב-codelab הזה צריכה להיות פחות מ-2$.

משך משוער: השלמת ה-codelab הזה תימשך כ-30 דקות.

‫2. לפני שמתחילים

יצירת פרויקט ב-Google Cloud

1. במסוף Google Cloud, בדף לבחירת הפרויקט, בוחרים פרויקט ב-Google Cloud או יוצרים פרויקט.
2. הקפידו לוודא שהחיוב מופעל בפרויקט שלכם ב-Cloud. כך בודקים אם החיוב מופעל בפרויקט

הפעלת Cloud Shell

‫Cloud Shell היא סביבת שורת פקודה שפועלת ב-Google Cloud וכוללת מראש את הכלים הנדרשים.

1. לוחצים על Activate Cloud Shell (הפעלת Cloud Shell) בחלק העליון של מסוף Google Cloud.
2. אחרי שמתחברים ל-Cloud Shell, מאמתים את האימות:

   gcloud auth list
   

3. מוודאים שהפרויקט מוגדר:

   gcloud config get project
   

4. אם הפרויקט לא מוגדר כמו שציפיתם, מגדירים אותו:

   gcloud config set project <YOUR_PROJECT_ID>
   

הגדרת מזהה הפרויקט והמיקום

מריצים את הפקודה הבאה כדי לאחזר את מזהה הפרויקט הפעיל ב-Google Cloud ולהגדיר את מיקום ברירת המחדל כמשתני סביבה לשימוש במהלך שיעור ה-Codelab הזה:

export PROJECT_ID=$(gcloud config get-value project)
export PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")
export LOCATION="us-central1"

הפעלת ממשקי ה-API

מריצים את הפקודה הבאה כדי להפעיל את ממשקי ה-API הנדרשים:

gcloud services enable \
 bigquery.googleapis.com \
 aiplatform.googleapis.com

3. הכנת נתונים ב-BigQuery

כדי שנוכל לבדוק את השמירה של הקשר במטמון, אנחנו צריכים קבוצת נתונים וטבלה שמכילים בקשות לדוגמה להחזרת מוצרים של לקוחות, כדי להריץ עליהן את השאילתות שלנו.

1. יצירת מערך נתונים

מריצים את הפקודה הבאה ב-Cloud Shell כדי ליצור מערך נתונים ב-BigQuery בשם caching_demo:

bq mk --dataset $PROJECT_ID:caching_demo

2. יצירה ואכלוס של הטבלה

מריצים את הפקודה הבאה כדי ליצור טבלה בשם return_requests ולהוסיף בקשות לדוגמה להחזרת מוצרים של לקוחות:

bq query \
  --use_legacy_sql=false \
  "CREATE OR REPLACE TABLE \`caching_demo.return_requests\` AS
SELECT
  10001 AS return_id,
  'P-1001' AS purchase_id,
  'I bought this jacket on Black Friday but it was too small.' AS return_comment,
  DATE('2025-11-28') AS purchase_date,
  DATE('2025-12-05') AS return_date,
  'ApexWear' AS product_brand,
  'Gold' AS customer_tier
UNION ALL
  SELECT
  10002 AS return_id,
  'P-1002' AS purchase_id,
  'The item arrived broken, I want a refund. I don\'t have photos because I threw it away.' AS return_comment,
  DATE('2026-04-01') AS purchase_date,
  DATE('2026-04-02') AS return_date,
  'GenericBrand' AS product_brand,
  'Standard' AS customer_tier
UNION ALL
  SELECT
  10003 AS return_id,
  'P-1003' AS purchase_id,
  'I bought this ApexWear jacket, took the tags off to wear it once, but it doesn\'t fit well.' AS return_comment,
  DATE('2026-02-15') AS purchase_date,
  DATE('2026-02-20') AS return_date,
  'ApexWear' AS product_brand,
  'Standard' AS customer_tier
UNION ALL
  SELECT
  10004 AS return_id,
  'P-1004' AS purchase_id,
  'This was a holiday gift but doesn\'t fit.' AS return_comment,
  DATE('2025-12-20') AS purchase_date,
  DATE('2026-01-28') AS return_date,
  'StyleCorp' AS product_brand,
  'Standard' AS customer_tier
UNION ALL
  SELECT
  10005 AS return_id,
  'P-1005' AS purchase_id,
  'I realized this doesn\'t fit' AS return_comment,
  DATE('2026-02-01') AS purchase_date,
  DATE('2026-03-15') AS return_date,
  'ApexWear' AS product_brand,
  'Gold' AS customer_tier;"

אמורה להופיע הודעה על סיום הפעולה:

Created your-project-id.caching_demo.return_requests

עכשיו אפשר ליצור את המטמון.

4. יצירת מטמון ההקשר

תצרו את המטמון באמצעות קריאת REST לנקודת הקצה של מודל Gemini Enterprise Agent Platform (לשעבר Vertex AI) באמצעות curl.

מריצים את הפקודה הבאה ב-Cloud Shell כדי ליצור קטגוריית אחסון חדשה. הנפח הזה ישמש לאחסון קבצים שרוצים לשמור במטמון:

gcloud storage buckets create gs://${PROJECT_ID}-caching-demo --location=${LOCATION}

בשלב הבא, מעתיקים את מסמך המדיניות לדוגמה לקטגוריה החדשה שיצרתם:

gcloud storage cp gs://sample-data-and-media/context_caching_demo/return_policy.md gs://${PROJECT_ID}-caching-demo/

עכשיו מריצים את הפקודה הבאה כדי ליצור את המטמון שמפנה למסמך המדיניות החדש שהועלה (התהליך עשוי להימשך כדקה):

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  "https://${LOCATION}-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/cachedContents" \
  -d '{
    "model": "projects/'"${PROJECT_ID}"'/locations/'"${LOCATION}"'/publishers/google/models/gemini-2.5-flash",
    "contents": [
      {
        "role": "user",
        "parts": [
          {
            "fileData": {
              "mimeType": "text/markdown",
              "fileUri": "gs://'"${PROJECT_ID}"'-caching-demo/return_policy.md"
            }
          }
        ]
      }
    ],
    "ttl": "3600s"
  }'

טיפ: הפרמטר TTL (Time to Live) בפקודה curl קובע כמה זמן המטמון יישאר פעיל. אם ההקשר שלכם סטטי ונעשה בו שימוש לעיתים קרובות, כדאי להגדיר זמן חיים (TTL) ארוך יותר כדי להימנע מעלויות של יצירה מחדש, תוך התחשבות בעמלת האחסון השעתית.

שימו לב לערך name שמוחזר ב-JSON של התגובה, שייראה כך: projects/PROJECT_NUMBER/locations/LOCATION/cachedContents/CACHE_ID. תצטרכו את CACHE_ID בשלב הבא.

{
  "name": "projects/123456789012/locations/us-central1/cachedContents/123456789012345"
}

שומרים את CACHE_ID כמשתנה סביבה ב-Cloud Shell:

export CACHE_ID="<YOUR_CACHE_ID>"

5. הפעלת AI.GENERATE עם תוכן שנשמר במטמון

קודם כול, נוודא שנתוני הדוגמה שלנו נוצרו בצורה נכונה. עוברים אל מסוף BigQuery, מאתרים את מערך הנתונים caching_demo ולוחצים על הטבלה return_requests.

בכרטיסייה תצוגה מקדימה, אמורות להופיע בקשות החזרת המוצרים של הלקוחות שיצרנו קודם:

אחרי שהמטמון נוצר ואוכלס, אפשר לשלוח שאילתה באמצעות AI.GENERATE כדי להעריך את בקשת ההחזר הכספי על ידי הפניה למזהה המטמון הזה.

כדי להימנע מהחלפה ידנית של משתנים, מריצים את הפקודה הבאה ב-Cloud Shell. הפעולה הזו תיצור באופן דינמי את שאילתת ה-SQL באמצעות משתני הסביבה הקיימים ותציג אותה על המסך כדי שתוכלו להעתיק אותה בקלות.

cat << EOF > query.sql
WITH generated_returns AS (
  SELECT
    *,
    -- Call AI.GENERATE with the prompt, schema, and cache ID
    AI.GENERATE(
      -- Construct the prompt referencing the cached policy
      prompt => CONCAT(
        'Analyze this return request using the cached Return Policy. ',
        'Return Comment: "', return_comment, '". ',
        'Purchase Date: ', purchase_date, '. ',
        'Brand: ', product_brand, '. ',
        'Customer Tier: ', customer_tier, '. '
      ),
      -- Define the structured output schema
      output_schema => """
        eligible_for_refund STRING OPTIONS(description = 'True/False whether the request is eligible for a refund based on the policy'),
        refund_type STRING OPTIONS(description = 'Classify as Full, Store Credit, or None'),
        reason_citation STRING OPTIONS(description = 'Quote the specific rule from the policy applied to this decision')
      """,    
      -- Construct the endpoint string dynamically using variables
      endpoint => 'gemini-2.5-flash',
      
      -- Pass the cached content ID using bash interpolation for the literal
      model_params => JSON '{"cachedContent": "projects/$PROJECT_NUMBER/locations/$LOCATION/cachedContents/$CACHE_ID"}'
    ) AS results
  FROM \`caching_demo.return_requests\`
)
SELECT 
  *,
  -- Extract token usage metrics from the raw JSON response
  CAST(JSON_EXTRACT_SCALAR(results.full_response, '$.usage_metadata.prompt_token_count') AS INT64) AS prompt_token_count,
  CAST(JSON_EXTRACT_SCALAR(results.full_response, '$.usage_metadata.cached_content_token_count') AS INT64) AS cached_content_token_count,
  CAST(JSON_EXTRACT_SCALAR(results.full_response, '$.usage_metadata.candidates_token_count') AS INT64) AS output_token_count,
  CAST(JSON_EXTRACT_SCALAR(results.full_response, '$.usage_metadata.total_token_count') AS INT64) AS total_token_count,
  CAST(JSON_EXTRACT_SCALAR(results.full_response, '$.usage_metadata.thoughts_token_count') AS INT64) AS thoughts_token_count,
  CAST(JSON_EXTRACT_SCALAR(results.full_response, '$.usage_metadata.billable_prompt_usage.text_count') AS INT64) AS billable_prompt_text_count,
  CAST(JSON_EXTRACT_SCALAR(results.full_response, '$.usage_metadata.billable_cached_content_usage.text_count') AS INT64) AS billable_cached_text_count
  
FROM generated_returns;
EOF

cat query.sql

עכשיו מעתיקים את ה-SQL במסוף, עוברים למסוף BigQuery בדפדפן ומריצים את השאילתה בכרטיסייה של עורך השאילתות.

הנה פירוט של הארגומנטים העיקריים בבקשה להפעלת פונקציה:

• ‫prompt: מכיל את המידע הספציפי לכל שורת לקוח. הטקסט הזה מצורף למעשה למסמך הגדול של מדיניות החזרת המוצרים שכבר נמצא במטמון.
• ‫output_schema: מגדיר את מבנה ה-JSON הצפוי של תגובת המודל.
• ‫endpoint: מציין את נקודת הקצה של מודל ה-AI ב-Agent Platform (Gemini 2.5 Flash במקרה שלנו) שמשמש ליצירה.
• ‫model_params: פרמטר חיוני שמעביר את מזהה המטמון שנוצר באמצעות השדה cachedContent.

יוצגו התוצאות שנוצרו, עם ניתוח של כל בקשה להחזרת מוצר בהתאם למדיניות המאוחסנת. גוללים שמאלה כדי לראות את מדדי הטוקנים שחולצו.

פירוט של מדדי האסימונים שמוצגים:

• ‫prompt_token_count: המספר הכולל של הטוקנים שעברו עיבוד בהנחיה לקלט (כולל התוכן שנשמר במטמון).
• ‫cached_content_token_count: מספר האסימונים שמוצגים מהמטמון (מייצג את מסמך מדיניות ההחזרה הסטטי).
• ‫output_token_count: מספר האסימונים שהמודל יצר בתגובה.
• ‫total_token_count: סכום הטוקנים של ההנחיה והפלט.
• ‫billable_prompt_text_count: מספר התווים שניתנים לחיוב בחלק של ההנחיה שלא נשמר במטמון.
• ‫billable_cached_text_count: מספר התווים שניתנים לחיוב בתוכן שנשמר במטמון.

בודקים את העמודה billable_prompt_text_count – בכל שורה מוצגים רק כמה מאות תווים, שכוללים רק את הבקשה הספציפית של הלקוח. לעומת זאת,מדיניות החזרת המוצרים המלאה יכולה להכיל עד billable_cached_text_count תווים. בלי שמירת מטמון של ההקשר, הייתם משלמים על עיבוד המסמך המלא של המדיניות עבור כל שורה. באמצעות שמירת המטמון, אתם משלמים על המסמך הגדול רק פעם אחת, ועל השורות הבאות אתם משלמים רק על הטקסט הקטן של ההנחיה שמשתנה.

התוצאה היא חיסכון משמעותי במשימות באצווה.

6. הסרת המשאבים

כדי להימנע מחיובים שוטפים בחשבון Google Cloud, מוחקים את המשאבים שנוצרו במהלך ה-codelab הזה.

מריצים את הפקודה הבאה ב-Cloud Shell כדי למחוק את מערך הנתונים ב-BigQuery ואת הטבלאות שלו:

bq rm -r -f -d caching_demo

מוחקים את קטגוריית האחסון הזמנית שנוצרה עבור מסמך המדיניות:

gcloud storage rm --recursive gs://${PROJECT_ID}-caching-demo

לבסוף, מוחקים את מטמון ההקשר כדי להימנע מחיובים שוטפים על אחסון באמצעות המשתנים ששמרתם קודם:

curl -X DELETE \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  "https://${LOCATION}-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/cachedContents/${CACHE_ID}"

7. מזל טוב

מעולה! יצרתם בהצלחה מטמון הקשר ב-Agent Platform והפניתם אליו בפונקציית AI של BigQuery כדי להאיץ את הניתוח ולצמצם את עלויות העיבוד של טוקני הקלט.

מה למדתם

• איך מגדירים טבלאות סביבה לניתוח בקשות להחזרת מוצרים.
• איך קוראים ל-Agent Platform (Vertex AI) API באמצעותcurl כדי ליצור באופן מפורש מטמון סטטי של הקשר המסמך.
• איך משתמשים במזהה המטמון שנוצר בשאילתת SQL‏ AI.GENERATE כדי להסיר טוקנים מיותרים של קלט מההנחיות הפעילות.

מסמכי עזר

• תחביר של BigQuery AI.GENERATE
• סקירה כללית על שמירת הקשר במטמון ב-Agent Platform AI