Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

BigQuery'de bağlam önbelleğe alma: Büyük veriler için hızlı, uygun maliyetli ve temellendirilmiş üretken yapay zeka

1. Giriş

BigQuery'nin üretken yapay zeka işlevleri, Büyük Dil Modelleri (LLM'ler) kullanarak verileriniz üzerinde akıl yürütmek için SQL'i kullanmanıza olanak tanır. Verilerinizi taşımadan milyonlarca satırda duygu analizi yapabilir, özetler oluşturabilir ve resimlere altyazı ekleyebilirsiniz.

Ancak isteminizin doğru ve güvenilir sonuçlar vermesi için çok fazla bağlam bilgisine (ör. politikalar, kılavuzlar veya bir video) ihtiyacı varsa ne olur?

Gemini bağlam önbelleği, bu büyük bağlamı önbellekte saklayarak bu sorunu çözer. Sonraki istemler, her seferinde içeriğin tamamını işlemek yerine önbelleğe başvurarak daha düşük gecikme süresi ve giriş jetonlarında% 90'a varan indirim sunar.

Bu codelab'de, BigQuery'deki büyük ve statik bir iade politikası belgesine karşı müşteri iade isteklerini analiz etmek için açık bağlam önbelleğe almayı kullanan bir "İnce Baskı" İade Politikası Denetleyicisi oluşturacaksınız.

BigQuery Context Cache İş Akışı (resim güncellenecek)

Yapacaklarınız

Bir BigQuery veri kümesi oluşturun ve örnek müşteri iade istekleriyle doldurun.
Gemini Enterprise Agent Platform'da (eski adıyla Vertex AI) Cloud Storage'da depolanan bir iade politikası belgesini işaret eden bir bağlam önbelleği oluşturun.
Satır satır istekleri verimli bir şekilde değerlendirmek için önbelleğe başvuran AI.GENERATE kullanarak bir sorgu çalıştırın.

İhtiyacınız olanlar

Chrome gibi bir web tarayıcısı
Faturalandırmanın etkin olduğu bir Google Cloud projesi
Google Cloud Shell'e erişim

Bu codelab, yeni başlayanlar da dahil olmak üzere her seviyeden geliştiriciye yöneliktir.

Bu codelab'de oluşturulan kaynakların maliyeti 2 ABD dolarından az olmalıdır.

Tahmini süre: Bu codelab'in tamamlanması yaklaşık 30 dakika sürer.

2. Başlamadan önce

Google Cloud projesi oluşturma

Google Cloud Console'daki proje seçici sayfasında bir Google Cloud projesi seçin veya oluşturun.
Cloud projeniz için faturalandırmanın etkinleştirildiğinden emin olun. Bir projede faturalandırmanın etkin olup olmadığını kontrol etmeyi öğrenin.

Cloud Shell'i Başlatma

Cloud Shell, Google Cloud'da çalışan ve gerekli araçların önceden yüklendiği bir komut satırı ortamıdır.

Google Cloud Console'un üst kısmında Cloud Shell'i etkinleştir'i () tıklayın.
Cloud Shell'e bağlandıktan sonra kimlik doğrulamanızı onaylayın:
```
gcloud auth list
```
Projenizin yapılandırıldığını onaylayın:
```
gcloud config get project
```
Projeniz beklendiği gibi ayarlanmamışsa ayarlayın:
```
gcloud config set project <YOUR_PROJECT_ID>
```

Proje kimliğinizi ve konumunuzu ayarlama

Bu codelab boyunca kullanmak üzere etkin Google Cloud proje kimliğinizi almak ve varsayılan konumu ayarlamak için aşağıdaki komutu çalıştırın:

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

API'leri etkinleştir

Gerekli API'leri etkinleştirmek için şu komutu çalıştırın:

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

3. BigQuery verilerini hazırlama

Bağlam önbelleğe almayı test edebilmemiz için sorgularımızı çalıştıracağımız bir veri kümesine ve örnek müşteri iade istekleriyle doldurulmuş bir tabloya ihtiyacımız var.

1. Veri kümesi oluşturma

caching_demo adlı bir BigQuery veri kümesi oluşturmak için Cloud Shell'de aşağıdaki komutu çalıştırın:

bq mk --dataset $PROJECT_ID:caching_demo

2. Tablo oluşturma ve tabloya veri ekleme

return_requests adlı bir tablo oluşturmak ve örnek müşteri iade istekleri eklemek için aşağıdaki komutu çalıştırın:

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;"

İşlemin başarılı olduğunu belirten bir mesaj görmeniz gerekir:

Created your-project-id.caching_demo.return_requests

Artık önbelleğimizi oluşturmaya hazırız.

4. Bağlam Önbelleğini Oluşturma

Önbelleği, curl kullanarak Gemini Enterprise Agent Platform (eski adıyla Vertex AI) model uç noktasına bir REST çağrısı yaparak oluşturacaksınız.

Yeni bir depolama paketi oluşturmak için Cloud Shell'de aşağıdaki komutu çalıştırın. Bu, önbelleğe almak istediğimiz dosyaları depolamak için kullanılır:

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

Ardından, örnek politika dokümanını kopyalayıp yeni oluşturduğunuz pakete yapıştırın:

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

Şimdi yeni hazırladığınız politika belgenize referans veren önbelleği oluşturmak için aşağıdaki komutu çalıştırın (bu işlem bir dakika kadar sürebilir):

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"
  }'

