Buforowanie kontekstu w Firebase AI Logic

W przypadku funkcji AI możesz wielokrotnie przekazywać do modelu te same tokeny wejściowe (treści). W takich przypadkach możesz zapisać w pamięci podręcznej te treści, co oznacza, że przekażesz je do modelu raz, zapiszesz i będziesz się do nich odwoływać w kolejnych żądaniach.

Buforowanie kontekstu może znacznie skrócić czas oczekiwania i obniżyć koszty w przypadku powtarzalnych zadań obejmujących dużą ilość treści, takich jak duże ilości tekstu, plik audio lub plik wideo. Do typowych przypadków użycia buforowanych treści należą szczegółowe dokumenty dotyczące profilu klienta, bazy kodu lub instrukcje.

Modele Gemini oferują 2 różne mechanizmy buforowania:

• Pamięć podręczna niejawna: automatycznie włączona w większości modeli, brak gwarantowanych oszczędności

• Jawne buforowanie: można je opcjonalnie i ręcznie włączyć w większości modeli, co zwykle przynosi oszczędności.

Jawne buforowanie jest przydatne w przypadkach, gdy chcesz zwiększyć prawdopodobieństwo oszczędności, ale wymaga to dodatkowej pracy programisty.

W przypadku buforowania niejawnego i jawnego pole cachedContentTokenCount w metadanych odpowiedzi wskazuje liczbę tokenów w części wejściowej, która została zapisana w pamięci podręcznej. W przypadku jawnego buforowania zapoznaj się z informacjami o cenach u dołu tej strony.

Obsługiwane modele

Pamięć podręczna jest obsługiwana w przypadku tych modeli:

• gemini-3.1-pro-preview
• gemini-3.8-flash (oraz starsze wersje gemini-3.7-flash, gemini-3.6-flash i gemini-3.5-flash)
• gemini-3.5-flash-lite (i starszy gemini-3.1-flash-lite)

Ogólne modele Gemini 2.5 obsługują tę funkcję, ale wszystkie zostały wycofane.

Modele generujące multimedia (np. modele „Nana Banana”, takie jak gemini-3.1-flash-image) nie obsługują pamięci podręcznej kontekstu.

Limity rozmiaru treści w pamięci podręcznej

Każdy model ma minimalną liczbę tokenów wymaganą w przypadku treści zapisanych w pamięci podręcznej. Maksymalna liczba tokenów jest określana przez okno kontekstu modelu.

• Gemini Modele Pro: co najmniej 4096 tokenów
• Gemini Modele Flash: co najmniej 1024 tokeny

Maksymalny rozmiar treści, które możesz buforować za pomocą obiektu blob lub tekstu, to 10 MB.

Niejawne buforowanie

Pamięć podręczna jest domyślnie włączona i dostępna w przypadku większości modeliGemini.

Jeśli Twoje żądanie dotyczy treści w pamięci podręcznej, Google automatycznie przekaże Ci oszczędności. Oto kilka sposobów na zwiększenie prawdopodobieństwa, że żądanie będzie korzystać z pamięci podręcznej typu implicit:

• Spróbuj umieścić na początku prompta duże i popularne treści.
• Wysyłaj żądania z podobnym prefiksem w krótkim czasie.

Liczba tokenów w części wejściowej danych, która jest przechowywana w pamięci podręcznej, jest podana w polu cachedContentTokenCount w metadanych odpowiedzi.

Jawne buforowanie

Jawne buforowanie nie jest domyślnie włączone i jest opcjonalną funkcją modeli Gemini.

Aby skonfigurować pamięć podręczną treści dla dorosłych i z niej korzystać:

• Tworzenie i używanie pamięci podręcznej

• Zarządzaj jawnymi pamięciami podręcznymi, w tym:

  • Wyświetl wszystkie pamięci podręczne

  • Pobieranie metadanych pamięci podręcznej

  • Aktualizowanie czasu życia (TTL) lub czasu wygaśnięcia pamięci podręcznej

  • Usuwanie pamięci podręcznej

Pamiętaj, że pamięć podręczna treści dla dorosłych wchodzi w interakcje z pamięcią podręczną treści domyślnych, co może prowadzić do dodatkowego buforowania poza treściami wyraźnie buforowanymi. Możesz zapobiec przechowywaniu danych w pamięci podręcznej, wyłączając niejawne buforowanie i nie tworząc jawnych pamięci podręcznych. Więcej informacji znajdziesz w artykule Włączanie i wyłączanie buforowania.

Tworzenie i używanie pamięci podręcznej z jawnym określeniem czasu przechowywania

Tworzenie i używanie pamięci podręcznej treści dla dorosłych wymaga spełnienia tych warunków:

1. Utwórz pamięć podręczną z wyraźnym określeniem.

2. Odwołaj się do pamięci podręcznej w szablonie prompta serwera.

3. W żądaniu prompta z aplikacji odwołaj się do szablonu prompta serwera.

Ważne informacje o tworzeniu i używaniu pamięci podręcznej

