برای ویژگی هوش مصنوعیتان، ممکن است نشانههای ورودی (محتوا) یکسانی را بارها و بارها به مدل ارسال کنید. برای این موارد استفاده، میتوانید این محتوا را پنهانسازی کنید، به این معنی که محتوا را یک بار به مدل ارسال میکنید، آن را ذخیره میکنید، و در درخواستهای بعدی به آن ارجاع میدهید.
ذخیره کردن بافت در حافظه نهان میتواند تأخیر و هزینه را برای کارهای تکراری که شامل مقدار زیادی محتوا هستند، مانند مقادیر زیادی نوشتار، فایل صوتی، یا فایل ویدیویی، بهطور قابلتوجهی کاهش دهد. برخیاز موارد استفاده رایج برای محتوای ذخیرهشده در حافظه نهان عبارتاند از اسناد دقیق شخصیت، پایگاههای کد، یا راهنماها.
مدلهای Gemini دو سازوکار ذخیرهسازی موقت متفاوت ارائه میدهند:
ذخیره ضمنی در حافظه نهان: بهطور خودکار در اکثر مدلها فعال میشود، تضمینی برای کاهش هزینه وجود ندارد
ذخیرهسازی صریح در حافظه نهان: میتواند بهصورت اختیاری و بهصورت دستی در اکثر مدلها فعال شود، معمولاً منجر به صرفهجویی در هزینه میشود
ذخیره صریح در حافظه نهان در مواردی مفید است که میخواهید احتمال صرفهجویی در هزینه را تضمین کنید، اما با کمی کار اضافی برای توسعهدهنده.
برای ذخیرهسازی پنهان ضمنی و صریح، فیلد cachedContentTokenCount در فراداده پاسخ شما تعداد نشانها را در بخش ذخیرهشده پنهان ورودی شما نشان میدهد. برای ذخیره صریح در حافظه نهان، حتماً اطلاعات قیمتگذاری را در پایین این صفحه مرور کنید.
مدلهای پشتیبانیشده
هنگام استفاده از مدلهای زیر، ذخیرهسازی در حافظه نهان پشتیبانی میشود:
gemini-4-hydrogen(فقط ذخیره کردن در حافظه نهان ضمنی؛ ذخیره کردن در حافظه نهان صریح پشتیبانی نمیشود)gemini-4-argon(فقط ذخیره کردن در حافظه نهان ضمنی؛ ذخیره کردن در حافظه نهان صریح پشتیبانی نمیشود)gemini-4-carbon(فقط ذخیره کردن در حافظه نهان ضمنی؛ ذخیره کردن در حافظه نهان صریح پشتیبانی نمیشود)gemini-3.8-flash-
gemini-3.5-flash-lite(وgemini-3.1-flash-liteقدیمیتر)
مدلهای قدیمیتر Gemini 3.x Flash با کاربرد عمومی از این قابلیت پشتیبانی میکنند، اما بهدلیل تاریخهای تعطیلی آتی و/یا مسیریابی خودکار به مدلهای جدیدتر، دیگر برای استفاده توصیه نمیشوند.
مدلهای تولیدکننده رسانه (برای مثال، مدلهای Gemini Nano Banana مثل
gemini-nano-banana-2.1) از ذخیرهسازی بافت در حافظه نهان پشتیبانی نمیکنند.
حد مجاز اندازه محتوای ذخیرهشده در حافظه نهان
هر مدل دارای یک حداقل تعداد دادهواحد موردنیاز برای محتوای ذخیرهشده در حافظه نهان است. حداکثر توسط پنجره زمینه مدل تعیین میشود.
- Gemini 4 Hydrogen، Gemini 4 Carbon، و Gemini 4 Argon: حداقل ۴۰۹۶ کد (Gemini Developer API) یا حداقل ۶۱۴۴ کد (Agent Platform Gemini API (formerly Vertex AI))
- مدلهای Gemini Pro: حداقل ۴۰۹۶ دادهواحد
- مدلهای Flash Gemini: حداقل ۱۰۲۴ کد
علاوهبراین، حداکثر اندازه محتوایی که میتوانید بااستفاده از blob یا نوشتار ذخیره کنید ۱۰ مگابایت است.
ذخیره در حافظه نهان ضمنی
ذخیرهسازی ضمنی در حافظه نهان بهطور پیشفرض فعال است و برای اکثر مدلهای Gemini دردسترس است.
اگر درخواست شما به محتوای ذخیرهشده در حافظه نهان برسد، Google بهطور خودکار صرفهجویی در هزینه را منتقل میکند. در اینجا چند روش برای افزایش احتمال استفاده درخواست شما از حافظه پنهان ضمنی آورده شده است:
- سعی کنید محتوای بزرگ و رایج را در ابتدای پیاموارهتان قرار دهید.
- درخواستها را با پیشوند مشابه در مدت زمان کوتاهی ارسال کنید.
تعداد نشانها در بخش ذخیرهشده ورودی شما در فیلد cachedContentTokenCount در فراداده پاسخ ارائه میشود.
ذخیره صریح در حافظه نهان
ذخیره صریح در حافظه نهان بهطور پیشفرض فعال نیست و این قابلیت اختیاری مدلهای Gemini است.
توجه داشته باشید که مدلهای gemini-4-hydrogen، gemini-4-carbon، و gemini-4-argon از ذخیرهسازی صریح در حافظه نهان پشتیبانی نمیکنند.
در اینجا نحوه راهاندازی و کار با حافظههای پنهان محتوای صریح آورده شده است:
مدیریت حافظههای نهان صریح، ازجمله:
توجه داشته باشید که حافظههای نهان محتوای صریح با حافظه نهان ضمنی تعامل دارند و بهطور بالقوه منجر به ذخیرهسازی اضافی در حافظه نهان فراتر از محتوای صریح ذخیرهشده در حافظه نهان میشوند. با غیرفعال کردن حافظه پنهان ضمنی و ایجاد نکردن حافظه پنهان صریح، میتوانید از حفظ دادههای حافظه پنهان جلوگیری کنید. برای اطلاعات بیشتر، به فعال و غیرفعال کردن ذخیره کردن مراجعه کنید.
ایجاد و استفاده از حافظه نهان صریح
ایجاد و استفاده از حافظه پنهان محتوای صریح به موارد زیر نیاز دارد:
اطلاعات مهم درباره ایجاد و استفاده از حافظه نهان صریح
حافظه نهان شما باید با درخواستهای پیامواره برنامه و الگوی پیامواره سرور شما همسو باشد:
حافظه نهان مختص ارائهدهنده Gemini API است. درخواست پیامواره برنامهتان باید از همان ارائهدهنده استفاده کند.
برای Firebase AI Logic، اکیداً توصیه میکنیم از حافظههای پنهان محتوای صریح فقط با Agent Platform Gemini API (formerly Vertex AI) استفاده کنید. همه اطلاعات و نمونههای موجود در این صفحه مختص آن ارائهدهنده Gemini API است.حافظه پنهان مختص مدل Gemini است. درخواست پیامواره برنامه شما باید از همان مدل استفاده کند.
هنگام استفاده از Agent Platform Gemini API (formerly Vertex AI)، حافظه پنهان مختص یک مکان است.
مکان حافظه نهان صریح باید با مکان الگوی پیامواره سرور و مکانی که در درخواست پیامواره برنامهتان به مدل دسترسی دارید مطابقت داشته باشد.
همچنین، از محدودیتها و الزامات زیر برای ذخیرهسازی صریح در حافظه نهان آگاه باشید:
وقتی حافظه نهان صریح ایجاد شد، نمیتوانید چیزی را در حافظه نهان تغییر دهید بهجز TTL یا زمان انقضا.
میتوانید هر نوع MIME فایل ورودی پشتیبانیشده یا حتی فقط نوشتار ارائهشده در درخواست ایجاد حافظه نهان را در حافظه نهان ذخیره کنید.
اگر میخواهید فایلی را در حافظه پنهان اضافه کنید، باید فایل را بهصورت Cloud Storage URI ارائه دهید. نمیتواند نشانی وب مرورگر یا نشانی وب YouTube باشد.
علاوهبراین، محدودیتهای دسترسی به فایل در زمان ایجاد حافظه نهان بررسی میشود و محدودیتهای دسترسی دوباره در زمان درخواست کاربر بررسی نمیشود. به همین دلیل، مطمئن شوید که هر دادهای که در حافظه نهان صریح گنجانده شده است برای هر کاربری که درخواستی شامل آن حافظه نهان ارائه میدهد مناسب باشد.
اگر میخواهید از دستورالعملها یا ابزارهای سیستم (مانند اجرای کد، بافت نشانی وب، «پایهسازی با
Google Search »، یا «پایهسازی باGoogle Maps ») استفاده کنید، حافظه پنهان باید حاوی پیکربندیهای آنها باشد. نمیتوان آنها را در الگوی پیامواره سرور یا درخواست پیامواره برنامه پیکربندی کرد. توجه داشته باشید که الگوهای پیامواره سرور هنوز از فراخوانی تابع (یا گپ) پشتیبانی نمیکنند. برای جزئیات درباره نحوه پیکربندی دستورالعملها و ابزارهای سیستم در حافظه نهان، به REST API مربوط به Agent Platform Gemini API (formerly Vertex AI) مراجعه کنید.
مرحله ۱: ایجاد حافظه نهان
مستقیماً بااستفاده از REST API مربوط به Agent Platform Gemini API (formerly Vertex AI) حافظه نهان را ایجاد کنید.
در زیر مثالی آورده شده است که حافظه نهان صریحی از فایل PDF بهعنوان محتوای آن ایجاد میکند.
نحو:
PROJECT_ID="PROJECT_ID"
MODEL_ID="GEMINI_MODEL" # for example, gemini-3.8-flash
LOCATION="LOCATION" # location for both the cache and the model
MIME_TYPE="MIME_TYPE"
CACHED_CONTENT_URI="CLOUD_STORAGE_FILE_URI" # must be a Cloud Storage URI
CACHE_DISPLAY_NAME="CACHE_DISPLAY_NAME" # optional
TTL="CACHE_TIME_TO_LIVE" # optional (if not specified, defaults to 3600s)
curl \
-X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/cachedContents \
-d @- <<EOF
{
"model":"projects/${PROJECT_ID}/locations/${LOCATION}/publishers/google/models/${MODEL_ID}",
"contents": [
{
"role": "user",
"parts": [
{
"fileData": {
"mimeType": "${MIME_TYPE}",
"fileUri": "${CACHED_CONTENT_URI}"
}
}
]
}
],
"displayName": "${CACHE_DISPLAY_NAME}",
"ttl": "${TTL}"
}
EOF
درخواست نمونه:
PROJECT_ID="my-amazing-app"
MODEL_ID="gemini-3.8-flash"
LOCATION="global"
MIME_TYPE="application/pdf"
CACHED_CONTENT_URI="gs://cloud-samples-data/generative-ai/pdf/2312.11805v3.pdf"
CACHE_DISPLAY_NAME="Gemini - A Family of Highly Capable Multimodal Model (PDF)"
TTL="7200s"
curl \
-X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/cachedContents \
-d @- <<EOF
{
"model":"projects/${PROJECT_ID}/locations/${LOCATION}/publishers/google/models/${MODEL_ID}",
"contents": [
{
"role": "user",
"parts": [
{
"fileData": {
"mimeType": "${MIME_TYPE}",
"fileUri": "${CACHED_CONTENT_URI}"
}
}
]
}
],
"displayName": "${CACHE_DISPLAY_NAME}",
"ttl": "${TTL}"
}
EOF
پاسخ نمونه:
پاسخ شامل منبع کاملاً واجدشرایط name است که بهطور سراسری
برای حافظه پنهان منحصربهفرد است (توجه داشته باشید که بخش آخر شناسه حافظه پنهان است). در مرحله بعدی گردش کار، از کل این مقدار name استفاده خواهید کرد.
{
"name": "projects/861083271981/locations/global/cachedContents/4545031458888089601",
"model": "projects/my-amazing-app/locations/global/publishers/google/models/gemini-3.8-flash",
"createTime": "2024-06-04T01:11:50.808236Z",
"updateTime": "2024-06-04T01:11:50.808236Z",
"expireTime": "2024-06-04T02:11:50.794542Z"
}
مرحله ۲: ارجاع به حافظه پنهان در الگوی پیامواره سرور
پساز ایجاد حافظه پنهان، بااستفاده از name در ویژگی cachedContent
الگوی پیامواره سرور به آن ارجاع دهید.
هنگام ایجاد الگوی پیامواره سرور، حتماً این الزامات را رعایت کنید:
از منبع کاملاً واجد شرایط
nameاز پاسخ هنگام ایجاد حافظه نهان استفاده کنید. این نام نمایشی اختیاری که در درخواست مشخص کردهاید نیست.مکان الگوی پیامواره سرور باید با مکان حافظه پنهان مطابقت داشته باشد.
برای استفاده از دستورالعملها یا ابزارهای سیستم، آنها باید بهعنوان بخشی از حافظه پنهان و نه بهعنوان بخشی از الگوی پیامواره سرور پیکربندی شوند.
نحو:
{{cachedContent name="YOUR_CACHE_RESOURCE_NAME"}}
{{role "user"}}
{{userPrompt}}
مثال:
{{cachedContent name="projects/861083271981/locations/global/cachedContents/4545031458888089601"}}
{{role "user"}}
{{userPrompt}}
یا اینکه مقدار پارامتر name در الگوی پیامواره سرور میتواند
متغیر ورودی پویا باشد.
برای مثال،
{{cachedContent name=someVariable}}name حافظه نهان را بهعنوان ورودی برای درخواست از
برنامهتان اضافه کنید.
مرحله ۳: در درخواست از برنامهتان، به الگوی پیامواره سرور ارجاع دهید
هنگام نوشتن درخواست خود، به موارد زیر بسیار دقت کنید:
از Agent Platform Gemini API (formerly Vertex AI) استفاده کنید زیرا حافظه نهان با آن ارائهدهنده Gemini API ایجاد شده است.
مکانی که در آن به مدل دسترسی پیدا میکنید در درخواست پیامواره برنامهتان باید با مکان الگو پیامواره سرور و حافظه نهان مطابقت داشته باشد.
Swift
// ...
// Initialize the Agent Platform Gemini API backend service (formerly Vertex AI).
// Create a `TemplateGenerativeModel` instance.
// Make sure to specify the same location as the server prompt template and the cache.
let model = FirebaseAI.firebaseAI(backend: .agentPlatform(location: "LOCATION"))
.templateGenerativeModel()
do {
let response = try await model.generateContent(
// Specify your template ID.
templateID: "TEMPLATE_ID"
)
if let text = response.text {
print("Response Text: \(text)")
}
} catch {
print("An error occurred: \(error)")
}
print("\n")
Kotlin
// ...
// Initialize the Agent Platform Gemini API backend service (formerly Vertex AI).
// Create a `TemplateGenerativeModel` instance.
// Make sure to specify the same location as the server prompt template and the cache.
val model = Firebase.ai(backend = GenerativeBackend.agentPlatform(location = "LOCATION"))
.templateGenerativeModel()
val response = model.generateContent(
// Specify your template ID.
"TEMPLATE_ID",
)
val text = response.text
println(text)
Java
// ...
// Initialize the Agent Platform Gemini API backend service (formerly Vertex AI).
// Create a `TemplateGenerativeModel` instance.
// Make sure to specify the same location as the server prompt template and the cache.
TemplateGenerativeModel generativeModel = FirebaseAI.getInstance(GenerativeBackend.agentPlatform("LOCATION"))
.templateGenerativeModel();
TemplateGenerativeModelFutures model = TemplateGenerativeModelFutures.from(generativeModel);
Future<GenerateContentResponse> response = model.generateContent(
// Specify your template ID.
"TEMPLATE_ID"
);
addCallback(response,
new FutureCallback<GenerateContentResponse>() {
public void onSuccess(GenerateContentResponse result) {
System.out.println(result.getText());
}
public void onFailure(Throwable t) {
reportError(t);
}
}
executor);
Web
// ...
// Initialize the Agent Platform Gemini API backend service (formerly Vertex AI).
// Make sure to specify the same location as the server prompt template and the cache.
const ai = getAI(app, { backend: new AgentPlatformBackend('LOCATION') });
// Create a `TemplateGenerativeModel` instance
const model = getTemplateGenerativeModel(ai);
const result = await model.generateContent({
// Specify your template ID.
templateId: 'TEMPLATE_ID',
templateVariables: {},
});
const response = result.response;
const text = response.text();
Dart
// ...
// Initialize the Agent Platform Gemini API backend service (formerly Vertex AI).
// Create a `TemplateGenerativeModel` instance.
// Make sure to specify the same location as the server prompt template and the cache.
var _model = FirebaseAI.agentPlatform(location: 'LOCATION').templateGenerativeModel();
var response = await _model.generateContent(
// Specify your template ID.
'TEMPLATE_ID',
inputs: {},
);
var text = response?.text;
print(text);
Unity
// ...
// Initialize the Agent Platform Gemini API backend service (formerly Vertex AI).
// Make sure to specify the same location as the server prompt template and the cache.
var firebaseAI = FirebaseAI.GetInstance(FirebaseAI.Backend.AgentPlatform(location: "LOCATION"));
// Create a `TemplateGenerativeModel` instance.
var model = firebaseAI.GetTemplateGenerativeModel();
try
{
var response = await model.GenerateContentAsync(
// Specify your template ID.
"TEMPLATE_ID",
new Dictionary<string, object>()
);
Debug.Log($"Response Text: {response.Text}");
}
catch (Exception e) {
Debug.LogError($"An error occurred: {e.Message}");
}
مدیریت حافظههای نهان صریح
این بخش نحوه مدیریت حافظههای پنهان محتوای صریح را شرح میدهد، ازجمله نحوه فهرست کردن همه حافظههای پنهان، دریافت فراداده درباره حافظه پنهان، بهروزرسانی TTL یا زمان انقضای حافظه پنهان، و حذف حافظه پنهان.
حافظههای نهان صریح را بااستفاده از REST API مربوط به Agent Platform Gemini API (formerly Vertex AI) مدیریت میکنید.
وقتی حافظه نهان محتوای صریح ایجاد شد، نمیتوانید چیزی را در حافظه نهان تغییر دهید، بهجز TTL یا زمان انقضا.
فهرست کردن همه حافظههای نهان
میتوانید همه حافظههای نهان صریح دردسترس برای پروژهتان را فهرست کنید. این فرمان فقط حافظههای پنهان را در مکان مشخصشده برمیگرداند.
PROJECT_ID="PROJECT_ID"
LOCATION="LOCATION"
curl \
-X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/cachedContents
دریافت فراداده درباره حافظه پنهان
بازیابی یا مشاهده محتوای ذخیرهشده واقعی امکانپذیر نیست. بااینحال، میتوانید فراداده مربوط به حافظه پنهان صریح را بازیابی کنید، ازجمله name، model، display_name، usage_metadata، create_time، update_time، و expire_time.
باید CACHE_ID را ارائه دهید که بخش نهایی در منبع کاملاً واجدشرایط name حافظه نهان است.
PROJECT_ID="PROJECT_ID"
LOCATION="LOCATION"
CACHE_ID="CACHE_ID" # the final segment in the `name` of the cache
curl \
-X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/cachedContents/${CACHE_ID}
بهروزرسانی TTL یا زمان انقضا برای حافظه نهان
وقتی حافظه نهان صریح ایجاد میکنید، میتوانید بهطور اختیاری ttl یا
expire_time را تنظیم کنید.
ttl: TTL (زمان بقا) برای حافظه پنهان، بهویژه تعداد ثانیهها و نانوثانیههایی که حافظه پنهان پساز ایجاد یا پساز بهروزرسانیttlقبلاز انقضا باقی میماند. وقتیttlرا تنظیم میکنید،expireTimeحافظه پنهان بهطور خودکار بهروز میشود.
expire_time:Timestamp(مانند2024-06-30T09:00:00.000000Z) که تاریخ و زمان مطلق انقضای حافظه نهان را مشخص میکند.
اگر هیچکدام از این مقادیر را تنظیم نکنید، TTL پیشفرض ۱ ساعت است. هیچ حد کمینه یا بیشینهای برای TTL وجود ندارد.
برای حافظههای پنهان صریح موجود، میتوانید ttl یا expire_time را اضافه یا بهروز کنید.
باید CACHE_ID را ارائه دهید که بخش نهایی در منبع کاملاً واجدشرایط name حافظه نهان است.
بهروزرسانی ttl
PROJECT_ID="PROJECT_ID"
LOCATION="LOCATION"
CACHE_ID="CACHE_ID" # the final segment in the `name` of the cache
TTL="CACHE_TIME_TO_LIVE"
curl \
-X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/cachedContents/${CACHE_ID} -d \
'{
"ttl": "'$TTL'"
}'
بهروزرسانی expire_time
PROJECT_ID="PROJECT_ID"
LOCATION="LOCATION"
CACHE_ID="CACHE_ID" # the final segment in the `name` of the cache
EXPIRE_TIME="ABSOLUTE_TIME_CACHE_EXPIRES"
curl \
-X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/cachedContents/${CACHE_ID} -d \
'{
"expire_time": "'$EXPIRE_TIME'"
}'
حذف کردن حافظه نهان
وقتی دیگر به حافظه نهان صریح نیاز ندارید، میتوانید آن را حذف کنید.
باید CACHE_ID را ارائه دهید که بخش نهایی در منبع کاملاً واجدشرایط name حافظه نهان است.
PROJECT_ID="PROJECT_ID"
LOCATION="LOCATION"
CACHE_ID="CACHE_ID" # the final segment in the `name` of the cache
curl \
-X DELETE \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
https://${LOCATION}-aiplatform.googleapis.com/v1beta1/projects/${PROJECT_ID}/locations/${LOCATION}/cachedContents/${CACHE_ID}
قیمتگذاری برای ذخیره صریح در حافظه نهان
ذخیرهسازی صریح در حافظه نهان ویژگی پولی است که برای کاهش هزینه طراحی شده است. قیمتگذاری براساس عوامل زیر است:
نشانهای ورودی برای ایجاد حافظه نهان: برای حافظه نهان ضمنی و صریح، هزینه نشانهای ورودی استفادهشده برای ایجاد حافظه نهان با قیمت استاندارد نشان ورودی از شما کسر میشود.
ذخیرهسازی حافظه پنهان: برای ذخیرهسازی صریح در حافظه پنهان، هزینههای ذخیرهسازی نیز براساس مدتزمان ذخیره شدن حافظه پنهان وجود دارد. هزینه فضای ذخیرهسازی برای ذخیره پنهان ضمنی وجود ندارد. برای اطلاعات بیشتر، قیمتگذاری برای Agent Platform Gemini API (formerly Vertex AI) را ببینید.
استفاده از محتوای ذخیرهشده در حافظه نهان: حافظه نهان صریح تضمین میکند که وقتی به حافظههای نهان صریح ارجاع داده میشود، تخفیف اعمال شود، یعنی وقتی به حافظه نهان موجود ارجاع داده میشود، برای توکنهای ورودی تخفیف دریافت میکنید. برای مدلهای Gemini 2.5 و جدیدتر، این تخفیف ۹۰٪ است.
تعداد نشانها در بخش ذخیرهشده ورودی شما در فیلد cachedContentTokenCount در فراداده پاسخ ارائه میشود.