Buforowanie kontekstu w Firebase AI Logic

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

Zapisywanie w pamięci podręcznej kontekstu może znacznie zmniejszyć opóźnienie i koszty 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 treści zapisanych w pamięci podręcznej należą szczegółowe dokumenty dotyczące person, bazy kodu lub instrukcje.

Gemini modele oferują 2 różne mechanizmy zapisywania w pamięci podręcznej:

• Niejawne zapisywanie w pamięci podręcznej: automatycznie włączone w przypadku większości modeli, bez gwarancji oszczędności kosztów.

• Jawne zapisywanie w pamięci podręcznej: można je opcjonalnie i ręcznie włączyć w przypadku większości modeli, zwykle prowadzi do oszczędności kosztów.

Jawne zapisywanie w pamięci podręcznej jest przydatne w przypadkach, gdy chcesz z większym prawdopodobieństwem zagwarantować oszczędności kosztów, ale wymaga to dodatkowej pracy dewelopera.

W przypadku niejawnego i jawnego zapisywania w pamięci podręcznej pole cachedContentTokenCount w metadanych odpowiedzi wskazuje liczbę tokenów w części wejściowej zapisanej w pamięci podręcznej. W przypadku jawnego zapisywania w pamięci podręcznej zapoznaj się z informacjami o cenach u dołu tej strony.

Obsługiwane modele

Zapisywanie w pamięci podręcznej jest obsługiwane w przypadku tych modeli:

• gemini-3.1-pro-preview
• gemini-3-flash-preview
• gemini-3.1-flash-lite
• gemini-2.5-pro
• gemini-2.5-flash
• gemini-2.5-flash-lite

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

Limity rozmiaru treści zapisanych 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żna zapisać w pamięci podręcznej za pomocą bloba lub tekstu, to 10 MB.

Niejawne zapisywanie w pamięci podręcznej

Niejawne zapisywanie w pamięci podręcznej jest domyślnie włączone i dostępne w przypadku większości Gemini modeli.

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

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

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

Jawne zapisywanie w pamięci podręcznej

Jawne zapisywanie w pamięci podręcznej nie jest domyślnie włączone i jest opcjonalną funkcją modeli Gemini.

Oto jak skonfigurować jawne pamięci podręczne treści i z nich korzystać:

• Utwórz, a następnie użyj jawnej pamięci podręcznej

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

  • Wyświetlanie listy wszystkich pamięci podręcznych

  • Pobieranie metadanych pamięci podręcznej

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

  • Usuwanie pamięci podręcznej

Pamiętaj, że jawne pamięci podręczne treści współdziałają z niejawnym zapisywaniem w pamięci podręcznej, co może prowadzić do dodatkowego zapisywania w pamięci podręcznej poza jawnymi treściami. Możesz zapobiec przechowywaniu danych w pamięci podręcznej, wyłączając niejawne zapisywanie w pamięci podręcznej i nie tworząc jawnych pamięci podręcznych. Więcej informacji znajdziesz w artykule Włączanie i wyłączanie zapisywania w pamięci podręcznej.

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

Aby utworzyć i używać jawnej pamięci podręcznej treści, musisz wykonać te czynności:

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

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

3. Odwołaj się do szablonu promptu serwera w żądaniu promptu 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 promptu serwera:

• Pamięć podręczna jest specyficzna dla dostawcy Gemini API. Żądanie promptu aplikacji musi korzystać z tego samego dostawcy.
  W przypadku Firebase AI Logic, zdecydowanie zalecamy używanie jawnych pamięci podręcznych treści tylko z Vertex AI Gemini API. Wszystkie informacje i przykłady na tej stronie dotyczą tego Gemini API dostawcy.

• Pamięć podręczna jest specyficzna dla modelu Gemini. Żądanie promptu aplikacji musi korzystać z tego samego modelu.

• Pamięć podręczna jest specyficzna dla lokalizacji, gdy używasz interfejsu Vertex AI Gemini API.
  Lokalizacja jawnej pamięci podręcznej musi być zgodna z lokalizacją szablonu promptu serwera i lokalizacją, w której uzyskujesz dostęp do modelu w żądaniu promptu aplikacji.

Pamiętaj też o tych ograniczeniach i wymaganiach dotyczących jawnego zapisywania w pamięci podręcznej:

• Po utworzeniu jawnej pamięci podręcznej nie możesz zmienić niczego poza czasem życia danych (TTL) lub czasem wygaśnięcia.

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

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

  Dodatkowo ograniczenia dostępu do pliku są sprawdzane podczas tworzenia pamięci podręcznej, a ograniczenia dostępu nie są sprawdzane ponownie w momencie żądania użytkownika. Z tego powodu upewnij się, że wszystkie dane uwzględnione 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 lub Grounding z Google Search), sama 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 interfejsu Vertex AI Gemini API.

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

Utwórz pamięć podręczną, korzystając bezpośrednio z interfejsu REST API Vertex AI Gemini API.

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

Składnia:

PROJECT_ID="PROJECT_ID"
MODEL_ID="GEMINI_MODEL"  # for example, gemini-3-flash-preview
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-flash-preview"
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 kwalifikowaną nazwę zasobu name, która jest globalnie unikalna dla pamięci podręcznej (pamiętaj, że ostatni segment to identyfikator pamięci podręcznej). W następnym kroku przepływu pracy 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-flash-preview",
  "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 promptu serwera .

Podczas tworzenia szablonu promptu serwera przestrzegaj tych wymagań:

• Użyj w pełni kwalifikowanej nazwy zasobu name z odpowiedzi, gdy utworzysz pamięć podręczną. Nie jest to opcjonalna nazwa wyświetlana, którą podajesz w żądaniu.

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

• Aby używać instrukcji systemowych lub narzędzi, 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}}

Alternatywnie wartość parametru name w szablonie promptu serwera może być 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. Odwołaj się do szablonu promptu serwera w żądaniu z aplikacji

Podczas pisania żądania zachowaj szczególną ostrożność:

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

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

// ...

// Initialize the Vertex AI Gemini API backend service
// Create a `TemplateGenerativeModel` instance
// Make sure to specify the same location as the server prompt template and the cache
let model = FirebaseAI.firebaseAI(backend: .vertexAI(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 Vertex AI Gemini API backend service
// 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.vertexAI(location = "LOCATION"))
                        .templateGenerativeModel()

val response = model.generateContent(
    // Specify your template ID
    "TEMPLATE_ID",
)

val text = response.text
println(text)

// ...

// Initialize the Vertex AI Gemini API backend service
// Create a `TemplateGenerativeModel` instance
// Make sure to specify the same location as the server prompt template and the cache
TemplateGenerativeModel generativeModel = FirebaseAI.getInstance().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 Vertex AI Gemini API backend service
// Make sure to specify the same location as the server prompt template and the cache
const ai = getAI(app, { backend: new VertexAIBackend('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 Vertex AI Gemini API backend service
// Create a `TemplateGenerativeModel` instance
// Make sure to specify the same location as the server prompt template and the cache
var _model = FirebaseAI.vertexAI(location: 'LOCATION').templateGenerativeModel()

var response = await _model.generateContent(
        // Specify your template ID
        'TEMPLATE_ID',
      );

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

// ...

// Initialize the Vertex AI Gemini API backend service
// Make sure to specify the same location as the server prompt template and the cache
var firebaseAI = FirebaseAI.GetInstance(FirebaseAI.Backend.VertexAI(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 jawnymi pamięciami podręcznymi

W tej sekcji opisujemy zarządzanie jawnymi pamięciami podręcznymi treści, w tym sposób wyświetlania listy wszystkich pamięci podręcznych, pobierania metadanych pamięci podręcznej, aktualizowania czasu życia danych (TTL) lub czasu wygaśnięcia pamięci podręcznej oraz usuwania pamięci podręcznej.

Jawnymi pamięciami podręcznymi zarządzasz za pomocą interfejsu REST API Vertex AI Gemini API.

Po utworzeniu jawnej pamięci podręcznej treści nie możesz zmienić niczego poza czasem życia danych (TTL) lub czasem 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 Twoim 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ć rzeczywistych treści zapisanych w pamięci podręcznej. Możesz jednak pobrać metadane 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łni kwalifikowanej 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 życia danych (TTL) lub czasu wygaśnięcia pamięci podręcznej

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

• ttl: czas życia danych (TTL) pamięci podręcznej, czyli liczba sekund i nanosekund, przez które pamięć podręczna jest aktywna po jej utworzeniu lub po zaktualizowaniu ttl przed wygaśnięciem. 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 absolutną datę i godzinę wygaśnięcia pamięci podręcznej.

Jeśli nie ustawisz żadnej z tych wartości, domyślny czas życia danych (TTL) to 1 godzina. Nie ma minimalnych ani maksymalnych ograniczeń czasu życia danych (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łni kwalifikowanej nazwie zasobu name pamięci podręcznej.

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

Aktualizowanie 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łni kwalifikowanej 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 zapisywania w pamięci podręcznej

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 niejawnego i jawnego zapisywania w pamięci podręcznej opłata jest naliczana za tokeny wejściowe użyte do utworzenia pamięci podręcznej według standardowej ceny tokena wejściowego.

• Przechowywanie pamięci podręcznej: w przypadku jawnego zapisywania w pamięci podręcznej obowiązują też koszty przechowywania zależne od czasu przechowywania pamięci podręcznych. W przypadku niejawnego zapisywania w pamięci podręcznej nie ma kosztów przechowywania. Więcej informacji znajdziesz w cenniku Vertex AI Gemini API.

• Używanie treści zapisanych w pamięci podręcznej: jawne zapisywanie w pamięci podręcznej zapewnia zniżkę, gdy odwołujesz się do jawnych pamięci podręcznych, co oznacza, że otrzymujesz zniżkę na tokeny wejściowe, gdy odwołują się do istniejącej pamięci podręcznej. W przypadku modeli Gemini 2.5 i nowszych, ta zniżka wynosi 90%.

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