Pamięć podręczna musi być zgodna z żądaniami promptów w aplikacji i z szablonem promptów na serwerze:

• Pamięć podręczna jest specyficzna dla dostawcy Gemini API. Żądanie prompta w aplikacji musi korzystać z tego samego dostawcy.
  W przypadku Firebase AI Logic zdecydowanie zalecamy używanie pamięci podręcznych treści dla pełnoletnichtylko z Agent Platform Gemini API (formerly Vertex AI). Wszystkie informacje i przykłady na tej stronie dotyczą tego konkretnego dostawcy Gemini API.

• Pamięć podręczna jest przeznaczona dla konkretnego modelu Gemini. Żądanie prompta w aplikacji musi korzystać z tego samego modelu.

• Pamięć podręczna jest specyficzna dla lokalizacji, gdy używasz właściwości Agent Platform Gemini API (formerly Vertex AI).
  Lokalizacja pamięci podręcznej musi być zgodna z lokalizacją szablonu prompta serwera i lokalizacją, w której uzyskujesz dostęp do modelu w żądaniu prompta aplikacji.

Pamiętaj też o tych ograniczeniach i wymaganiach dotyczących jawnego buforowania:

• Po utworzeniu pamięci podręcznej nie można w niej niczego zmieniać, z wyjątkiem czasu życia (TTL) lub czasu wygaśnięcia.

• Możesz zapisać w pamięci podręcznej dowolny obsługiwany typ MIME pliku wejściowego lub nawet sam tekst podany w żądaniu utworzenia pamięci podręcznej.

• Jeśli chcesz uwzględnić plik w pamięci podręcznej, musisz podać go jako identyfikator URI Cloud Storage. Nie może to być adres URL przeglądarki ani adres URL YouTube.

  Dodatkowo ograniczenia dostępu do pliku są sprawdzane w momencie tworzenia pamięci podręcznej, a ograniczenia dostępu nie są ponownie sprawdzane w momencie wysłania żądania przez użytkownika. Z tego powodu upewnij się, że wszystkie dane uwzględnione w pamięci podręcznej są odpowiednie dla każdego użytkownika, który wysyła żądanie zawierające tę pamięć podręczną.

• Jeśli chcesz używać instrukcji lub narzędzi systemowych (takich jak wykonywanie kodu, kontekst adresu URL, ugruntowanie za pomocą Google Search lub ugruntowanie za pomocą Google Maps), pamięć podręczna musi zawierać ich konfiguracje. Nie można ich skonfigurować w szablonie prompta serwera ani w żądaniu prompta aplikacji. Pamiętaj, że szablony promptów serwera nie obsługują jeszcze wywoływania funkcji (ani czatu). Szczegółowe informacje o konfigurowaniu instrukcji systemowych i narzędzi w pamięci podręcznej znajdziesz w interfejsie REST API usługi Agent Platform Gemini API (formerly Vertex AI).

Krok 1. Utwórz pamięć podręczną

Utwórz pamięć podręczną, korzystając bezpośrednio z interfejsu API REST usługi Agent Platform Gemini API (formerly Vertex AI).

Poniżej znajdziesz przykład tworzenia jawnej pamięci podręcznej pliku PDF jako jego zawartości.

Składnia:

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

Przykładowe żądanie:

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

Przykładowa odpowiedź:

Odpowiedź zawiera w pełni kwalifikowany zasób name, który jest globalnie unikalny dla pamięci podręcznej (pamiętaj, że ostatni segment to identyfikator pamięci podręcznej). W następnym kroku procesu użyjesz całej wartości 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"
}

Krok 2. Odwołaj się do pamięci podręcznej w szablonie promptu serwera

Po utworzeniu pamięci podręcznej odwołaj się do niej za pomocą symbolu name w cachedContent właściwości szablonu prośby do serwera.

Podczas tworzenia szablonu promptu serwera przestrzegaj tych wymagań:

• Podczas tworzenia pamięci podręcznej użyj w odpowiedzi w pełni kwalifikowanego zasobu name. To nie jest opcjonalna wyświetlana nazwa podana w żądaniu.

• Lokalizacja szablonu promptu serwera musi być zgodna z lokalizacją pamięci podręcznej.

• Aby używać instrukcji lub narzędzi systemowych, musisz je skonfigurować jako część pamięci podręcznej, a nie jako część szablonu promptu serwera.

Składnia:

{{cachedContent name="YOUR_CACHE_RESOURCE_NAME"}}

{{role "user"}}
{{userPrompt}}

Przykład:

{{cachedContent name="projects/861083271981/locations/global/cachedContents/4545031458888089601"}}

{{role "user"}}
{{userPrompt}}

Wartość parametru name w szablonie promptu serwera może być też dynamiczną zmienną wejściową. Na przykład {{cachedContent name=someVariable}} umożliwia uwzględnienie name pamięci podręcznej jako danych wejściowych żądania z aplikacji.

Krok 3. W żądaniu z aplikacji odwołaj się do szablonu prompta serwera.

