ذخیره‌سازی متن، ذخیره‌سازی متن

در یک گردش کاری معمولی هوش مصنوعی، ممکن است همان توکن های ورودی را بارها و بارها به یک مدل ارسال کنید. Gemini API دو مکانیسم کش متفاوت ارائه می دهد:

  • کش ضمنی (خودکار، بدون ضمانت صرفه جویی در هزینه)
  • ذخیره صریح (دستی، ضمانت صرفه جویی در هزینه)

کش ضمنی در مدل های Gemini 2.5 به طور پیش فرض فعال است. اگر درخواستی حاوی محتوایی باشد که در حافظه پنهان است، ما به‌طور خودکار هزینه‌های صرفه‌جویی را به شما پس می‌دهیم.

ذخیره سازی آشکار در مواردی مفید است که می خواهید صرفه جویی در هزینه را تضمین کنید، اما با برخی کار توسعه دهنده اضافه شده است.

ذخیره سازی ضمنی

کش ضمنی به طور پیش فرض برای همه مدل های Gemini 2.5 فعال است. اگر درخواست شما به حافظه پنهان برسد، ما به طور خودکار در هزینه صرفه جویی می کنیم. برای فعال کردن این کار نیازی به انجام کاری نیست. از 8 مه 2025 قابل اجرا است. حداقل تعداد توکن ورودی برای ذخیره متنی 1024 برای 2.5 Flash و 2048 برای 2.5 Pro است.

برای افزایش احتمال ضربه پنهان ضمنی:

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

می‌توانید تعداد نشانه‌هایی را که در حافظه پنهان بازدید کرده‌اند را در قسمت usage_metadata شی پاسخ ببینید.

ذخیره سازی آشکار

با استفاده از ویژگی cache صریح Gemini API، می‌توانید یک بار مقداری از محتوا را به مدل ارسال کنید، نشانه‌های ورودی را در حافظه پنهان نگه دارید و سپس برای درخواست‌های بعدی به نشانه‌های کش شده مراجعه کنید. در حجم‌های معین، استفاده از توکن‌های ذخیره‌سازی شده هزینه کمتری نسبت به ارسال مکرر در یک مجموعه توکن‌ها دارد.

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

این بخش فرض می‌کند که Gemini SDK را نصب کرده‌اید (یا curl را نصب کرده‌اید) و یک کلید API را پیکربندی کرده‌اید، همانطور که در شروع سریع نشان داده شده است.

با استفاده از حافظه پنهان محتوا تولید کنید

مثال زیر نحوه ایجاد کش و سپس استفاده از آن برای تولید محتوا را نشان می دهد.

ویدیوها فایل های PDF 
wget https://storage.googleapis.com/generativeai-downloads/data/a11.txt
echo '{
  "model": "models/gemini-2.0-flash-001",
  "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-2.0-flash-001: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://www.nasa.gov/wp-content/uploads/static/history/alsj/a17/A17_FlightPlan.pdf"
DISPLAY_NAME="A17_FlightPlan"
SYSTEM_INSTRUCTION="You are an expert at analyzing transcripts."
PROMPT="Please summarize this transcript"
MODEL="models/gemini-2.0-flash-001"
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 ، displayName ، usageMetadata ، createTime ، updateTime ، و expireTime ) را بازیابی کنید. 

curl "https://generativelanguage.googleapis.com/v1beta/cachedContents?key=$GEMINI_API_KEY"

یک کش را به روز کنید

می توانید یک ttl یا expireTime جدید برای کش تنظیم کنید. تغییر هر چیز دیگری در مورد حافظه پنهان پشتیبانی نمی شود.

مثال زیر نحوه به روز رسانی ttl یک کش را نشان می دهد. 

curl -X PATCH "https://generativelanguage.googleapis.com/v1beta/$CACHE_NAME?key=$GEMINI_API_KEY" \
 -H 'Content-Type: application/json' \
 -d '{"ttl": "600s"}'

یک کش را حذف کنید

سرویس کش عملیات حذف را برای حذف دستی محتوا از کش ارائه می دهد. مثال زیر نحوه حذف کش را نشان می دهد. 

curl -X DELETE "https://generativelanguage.googleapis.com/v1beta/$CACHE_NAME?key=$GEMINI_API_KEY"

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

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

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

چگونه ذخیره صریح هزینه ها را کاهش می دهد

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

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

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

