1. Pengantar
Fungsi AI generatif BigQuery memungkinkan Anda menggunakan SQL untuk menganalisis data menggunakan Model Bahasa Besar (LLM). Anda dapat menganalisis sentimen, membuat ringkasan, dan memberi teks pada gambar di jutaan baris tanpa memindahkan data Anda.
Namun, bagaimana jika perintah Anda memerlukan banyak konteks (seperti kebijakan, panduan, atau video) untuk mendapatkan hasil yang akurat dan andal?
Caching konteks Gemini mengatasi masalah ini dengan menyimpan konteks besar tersebut dalam cache. Perintah berikutnya mereferensikan cache, bukan memproses seluruh konten setiap saat, sehingga menawarkan latensi yang lebih rendah dan diskon hingga 90% untuk token input.
Dalam codelab ini, Anda akan membuat Pemeriksa Kebijakan Pengembalian "Detail" yang menggunakan penyimpanan cache konteks eksplisit untuk menganalisis permintaan pengembalian barang pelanggan berdasarkan dokumen kebijakan pengembalian barang statis yang sangat besar di BigQuery.
Yang akan Anda lakukan
- Buat set data BigQuery dan isi dengan contoh permintaan pengembalian pelanggan.
- Buat Cache Konteks di Gemini Enterprise Agent Platform (sebelumnya dikenal sebagai Vertex AI), yang mengarah ke dokumen kebijakan pengembalian yang disimpan di Cloud Storage.
- Jalankan kueri menggunakan
AI.GENERATEyang mereferensikan cache untuk mengevaluasi permintaan secara baris per baris secara efisien.
Yang Anda butuhkan
- Browser web seperti Chrome
- Project Google Cloud yang mengaktifkan penagihan
- Akses ke Google Cloud Shell
Codelab ini ditujukan bagi developer dari semua level, termasuk pemula.
Resource yang dibuat dalam codelab ini seharusnya berbiaya kurang dari $2.
Perkiraan durasi: Codelab ini akan memerlukan waktu sekitar 30 menit untuk diselesaikan.
2. Sebelum memulai
Buat Project Google Cloud
- Di Konsol Google Cloud, di halaman pemilih project, pilih atau buat project Google Cloud.
- Pastikan penagihan diaktifkan untuk project Cloud Anda. Pelajari cara memeriksa apakah penagihan telah diaktifkan pada suatu project.
Mulai Cloud Shell
Cloud Shell adalah lingkungan command line yang berjalan di Google Cloud yang telah dilengkapi dengan alat yang diperlukan.
- Klik Activate Cloud Shell di bagian atas konsol Google Cloud.
- Setelah terhubung ke Cloud Shell, verifikasi autentikasi Anda:
gcloud auth list - Pastikan project Anda dikonfigurasi:
gcloud config get project - Jika project Anda tidak ditetapkan seperti yang diharapkan, tetapkan project:
gcloud config set project <YOUR_PROJECT_ID>
Menetapkan Project ID dan Lokasi Anda
Jalankan perintah berikut untuk mengambil Project ID Google Cloud aktif Anda dan menetapkan lokasi default sebagai variabel lingkungan yang akan digunakan di seluruh codelab ini:
export PROJECT_ID=$(gcloud config get-value project)
export PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")
export LOCATION="us-central1"
Mengaktifkan API
Jalankan perintah ini untuk mengaktifkan API yang diperlukan:
gcloud services enable \
bigquery.googleapis.com \
aiplatform.googleapis.com
3. Menyiapkan Data BigQuery
Sebelum dapat menguji penayangan cache konteks, kita memerlukan set data dan tabel yang diisi dengan contoh permintaan pengembalian pelanggan untuk menjalankan kueri.
1. Membuat set data
Jalankan perintah berikut di Cloud Shell untuk membuat set data BigQuery bernama caching_demo:
bq mk --dataset $PROJECT_ID:caching_demo
2. Membuat dan mengisi tabel
Jalankan perintah berikut untuk membuat tabel bernama return_requests dan menyisipkan contoh permintaan pengembalian pelanggan:
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;"
Anda akan melihat pesan keberhasilan:
Created your-project-id.caching_demo.return_requests
Sekarang kita siap membuat cache.
4. Membuat Context Cache
Anda akan membuat cache menggunakan panggilan REST ke endpoint model Gemini Enterprise Agent Platform (sebelumnya dikenal sebagai Vertex AI) menggunakan curl.
Jalankan perintah berikut di Cloud Shell untuk membuat bucket penyimpanan baru. Ini akan digunakan untuk menyimpan file yang ingin kita cache:
gcloud storage buckets create gs://${PROJECT_ID}-caching-demo --location=${LOCATION}
Selanjutnya, salin dokumen kebijakan contoh ke dalam bucket yang baru dibuat:
gcloud storage cp gs://sample-data-and-media/context_caching_demo/return_policy.md gs://${PROJECT_ID}-caching-demo/
Sekarang, jalankan perintah berikut untuk membuat cache yang mereferensikan dokumen kebijakan yang baru Anda siapkan (proses ini mungkin memerlukan waktu sekitar satu menit):
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"
}'
Catat name yang ditampilkan dalam JSON respons, yang akan terlihat seperti ini: projects/PROJECT_NUMBER/locations/LOCATION/cachedContents/CACHE_ID. Anda akan memerlukan CACHE_ID tersebut untuk langkah berikutnya.
{
"name": "projects/123456789012/locations/us-central1/cachedContents/123456789012345"
}
Simpan CACHE_ID sebagai variabel lingkungan di Cloud Shell:
export CACHE_ID="<YOUR_CACHE_ID>"
5. Menjalankan AI.GENERATE dengan Konten yang Di-cache
Pertama, mari kita verifikasi bahwa data sampel kita dibuat dengan benar. Buka konsol BigQuery, cari set data caching_demo, lalu klik tabel return_requests.
Di tab Preview, Anda akan melihat permintaan pengembalian pelanggan yang kita buat sebelumnya:
Setelah cache dibuat dan diisi, Anda dapat membuat kueri menggunakan AI.GENERATE untuk mengevaluasi permintaan pengembalian dana hanya dengan merujuk ke ID Cache tersebut.
Untuk menghindari pencarian dan penggantian variabel secara manual, jalankan perintah berikut di Cloud Shell. Tindakan ini akan membuat kueri SQL secara dinamis menggunakan variabel lingkungan yang ada dan mencetaknya ke layar sehingga Anda dapat menyalinnya dengan mudah.
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
Sekarang, salin SQL di terminal, buka konsol BigQuery di browser Anda, lalu jalankan kueri di tab editor kueri.
Berikut perincian argumen utama dalam panggilan fungsi ini:
prompt: Berisi informasi spesifik untuk setiap baris pelanggan. Teks ini secara efektif ditambahkan ke dokumen Kebijakan Pengembalian berukuran besar yang sudah ada di cache.output_schema: Menentukan struktur JSON yang diharapkan dari respons model.endpoint: Menentukan endpoint model AI Agent Platform (Gemini 2.5 Flash dalam kasus ini) yang digunakan untuk pembuatan.model_params: Parameter penting yang meneruskan ID Cache yang dihasilkan menggunakan kolomcachedContent.
Anda akan melihat hasil yang dihasilkan yang menganalisis setiap permintaan pengembalian barang menurut kebijakan yang disimpan. Scroll ke kanan untuk melihat metrik token yang diekstrak.
Berikut perincian metrik token yang Anda lihat:
prompt_token_count: Jumlah total token yang diproses dalam perintah input (termasuk konten yang di-cache).cached_content_token_count: Jumlah token yang disajikan dari cache (mewakili dokumen Kebijakan Pengembalian statis).output_token_count: Jumlah token yang dihasilkan oleh model dalam respons.total_token_count: Jumlah token perintah dan output.billable_prompt_text_count: Jumlah karakter yang dapat ditagih di bagian prompt yang tidak di-cache.billable_cached_text_count: Jumlah karakter yang dapat ditagih dalam konten yang di-cache.
Lihat kolom billable_prompt_text_count—kolom ini hanya menampilkan beberapa ratus karakter per baris, yang merupakan permintaan spesifik pelanggan. Bandingkan dengan billable_cached_text_count lebih dari 30.000 karakter untuk Kebijakan Pengembalian secara keseluruhan. Tanpa penyimpanan data ke dalam cache konteks, Anda akan membayar untuk memproses dokumen kebijakan lengkap tersebut untuk setiap baris. Dengan menyimpannya dalam cache, Anda hanya membayar dokumen besar satu kali, dan baris berikutnya hanya menagih Anda untuk teks perintah kecil yang berubah.
Hal ini menghasilkan penghematan besar untuk tugas batch.
6. Pembersihan
Untuk menghindari biaya berkelanjutan pada akun Google Cloud Anda, hapus resource yang dibuat selama codelab ini.
Jalankan perintah berikut di Cloud Shell untuk menghapus set data BigQuery dan tabelnya:
bq rm -r -f -d caching_demo
Hapus bucket penyiapan yang dibuat untuk dokumen kebijakan:
gcloud storage rm --recursive gs://${PROJECT_ID}-caching-demo
Terakhir, hapus cache konteks untuk menghindari biaya penyimpanan berkelanjutan menggunakan variabel yang Anda simpan sebelumnya:
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. Selamat
Selamat! Anda telah berhasil membuat cache konteks di Agent Platform dan mereferensikannya dalam fungsi AI BigQuery untuk mempercepat analisis sekaligus mengurangi biaya pemrosesan token input.
Yang telah Anda pelajari
- Cara menyiapkan tabel lingkungan untuk analisis permintaan pengembalian barang.
- Cara memanggil Agent Platform (Vertex AI) API menggunakan
curluntuk membuat cache konteks dokumen statis secara eksplisit. - Cara menggunakan ID Cache yang dihasilkan dalam kueri SQL
AI.GENERATEuntuk menghilangkan token input yang berlebihan di seluruh perintah aktif.