ذخیره کردن زمینه‌ای در Firebase AI Logic

برای ویژگی هوش مصنوعی‌تان، ممکن است همان کدهای ورودی (محتوا) را بارها و بارها به مدل ارسال کنید. برای این موارد استفاده، می‌توانید این محتوا را در حافظه نهان ذخیره کنید، به این معنی که محتوا را یک بار به مدل ارسال می‌کنید، آن را ذخیره می‌کنید، و در درخواست‌های بعدی به آن ارجاع می‌دهید.

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

مدل‌های Gemini دو سازوکار ذخیره‌سازی موقت متفاوت ارائه می‌دهند:

• ذخیره‌سازی ضمنی در حافظه نهان: به‌طور خودکار در اکثر مدل‌ها فعال می‌شود، تضمینی برای کاهش هزینه وجود ندارد

• ذخیره‌سازی صریح در حافظه نهان: می‌تواند به‌صورت اختیاری و به‌صورت دستی در اکثر مدل‌ها فعال شود، معمولاً منجر به صرفه‌جویی در هزینه می‌شود

ذخیره صریح در حافظه نهان در مواردی مفید است که می‌خواهید احتمال صرفه‌جویی در هزینه را تضمین کنید، اما با کمی کار توسعه‌دهنده اضافی.

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

توجه: ذخیره کردن بافت در حافظه نهان معمولاً به‌عنوان ذخیره کردن محتوا در حافظه نهان شناخته می‌شود (همان‌طور که در بیشتر بخش‌های این صفحه انجام شده است).

مدل‌های پشتیبانی‌شده

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

• gemini-4-argon (فقط ذخیره کردن در حافظه نهان ضمنی؛ ذخیره کردن در حافظه نهان صریح پشتیبانی نمی‌شود)
• ‫gemini-3.8-flash (و مدل‌های قدیمی‌تر gemini-3.7-flash،‏ gemini-3.6-flash، و gemini-3.5-flash)
• gemini-3.5-flash-lite (و gemini-3.1-flash-lite قدیمی‌تر)

مدل‌های gemini-3.1-pro-preview و Gemini 2.5 با کاربرد عمومی (که منسوخ شده‌اند) نیز از این قابلیت پشتیبانی می‌کنند.

مدل‌های تولیدکننده رسانه (برای مثال، مدل‌های Gemini Nano Banana مثل gemini-nano-banana-2.1) از ذخیره‌سازی موقت بافت پشتیبانی نمی‌کنند.

حد مجاز اندازه محتوای ذخیره‌شده در حافظه نهان

هر مدل دارای یک شرط حداقل تعداد داده‌واحد برای محتوای ذخیره‌شده در حافظه نهان است. حداکثر توسط پنجره زمینه‌ای مدل تعیین می‌شود.

• Gemini 4 Argon: حداقل ۴۰۹۶ (Gemini Developer API) یا حداقل ۶۱۴۴ (Agent Platform Gemini API (formerly Vertex AI))
• مدل‌های Gemini Pro: حداقل ۴۰۹۶ داده‌واحد
• مدل‌های Flash‏ Gemini: حداقل ۱۰۲۴ داده‌واحد

علاوه‌براین، حداکثر اندازه محتوایی که می‌توانید بااستفاده از blob یا نوشتار ذخیره کنید ۱۰ مگابایت است.

---

ذخیره در حافظه نهان ضمنی

ذخیره‌سازی ضمنی در حافظه نهان به‌طور پیش‌فرض فعال است و برای اکثر مدل‌های Gemini دردسترس است.

اگر درخواست شما به محتوای ذخیره‌شده در حافظه نهان برسد، Google به‌طور خودکار صرفه‌جویی در هزینه را منتقل می‌کند. در اینجا چند روش برای افزایش احتمال استفاده درخواست شما از حافظه نهان ضمنی آورده شده است:

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

تعداد توکن‌ها در بخش ذخیره‌شده ورودی شما در فیلد cachedContentTokenCount در فراداده پاسخ ارائه می‌شود.

---

ذخیره در حافظه نهان صریح

ذخیره صریح در حافظه نهان به‌طور پیش‌فرض فعال نیست و این قابلیت اختیاری مدل‌های Gemini است.

توجه داشته باشید که مدل gemini-4-argon از ذخیره‌سازی صریح در حافظه نهان پشتیبانی نمی‌کند.

مهم: Firebase AI Logic دسترسی به حافظه‌های نهان محتوای صریح را فقط هنگام استفاده از الگوهای پیام‌واره سرور مجاز می‌کند.