ملاحظات اضافی

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

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

در یک گردش کاری معمولی هوش مصنوعی، ممکن است همان توکن های ورودی را بارها و بارها به یک مدل ارسال کنید. Gemini API دو مکانیسم کش متفاوت ارائه می دهد:

  • کش ضمنی (خودکار، بدون ضمانت صرفه جویی در هزینه)
  • ذخیره صریح (دستی، ضمانت صرفه جویی در هزینه)

کش ضمنی در مدل های Gemini 2.5 به طور پیش فرض فعال است. اگر درخواستی حاوی محتوایی باشد که در حافظه پنهان است، ما به‌طور خودکار هزینه‌های صرفه‌جویی را به شما پس می‌دهیم.

ذخیره سازی آشکار در مواردی مفید است که می خواهید صرفه جویی در هزینه را تضمین کنید، اما با برخی کار توسعه دهنده اضافه شده است.

ذخیره سازی ضمنی

کش ضمنی به طور پیش فرض برای همه مدل های Gemini 2.5 فعال است. اگر درخواست شما به حافظه پنهان برسد، ما به طور خودکار در هزینه صرفه جویی می کنیم. برای فعال کردن این کار نیازی به انجام کاری نیست. از 8 مه 2025 قابل اجرا است. حداقل تعداد توکن ورودی برای ذخیره متنی 1024 برای 2.5 Flash و 2048 برای 2.5 Pro است.

برای افزایش احتمال ضربه پنهان ضمنی:

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

می‌توانید تعداد نشانه‌هایی را که در حافظه پنهان بازدید کرده‌اند را در قسمت usage_metadata شی پاسخ ببینید.

ذخیره سازی آشکار

با استفاده از ویژگی cache صریح Gemini API، می‌توانید یک بار مقداری از محتوا را به مدل ارسال کنید، نشانه‌های ورودی را در حافظه پنهان نگه دارید و سپس برای درخواست‌های بعدی به نشانه‌های کش شده مراجعه کنید. در حجم‌های معین، استفاده از توکن‌های ذخیره‌سازی شده هزینه کمتری نسبت به ارسال مکرر در یک مجموعه توکن‌ها دارد.

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

این بخش فرض می‌کند که Gemini SDK را نصب کرده‌اید (یا curl را نصب کرده‌اید) و یک کلید API را پیکربندی کرده‌اید، همانطور که در شروع سریع نشان داده شده است.

با استفاده از حافظه پنهان محتوا تولید کنید

مثال زیر نحوه ایجاد کش و سپس استفاده از آن برای تولید محتوا را نشان می دهد.

ویدیوها فایل های PDF 
wget https://storage.googleapis.com/generativeai-downloads/data/a11.txt
echo '{
  "model": "models/gemini-2.0-flash-001",
  "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-2.0-flash-001: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://www.nasa.gov/wp-content/uploads/static/history/alsj/a17/A17_FlightPlan.pdf"
DISPLAY_NAME="A17_FlightPlan"
SYSTEM_INSTRUCTION="You are an expert at analyzing transcripts."
PROMPT="Please summarize this transcript"
MODEL="models/gemini-2.0-flash-001"
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 ، displayName ، usageMetadata ، createTime ، updateTime ، و expireTime ) را بازیابی کنید. 

curl "https://generativelanguage.googleapis.com/v1beta/cachedContents?key=$GEMINI_API_KEY"

یک کش را به روز کنید

می توانید یک ttl یا expireTime جدید برای کش تنظیم کنید. تغییر هر چیز دیگری در مورد حافظه پنهان پشتیبانی نمی شود.

مثال زیر نحوه به روز رسانی ttl یک کش را نشان می دهد. 

curl -X PATCH "https://generativelanguage.googleapis.com/v1beta/$CACHE_NAME?key=$GEMINI_API_KEY" \
 -H 'Content-Type: application/json' \
 -d '{"ttl": "600s"}'

یک کش را حذف کنید

سرویس کش عملیات حذف را برای حذف دستی محتوا از کش ارائه می دهد. مثال زیر نحوه حذف کش را نشان می دهد. 

curl -X DELETE "https://generativelanguage.googleapis.com/v1beta/$CACHE_NAME?key=$GEMINI_API_KEY"

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

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

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

چگونه ذخیره صریح هزینه ها را کاهش می دهد

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

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

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

