Skip to main content

​
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:
Cache semantyczny używa embeddingów i wyszukiwania wektorowego, dzięki czemu prompty o równoważnym znaczeniu mogą ponownie wykorzystać zapisaną odpowiedź:
/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: podobny stan to nie ta sama decyzja.

​
Włącz cache dokładny

Skieruj cache odpowiedzi na Redisa:
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ą:
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 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 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.

​
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:
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.
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, 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:
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.
Zobacz endpointy administracyjne oraz Usage API.
Ostatnia modyfikacja 24 października 2026