همچنین، برای Firebase AI Logic، اکیداً توصیه می‌کنیم از حافظه‌های نهان محتوای صریح فقط با Agent Platform Gemini API (formerly Vertex AI) استفاده کنید تا هنگام ایجاد و مدیریت حافظه‌های نهان محتوای صریح، نگران استفاده یا افشای تصادفی کلید Gemini API نباشید.

توجه داشته باشید که Firebase AI Logic درحال تلاش برای بهبود گردش کار ذخیره‌سازی صریح در حافظه نهان است. اگر به این قابلیت علاقه دارید، می‌توانید به ورودی User Voice رأی موافق دهید تا بدانیم که این حوزه‌ای است که باید منابع را روی آن متمرکز کنیم.

در اینجا نحوه راه‌اندازی و کار با حافظه‌های پنهان محتوای صریح آورده شده است:

• ایجاد کردن و سپس استفاده کردن از حافظه نهان صریح

• حافظه‌های نهان صریح را مدیریت کنید، ازجمله:

  • فهرست کردن همه حافظه‌های پنهان

  • دریافت فراداده درباره حافظه پنهان

  • به‌روزرسانی TTL یا زمان انقضای حافظه نهان

  • حذف حافظه پنهان

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

---

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

ایجاد و استفاده از حافظه نهان محتوای صریح به موارد زیر نیاز دارد:

1. حافظه پنهان صریح ایجاد کنید.

2. به حافظه نهان در الگوی پیام‌واره سرور ارجاع دهید.

3. در درخواست پیام‌واره از برنامه‌تان، به الگوی پیام‌واره سرور ارجاع دهید.

اطلاعات مهم درباره ایجاد و استفاده از حافظه نهان صریح

حافظه نهان شما باید با درخواست‌های پیام‌واره برنامه و الگوی پیام‌واره سرور شما همسو باشد:

• حافظه پنهان مختص ارائه‌دهنده 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 به‌عنوان محتوای آن ایجاد می‌کند.

توجه: در مثال زیر فرض می‌شود که با اجرای gcloud init یا gcloud auth login به سیستم gcloud CLI وارد شده‌اید.
توصیه می‌کنیم مستقیماً در کنسول Firebase از Cloud Shell به gcloud CLI دسترسی پیدا کنید (که قبلاً با «حساب Google» که برای ورود به سیستم کنسول Firebase استفاده کرده‌اید اصالت‌سنجی شده است).

نحو:

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"
}

مرحله ۲: ارجاع به حافظه پنهان در الگوی پیام‌واره سرور

مهم: Firebase AI Logic فقط هنگام استفاده از الگوهای پیام‌واره سرور اجازه دسترسی به حافظه‌های نهان محتوای صریح را می‌دهد.

پس‌از ایجاد حافظه پنهان، بااستفاده از 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}");
}

توجه: اگر name حافظه نهان در الگو نامعتبر باشد، اگر مکان‌ها در همه مؤلفه‌ها مطابقت نداشته باشند، یا اگر حافظه نهان منقضی شده باشد، درخواست با خطای Explicit content cache doesn't exist ناموفق خواهد بود.

---

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

این بخش نحوه مدیریت حافظه‌های نهان محتوای صریح را شرح می‌دهد، ازجمله نحوه فهرست کردن همه حافظه‌های نهان، دریافت فراداده درباره حافظه نهان، به‌روزرسانی TTL یا زمان انقضای حافظه نهان، و حذف حافظه نهان.

حافظه‌های نهان صریح را بااستفاده از REST API مربوط به Agent Platform Gemini API (formerly Vertex AI) مدیریت می‌کنید.

پس‌از ایجاد حافظه نهان محتوای صریح، نمی‌توانید چیزی را در حافظه نهان تغییر دهید، به‌جز TTL یا زمان انقضا.

توجه: در مثال‌های زیر فرض می‌شود که با اجرای gcloud init یا gcloud auth login به سیستم gcloud CLI وارد شده‌اید.
توصیه می‌کنیم مستقیماً در کنسول Firebase از Cloud Shell به gcloud CLI دسترسی پیدا کنید (که قبلاً با «حساب Google» که برای ورود به سیستم کنسول Firebase استفاده کرده‌اید اصالت‌سنجی شده است).

فهرست کردن همه حافظه‌های نهان

می‌توانید همه حافظه‌های نهان صریح دردسترس برای پروژه‌تان را فهرست کنید. این فرمان فقط حافظه‌های پنهان را در مکان مشخص‌شده برمی‌گرداند.

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 یا 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 در فراداده پاسخ ارائه می‌شود.