ذخیره کردن بافت در حافظه نهان

در گردش کار هوش مصنوعی معمولی، ممکن است نشانه‌های ورودی یکسانی را بارها و بارها به مدل ارسال کنید. ‫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، ذخیره‌سازی صریح را فعال کنید.

زمان استفاده از حافظه نهان صریح

ذخیره کردن بافت به‌ویژه برای سناریوهایی مناسب است که در آن‌ها یک بافت اولیه قابل‌توجه به‌طور مکرر توسط درخواست‌های کوتاه‌تر ارجاع داده می‌شود. برای موارد استفاده‌ای مثل موارد زیر، از ذخیره کردن زمینه‌ای استفاده کنید:

  • روبات‌های گپ با دستورالعمل‌های سیستم گسترده
  • تجزیه‌وتحلیل تکراری فایل‌های ویدیویی طولانی
  • پُرسمان‌های تکرارشونده دربرابر مجموعه‌های بزرگ سند
  • تجزیه‌وتحلیل مکرر مخزن کد یا رفع اشکال

نحوه کاهش هزینه‌ها با ذخیره کردن صریح

ذخیره کردن بافتار ویژگی پولی است که برای کاهش هزینه طراحی شده است. صورت‌حساب براساس عوامل زیر است:

  1. تعداد نشان‌های حافظه نهان: تعداد نشان‌های ورودی ذخیره‌شده در حافظه نهان که وقتی در پیام‌واره‌های بعدی گنجانده می‌شوند با نرخ کاهش‌یافته صورت‌حساب می‌شوند.
  2. مدت ذخیره‌سازی: مدت زمانی که کدهای حافظه نهان ذخیره می‌شوند (TTL)، صورت‌حساب براساس مدت TTL تعداد کدهای حافظه نهان صادر می‌شود. هیچ محدوده حداقلی یا حداکثری برای TTL وجود ندارد.
  3. عوامل دیگر: هزینه‌های دیگری اعمال می‌شود، مانند هزینه‌های مربوط به نشان‌های ورودی غیرذخیره‌شده در حافظه نهان و نشان‌های خروجی.

برای جزئیات قیمت‌گذاری به‌روز، به صفحه قیمت‌گذاری Gemini API مراجعه کنید. برای آشنایی با نحوه شمارش نشان‌ها، راهنمای نشان را ببینید.

سایر ملاحظات

هنگام استفاده از حافظه نهان زمینه‌ای، ملاحظات زیر را درنظر داشته باشید:

  • تعداد حداقل نشان ورودی برای حافظه نهان زمینه‌ای بسته به مدل متفاوت است. حداکثر با حداکثر برای مدل داده‌شده یکسان است. (برای اطلاعات بیشتر درباره شمارش نشانه‌ها، راهنمای نشانه‌ها را ببینید).
  • این مدل هیچ تفاوتی بین نشان‌های ذخیره‌شده در حافظه نهان و نشان‌های ورودی معمولی قائل نمی‌شود. محتوای ذخیره‌شده در حافظه نهان پیشوندی برای پیام‌واره است.
  • هیچ حد نرخ یا حد استفاده ویژه‌ای برای حافظه نهان زمینه‌ای وجود ندارد؛ حد نرخ استاندارد برای GenerateContent اعمال می‌شود و حد نشان شامل نشان‌های ذخیره‌شده در حافظه نهان می‌شود.
  • تعداد نشان‌های ذخیره‌شده در حافظه نهان در usage_metadata از عملیات‌های ایجاد، دریافت، و فهرست کردن سرویس حافظه نهان، و همچنین در GenerateContent هنگام استفاده از حافظه نهان برگردانده می‌شود.