Yanıt JSON'ında döndürülen name değerini not edin. Bu değer projects/PROJECT_NUMBER/locations/LOCATION/cachedContents/CACHE_ID şeklinde görünür. Sonraki adımda bu CACHE_ID kimliğine ihtiyacınız olacak.

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

Cloud Shell'de CACHE_ID'yi ortam değişkeni olarak kaydedin:

export CACHE_ID="<YOUR_CACHE_ID>"

5. Önbelleğe alınmış içerikle AI.GENERATE'i çalıştırma

Öncelikle örnek verilerimizin doğru şekilde oluşturulduğunu doğrulayalım. BigQuery konsoluna gidin, caching_demo veri kümesini bulun ve return_requests tablosunu tıklayın.

Önizleme sekmesinde, daha önce oluşturduğumuz müşteri iade isteklerini görmeniz gerekir:

BigQuery'deki return_requests tablosunun önizlemesi

Önbellek oluşturulup doldurulduktan sonra, iade isteğini değerlendirmek için AI.GENERATE kullanarak sorgu yapabilirsiniz. Bunun için önbellek kimliğine başvurmanız yeterlidir.

Değişkenleri manuel olarak bulup değiştirmekten kaçınmak için Cloud Shell'de aşağıdaki komutu çalıştırın. Bu işlem, mevcut ortam değişkenlerinizi kullanarak SQL sorgusunu dinamik olarak oluşturur ve kolayca kopyalayabilmeniz için ekrana yazdırır.

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

Şimdi terminaldeki SQL'i kopyalayın, tarayıcınızda BigQuery konsoluna gidin ve sorgu düzenleyici sekmesinde sorguyu çalıştırın.

BigQuery'deki return_requests tablosunun önizlemesi

Bu işlev çağrısındaki temel bağımsız değişkenlerin dökümünü aşağıda bulabilirsiniz:

prompt: Her müşteri satırıyla ilgili belirli bilgileri içerir. Bu metin, önbellekteki büyük iade politikası belgesine eklenir.
output_schema: Modelin yanıtının beklenen JSON yapısını tanımlar.
endpoint: Üretim için kullanılan Agent Platform yapay zeka modeli uç noktasını (bizim durumumuzda Gemini 2.5 Flash) belirtir.
model_params: cachedContent alanı kullanılarak oluşturulan önbellek kimliğini ileten önemli parametre.

Depolanan politikaya göre her iade isteğini analiz eden oluşturulmuş sonuçları görürsünüz. Ayıklanan jeton metriklerini görmek için sağa kaydırın.

Model analizini ve jeton sayılarını gösteren sorgu sonuçları.

Gördüğünüz jeton metriklerinin dökümü aşağıda verilmiştir:

prompt_token_count: Giriş isteminde işlenen toplam jeton sayısı (önbelleğe alınan içerik dahil).
cached_content_token_count: Önbellekten sunulan jeton sayısı (statik iade politikası belgesini temsil eder).
output_token_count: Yanıtta model tarafından oluşturulan parça sayısı.
total_token_count: İstem ve çıkış jetonlarının toplamı.
billable_prompt_text_count: İstemde önbelleğe alınmamış kısımda faturalandırılabilir karakter sayısı.
billable_cached_text_count: Önbelleğe alınmış içerikteki faturalandırılabilir karakter sayısı.

billable_prompt_text_count sütununa bakın. Bu sütunda satır başına yalnızca birkaç yüz karakter gösterilir. Bu da müşterinin belirli isteğidir. Bunu,tam İade Politikası için 30.000'den fazla karakter olan billable_cached_text_count ile karşılaştırın. Bağlam önbelleğe alma olmadan, bu tam politika belgesinin her satır için işlenmesi için ödeme yapmanız gerekirdi. Büyük dokümanı önbelleğe alarak yalnızca bir kez ödeme yaparsınız ve sonraki satırlarda yalnızca küçük, değişen istem metni için ücretlendirilirsiniz.

Bu sayede toplu işlerde büyük tasarruf sağlanır.

6. Temizleme

Google Cloud hesabınızın sürekli olarak ücretlendirilmesini önlemek için bu codelab sırasında oluşturulan kaynakları silin.

BigQuery veri kümesini ve tablolarını silmek için Cloud Shell'de aşağıdaki komutu çalıştırın:

bq rm -r -f -d caching_demo

Politika belgesi için oluşturulan hazırlama paketini silin:

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

Son olarak, daha önce depoladığınız değişkenleri kullanarak devam eden depolama ücretlerinden kaçınmak için bağlam önbelleğini silin:

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. Tebrikler

Tebrikler! Agent Platform'da bağlam önbelleğini başarıyla oluşturdunuz ve giriş jetonu işleme maliyetlerini düşürürken analizi hızlandırmak için BigQuery AI işlevinde buna referans verdiniz.

Öğrendikleriniz

İade isteği analizleri için ortam tablolarını ayarlama
Statik belge bağlamı önbelleğini açıkça oluşturmak için curl kullanarak Agent Platform (Vertex AI) API'yi çağırma
Etkin istemlerdeki gereksiz giriş jetonlarını ortadan kaldırmak için oluşturulan önbellek kimliğini AI.GENERATE SQL sorgusunda kullanma.