mirror of https://github.com/diegosouzapw/OmniRoute.git synced 2026-08-12 10:12:11 +03:00

Files

Adrian Rogala 71c5a7592f docs: replace outdated Polish docs with translation from latest English (#8823 )

2026-07-28 00:45:21 -03:00

21 KiB

Raw Blame History

title, version, lastUpdated

title	version	lastUpdated
🗜️ Przewodnik po kompresji promptów — OmniRoute	3.8.40	2026-06-28

🗜️ Przewodnik po kompresji promptów — OmniRoute

Oszczędzaj automatycznie 15–95% kwalifikującego się kontekstu. Szybki przegląd: sekcja Compression w README.

Przegląd

OmniRoute implementuje modularny potok kompresji promptów, który działa proaktywnie zanim żądania trafią do upstreamowych providerów. Oszczędności tokenów zachodzą więc przejrzyście — bez zmian w Twoim workflow.

Client Request
  → Compression Strategy Selector
    → Combo override? → Use combo setting
    → Auto-trigger threshold? → Use auto mode
    → Default mode? → Use global setting
    → Off? → Skip compression
  → Selected Compression Mode
    → Off: No compression
    → Lite: Safe whitespace/formatting cleanup (~15%)
    → Standard: Caveman-speak filler removal (~30%)
    → Aggressive: History aging + summarization (~50%)
    → Ultra: Heuristic pruning + code-block thinning (~75%)
    → RTK: Command-aware terminal/tool-output filtering (60-90% upstream range)
    → Stacked: Ordered multi-engine pipeline, usually RTK then Caveman (78-95% eligible range)
  → Compressed Request → Provider

Tryby kompresji

Off

Brak kompresji. Wszystkie wiadomości przechodzą bez zmian.

Lite Mode (~15% oszczędności, opóźnienie <1 ms)

Najbezpieczniejszy tryb — zero zmian semantycznych, tylko porządkowanie formatowania:

Technique	Description
`collapseWhitespace`	Scala kolejne puste linie i końcowe spacje
`dedupSystemPrompt`	Usuwa zduplikowane wiadomości systemowe
`compressToolResults`	Kompresuje rozwlekłe wyjścia narzędzi/funkcji
`removeRedundantContent`	Usuwa powtórzone instrukcje
`replaceImageUrls`	Skraca URI danych obrazów base64

Najlepsze do: ciągłego włączonego użycia, workflow krytycznych dla bezpieczeństwa.

Standard Mode (~30% oszczędności)

Inspirowany Caveman — usuwa wypełniacze i rozwlekłe sformułowania, zachowując sens:

Usuwa słowa-wypełniacze („please”, „I think”, „basically”, „actually”)
Skraca rozwlekłe frazy („in order to” → „to”, „as a result of” → „because”)
Usuwa grzecznościowe owijanie („Would you mind...”, „If you could possibly...”)
Ponad 30 reguł regex dostrojonych do promptów kodowania

Najlepsze do: codziennego kodowania, zespołów dbających o koszty.

Aggressive Mode (~50% oszczędności)

Inteligentne zarządzanie historią w długich sesjach:

Message Aging — starsze wiadomości są stopniowo mocniej kompresowane
Tool Result Summarization — długie wyjścia narzędzi zastępowane streszczeniami
Structural Integrity Guards — pary tool_use + tool_result pozostają spójne
Context Window Awareness — respektuje limity tokenów per model

Najlepsze do: długich sesji debugowania, dużych codebase’ów.

Ultra Mode (~75% oszczędności)

Maksymalna kompresja w scenariuszach krytycznych dla tokenów:

Heuristic Pruning — usuwa wiadomości poniżej progu istotności
Code Block Thinning — kompresuje powtarzalne przykłady kodu
Binary Search Truncation — znajduje optymalny punkt cięcia okna kontekstu
Zawiera wszystkie funkcje trybu Aggressive

Najlepsze do: gdy wielokrotnie dobijasz do limitów kontekstu.

RTK Mode (zakres upstream 60–90%)

Tryb RTK jest zoptymalizowany pod rozwlekłe wyjścia narzędzi w sesjach agentów kodujących:

Wykrywa klasy poleceń/wyjść takie jak git status, git diff, git log, test runnery, buildy TypeScript/Vite/Webpack, ESLint/Biome/Prettier, npm audit/install, logi Docker, wyjście infrastruktury oraz generyczne wyjście shell
Stosuje pakiety filtrów JSON z open-sse/services/compression/engines/rtk/filters/
Importuje filtry schematu RTK TOML v1 z projektowych lub globalnych plików filters.toml, z walidacją testów inline i bramką zaufania dla plików projektowych
Dostarcza 49 wbudowanych filtrów z próbkami weryfikacji inline
Usuwa sekwencje sterujące ANSI, paski postępu, powtórzone linie i nieistotny szum
Zachowuje awarie, błędy, ostrzeżenia, zmienione pliki, podsumowania oraz ogon długiego wyjścia
Wspiera filtry projektowe z bramką zaufania, filtry globalne oraz opcjonalne odzyskiwanie zredagowanego surowego wyjścia

Najlepsze do: sesji agentów z transkryptami shell, build, test, git, grep i wyjściem plików.

Stacked Mode (zakres kwalifikowalny 78–95%)

Tryb stacked uruchamia wiele silników kompresji w deterministycznej kolejności. Domyślny potok:

RTK -> Caveman

Ta kolejność najpierw kompaktuje wyjście terminala/narzędzi, a potem stosuje semantyczną kondensację Caveman do pozostałego promptu w języku naturalnym. Potoki stacked można konfigurować globalnie lub przez combo kompresji przypisane do combo routingu.

Najlepsze do: mieszanego kontekstu z dużymi logami narzędzi oraz instrukcjami człowieka lub streszczeniami asystenta.

Matematyka oszczędności upstream

OmniRoute dokumentuje oszczędności kompresji z dwóch źródeł: benchmarków projektów upstream oraz własnej kompozycji silników OmniRoute.

Source	Upstream README number used here
Caveman	`~75%` fewer output tokens, `65%` benchmark average output savings, `22-87%` range, and `~46%` input compression tool
RTK	`60-90%` command-output savings; sample session `~118,000 -> ~23,900` tokens, or `79.7%` saved (`~80%`)

Dla nakładających się payloadów narzędzi/kontekstu domyślne combo OmniRoute układa silniki w stos:

RTK -> Caveman

Połączone oszczędności są multiplikatywne, nie addytywne:

combined = 1 - (1 - RTK savings) * (1 - Caveman input savings)
average  = 1 - (1 - 0.80) * (1 - 0.46) = 89.2%
range    = 1 - (1 - 0.60..0.90) * (1 - 0.46) = 78.4-94.6%

Liczba 78-95% dotyczy sytuacji, gdy zarówno RTK, jak i Caveman mogą zredukować ten sam payload wejścia/kontekstu. Tryb wyjścia odpowiedzi Caveman jest osobny: gdy włączony, stosuj własne oszczędności wyjścia Caveman (65% średnio, ~75% w nagłówku, zakres 22-87%). Całkowite oszczędności rozliczeniowe zależą od mieszanki prompt/wyjście.

Wizualizacja oszczędności tokenów

Without compression: 47K tokens sent to LLM
With Lite:           40K tokens sent          (15% saved — safe, always-on)
With Standard:       33K tokens sent          (30% saved — caveman-speak rules)
With Aggressive:     24K tokens sent          (50% saved — aging + summarization)
With Ultra:          12K tokens sent          (75% saved — heuristic pruning)
With RTK:            19K-5K tokens sent       (60-90% saved on command/tool output)
With Stacked:        10K-2.5K tokens sent     (78-95% eligible RTK+Caveman range)

Konfiguracja

Dashboard

Przejdź do Dashboard → Context & Cache:

Caveman — wybór trybu, language packi, podgląd i globalne domyślne
RTK — podgląd filtrów poleceń, ustawienia bezpieczeństwa RTK i katalog filtrów
Compression Combos — nazwane potoki silników przypisane do combo routingu
Auto-Trigger Threshold — automatycznie włącza kompresję, gdy liczba tokenów przekroczy próg

Nadpisanie per combo

W Dashboard → Context & Cache → Compression Combos przypisz combo kompresji do combo routingu:

Combo: "free-forever"
  Compression Combo: "coding-agent-stack"
  Pipeline: RTK -> Caveman
  Targets:
    1. if/kimi-k2.7-code
    2. if/qwen3.8-max-preview

Pozwala to używać kompresji stacked na darmowych/kodujących providerach, a trybu lite na płatnych subskrypcjach.

To przypisanie „Per-Combo Override” to inna kontrolka niż nadpisanie trybu kompresji combo routingu (Default/Off/Lite/Standard/Aggressive/Ultra) — to nadpisanie nie wybiera nazwanego potoku compression-combo; ustawia jedynie pole compressionMode odczytywane przez resolveCompressionPlan. Można je ustawić na karcie combo (Dashboard → Combos) albo, od #6760, per combo routingu na liście „Assign to routing” w Dashboard → Context & Cache → Compression Combos, tuż obok checkboxa przypisania potoku opisanego wyżej. Oba miejsca zapisują przez ten sam endpoint PUT /api/combos/{id}.

Nadpisanie per żądanie

Wyślij nagłówek żądania x-omniroute-compression, aby nadpisać plan kompresji dla pojedynczego żądania. Ma najwyższy priorytet — wygrywa z nadpisaniem combo routingu, aktywnym profilem, auto-triggerem i panelem Default. Nieznane wartości są ignorowane (żądanie nigdy nie jest odrzucane), a globalny przełącznik główny nadal blokuje wszystko: gdy kompresja jest globalnie wyłączona, nagłówek nie może jej włączyć. Wartości:

Value	Effect
`off`	Brak kompresji dla tego żądania.
`default`	Profil Default z panelu (ignoruje aktywny profil).
`engine:<id>`	Pojedynczy silnik, gdy włączony, np. `engine:rtk`.
`<combo>`	Nazwane combo — najpierw po nazwie (bez wielkości liter), potem po id.

Zastosowany plan jest zwracany w nagłówku odpowiedzi X-OmniRoute-Compression: <mode>; source=<source>, gdzie <source> to jedno z: request-header, routing-override, active-profile, auto-trigger, default lub off.

API

# Get compression settings
curl http://localhost:20128/api/settings/compression

# Update compression settings
curl -X PUT http://localhost:20128/api/settings/compression \
  -H "Content-Type: application/json" \
  -d '{"defaultMode":"stacked","autoTriggerMode":"stacked","autoTriggerTokens":32000}'

# Preview a specific RTK/stacked payload
curl -X POST http://localhost:20128/api/compression/preview \
  -H "Content-Type: application/json" \
  -d '{"mode":"rtk","messages":[{"role":"tool","content":"npm test output here"}]}'

# List RTK filter packs
curl http://localhost:20128/api/context/rtk/filters

# Test RTK directly with optional command metadata
curl -X POST http://localhost:20128/api/context/rtk/test \
  -H "Content-Type: application/json" \
  -d '{"command":"npm test","text":"FAIL tests/example.test.ts\nError: boom"}'

Co jest chronione

Silnik kompresji zawsze zachowuje:

✅ Bloki kodu (fenced i inline)
✅ URL-e i ścieżki plików
✅ Struktury JSON i dane strukturalne
✅ Identyfikatory i chronione tokeny techniczne
✅ Wyrażenia matematyczne
✅ Definicje wywołań narzędzi/funkcji
✅ System prompty (w trybie lite)

Odzyskiwanie surowego wyjścia RTK redaguje typowe klucze API, tokeny bearer, tokeny Slack, klucze dostępu AWS, hasła, tokeny i sekrety zanim cokolwiek zostanie zapisane.

Statystyki kompresji

Każde skompresowane żądanie zawiera statystyki w logach serwera:

{
  "originalTokens": 47200,
  "compressedTokens": 40120,
  "savingsPercent": 15.0,
  "techniquesUsed": ["collapseWhitespace", "dedupSystemPrompt"],
  "mode": "lite",
  "engine": "caveman",
  "compressionComboId": "coding-agent-stack",
  "durationMs": 0.8,
  "rtkRawOutputPointers": []
}

Roadmapa faz

Phase	Modes	Status
Phase 1	Off, Lite	✅ Wydane
Phase 2	Standard, Aggressive, Ultra	✅ Wydane
Phase 3	RTK, Stacked, Compression Combos	✅ Wydane
Phase 4	Output Styles, SLM-tier Ultra, eval harness	✅ Wydane
Phase 4C	Adaptive context-budget („dial”) — silnik compute + API (`contextBudget` na `PUT /api/settings/compression`)	✅ Wydane (konfigurowalne przez API; kontrolki dashboardu jeszcze nie, #7005)

Podziękowania

Reguły kompresji trybu Standard są inspirowane przez Caveman autorstwa JuliusBrussee (⭐ 51K+) — viralowy projekt „why use many token when few token do trick”. Caveman raportuje ~75% mniej tokenów wyjścia, 65% średnich oszczędności wyjścia w benchmarku, zakres wyjścia 22-87% oraz narzędzie kompresji wejścia ~46%.

Tryb RTK jest inspirowany przez RTK - Rust Token Killer autorstwa RTK AI — wysokowydajny projekt kompresji wyjścia poleceń do filtrowania terminala, buildów, testów, git i wyjścia narzędzi. RTK raportuje oszczędności 60-90%, a przykładowa sesja w README pokazuje ~80% zaoszczędzonych tokenów.

Zaawansowane systemy kompresji

Poza 7 standardowymi trybami OmniRoute zawiera kilka zaawansowanych systemów kompresji, które działają automatycznie w zależności od kontekstu.

Kompresja świadoma cache

Niektórzy providerzy (np. Anthropic z prompt caching) wspierają prompt caching, który pozwala cache’ować części promptu w celu obniżenia kosztów i opóźnień. Gdy cache jest włączony, agresywna kompresja może faktycznie pogorszyć wydajność, bo zmienia cache’owane tokeny i unieważnia cache.

Moduł cachingAware.ts rozwiązuje to przez wykrywanie kontekstu cache i dostosowanie strategii kompresji.

Jak to działa

Wykryj kontekst cache — skanuje body żądania pod kątem znaczników cache_control
Zidentyfikuj providerów z cache — sprawdza, czy docelowy provider wspiera cache
Dostosuj strategię — obniża aggressive/ultra do standard dla providerów z cache
Pomiń system prompt — system prompty zwykle są cache’owane, więc ich nie kompresuj
Używaj transformacji deterministycznych — tylko transformacje dające spójne wyjście

Przykład kodu

import {
  detectCachingContext,
  getCacheAwareStrategy,
} from "@omniroute/open-sse/services/compression/cachingAware";

const body = {
  model: "anthropic/claude-sonnet-4.5",
  messages: [{ role: "user", content: "Hello" }],
  cache_control: { type: "ephemeral" }, // ← Cache marker
};

const ctx = detectCachingContext(body, { provider: "anthropic" });
// → { hasCacheControl: true, provider: "anthropic", isCachingProvider: true }

const strategy = getCacheAwareStrategy("aggressive", ctx);
// → { strategy: "standard", skipSystemPrompt: true, deterministicOnly: true }

Kiedy używać

Kompresja świadoma cache jest zawsze włączona — bez konfiguracji. Włącza się tylko gdy:

Żądanie ma znaczniki cache_control
Docelowy provider wspiera prompt caching (Anthropic, OpenAI itd.)

Progressive Aging

Długie rozmowy gromadzą wiele tur wiadomości, ale starsze tury stają się mniej istotne. Moduł progressiveAging.ts degraduje wiadomości według odległości tur:

Ostatnie tury (0–3): bez zmian (pełny detal)
Średnie tury (4–8): kompresja lite (whitespace, porządkowanie formatowania)
Stare tury (9+): kompresja Caveman (usuwanie wypełniaczy, streszczanie)
Bardzo stare tury (20+): mocno streszczone lub usunięte

Przykład kodu

import { applyAging } from "@omniroute/open-sse/services/compression/progressiveAging";

const messages = [
  { role: "system", content: "You are a helpful assistant" },
  { role: "user", content: "What is 2+2?" },
  { role: "assistant", content: "4" },
  // ... 50 more turns ...
];

const { messages: aged, saved } = applyAging(messages, {
  verbatim: 3, // First 3 turns: verbatim
  light: 8, // Turns 4-8: lite compression
  moderate: 20, // Turns 9-20: caveman compression
  // Turns 21+: heavy summarization
});

// saved = number of tokens saved

Kiedy używać

Progressive aging jest zawsze włączone dla trybów aggressive i ultra. Szczególnie skuteczne przy:

Długich sesjach kodowania
Rozmowach wielodniowych
Workflow agentowych z wieloma wywołaniami narzędzi

Tryb wyjścia Caveman

Moduł outputMode.ts wstrzykuje instrukcje system promptu, aby model sam produkował skompresowane, zwięzłe wyjście (styl „caveman”).

Jak to działa

Zamiast kompresować wejście, ten tryb dodaje system prompt w stylu:

"Reply in minimal words. Skip pleasantries. Use short sentences."

Szczególnie dobrze działa przy:

Generowaniu kodu (zwięźlejsze wyjście = mniej tokenów)
Szybkim Q&A (bez rozbudowanych wyjaśnień)
Przetwarzaniu wsadowym (maksymalna przepustowość)

Kiedy używać

Tryb wyjścia Caveman jest opt-in — ustaw go w konfiguracji combo:

{
  "strategy": "auto",
  "config": {
    "auto": {
      "outputMode": "caveman"
    }
  }
}

Kompresja wyników narzędzi

Moduł toolResultCompressor.ts oferuje 5 specjalistycznych strategii kompresji dla wyników narzędzi (wywołania funkcji, wyjścia agentów, wyniki wyszukiwania itd.):

Kompresja wyników wyszukiwania — usuwa zbędne wyniki, zostawia top-N
Kompresja odczytu plików — obcina duże pliki, zachowuje nagłówki/importy
Kompresja wykonania kodu — zostawia tylko istotny stdout/stderr
Kompresja zapytań do bazy — limituje wiersze, usuwa rozwlekłe metadane
Kompresja odpowiedzi API — usuwa pola null, kondensuje tablice

Kiedy używać

Kompresja wyników narzędzi jest zawsze włączona, gdy obecne są wywołania narzędzi. Bez konfiguracji.

Potok Stacked

Tryb stacked uruchamia wiele silników sekwencyjnie — zwykle najpierw RTK (60–90% oszczędności na wyjściu narzędzi), potem Caveman (dodatkowe ~30% na pozostałym tekście). Daje to łącznie 78–95% oszczędności.

Jak to działa

Input (1000 tokens)
  → RTK (command-aware filter) → 200 tokens
    → Caveman (filler removal) → 140 tokens
  → Output (140 tokens, 86% savings)

Kiedy używać

Używaj trybu stacked dla:

Workflow mocno opartych o narzędzia (agentowe kodowanie, research)
Przetwarzania wsadowego wrażliwego na koszty
Gdy potrzebujesz maksymalnych oszczędności tokenów

Konfiguracja przez combo:

{
  "strategy": "auto",
  "config": {
    "auto": {
      "modePack": "stacked"
    }
  }
}

Nadpisania combo kompresji

Możesz nadpisać globalny tryb kompresji per combo, aby dostroić zachowanie dla różnych przypadków użycia:

{
  "id": "coding-combo",
  "strategy": "priority",
  "config": {
    "auto": {
      "weights": { "taskFit": 0.5 },
      "modePack": "quality-first"
    }
  },
  "compressionOverride": {
    "mode": "aggressive",
    "stackedPipelines": ["rtk", "caveman"],
    "preserveToolDefinitions": true
  }
}

Przydatne dla:

Combo kodowania: tryb aggressive przy długich sesjach
Combo szybkiego Q&A: tryb lite dla szybkich odpowiedzi
Combo mocno narzędziowe: tryb stacked dla max oszczędności
Combo produkcyjne: tryb cache-aware dla providerów z cache

Zobacz też

Konfiguracja środowiska — zmienne środowiskowe kompresji
Przewodnik po architekturze — wnętrze potoku kompresji
Przewodnik użytkownika — pierwsze kroki z kompresją
Kompresja RTK — filtry RTK, model zaufania, bramka verify, odzyskiwanie surowego wyjścia
Silniki kompresji — Caveman, RTK, stacked, API, MCP, dashboard
Format reguł kompresji — format pakietów reguł JSON
Language packi kompresji — reguły Caveman zależne od języka

21 KiB Raw Blame History Unescape Escape

🗜️ Przewodnik po kompresji promptów — OmniRoute

Przegląd

Tryby kompresji

Off

Lite Mode (~15% oszczędności, opóźnienie <1 ms)

Standard Mode (~30% oszczędności)

Aggressive Mode (~50% oszczędności)

Ultra Mode (~75% oszczędności)

RTK Mode (zakres upstream 60–90%)

Stacked Mode (zakres kwalifikowalny 78–95%)

Matematyka oszczędności upstream

Wizualizacja oszczędności tokenów

Konfiguracja

Dashboard

Nadpisanie per combo

Nadpisanie per żądanie

API

Co jest chronione

Statystyki kompresji

Roadmapa faz

Podziękowania

Zaawansowane systemy kompresji

Kompresja świadoma cache

Jak to działa

Przykład kodu

Kiedy używać

Progressive Aging

Przykład kodu

Kiedy używać

Tryb wyjścia Caveman

Jak to działa

Kiedy używać

Kompresja wyników narzędzi

Kiedy używać

Potok Stacked

Jak to działa

Kiedy używać

Nadpisania combo kompresji

Zobacz też

21 KiB

Raw Blame History