Buforowanie kontekstu w Firebase AI Logic

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

Pamięć podręczna kontekstu może znacznie zmniejszyć czas oczekiwania i koszty w przypadku powtarzających się zadań, które obejmują dużą ilość treści, takich jak duże ilości tekstu, plik audio lub plik wideo. Do typowych przypadków użycia treści zapisanych w pamięci podręcznej należą szczegółowe dokumenty dotyczące profilu klienta, bazy kodu lub instrukcje.

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

  • Niejawne buforowanie: automatycznie włączone w większości modeli, brak gwarancji oszczędności kosztów.

  • Jawne buforowanie: można opcjonalnie i ręcznie włączyć w przypadku większości modeli, co zwykle pozwala obniżyć koszty.

Jawne buforowanie jest przydatne, gdy chcesz mieć większą pewność, że zaoszczędzisz, ale wymaga to dodatkowej pracy programisty.

Zarówno w przypadku niejawnego, jak i jawnego buforowania pole cachedContentTokenCount w metadanych odpowiedzi wskazuje liczbę tokenów w buforowanej części danych wejściowych. W przypadku jawnego buforowania zapoznaj się z informacjami o cenach na dole tej strony.

Obsługiwane modele

Buforowanie jest obsługiwane w przypadku tych modeli:

  • gemini-4-argon (tylko niejawne zapisywanie w pamięci podręcznej; jawne zapisywanie w pamięci podręcznej nie jest obsługiwane)
  • gemini-3.8-flash
  • gemini-3.5-flash-lite (oraz starszy model gemini-3.1-flash-lite)

Starsze modele Gemini 3.x Flash ogólnego zastosowania obsługują tę funkcję, ale nie zalecamy już ich używania ze względu na zbliżające się daty wyłączenia lub automatyczne przekierowywanie do nowszych modeli.

Modele generujące multimedia (np. modele Gemini Nano Banana, takie jak gemini-nano-banana-2.1) 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ą do zapisania treści w pamięci podręcznej. Maksymalna wartość jest określana przez okno kontekstu modelu.

  • Gemini 4 Argon: co najmniej 4096 tokenów (Gemini Developer API) lub co najmniej 6144 tokeny (Agent Platform Gemini API (formerly Vertex AI))
  • Modele Gemini Pro: co najmniej 4096 tokenów
  • Modele Gemini Flash: co najmniej 1024 tokeny

Dodatkowo maksymalny rozmiar treści, które można zapisać w pamięci podręcznej za pomocą obiektu blob lub tekstu, wynosi 10 MB.


Automatyczne buforowanie

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

Google automatycznie przekazuje oszczędności, jeśli żądanie trafi do treści z pamięci podręcznej. Oto kilka sposobów na zwiększenie prawdopodobieństwa, że żądanie będzie korzystać z niejawnego buforowania:

  • Spróbuj umieścić duże i często używane treści na początku prompta.
  • Spróbuj wysłać żądania z podobnym prefiksem w krótkim czasie.

Liczba tokenów w zapisanej w pamięci podręcznej części danych wejściowych jest podana w polu cachedContentTokenCount w metadanych odpowiedzi.


Jawne buforowanie

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

Pamiętaj, że model gemini-4-argon nie obsługuje jawnego buforowania.

Aby skonfigurować pamięci podręczne treści dla pełnoletnich i z nimi pracować:

Pamiętaj, że pamięci podręczne treści jawnych współdziałają z pamięcią podręczną treści niejawnych, co może prowadzić do dodatkowego buforowania poza treściami jawnymi. 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 o włączaniu i wyłączaniu buforowania.


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