Podczas pisania prośby zachowaj szczególną ostrożność w tych kwestiach:

• Użyj Agent Platform Gemini API (formerly Vertex AI), ponieważ pamięć podręczna została utworzona za pomocą tego dostawcy Gemini API.

• Lokalizacja, w której uzyskujesz dostęp do modelu w żądaniu prompta w aplikacji, musi być zgodna z lokalizacją szablonu prompta serwera i pamięci podręcznej.

// ...

// 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")

// ...

// 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)

// ...

// 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);

// ...

// 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.
  'TEMPLATE_ID'
);

const response = result.response;
const text = response.text();

// ...

// 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',
      );

var text = response?.text;
print(text);

// ...

// 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"
  );
  Debug.Log($"Response Text: {response.Text}");
}
catch (Exception e) {
  Debug.LogError($"An error occurred: {e.Message}");
}

Zarządzanie pamięciami podręcznymi

W tej sekcji opisujemy zarządzanie pamięcią podręczną treści dla dorosłych, w tym jak wyświetlić listę wszystkich pamięci podręcznych, pobrać metadane pamięci podręcznej, zaktualizować czas TTL lub czas wygaśnięcia pamięci podręcznej i usunąć pamięć podręczną.

Jawnie zarządzasz pamięcią podręczną za pomocą interfejsu REST API usługi Agent Platform Gemini API (formerly Vertex AI).

Po utworzeniu pamięci podręcznej treści dla dorosłych nie można w niej niczego zmienić oprócz czasu życia (TTL) lub czasu wygaśnięcia.

Wyświetl listę wszystkich pamięci podręcznych

Możesz wyświetlić listę wszystkich pamięci podręcznych dostępnych w Twoim projekcie. To polecenie zwróci tylko pamięci podręczne w podanej lokalizacji.

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

Pobieranie metadanych pamięci podręcznej

Nie można pobrać ani wyświetlić rzeczywistej zawartości z pamięci podręcznej. Możesz jednak pobrać metadane dotyczące pamięci podręcznej, w tym name, model, display_name, usage_metadata, create_time, update_time i expire_time.

Musisz podać CACHE_ID, czyli ostatni segment w name w pełni kwalifikowanej nazwie zasobu pamięci podręcznej.

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}

Aktualizowanie czasu TTL lub czasu wygaśnięcia pamięci podręcznej

Podczas tworzenia pamięci podręcznej możesz opcjonalnie ustawić ttl lub expire_time.

• ttl: czas życia danych (TTL) w pamięci podręcznej, a konkretnie liczba sekund i nanosekund, przez które pamięć podręczna jest aktywna po utworzeniu lub po zaktualizowaniu ttl, zanim wygaśnie. Gdy ustawisz ttl, expireTime pamięci podręcznej zostanie automatycznie zaktualizowany.

• expire_time: Timestamp (np. 2024-06-30T09:00:00.000000Z), która określa bezwzględną datę i godzinę wygaśnięcia pamięci podręcznej.

Jeśli nie ustawisz żadnej z tych wartości, domyślny czas TTL to 1 godzina. Nie ma minimalnych ani maksymalnych ograniczeń dotyczących wartości TTL.

W przypadku istniejących pamięci podręcznych możesz dodać lub zaktualizować ttl lub expire_time. Musisz podać CACHE_ID, czyli ostatni segment w name w pełni kwalifikowanej nazwie zasobu pamięci podręcznej.

Aktualizacjattl

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

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

Usuwanie pamięci podręcznej

Gdy pamięć podręczna nie jest już potrzebna, możesz ją usunąć.

Musisz podać CACHE_ID, czyli ostatni segment w name w pełni kwalifikowanej nazwie zasobu pamięci podręcznej.

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}

Ceny jawnego buforowania

Jawne zapisywanie w pamięci podręcznej to płatna funkcja, która ma na celu zmniejszenie kosztów. Ceny zależą od tych czynników:

• Tokeny wejściowe do tworzenia pamięci podręcznej: w przypadku automatycznego i jawnego buforowania opłaty są naliczane za tokeny wejściowe użyte do utworzenia pamięci podręcznej według standardowej ceny tokenów wejściowych.

• Przechowywanie pamięci podręcznej: w przypadku jawnego buforowania występują też koszty przechowywania zależne od czasu przechowywania pamięci podręcznych. W przypadku buforowania niejawnego nie ma opłat za miejsce na dane. Więcej informacji znajdziesz w cenniku Agent Platform Gemini API (formerly Vertex AI).

• Korzystanie z treści w pamięci podręcznej: jawne buforowanie zapewnia zniżkę, gdy odwołujesz się do jawnych pamięci podręcznych. Oznacza to, że otrzymujesz zniżkę na tokeny wejściowe, gdy odwołują się one do istniejącej pamięci podręcznej. W przypadku modeli Gemini 2.5 i nowszych zniżka wynosi 90%.

Liczba tokenów w części wejściowej danych, która jest przechowywana w pamięci podręcznej, jest podana w polu cachedContentTokenCount w metadanych odpowiedzi.