التخزين المؤقت للسياق في BigQuery: ذكاء اصطناعي توليدي سريع وفعّال من حيث التكلفة ومستند إلى بيانات واقعية للبيانات الكبيرة

1. مقدمة

تتيح لك وظائف الذكاء الاصطناعي التوليدي في BigQuery استخدام لغة الاستعلامات البنيوية (SQL) للتعامل مع بياناتك باستخدام النماذج اللغوية الكبيرة (LLM). يمكنك تحليل المشاعر وإنشاء ملخّصات وإضافة تعليقات توضيحية إلى الصور على مستوى ملايين الصفوف بدون نقل بياناتك.

ولكن ماذا لو كان طلبك يحتاج إلى قدر كبير من السياق (مثل السياسات أو الأدلة أو فيديو) للحصول على نتائج دقيقة وموثوقة؟

تعمل ميزة التخزين المؤقت لسياق Gemini على حلّ هذه المشكلة من خلال تخزين هذا السياق الكبير في ذاكرة تخزين مؤقت. تشير الطلبات اللاحقة إلى ذاكرة التخزين المؤقت بدلاً من معالجة المحتوى الكامل في كل مرة، ما يوفّر وقت استجابة أقل وخصمًا يصل إلى% 90 على الرموز المميزة للإدخال.

في هذا الدرس التطبيقي حول الترميز، ستنشئ أداة "مدقّق سياسة الإرجاع" التي تستخدم التخزين المؤقت للسياق الصريح من أجل تحليل طلبات إرجاع العملاء مقارنةً بمستند ضخم وثابت لسياسة الإرجاع في BigQuery.

سير عمل ذاكرة التخزين المؤقت لسياق BigQuery (سيتم تعديل الصورة)

الإجراءات التي ستنفذّها

  • أنشئ مجموعة بيانات BigQuery واملأها بنماذج لطلبات إرجاع المنتجات من العملاء.
  • أنشئ ذاكرة تخزين مؤقت للسياق في "منصة وكيل Gemini Enterprise" (المعروفة سابقًا باسم Vertex AI)، مع الإشارة إلى مستند سياسة الإرجاع المخزّن في Cloud Storage.
  • نفِّذ طلب بحث باستخدام AI.GENERATE يشير إلى ذاكرة التخزين المؤقت لتقييم الطلبات على أساس كل صف على حدة بكفاءة.

المتطلبات

  • متصفّح ويب، مثل Chrome
  • مشروع Google Cloud تم تفعيل الفوترة فيه
  • الوصول إلى Google Cloud Shell

هذا الدرس التطبيقي حول الترميز مخصّص للمطوّرين من جميع المستويات، بما في ذلك المبتدئين.

يجب أن تكون تكلفة الموارد التي تم إنشاؤها في هذا الدرس التطبيقي حول الترميز أقل من 2 دولار أمريكي.

المدة المقدّرة: يستغرق إكمال هذا الدرس العملي حوالي 30 دقيقة.

2. قبل البدء

إنشاء مشروع على Google Cloud

  1. في Google Cloud Console، في صفحة اختيار المشروع، اختَر مشروعًا على Google Cloud أو أنشِئ مشروعًا.
  2. تأكَّد من تفعيل الفوترة لمشروعك على السحابة الإلكترونية. كيفية التحقّق مما إذا كانت الفوترة مفعَّلة في مشروع

بدء Cloud Shell

Cloud Shell هي بيئة سطر أوامر تعمل في Google Cloud ومحمّلة مسبقًا بالأدوات اللازمة.

  1. انقر على تفعيل Cloud Shell في أعلى "وحدة تحكّم Google Cloud". تفعيل صورة Cloud Shell
  2. بعد الاتصال بـ Cloud Shell، تحقَّق من المصادقة باتّباع الخطوات التالية:
    gcloud auth list
  3. تأكَّد من إعداد مشروعك باتّباع الخطوات التالية:
    gcloud config get project
  4. إذا لم يتم ضبط مشروعك على النحو المتوقّع، اضبطه باتّباع الخطوات التالية:
    gcloud config set project <YOUR_PROJECT_ID>

تحديد رقم تعريف المشروع والموقع الجغرافي

نفِّذ الأمر التالي لاسترداد رقم تعريف مشروع Google Cloud النشط وضبط الموقع الجغرافي التلقائي كمتغيّرات بيئية لاستخدامها في هذا الدرس التطبيقي حول الترميز:

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

تفعيل واجهات برمجة التطبيقات

نفِّذ الأمر التالي لتفعيل واجهات برمجة التطبيقات المطلوبة:

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" (المعروفة سابقًا باسم 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"
  }'

دوِّن 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.

ضمن علامة التبويب معاينة، من المفترض أن ترى طلبات إرجاع العملاء التي أنشأناها سابقًا:

معاينة لجدول return_requests في BigQuery

بعد إنشاء ذاكرة التخزين المؤقت وتعبئتها، يمكنك تنفيذ طلب بحث باستخدام 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 في المتصفّح، ثم نفِّذ طلب البحث في علامة التبويب "محرِّر طلب البحث".

معاينة لجدول return_requests في BigQuery

في ما يلي تفاصيل الوسيطات الرئيسية في استدعاء الدالة هذا:

  • prompt: يحتوي على المعلومات المحدّدة لكل صف من صفوف العملاء. يتم إلحاق هذا النص بشكل فعّال بمستند "سياسة الإرجاع" الكبير المتوفّر في ذاكرة التخزين المؤقت.
  • output_schema: تحدّد بنية JSON المتوقّعة لاستجابة النموذج.
  • استبدِل endpoint بما يلي: تحدّد هذه السمة نقطة نهاية نموذج الذكاء الاصطناعي لمنصّة 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 الذي يضم أكثر من 30,000 حرف لسياسة الإرجاع الكاملة. بدون التخزين المؤقت للسياق، ستدفع مقابل معالجة مستند السياسة الكامل هذا لكل صف. من خلال تخزينها مؤقتًا، ستدفع مقابل المستند الكبير مرة واحدة، ولن يتم تحصيل رسوم منك مقابل الصفوف اللاحقة إلا مقابل نص الطلب الصغير المتغيّر.

ويؤدي ذلك إلى توفير كبير في تكلفة المهام المُجمَّعة.

6. تَنظيم

لتجنُّب الرسوم المستمرة على حسابك على Google Cloud، احذف الموارد التي تم إنشاؤها أثناء هذا الدرس العملي.

نفِّذ الأمر التالي في 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. تهانينا

تهانينا! لقد أنشأت بنجاح ذاكرة تخزين مؤقت للسياق في "منصة الوكيل" وأشرت إليها في إحدى دوال الذكاء الاصطناعي في BigQuery لتسريع عملية التحليل مع خفض تكاليف معالجة الرموز المميزة للإدخال.

ما تعلّمته

  • كيفية إعداد جداول البيئة لإحصاءات طلبات إرجاع السلع
  • كيفية استدعاء Agent Platform (Vertex AI) API باستخدامcurl لإنشاء ذاكرة تخزين مؤقت لسياق مستند ثابت بشكل صريح
  • كيفية استخدام معرّف ذاكرة التخزين المؤقت الذي تم إنشاؤه في طلب بحث AI.GENERATE SQL لإزالة الرموز المميزة المتكررة للإدخال في الطلبات النشطة

المستندات المرجعية