Tworzenie i używanie jawnej pamięci podręcznej treści wymaga:

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

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

  3. Odwołaj się do szablonu prompta serwera w żądaniu prompta z aplikacji.

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

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

  • Pamięć podręczna jest powiązana z dostawcą Gemini API. Prośba o prompt w aplikacji musi używać tego samego dostawcy.
    W przypadku Firebase AI Logic zdecydowanie zalecamy używanie jawnych pamięci podręcznych treści tylko z Agent Platform Gemini API (formerly Vertex AI). Wszystkie informacje i przykłady na tej stronie dotyczą tego dostawcy (Gemini API).

  • Pamięć podręczna jest powiązana z modelem Gemini. Żądanie prompta aplikacji musi używać tego samego modelu.

  • Pamięć podręczna jest powiązana z lokalizacją, gdy używasz Agent Platform Gemini API (formerly Vertex AI).
    Lokalizacja jawnej 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 jawnej pamięci podręcznej nie można w niej niczego zmienić oprócz czasu TTL lub czasu ważności.

  • Możesz zapisać w pamięci podręcznej dowolny obsługiwany typ MIME pliku wejściowego, a 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 YouTube.

    Dodatkowo ograniczenia dostępu do pliku są sprawdzane w czasie tworzenia pamięci podręcznej, a nie w czasie żądania użytkownika. Z tego powodu upewnij się, że wszystkie dane zawarte w jawnej 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 systemowych lub narzędzi (takich jak wykonywanie kodu, kontekst adresu URL, Grounding with Google Search lub Grounding with Google Maps), pamięć podręczna musi zawierać ich konfiguracje. Nie można ich skonfigurować w szablonie promptu serwera ani w żądaniu promptu 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 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, który tworzy jawną pamięć podręczną pliku PDF jako jego zawartość.

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 pełny 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ą name we właściwości cachedContent szablonu prompta serwera.

Podczas tworzenia szablonu promptu serwera przestrzegaj tych wymagań:

  • Użyj w pełni kwalifikowanej nazwy zasobu name z odpowiedzi otrzymanej podczas tworzenia pamięci podręcznej. Nie jest to opcjonalna wyświetlana nazwa podana w żądaniu.

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

  • Aby korzystać z instrukcji systemowych lub narzędzi, musisz je skonfigurować jako część pamięci podręcznej, a nie jako część szablonu prompta 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 też być dynamiczną zmienną wejściową. Na przykład {{cachedContent name=someVariable}} pozwala uwzględnić name pamięci podręcznej jako dane wejściowe żądania z aplikacji.

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

Podczas pisania prośby zwróć szczególną uwagę na te kwestie:

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

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

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


Zarządzanie pamięciami podręcznymi

W tej sekcji opisano zarządzanie jawnymi pamięciami podręcznymi treści, w tym wyświetlanie listy wszystkich pamięci podręcznych, pobieranie metadanych o pamięci podręcznej, aktualizowanie czasu TTL lub czasu ważności pamięci podręcznej oraz usuwanie pamięci podręcznej.

Pamięciami podręcznymi zarządzasz za pomocą interfejsu API typu REST usługi Agent Platform Gemini API (formerly Vertex AI).

Po utworzeniu jawnej pamięci podręcznej treści nie można w niej niczego zmienić oprócz czasu TTL lub czasu wygaśnięcia.

Wyświetlanie listy wszystkich pamięci podręcznych

Możesz wyświetlić listę wszystkich jawnych pamięci podręcznych dostępnych w projekcie. To polecenie zwróci tylko pamięci podręczne w określonej 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 jawnej 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 pełnej nazwie zasobu name 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 ważności pamięci podręcznej

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

  • ttl: czas życia danych (TTL) w pamięci podręcznej, czyli 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óry 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 będzie wynosić 1 godzinę. Nie ma minimalnych ani maksymalnych wartości TTL.

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

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

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

Usuwanie pamięci podręcznej

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

Musisz podać CACHE_ID, czyli ostatni segment w pełnej nazwie zasobu name 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 buforowanie to płatna funkcja, która pozwala obniżyć koszty. Ceny zależą od tych czynników:

  • Tokeny wejściowe do tworzenia pamięci podręcznej: zarówno w przypadku automatycznego, jak i ręcznego zapisywania w pamięci podręcznej, opłata za tokeny wejściowe używane do tworzenia pamięci podręcznej jest naliczana według standardowej ceny tokena wejściowego.

  • Przechowywanie pamięci podręcznej: w przypadku jawnego buforowania obowiązują też koszty przechowywania, które zależą od tego, jak długo pamięć podręczna jest przechowywana. Nie ma opłat za miejsce na dane w przypadku niejawnego buforowania. Więcej informacji znajdziesz w cenniku Agent Platform Gemini API (formerly Vertex AI).

  • Korzystanie z treści z pamięci podręcznej: jawne buforowanie zapewnia rabat, gdy odwołujesz się do jawnej pamięci podręcznej, co oznacza, że otrzymujesz rabat 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 zapisanej w pamięci podręcznej części danych wejściowych jest podana w polu cachedContentTokenCount w metadanych odpowiedzi.