ملاحظات اضافی

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

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

در یک گردش کاری معمولی هوش مصنوعی، ممکن است همان توکن های ورودی را بارها و بارها به یک مدل ارسال کنید. Gemini API دو مکانیسم کش متفاوت ارائه می دهد:

  • کش ضمنی (خودکار، بدون ضمانت صرفه جویی در هزینه)
  • ذخیره صریح (دستی، ضمانت صرفه جویی در هزینه)

کش ضمنی در مدل های Gemini 2.5 به طور پیش فرض فعال است. اگر درخواستی حاوی محتوایی باشد که در حافظه پنهان است، ما به‌طور خودکار هزینه‌های صرفه‌جویی را به شما پس می‌دهیم.

ذخیره سازی آشکار در مواردی مفید است که می خواهید صرفه جویی در هزینه را تضمین کنید، اما با برخی کار توسعه دهنده اضافه شده است.

ذخیره سازی ضمنی

کش ضمنی به طور پیش فرض برای همه مدل های Gemini 2.5 فعال است. اگر درخواست شما به حافظه پنهان برسد، ما به طور خودکار در هزینه صرفه جویی می کنیم. برای فعال کردن این کار نیازی به انجام کاری نیست. از 8 مه 2025 قابل اجرا است. حداقل تعداد توکن ورودی برای ذخیره متنی 1024 برای 2.5 Flash و 2048 برای 2.5 Pro است.

برای افزایش احتمال ضربه پنهان ضمنی:

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

می‌توانید تعداد نشانه‌هایی را که در حافظه پنهان بازدید کرده‌اند را در قسمت usage_metadata شی پاسخ ببینید.

ذخیره سازی آشکار

با استفاده از ویژگی cache صریح Gemini API، می‌توانید یک بار مقداری از محتوا را به مدل ارسال کنید، نشانه‌های ورودی را در حافظه پنهان نگه دارید و سپس برای درخواست‌های بعدی به نشانه‌های کش شده مراجعه کنید. در حجم‌های معین، استفاده از توکن‌های ذخیره‌سازی شده هزینه کمتری نسبت به ارسال مکرر در یک مجموعه توکن‌ها دارد.

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

این بخش فرض می‌کند که Gemini SDK را نصب کرده‌اید (یا curl را نصب کرده‌اید) و یک کلید API را پیکربندی کرده‌اید، همانطور که در شروع سریع نشان داده شده است.

با استفاده از حافظه پنهان محتوا تولید کنید

مثال زیر نحوه ایجاد کش و سپس استفاده از آن برای تولید محتوا را نشان می دهد.

ویدیوها فایل های PDF 
wget https://storage.googleapis.com/generativeai-downloads/data/a11.txt
echo '{
  "model": "models/gemini-2.0-flash-001",
  "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-2.0-flash-001: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://www.nasa.gov/wp-content/uploads/static/history/alsj/a17/A17_FlightPlan.pdf"
DISPLAY_NAME="A17_FlightPlan"
SYSTEM_INSTRUCTION="You are an expert at analyzing transcripts."
PROMPT="Please summarize this transcript"
MODEL="models/gemini-2.0-flash-001"
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 ، displayName ، usageMetadata ، createTime ، updateTime ، و expireTime ) را بازیابی کنید. 

curl "https://generativelanguage.googleapis.com/v1beta/cachedContents?key=$GEMINI_API_KEY"

یک کش را به روز کنید

می توانید یک ttl یا expireTime جدید برای کش تنظیم کنید. تغییر هر چیز دیگری در مورد حافظه پنهان پشتیبانی نمی شود.

مثال زیر نحوه به روز رسانی ttl یک کش را نشان می دهد. 

curl -X PATCH "https://generativelanguage.googleapis.com/v1beta/$CACHE_NAME?key=$GEMINI_API_KEY" \
 -H 'Content-Type: application/json' \
 -d '{"ttl": "600s"}'

یک کش را حذف کنید

سرویس کش عملیات حذف را برای حذف دستی محتوا از کش ارائه می دهد. مثال زیر نحوه حذف کش را نشان می دهد. 

curl -X DELETE "https://generativelanguage.googleapis.com/v1beta/$CACHE_NAME?key=$GEMINI_API_KEY"

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

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

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

چگونه ذخیره صریح هزینه ها را کاهش می دهد

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

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

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

ملاحظات اضافی

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

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

