> ## Documentation Index
> Fetch the complete documentation index at: https://gomodel.enterpilot.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Cache

> Jak działa cache odpowiedzi w GoModel, jak włączyć warstwy cache'u dokładnego i semantycznego oraz co wchodzi w skład klucza cache'u dokładnego.

## Przegląd

GoModel ma dwie warstwy cache'u odpowiedzi dla requestów streamingowych
i niestreamingowych na:

* `/v1/chat/completions`
* `/v1/responses`
* `/v1/messages`
* `/v1/embeddings`
* `/v1/systemone` (oraz `/permute` i `/separate` Keva)

Streamingowe i niestreamingowe warianty tego samego requestu są cache'owane
niezależnie: streamingowy cache miss zapisuje surowe bajty SSE, a streamingowy
cache hit odtwarza je bez zmian jako `text/event-stream`.

Cache dokładnego dopasowania zwraca identyczne co do bajtu odpowiedzi z:

```http theme={null}
X-Cache: HIT (exact)
```

Cache semantyczny używa embeddingów i wyszukiwania wektorowego, dzięki czemu prompty
o równoważnym znaczeniu mogą ponownie wykorzystać zapisaną odpowiedź:

```http theme={null}
X-Cache: HIT (semantic)
```

> [!NOTE]
>
> `/v1/embeddings` korzysta tylko z cache'u dokładnego. Embedding musi
> reprezentować dokładnie ten tekst, dla którego go zażądano, więc odtworzenie
> wektora jedynie podobnego wejścia byłoby błędną odpowiedzią, a nie równoważną.
> Requesty embeddingów nigdy nie są też streamowane, więc cache'owana jest tylko
> odpowiedź JSON. To samo dotyczy decyzji [System One](https://gomodel.enterpilot.io/docs/pl/advanced/systemone-api.md#cache):
> podobny stan to nie ta sama decyzja.

## Włącz cache dokładny

Skieruj cache odpowiedzi na Redisa:

```yaml theme={null}
cache:
  response:
    simple:
      redis:
        url: redis://localhost:6379
        ttl: 3600
```

Możesz go też skonfigurować zmiennymi środowiskowymi:

* `REDIS_URL`
* `REDIS_KEY_RESPONSES`
* `REDIS_TTL_RESPONSES`

## Włącz cache semantyczny

Dodaj blok `semantic` z providerem embeddera i bazą wektorową:

```yaml theme={null}
cache:
  response:
    semantic:
      enabled: true
      embedder:
        provider: openai
      vector_store:
        type: qdrant
        qdrant:
          url: http://localhost:6333
          collection: gomodel_semantic
```

Obsługiwane bazy wektorowe:

* `qdrant`
* `pgvector`
* `pinecone`
* `weaviate`

Obie warstwy cache'u działają po modyfikacjach wprowadzonych przez workflow i guardrails,
więc operują na końcowym requeście wysyłanym do upstreamu. Użyj
`Cache-Control: no-cache` lub `Cache-Control: no-store`, aby pominąć cache dla
pojedynczego requestu. [Plugin](https://gomodel.enterpilot.io/docs/pl/advanced/plugins.md#decyzje) może też wykluczyć
jedną odpowiedź z obu warstw, ustawiając `NoStore` w swojej decyzji – korzysta
z tego guardrail, który przywraca do odpowiedzi dane specyficzne dla requestu, aby
przywrócony tekst nigdy nie został odtworzony innemu wywołującemu. Request
`background: true` na
[`/v1/responses`](https://gomodel.enterpilot.io/docs/pl/advanced/responses-api#odpowiedzi-w-tle) także pomija obie
warstwy: jego body `queued` zawiera id należące do odpowiedzi jednego wywołującego.

Pełny projekt cache'u semantycznego i opcje przechowywania opisuje
[ADR-0006](https://gomodel.enterpilot.io/docs/adr/0006-semantic-response-cache).

## Na czym opiera się klucz cache'u dokładnego

Cache dokładny hashuje:

* ścieżkę requestu
* rozwiązany kontekst workflow użyty do wykonania,
  konkretnie tryb wykonania, typ providera i rozwiązany model
* łańcuch guardrails, do którego rozwiązuje się request, w fazach promptu,
  odpowiedzi i strumienia
* końcowe body requestu

Oznacza to, że guardrails i workflow wpływają na klucze cache'u, gdy zmieniają
rozwiązany workflow lub końcowe body przekazywane do wykonania.

Cache hit odtwarza zapisaną odpowiedź bez ponownego uruchamiania łańcuchów guardrails
odpowiedzi i strumienia, więc wpis jest zwracany tylko requestowi, którego łańcuch
jest zgodny z tym, który go wytworzył. Edycja, dodanie lub usunięcie kroku guardraila
– albo drugi workflow z innym łańcuchem – daje cache miss zamiast odpowiedzi, której
te guardrails nigdy nie widziały. Zmiana konfiguracji guardrails unieważnia więc
wpisy zapisane pod starym łańcuchem.

Kolejność pól obiektów JSON i nieistotne białe znaki są kanonizowane przed
hashowaniem. Requesty różniące się tylko formatowaniem współdzielą więc jeden wpis
cache'u dokładnego. Równoczesne identyczne cache missy są też łączone w obrębie
procesu: jeden request trafia do providera, a oczekujące requesty odtwarzają jego
odpowiedź. Odpowiedzi zakończone błędem lub z innych powodów niecache'owalne nigdy
nie są rozsyłane do oczekujących.

## Planowanie prompt cache u providera

Gdy routing ustali konkretnego providera i model, GoModel dodaje plan cache'owania,
jeśli stały prefiks spełnia minimalny rozmiar wymagany przez tego providera, a klient
nie przekazał już własnej dyrektywy cache:

* OpenAI otrzymuje stały `prompt_cache_key`; modele obsługujące jawne cache'owanie
  otrzymują też breakpoint i jawny tryb cache.
* Anthropic otrzymuje automatyczne cache'owanie ephemeral na najwyższym poziomie.
* Amazon Bedrock Converse otrzymuje cache point po stałym prefiksie.
* Natywne Gemini AI Studio tworzy i ponownie wykorzystuje pięciominutowy obiekt
  cached content; równoczesne tworzenie jest łączone według prefiksu i stałych
  danych uwierzytelniających.

Plan jest stosowany po routingu, więc pola specyficzne dla providera nie mogą wyciec
przez fallback do innego backendu. Klucze cache'u obejmują konkretną instancję
providera i model, a kontrolki cache przekazane przez wywołującego zawsze mają
pierwszeństwo.

Planowanie prompt cache u providera jest domyślnie włączone. Aby wyłączyć
automatyczne planowanie GoModel i nadal przekazywać kompatybilne dyrektywy cache
klienta, ustaw:

```bash theme={null}
PROVIDER_PROMPT_CACHE_PLANNER_ENABLED=false
```

Flaga akceptuje wartości logiczne w formacie Go. Brakujące, puste lub nieprawidłowe
wartości zachowują bezpieczną wartość domyślną (`true`), a nieprawidłowa wartość
generuje ostrzeżenie przy starcie.

## Zachowanie `user_path`

W cache'u dokładnym `user_path` sam w sobie nie jest dodawany do klucza cache'u.

To zamierzone. Jeśli dwa requesty mają tę samą ścieżkę, rozwiązany workflow
i końcowe body requestu, mogą współdzielić ten sam wpis cache'u dokładnego,
nawet jeśli pochodzą z różnych wartości `user_path`.

> [!NOTE]
>
> Jeśli potrzebujesz zachowania cache'u specyficznego dla tenanta lub ścieżki, użyj
> workflow z zakresem albo w inny sposób spraw, by końcowy request różnił się dla tego
> zakresu. Sam `user_path` nie jest kluczem partycjonowania cache'u dokładnego.

Typowe wzorce:

* wyłącz cache w workflow z zakresem
* używaj różnych workflow z zakresem dla różnych wartości `user_path`
* dołącz kontekst specyficzny dla zakresu, aby końcowe body requestu się różniło

## Odpowiedzi obsłużone przez failover nie są cache'owane

Gdy na request odpowiada cel [failoveru](https://gomodel.enterpilot.io/docs/pl/features/failover.md), a nie ten, który
routing wybrał jako pierwszy, odpowiedź nie jest zapisywana. Klucz cache'u dokładnego
jest hashowany z rozwiązania sprzed failoveru, więc zapisanie odpowiedzi zapasowego
celu powodowałoby jej zwracanie pod kluczem celu głównego, gdy ten wróci do działania.

Praktyczna konsekwencja: model wirtualny, którego pierwszy cel jest chronicznie
niedostępny, przestaje gromadzić wpisy w cache'u tak długo, jak ten cel nie działa –
każdy request z cache missem przechodzi failover i jest obsługiwany na świeżo, a nic,
co wytworzy, nie jest zapisywane. Wpisy zapisane przed awarią są zwracane aż do
wygaśnięcia ich TTL: wyszukiwanie w cache'u odbywa się przed wysłaniem, więc cache hit
jest zwracany bez angażowania żadnego z celów. Jeśli cel ma być niedostępny przez
dłuższy czas, zmień kolejność łańcucha (lub wskaż w modelu wirtualnym sprawny cel),
aby odpowiedzi na niego znów mogły trafiać do cache'u.

Retry w obrębie jednego celu nie są tym objęte: z obu warstw cache'u wykluczana jest
tylko odpowiedź wytworzona po tym, jak przeszukiwanie przeszło do innego celu.

## Analityka cache'u

Gdy cache odpowiedzi i śledzenie użycia są włączone, Admin API udostępnia przegląd
obejmujący tylko odpowiedzi z cache'u pod:

```text theme={null}
/admin/cache/overview
```

Cache hity są też zapisywane jako wpisy użycia, z `user_path` wywołującego
i `cache_type` równym `exact` lub `semantic`. Endpointy użycia
(`/admin/usage/*` i `/v1/usage`) domyślnie je pomijają, aby sumy i koszty
odzwierciedlały wydatki u providerów; przekaż `cache_mode=all`, aby je uwzględnić,
lub `cache_mode=cached`, aby zobaczyć tylko cache hity. Wyjątkiem jest
`/admin/usage/sessions`: sumy requestów i tokenów sesji zawsze obejmują cache hity,
a jego pola kosztów pozostają ograniczone do providerów.

```bash theme={null}
# tylko requesty kierowane do providerów (domyślnie)
curl "http://localhost:8080/admin/usage/summary?user_path=/team/alpha" \
  -H "Authorization: Bearer $GOMODEL_MASTER_KEY"

# z uwzględnieniem lokalnych cache hitów
curl "http://localhost:8080/admin/usage/summary?user_path=/team/alpha&cache_mode=all" \
  -H "Authorization: Bearer $GOMODEL_MASTER_KEY"
```

Zobacz [endpointy administracyjne](https://gomodel.enterpilot.io/docs/pl/advanced/admin-endpoints.md#tryb-cache) oraz
[Usage API](https://gomodel.enterpilot.io/docs/pl/advanced/usage-api.md#tryb-cache).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.