در گردش کار هوش مصنوعی معمولی، ممکن است نشانههای ورودی یکسانی را بارها و بارها به مدل ارسال کنید. Gemini API دو سازوکار مختلف ذخیره در حافظه نهان ارائه میدهد:
- ذخیرهسازی نهان ضمنی (در Gemini 2.5 و مدلهای جدیدتر بهطور خودکار فعال میشود، صرفهجویی در هزینه تضمین نمیشود)
- ذخیرهسازی صریح (در اکثر مدلها میتوان آن را بهصورت دستی فعال کرد، صرفهجویی در هزینه تضمینی است)
ذخیرهسازی صریح در مواردی که میخواهید صرفهجویی در هزینه را تضمین کنید مفید است، اما با مقداری کار توسعهدهنده اضافی.
ذخیره ضمنی در حافظه نهان
ذخیرهسازی نهان ضمنی بهطور پیشفرض برای همه مدلهای Gemini 2.5 و جدیدتر فعال است. اگر درخواست شما به حافظههای نهان برخورد کند، صرفهجویی در هزینه را بهطور خودکار به شما منتقل میکنیم. برای فعال کردن این ویژگی، لازم نیست کاری انجام دهید. حداقل تعداد نشان ورودی برای حافظه نهان زمینهای در جدول زیر برای هر مدل فهرست شده است:
| مدل | حداقل حد دادهواحد |
|---|---|
| Gemini 3.8 Flash | ۴٬۰۹۶ |
| Gemini 3.6 Flash | ۴٬۰۹۶ |
| پیشنمایش Gemini 3.1 Pro | ۴٬۰۹۶ |
| Gemini 2.5 Flash | ۲٬۰۴۸ |
| Gemini 2.5 Pro | ۲٬۰۴۸ |
برای افزایش احتمال برخورد با حافظه نهان ضمنی:
- محتوای بزرگ و رایج را در ابتدای پیاموارهتان قرار دهید
- سعی کنید درخواستهایی با پیشوند مشابه را در مدت زمان کوتاهی ارسال کنید
میتوانید تعداد نشانهایی را که در فیلد usage_metadata شیء پاسخ در حافظه نهان وجود داشته است ببینید.
ذخیره در حافظه نهان صریح
بااستفاده از ویژگی ذخیرهسازی صریح Gemini API، میتوانید محتوایی را یکبار به مدل منتقل کنید، نشانههای ورودی را در حافظه نهان ذخیره کنید، و سپس برای درخواستهای بعدی به نشانههای ذخیرهشده در حافظه نهان ارجاع دهید. در حجمهای معینی، استفاده از نشانهای ذخیرهشده در حافظه نهان هزینه کمتری نسبتبه انتقال مکرر همان پیکره نشانها دارد.
وقتی مجموعهای از نشانها را در حافظه نهان ذخیره میکنید، میتوانید انتخاب کنید حافظه نهان تا چه مدت وجود داشته باشد و پساز آن نشانها بهطور خودکار حذف شوند. این مدت زمان ذخیرهسازی موقت زمان بقا (TTL) نامیده میشود. اگر تنظیم نشده باشد، TTL بهطور پیشفرض روی ۱ ساعت تنظیم میشود. هزینه ذخیره در حافظه نهان به اندازه کد ورودی و مدت زمانی که میخواهید کدها ماندگار باشند بستگی دارد.
این بخش فرض میکند که «کیت توسعه نرمافزار Gemini» را نصب کردهاید (یا curl نصب کردهاید) و کلید API را همانطور که در راهنمای شروع به کار نشان داده شده است پیکربندی کردهاید.
تولید محتوا بااستفاده از حافظه نهان
Python
مثال زیر نحوه تولید محتوا بااستفاده از دستورالعمل سیستم ذخیرهشده در حافظه نهان و فایل ویدیویی را نشان میدهد.
ویدیوها
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.8-flash'
# 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)
فایلهای پیدیاف
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.8-flash"
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)
JavaScript
مثال زیر نحوه تولید محتوا بااستفاده از دستورالعمل سیستم ذخیرهشده در حافظه نهان و فایل نوشتاری را نشان میدهد.
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.8-flash";
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();
رفتن
مثال زیر نحوه تولید محتوا بااستفاده از حافظه نهان را نشان میدهد.
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.8-flash"
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
}
REST
مثال زیر نشان میدهد که چگونه میتوان حافظه نهان ایجاد کرد و سپس از آن برای تولید محتوا استفاده کرد.
ویدیوها
wget https://storage.googleapis.com/generativeai-downloads/data/a11.txt
echo '{
"model": "models/gemini-3.8-flash",
"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.8-flash:generateContent?key=$GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-d '{
"contents": [
{
"parts":[{
"text": "Please summarize this transcript"
}],
"role": "user"
},
],
"cachedContent": "'$CACHE_NAME'"
}'
فایلهای پیدیاف
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.8-flash"
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
فهرست کردن حافظههای نهان
امکان بازیابی یا مشاهده محتوای ذخیرهشده در حافظه نهان وجود ندارد، اما میتوانید فراداده حافظه نهان (name، model، display_name، usage_metadata،
create_time، update_time، و expire_time) را بازیابی کنید.
Python
برای فهرست کردن فرادادههای همه حافظههای نهان بارگذاریشده، از CachedContent.list() استفاده کنید:
for cache in client.caches.list():
print(cache)
برای واکشی فرادادههای یک شیء حافظه نهان، اگر نام آن را میدانید، از get استفاده کنید:
client.caches.get(name=name)
JavaScript
برای فهرست کردن فرادادههای همه حافظههای نهان بارگذاریشده، از 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++
}
REST
curl "https://generativelanguage.googleapis.com/v1beta/cachedContents?key=$GEMINI_API_KEY"
بهروزرسانی حافظه نهان
میتوانید ttl یا expire_time جدیدی برای حافظه نهان تنظیم کنید. تغییر هر چیز دیگری درباره حافظه نهان پشتیبانی نمیشود.
Python
مثال زیر نحوه بهروزرسانی ttl حافظه نهان را بااستفاده از
client.caches.update() نشان میدهد.
from google import genai
from google.genai import types
client.caches.update(
name = cache.name,
config = types.UpdateCachedContentConfig(
ttl='300s'
)
)
برای تنظیم زمان انقضا، هم شیء 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
)
)
JavaScript
مثال زیر نحوه بهروزرسانی ttl حافظه نهان را بااستفاده از
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)
REST
مثال زیر نحوه بهروزرسانی ttl حافظه نهان را نشان میدهد.
curl -X PATCH "https://generativelanguage.googleapis.com/v1beta/$CACHE_NAME?key=$GEMINI_API_KEY" \
-H 'Content-Type: application/json' \
-d '{"ttl": "600s"}'
حذف کردن حافظه نهان
سرویس ذخیرهسازی در حافظه نهان عملیات حذف برای برداشتن دستی محتوا از حافظه نهان ارائه میدهد. مثال زیر نحوه حذف حافظه نهان را نشان میدهد:
Python
client.caches.delete(cache.name)
JavaScript
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)
REST
curl -X DELETE "https://generativelanguage.googleapis.com/v1beta/$CACHE_NAME?key=$GEMINI_API_KEY"
ذخیرهسازی صریح بااستفاده از کتابخانه OpenAI
اگر از کتابخانه OpenAI استفاده میکنید، میتوانید بااستفاده از دارایی cached_content در extra_body،
ذخیرهسازی صریح را فعال کنید.
زمان استفاده از حافظه نهان صریح
ذخیره کردن بافت بهویژه برای سناریوهایی مناسب است که در آنها یک بافت اولیه قابلتوجه بهطور مکرر توسط درخواستهای کوتاهتر ارجاع داده میشود. برای موارد استفادهای مثل موارد زیر، از ذخیره کردن زمینهای استفاده کنید:
- روباتهای گپ با دستورالعملهای سیستم گسترده
- تجزیهوتحلیل تکراری فایلهای ویدیویی طولانی
- پُرسمانهای تکرارشونده دربرابر مجموعههای بزرگ سند
- تجزیهوتحلیل مکرر مخزن کد یا رفع اشکال
نحوه کاهش هزینهها با ذخیره کردن صریح
ذخیره کردن بافتار ویژگی پولی است که برای کاهش هزینه طراحی شده است. صورتحساب براساس عوامل زیر است:
- تعداد نشانهای حافظه نهان: تعداد نشانهای ورودی ذخیرهشده در حافظه نهان که وقتی در پیاموارههای بعدی گنجانده میشوند با نرخ کاهشیافته صورتحساب میشوند.
- مدت ذخیرهسازی: مدت زمانی که کدهای حافظه نهان ذخیره میشوند (TTL)، صورتحساب براساس مدت TTL تعداد کدهای حافظه نهان صادر میشود. هیچ محدوده حداقلی یا حداکثری برای TTL وجود ندارد.
- عوامل دیگر: هزینههای دیگری اعمال میشود، مانند هزینههای مربوط به نشانهای ورودی غیرذخیرهشده در حافظه نهان و نشانهای خروجی.
برای جزئیات قیمتگذاری بهروز، به صفحه قیمتگذاری Gemini API مراجعه کنید. برای آشنایی با نحوه شمارش نشانها، راهنمای نشان را ببینید.
سایر ملاحظات
هنگام استفاده از حافظه نهان زمینهای، ملاحظات زیر را درنظر داشته باشید:
- تعداد حداقل نشان ورودی برای حافظه نهان زمینهای بسته به مدل متفاوت است. حداکثر با حداکثر برای مدل دادهشده یکسان است. (برای اطلاعات بیشتر درباره شمارش نشانهها، راهنمای نشانهها را ببینید).
- این مدل هیچ تفاوتی بین نشانهای ذخیرهشده در حافظه نهان و نشانهای ورودی معمولی قائل نمیشود. محتوای ذخیرهشده در حافظه نهان پیشوندی برای پیامواره است.
- هیچ حد نرخ یا حد استفاده ویژهای برای حافظه نهان زمینهای وجود ندارد؛ حد نرخ استاندارد برای
GenerateContentاعمال میشود و حد نشان شامل نشانهای ذخیرهشده در حافظه نهان میشود. - تعداد نشانهای ذخیرهشده در حافظه نهان در
usage_metadataاز عملیاتهای ایجاد، دریافت، و فهرست کردن سرویس حافظه نهان، و همچنین درGenerateContentهنگام استفاده از حافظه نهان برگردانده میشود.