Compression Engines (Português (Brasil))

Combos de compressão

Combos de compressão são perfis de compressão nomeados que podem ser atribuídos a combos de roteamento:

• compression_combos: armazena modo, pipeline, configuração do RTK, configuração de idioma e marcador padrão
• compression_combo_assignments: mapeia um combo de compressão para um combo de roteamento
• a integração em tempo de execução resolve um combo de compressão atribuído antes das substituições genéricas de combo
• as análises incluem compression_combo_id e engine

Área no dashboard: Dashboard -> Context & Cache -> Compression Combos.

Superfície da API

Rota	Finalidade
/api/settings/compression	Configurações globais de compressão (inclui a configuração mcpAccessibility)
/api/compression/preview	Visualizar qualquer modo de compressão
/api/compression/language-packs	Listar os pacotes de idioma Caveman disponíveis
/api/context/caveman/config	Alias das configurações do Caveman
/api/context/rtk/config	Padrões e configurações do RTK
/api/context/rtk/filters	Catálogo de filtros do RTK
/api/context/rtk/test	Endpoint de visualização/teste do RTK
/api/context/rtk/raw-output/[id]	Recuperação autenticada da saída bruta com dados sensíveis ocultados
/api/context/combos	CRUD de combos de compressão
/api/context/combos/[id]/assignments	CRUD de atribuições de combos de roteamento
/api/context/analytics	Alias das análises de compressão

As rotas de gerenciamento exigem autenticação de gerenciamento ou verificações de política de chave de API.

Ferramentas MCP

A compressão disponibiliza cinco ferramentas MCP:

Ferramenta	Escopo	Finalidade
omniroute_compression_status	read:compression	Configurações, análises e estatísticas de cache
omniroute_compression_configure	write:compression	Atualizar configurações globais
omniroute_set_compression_engine	write:compression	Definir modo e pipeline opcional
omniroute_list_compression_combos	read:compression	Listar combos de compressão
omniroute_compression_combo_stats	read:compression	Consultar análises de combos/engines

Escopo e exclusões

Embeddings nunca são comprimidos. open-sse/handlers/embeddings.ts nunca chama nenhum engine de compressão — os corpos da solicitação/resposta são encaminhados diretamente ao executor sem alterações. Atualmente, isso é estrutural (embeddings e conclusões de chat têm handlers separados), não uma verificação em tempo de execução, mas significa que a preocupação com distorção de vetores em #8034 não tem superfície de exposição no caminho de embeddings.

Filtro de exclusão por modelo/endpoint (#8034). Para conclusões de chat, um operador pode especificar ids de modelo/alvos provider/model que nunca devem ser comprimidos — uma proteção útil caso a compressão seja futuramente conectada mais perto de um caminho adjacente a embeddings e, em geral, útil para qualquer modelo em que o prompt exato, byte por byte, seja importante (avaliações determinísticas, prefixos sensíveis ao cache etc.).

• Campo de configuração: exclusions?: string[] na configuração global de compressão (GET/PUT /api/settings/compression), persistido por meio do namespace de compressão key_value existente (src/lib/db/compression.ts) — nenhuma tabela nova.
• Aba do dashboard: Dashboard → Compression → Exclusions (/dashboard/compression/exclusions).
• Sintaxe dos padrões: * é o único curinga. Todos os demais metacaracteres de regex em um padrão são escapados antes da correspondência, de modo que gpt-5.6 corresponde apenas à string literal, nunca a gpt-5x6 (seguro contra ReDoS, limitado, sem quantificadores aninhados). Os padrões são comparados sem distinção entre maiúsculas e minúsculas tanto com o id simples do modelo quanto com o composto provider/model — gpt-5-6, openai/gpt-5-6 e openai/* funcionam, e * sozinho exclui todos os modelos.
• Correspondência: isCompressionExcluded() / normalizeCompressionExclusions() em open-sse/services/compression/exclusions.ts. chatCore.ts verifica o alvo excluído logo após resolver as configurações de compressão, antes da execução de qualquer engine, e trata uma correspondência exatamente como se a compressão estivesse globalmente desabilitada — o corpo da solicitação é comprovadamente idêntico byte por byte. A omissão é registrada por meio de writeCompressionSkip(..., "excluded") para visibilidade nas análises.
• Padrão (lista vazia/ausente): idêntico ao comportamento anterior ao #8034 — nada é excluído.

Limitações conhecidas

• O LLMLingua-2 (SLM) exige dependências opcionais colocalizadas. O worker só é executado em uma compilação de produção quando @atjsh/llmlingua-2 + pares são colocalizados em dist/node_modules (consulte scripts/build/colocateOptionals.mjs, #4286). Sem eles, o mecanismo falha de forma aberta (retorna o texto original). A resolução do worker não depende mais de import.meta.url (isso falha no bundle independente) — ela se ancora no cwd / argv[1] do runtime.
• Os pacotes de idiomas de / fr / ja do Caveman são parciais. Eles incluem regras de context + filler + structural, mas não incluem pacotes dedup / ultra; portanto, a intensidade ultra não é mais forte que full para esses idiomas (eles usam apenas suas próprias regras — não há fallback silencioso para as regras dedup/ultra em inglês, que corromperiam textos em outros idiomas). en / es / id / pt-BR estão completos. Contribuições de dedup.json + ultra.json para os pacotes parciais são bem-vindas.
• A telemetria empilhada lista apenas os mecanismos que realizaram compressão. Uma etapa do pipeline empilhado cujo mecanismo foi executado, mas produziu 0 % de economia, retorna stats:null e, portanto, não aparece em engineBreakdown — não sendo possível distingui-la de uma etapa que foi ignorada. Distinguir “executada, 0 %” de “ignorada” exigiria uma alteração no modelo de detalhamento e foi adiado.

Validação

Os “gates” focados para esta área são:

node --import tsx/esm --test tests/unit/compression/rtk-*.test.ts tests/unit/compression/pipeline-integration.test.ts tests/unit/compression/context-compression-api.test.ts
node --import tsx/esm --test tests/unit/compression/*.test.ts tests/golden-set/*.test.ts tests/integration/compression-pipeline.test.ts tests/unit/api/compression/compression-api.test.ts
node --import tsx/esm --test tests/unit/compression/mcpAccessibility*.test.ts
npm run typecheck:core

---

Código-fonte do OmniRoute (a58000c7685f)