Buforowanie kontekstu w Firebase AI Logic

W przypadku funkcji opartych na AI możesz wielokrotnie przekazywać do modelu te same tokeny wejściowe (treści). W takich przypadkach użycia 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 zmniejszyć opóźnienia i 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 gwarancji oszczędności kosztów.

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

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 buforowanej części danych wejściowych. 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-flash-preview
• gemini-3.1-flash-lite-preview
• 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ą buforowania kontekstu.

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

Każdy model ma minimalną liczbę tokenów wymaganą w przypadku treści w pamięci podręcznej. Maksymalna liczba 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 niejawnej:

• Spróbuj umieścić na początku promptu duże i powszechne treści.
• Spróbuj wysyłać żą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 jest domyślnie wyłączone i jest opcjonalną funkcją modeli Gemini.

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

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

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

  • Wyświetlanie wszystkich pamięci podręcznych

  • 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 jawnych wchodzi w interakcję z pamięcią podręczną treści niejawnych, co może prowadzić do dodatkowego buforowania poza treściami jawnie 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 zapisem

Aby utworzyć i używać pamięci podręcznej treści dla dorosłych, musisz spełnić te wymagania:

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

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

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

• 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 Vertex AI Gemini API. Wszystkie informacje i przykłady na tej stronie dotyczą tego dostawcy Gemini API.

• Pamięć podręczna jest powiązana z konkretnym modelem Gemini. Żądanie prompta w aplikacji musi korzystać z tego samego modelu.

• Pamięć podręczna jest specyficzna dla lokalizacji, gdy używasz Vertex AI Gemini API.
  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żesz w niej niczego zmienić, 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 czy oparcie na faktach za pomocą wyszukiwarki Google), 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 API REST Vertex AI Gemini API.

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

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

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-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ładowa prośba:

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 pełny i jednoznaczny identyfikator zasobu name, który jest unikalny w skali globalnej w przypadku 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-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ą symbolu name we właściwości cachedContent szablonu promptu serwera.

Podczas tworzenia szablonu prompta 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, którą podano 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 Vertex AI Gemini API, 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 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 pamięciami podręcznymi

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

Jawne pamięci podręczne są zarządzane za pomocą interfejsu API REST usługi Vertex AI Gemini API.

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świetlanie listy 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 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 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 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 czasu życia.

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 pełnej nazwie zasobu name 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 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

Buforowanie jawne to funkcja płatna, 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 buforowania niejawnego i jawnego opłata jest naliczana 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ęcznej. W przypadku buforowania niejawnego nie ma kosztów pamięci masowej. Więcej informacji znajdziesz w cenniku Vertex AI Gemini API.

• Korzystanie z treści w pamięci podręcznej: jawne buforowanie zapewnia zniżkę, gdy odwołania są kierowane 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.