در یک گردش کاری معمولی هوش مصنوعی، ممکن است همان توکن های ورودی را بارها و بارها به یک مدل ارسال کنید. Gemini API دو مکانیسم کش متفاوت ارائه می دهد:

  • کش ضمنی (خودکار، بدون ضمانت صرفه جویی در هزینه)
  • ذخیره صریح (دستی، ضمانت صرفه جویی در هزینه)

کش ضمنی در مدل های Gemini 2.5 به طور پیش فرض فعال است. اگر درخواستی حاوی محتوایی باشد که در حافظه پنهان است، ما به‌طور خودکار هزینه‌های صرفه‌جویی را به شما پس می‌دهیم.

ذخیره سازی آشکار در مواردی مفید است که می خواهید صرفه جویی در هزینه را تضمین کنید، اما با برخی کار توسعه دهنده اضافه شده است.

ذخیره سازی ضمنی

کش ضمنی به طور پیش فرض برای همه مدل های Gemini 2.5 فعال است. اگر درخواست شما به حافظه پنهان برسد، ما به طور خودکار در هزینه صرفه جویی می کنیم. برای فعال کردن این کار نیازی به انجام کاری نیست. از 8 مه 2025 قابل اجرا است. حداقل تعداد توکن ورودی برای ذخیره متنی 1024 برای 2.5 Flash و 2048 برای 2.5 Pro است.

برای افزایش احتمال ضربه پنهان ضمنی:

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

می‌توانید تعداد نشانه‌هایی را که در حافظه پنهان بازدید کرده‌اند را در قسمت usage_metadata شی پاسخ ببینید.

ذخیره سازی آشکار

با استفاده از ویژگی cache صریح Gemini API، می‌توانید یک بار مقداری از محتوا را به مدل ارسال کنید، نشانه‌های ورودی را در حافظه پنهان نگه دارید و سپس برای درخواست‌های بعدی به نشانه‌های کش شده مراجعه کنید. در حجم‌های معین، استفاده از توکن‌های ذخیره‌سازی شده هزینه کمتری نسبت به ارسال مکرر در یک مجموعه توکن‌ها دارد.

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

این بخش فرض می‌کند که Gemini SDK را نصب کرده‌اید (یا curl را نصب کرده‌اید) و یک کلید API را پیکربندی کرده‌اید، همانطور که در شروع سریع نشان داده شده است.

با استفاده از حافظه پنهان محتوا تولید کنید

مثال زیر نحوه ایجاد کش و سپس استفاده از آن برای تولید محتوا را نشان می دهد.

ویدیوها فایل های PDF 
wget https://storage.googleapis.com/generativeai-downloads/data/a11.txt
echo '{
  "model": "models/gemini-2.0-flash-001",
  "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-2.0-flash-001: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://www.nasa.gov/wp-content/uploads/static/history/alsj/a17/A17_FlightPlan.pdf"
DISPLAY_NAME="A17_FlightPlan"
SYSTEM_INSTRUCTION="You are an expert at analyzing transcripts."
PROMPT="Please summarize this transcript"
MODEL="models/gemini-2.0-flash-001"
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 ، displayName ، usageMetadata ، createTime ، updateTime ، و expireTime ) را بازیابی کنید. 

curl "https://generativelanguage.googleapis.com/v1beta/cachedContents?key=$GEMINI_API_KEY"

یک کش را به روز کنید

می توانید یک ttl یا expireTime جدید برای کش تنظیم کنید. تغییر هر چیز دیگری در مورد حافظه پنهان پشتیبانی نمی شود.

مثال زیر نحوه به روز رسانی ttl یک کش را نشان می دهد. 

curl -X PATCH "https://generativelanguage.googleapis.com/v1beta/$CACHE_NAME?key=$GEMINI_API_KEY" \
 -H 'Content-Type: application/json' \
 -d '{"ttl": "600s"}'

یک کش را حذف کنید

سرویس کش عملیات حذف را برای حذف دستی محتوا از کش ارائه می دهد. مثال زیر نحوه حذف کش را نشان می دهد. 

curl -X DELETE "https://generativelanguage.googleapis.com/v1beta/$CACHE_NAME?key=$GEMINI_API_KEY"

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

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

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

چگونه ذخیره صریح هزینه ها را کاهش می دهد

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

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

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

ملاحظات اضافی

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

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