در یک گردش کار معمول هوش مصنوعی، ممکن است توکنهای ورودی یکسانی را بارها و بارها به یک مدل ارسال کنید. API Gemini دو مکانیسم ذخیرهسازی مختلف ارائه میدهد:
- ذخیره سازی ضمنی (به طور خودکار در اکثر مدل های Gemini فعال است، بدون تضمین صرفه جویی در هزینه)
- ذخیره سازی صریح (در اکثر مدل ها می توان به صورت دستی فعال کرد، تضمین صرفه جویی در هزینه)
ذخیرهسازی صریح در مواردی مفید است که میخواهید صرفهجویی در هزینه را تضمین کنید، اما با مقداری کار توسعهدهندهی اضافی.
ذخیره سازی ضمنی
ذخیرهسازی ضمنی (implicit caching) به طور پیشفرض فعال است و برای اکثر مدلهای Gemini در دسترس است. اگر درخواست شما به حافظه پنهان (cache) برسد، ما به طور خودکار صرفهجویی در هزینه را اعمال میکنیم. برای فعال کردن این قابلیت، نیازی به انجام هیچ کاری از سوی شما نیست. این قابلیت از ۸ مه ۲۰۲۵ فعال است. حداقل تعداد توکن ورودی برای ذخیرهسازی زمینه (context caching) برای هر مدل در جدول زیر ذکر شده است:
| مدل | حداقل محدودیت توکن |
|---|---|
| پیشنمایش فلش جمینی ۳ | ۱۰۲۴ عدد |
| پیشنمایش جمینی ۳ پرو | ۴۰۹۶ عدد |
| فلش جمینی ۲.۵ | ۱۰۲۴ عدد |
| جمینی ۲.۵ پرو | ۴۰۹۶ عدد |
برای افزایش احتمال برخورد با حافظه پنهان ضمنی:
- سعی کنید مطالب بزرگ و رایج را در ابتدای درخواست خود قرار دهید.
- سعی کنید درخواستهایی با پیشوند مشابه را در مدت زمان کوتاهی ارسال کنید
میتوانید تعداد توکنهایی که در حافظه پنهان (cache hits) بودهاند را در فیلد usage_metadata شیء پاسخ مشاهده کنید.
ذخیره سازی صریح
با استفاده از ویژگی ذخیرهسازی صریح API Gemini، میتوانید یک بار مقداری محتوا را به مدل ارسال کنید، توکنهای ورودی را ذخیره کنید و سپس برای درخواستهای بعدی به توکنهای ذخیرهشده مراجعه کنید. در حجمهای خاص، استفاده از توکنهای ذخیرهشده هزینه کمتری نسبت به ارسال مکرر همان مجموعه توکنها دارد.
وقتی مجموعهای از توکنها را ذخیره میکنید، میتوانید مدت زمانی را که میخواهید حافظه پنهان وجود داشته باشد تا توکنها به طور خودکار حذف شوند، انتخاب کنید. این مدت زمان ذخیره، زمان حیات (TTL) نامیده میشود. اگر تنظیم نشود، TTL به طور پیشفرض ۱ ساعت است. هزینه ذخیره سازی به اندازه توکن ورودی و مدت زمانی که میخواهید توکنها باقی بمانند بستگی دارد.
این بخش فرض میکند که شما یک Gemini SDK نصب کردهاید (یا curl را نصب کردهاید) و یک کلید API را پیکربندی کردهاید، همانطور که در شروع سریع نشان داده شده است.
تولید محتوا با استفاده از حافظه پنهان (cache)
پایتون
مثال زیر نحوه تولید محتوا با استفاده از یک دستورالعمل سیستمی ذخیره شده و فایل ویدیویی را نشان میدهد.
ویدیوها
import os
import pathlib
import requests
import time
from google import genai
from google.genai import types
client = genai.Client()
# Download a test video file and save it locally
url = 'https://storage.googleapis.com/generativeai-downloads/data/SherlockJr._10min.mp4'
path_to_video_file = pathlib.Path('SherlockJr._10min.mp4')
if not path_to_video_file.exists():
path_to_video_file.write_bytes(requests.get(url).content)
# Upload the video using the Files API
video_file = client.files.upload(file=path_to_video_file)
# Wait for the file to finish processing
while video_file.state.name == 'PROCESSING':
time.sleep(2.5)
video_file = client.files.get(name=video_file.name)
print(f'Video processing complete: {video_file.uri}')
model='models/gemini-3-flash-preview'
# Create a cache with a 5 minute TTL (300 seconds)
cache = client.caches.create(
model=model,
config=types.CreateCachedContentConfig(
display_name='sherlock jr movie', # used to identify the cache
system_instruction=(
'You are an expert video analyzer, and your job is to answer '
'the user\'s query based on the video file you have access to.'
),
contents=[video_file],
ttl="300s",
)
)
response = client.models.generate_content(
model = model,
contents= (
'Introduce different characters in the movie by describing '
'their personality, looks, and names. Also list the timestamps '
'they were introduced for the first time.'),
config=types.GenerateContentConfig(cached_content=cache.name)
)
print(response.usage_metadata)
print(response.text)
فایلهای PDF
from google import genai
from google.genai import types
import io
import httpx
client = genai.Client()
long_context_pdf_path = "https://sma.nasa.gov/SignificantIncidents/assets/a11_missionreport.pdf"
# Retrieve and upload the PDF using the File API
doc_io = io.BytesIO(httpx.get(long_context_pdf_path).content)
document = client.files.upload(
file=doc_io,
config=dict(mime_type='application/pdf')
)
model_name = "gemini-3-flash-preview"
system_instruction = "You are an expert analyzing transcripts."
# Create a cached content object
cache = client.caches.create(
model=model_name,
config=types.CreateCachedContentConfig(
system_instruction=system_instruction,
contents=[document],
)
)
print(f'{cache=}')
response = client.models.generate_content(
model=model_name,
contents="Please summarize this transcript",
config=types.GenerateContentConfig(
cached_content=cache.name
))
print(f'{response.usage_metadata=}')
print('\n\n', response.text)
جاوا اسکریپت
مثال زیر نحوه تولید محتوا با استفاده از یک دستورالعمل سیستمی ذخیره شده در حافظه پنهان و یک فایل متنی را نشان میدهد.
import {
GoogleGenAI,
createUserContent,
createPartFromUri,
} from "@google/genai";
const ai = new GoogleGenAI({ apiKey: "GEMINI_API_KEY" });
async function main() {
const doc = await ai.files.upload({
file: "path/to/file.txt",
config: { mimeType: "text/plain" },
});
console.log("Uploaded file name:", doc.name);
const modelName = "gemini-3-flash-preview";
const cache = await ai.caches.create({
model: modelName,
config: {
contents: createUserContent(createPartFromUri(doc.uri, doc.mimeType)),
systemInstruction: "You are an expert analyzing transcripts.",
},
});
console.log("Cache created:", cache);
const response = await ai.models.generateContent({
model: modelName,
contents: "Please summarize this transcript",
config: { cachedContent: cache.name },
});
console.log("Response text:", response.text);
}
await main();
برو
مثال زیر نحوه تولید محتوا با استفاده از حافظه پنهان (cache) را نشان میدهد.
package main
import (
"context"
"fmt"
"log"
"google.golang.org/genai"
)
func main() {
ctx := context.Background()
client, err := genai.NewClient(ctx, &genai.ClientConfig{
APIKey: "GOOGLE_API_KEY",
Backend: genai.BackendGeminiAPI,
})
if err != nil {
log.Fatal(err)
}
modelName := "gemini-3-flash-preview"
document, err := client.Files.UploadFromPath(
ctx,
"media/a11.txt",
&genai.UploadFileConfig{
MIMEType: "text/plain",
},
)
if err != nil {
log.Fatal(err)
}
parts := []*genai.Part{
genai.NewPartFromURI(document.URI, document.MIMEType),
}
contents := []*genai.Content{
genai.NewContentFromParts(parts, genai.RoleUser),
}
cache, err := client.Caches.Create(ctx, modelName, &genai.CreateCachedContentConfig{
Contents: contents,
SystemInstruction: genai.NewContentFromText(
"You are an expert analyzing transcripts.", genai.RoleUser,
),
})
if err != nil {
log.Fatal(err)
}
fmt.Println("Cache created:")
fmt.Println(cache)
// Use the cache for generating content.
response, err := client.Models.GenerateContent(
ctx,
modelName,
genai.Text("Please summarize this transcript"),
&genai.GenerateContentConfig{
CachedContent: cache.Name,
},
)
if err != nil {
log.Fatal(err)
}
printResponse(response) // helper for printing response parts
}
استراحت
مثال زیر نحوه ایجاد یک حافظه پنهان و سپس استفاده از آن برای تولید محتوا را نشان میدهد.
ویدیوها
wget https://storage.googleapis.com/generativeai-downloads/data/a11.txt
echo '{
"model": "models/gemini-3-flash-preview",
"contents":[
{
"parts":[
{
"inline_data": {
"mime_type":"text/plain",
"data": "'$(base64 $B64FLAGS a11.txt)'"
}
}
],
"role": "user"
}
],
"systemInstruction": {
"parts": [
{
"text": "You are an expert at analyzing transcripts."
}
]
},
"ttl": "300s"
}' > request.json
curl -X POST "https://generativelanguage.googleapis.com/v1beta/cachedContents?key=$GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-d @request.json \
> cache.json
CACHE_NAME=$(cat cache.json | grep '"name":' | cut -d '"' -f 4 | head -n 1)
curl -X POST "https://generativelanguage.googleapis.com/v1beta/models/gemini-3-flash-preview:generateContent?key=$GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"contents": [
{
"parts":[{
"text": "Please summarize this transcript"
}],
"role": "user"
},
],
"cachedContent": "'$CACHE_NAME'"
}'
فایلهای PDF
DOC_URL="https://sma.nasa.gov/SignificantIncidents/assets/a11_missionreport.pdf"
DISPLAY_NAME="A11_Mission_Report"
SYSTEM_INSTRUCTION="You are an expert at analyzing transcripts."
PROMPT="Please summarize this transcript"
MODEL="models/gemini-3-flash-preview"
TTL="300s"
# Download the PDF
wget -O "${DISPLAY_NAME}.pdf" "${DOC_URL}"
MIME_TYPE=$(file -b --mime-type "${DISPLAY_NAME}.pdf")
NUM_BYTES=$(wc -c < "${DISPLAY_NAME}.pdf")
echo "MIME_TYPE: ${MIME_TYPE}"
echo "NUM_BYTES: ${NUM_BYTES}"
tmp_header_file=upload-header.tmp
# Initial resumable request defining metadata.
# The upload url is in the response headers dump them to a file.
curl "${BASE_URL}/upload/v1beta/files?key=${GOOGLE_API_KEY}" \
-D upload-header.tmp \
-H "X-Goog-Upload-Protocol: resumable" \
-H "X-Goog-Upload-Command: start" \
-H "X-Goog-Upload-Header-Content-Length: ${NUM_BYTES}" \
-H "X-Goog-Upload-Header-Content-Type: ${MIME_TYPE}" \
-H "Content-Type: application/json" \
-d "{'file': {'display_name': '${DISPLAY_NAME}'}}" 2> /dev/null
upload_url=$(grep -i "x-goog-upload-url: " "${tmp_header_file}" | cut -d" " -f2 | tr -d "\r")
rm "${tmp_header_file}"
# Upload the actual bytes.
curl "${upload_url}" \
-H "Content-Length: ${NUM_BYTES}" \
-H "X-Goog-Upload-Offset: 0" \
-H "X-Goog-Upload-Command: upload, finalize" \
--data-binary "@${DISPLAY_NAME}.pdf" 2> /dev/null > file_info.json
file_uri=$(jq ".file.uri" file_info.json)
echo "file_uri: ${file_uri}"
# Clean up the downloaded PDF
rm "${DISPLAY_NAME}.pdf"
# Create the cached content request
echo '{
"model": "'$MODEL'",
"contents":[
{
"parts":[
{"file_data": {"mime_type": "'$MIME_TYPE'", "file_uri": '$file_uri'}}
],
"role": "user"
}
],
"system_instruction": {
"parts": [
{
"text": "'$SYSTEM_INSTRUCTION'"
}
],
"role": "system"
},
"ttl": "'$TTL'"
}' > request.json
# Send the cached content request
curl -X POST "${BASE_URL}/v1beta/cachedContents?key=$GOOGLE_API_KEY" \
-H 'Content-Type: application/json' \
-d @request.json \
> cache.json
CACHE_NAME=$(cat cache.json | grep '"name":' | cut -d '"' -f 4 | head -n 1)
echo "CACHE_NAME: ${CACHE_NAME}"
# Send the generateContent request using the cached content
curl -X POST "${BASE_URL}/${MODEL}:generateContent?key=$GOOGLE_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"contents": [
{
"parts":[{
"text": "'$PROMPT'"
}],
"role": "user"
}
],
"cachedContent": "'$CACHE_NAME'"
}' > response.json
cat response.json
echo jq ".candidates[].content.parts[].text" response.json
فهرست کردن حافظههای پنهان
بازیابی یا مشاهده محتوای ذخیره شده در حافظه پنهان (cache) امکانپذیر نیست، اما میتوانید متادیتای حافظه پنهان ( name ، model ، display_name ، usage_metadata ، create_time ، update_time و expire_time ) را بازیابی کنید.
پایتون
برای فهرست کردن متادیتای همه حافظههای پنهان آپلود شده، از CachedContent.list() استفاده کنید:
for cache in client.caches.list():
print(cache)
برای دریافت متادیتای یک شیء کش، اگر نام آن را میدانید، get استفاده کنید:
client.caches.get(name=name)
جاوا اسکریپت
برای فهرست کردن متادیتای همه حافظههای پنهان آپلود شده، از GoogleGenAI.caches.list() استفاده کنید:
console.log("My caches:");
const pager = await ai.caches.list({ config: { pageSize: 10 } });
let page = pager.page;
while (true) {
for (const c of page) {
console.log(" ", c.name);
}
if (!pager.hasNextPage()) break;
page = await pager.nextPage();
}
برو
مثال زیر تمام حافظههای پنهان را فهرست میکند.
caches, err := client.Caches.All(ctx)
if err != nil {
log.Fatal(err)
}
fmt.Println("Listing all caches:")
for _, item := range caches {
fmt.Println(" ", item.Name)
}
مثال زیر حافظههای نهان را با استفاده از اندازه صفحه ۲ فهرست میکند.
page, err := client.Caches.List(ctx, &genai.ListCachedContentsConfig{PageSize: 2})
if err != nil {
log.Fatal(err)
}
pageIndex := 1
for {
fmt.Printf("Listing caches (page %d):\n", pageIndex)
for _, item := range page.Items {
fmt.Println(" ", item.Name)
}
if page.NextPageToken == "" {
break
}
page, err = page.Next(ctx)
if err == genai.ErrPageDone {
break
} else if err != nil {
return err
}
pageIndex++
}
استراحت
curl "https://generativelanguage.googleapis.com/v1beta/cachedContents?key=$GEMINI_API_KEY"
بهروزرسانی حافظه پنهان
شما میتوانید یک ttl یا expire_time جدید برای کش تنظیم کنید. تغییر هر چیز دیگری در مورد کش پشتیبانی نمیشود.
پایتون
مثال زیر نحوه بهروزرسانی ttl یک حافظه پنهان (cache) را با استفاده از client.caches.update() نشان میدهد.
from google import genai
from google.genai import types
client.caches.update(
name = cache.name,
config = types.UpdateCachedContentConfig(
ttl='300s'
)
)
برای تنظیم زمان انقضا، این تابع یا یک شیء datetime یا یک رشته datetime با فرمت ISO ( dt.isoformat() مانند 2025-01-27T16:02:36.473528+00:00 ) را میپذیرد. زمان شما باید شامل یک منطقه زمانی باشد ( datetime.utcnow() منطقه زمانی را ضمیمه نمیکند، datetime.now(datetime.timezone.utc) یک منطقه زمانی را ضمیمه میکند).
from google import genai
from google.genai import types
import datetime
# You must use a time zone-aware time.
in10min = datetime.datetime.now(datetime.timezone.utc) + datetime.timedelta(minutes=10)
client.caches.update(
name = cache.name,
config = types.UpdateCachedContentConfig(
expire_time=in10min
)
)
جاوا اسکریپت
مثال زیر نحوه بهروزرسانی ttl یک حافظه پنهان (cache) را با استفاده از GoogleGenAI.caches.update() نشان میدهد.
const ttl = `${2 * 3600}s`; // 2 hours in seconds
const updatedCache = await ai.caches.update({
name: cache.name,
config: { ttl },
});
console.log("After update (TTL):", updatedCache);
برو
مثال زیر نحوه بهروزرسانی TTL یک حافظه پنهان را نشان میدهد.
// Update the TTL (2 hours).
cache, err = client.Caches.Update(ctx, cache.Name, &genai.UpdateCachedContentConfig{
TTL: 7200 * time.Second,
})
if err != nil {
log.Fatal(err)
}
fmt.Println("After update:")
fmt.Println(cache)
استراحت
مثال زیر نحوه بهروزرسانی ttl یک حافظه پنهان را نشان میدهد.
curl -X PATCH "https://generativelanguage.googleapis.com/v1beta/$CACHE_NAME?key=$GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"ttl": "600s"}'
حذف حافظه پنهان
سرویس ذخیرهسازی، عملیات حذف را برای حذف دستی محتوا از حافظه پنهان ارائه میدهد. مثال زیر نحوه حذف حافظه پنهان را نشان میدهد:
پایتون
client.caches.delete(cache.name)
جاوا اسکریپت
await ai.caches.delete({ name: cache.name });
برو
_, err = client.Caches.Delete(ctx, cache.Name, &genai.DeleteCachedContentConfig{})
if err != nil {
log.Fatal(err)
}
fmt.Println("Cache deleted:", cache.Name)
استراحت
curl -X DELETE "https://generativelanguage.googleapis.com/v1beta/$CACHE_NAME?key=$GEMINI_API_KEY"
ذخیره سازی صریح با استفاده از کتابخانه OpenAI
اگر از کتابخانه OpenAI استفاده میکنید، میتوانید با استفاده از ویژگی cached_content در extra_body ، ذخیرهسازی صریح را فعال کنید.
چه زمانی از ذخیرهسازی صریح استفاده کنیم؟
ذخیرهسازی زمینه (Context caching) به ویژه برای سناریوهایی مناسب است که در آنها یک زمینه اولیه قابل توجه به طور مکرر توسط درخواستهای کوتاهتر ارجاع داده میشود. استفاده از ذخیرهسازی زمینه را برای موارد استفادهای مانند موارد زیر در نظر بگیرید:
- چتباتها با دستورالعملهای سیستمی گسترده
- تجزیه و تحلیل مکرر فایلهای ویدیویی طولانی
- پرسوجوهای مکرر در برابر مجموعههای بزرگ اسناد
- تحلیل مکرر مخزن کد یا رفع اشکال
چگونه ذخیرهسازی صریح هزینهها را کاهش میدهد
ذخیرهسازی متن یک ویژگی پولی است که برای کاهش هزینه طراحی شده است. هزینه بر اساس عوامل زیر محاسبه میشود:
- تعداد توکنهای ورودی ذخیرهشده در حافظه پنهان: تعداد توکنهای ورودی ذخیرهشده که در صورت اضافه شدن در درخواستهای بعدی، با نرخ کاهشیافته محاسبه میشوند.
- مدت زمان ذخیرهسازی: میزان زمانی که توکنهای ذخیرهشده در حافظه پنهان (TTL) ذخیره میشوند، که بر اساس مدت زمان TTL تعداد توکنهای ذخیرهشده محاسبه میشود. هیچ محدودیت حداقل یا حداکثری برای TTL وجود ندارد.
- عوامل دیگر: هزینههای دیگری نیز اعمال میشود، مانند توکنهای ورودی غیر ذخیره شده و توکنهای خروجی.
برای جزئیات بهروز قیمتگذاری، به صفحه قیمتگذاری API Gemini مراجعه کنید. برای یادگیری نحوه شمارش توکنها، به راهنمای توکن مراجعه کنید.
ملاحظات اضافی
هنگام استفاده از ذخیرهسازی زمینهای (context caching)، نکات زیر را در نظر داشته باشید:
- حداقل تعداد توکنهای ورودی برای ذخیرهسازی زمینه بر اساس مدل متفاوت است. حداکثر آن مشابه حداکثر برای مدل داده شده است. (برای اطلاعات بیشتر در مورد شمارش توکنها، به راهنمای توکن مراجعه کنید).
- این مدل هیچ تمایزی بین توکنهای ذخیرهشده در حافظه پنهان و توکنهای ورودی معمولی قائل نمیشود. محتوای ذخیرهشده پیشوندی برای اعلان است.
- هیچ محدودیت نرخ یا استفاده خاصی برای ذخیرهسازی زمینه وجود ندارد؛ محدودیتهای نرخ استاندارد برای
GenerateContentاعمال میشود و محدودیتهای توکن شامل توکنهای ذخیره شده نیز میشود. - تعداد توکنهای ذخیرهشده در
usage_metadataاز عملیات ایجاد، دریافت و فهرست سرویس حافظه پنهان و همچنین درGenerateContentهنگام استفاده از حافظه پنهان، بازگردانده میشود.