Poznámka:
Přístup k této stránce vyžaduje autorizaci. Můžete se zkusit přihlásit nebo změnit adresáře.
Přístup k této stránce vyžaduje autorizaci. Můžete zkusit změnit adresáře.
S růstem konverzací může počet tokenů historie chatu překročit kontextová okna modelu nebo zvýšit náklady. Strategie komprimace zmenšují velikost historie konverzací při zachování důležitého kontextu, takže agenti můžou dál fungovat při dlouhotrvajících interakcích.
Důležité
Architektura komprimace je v současné době experimentální. Pokud ho chcete použít, budete muset přidat #pragma warning disable MAAI001.
Důležité
Architektura komprimace je v současné době experimentální v Pythonu. Importovat strategie z agent_framework._compaction.
Proč komprimace záleží
Každé volání na LLM zahrnuje kompletní historii konverzace. Bez komprimace:
- Limity tokenů – Konverzace nakonec překračují kontextové okno modelu, což způsobuje chyby.
- Náklady – Větší výzvy spotřebovávají více tokenů a zvyšují náklady na rozhraní API.
- Latence – Více vstupních tokenů znamená pomalejší doby odezvy.
Komprimace tyto problémy řeší selektivním odebráním, zhuštěním nebo shrnutím starších částí konverzace.
Klíčové koncepty
Použitelnost: Pouze historie agentů v paměti
Komprimace se vztahuje pouze na agenty, kteří spravují vlastní historii konverzací v paměti. Agenti, kteří spoléhají na kontext spravovaný službou nebo stav konverzace, nemají prospěch z komprimace, protože služba už zpracovává správu kontextu. Mezi příklady agentů spravovaných službou patří:
- Foundry Agents – kontext je spravovaný na straně serveru službou Azure AI Foundry.
- Rozhraní API pro odpovědi s povoleným úložištěm (výchozí) – stav konverzace je uložený a spravovaný službou OpenAI.
- Agenti Copilot Studio – kontext konverzace udržuje služba Copilot Studio.
U těchto typů agentů nemá konfigurace strategie komprimace žádný vliv. Komprimace je relevantní pouze v případech, kdy agent udržuje vlastní seznam zpráv v paměti a předává úplnou historii modelu při každém volání.
Komprimace operuje na MessageIndex — strukturovaném zobrazení plochého seznamu zpráv, které seskupuje zprávy do atomických jednotek nazývaných instance MessageGroup. Každá skupina sleduje počet zpráv, počet bajtů a odhadovaný počet tokenů.
Skupiny zpráv
A MessageGroup představuje logicky související zprávy, které musí být udržovány nebo odebrány společně. Například zpráva asistenta obsahující volání nástrojů a odpovídající zprávy výsledků nástroje tvoří atomické skupiny – odebrání jedné bez druhé způsobí chyby rozhraní LLM API.
Každá skupina má MessageGroupKind:
| Druh | Description |
|---|---|
System |
Jedna nebo více systémových zpráv. Během komprimace se vždy zachová. |
User |
Jedna zpráva uživatele, která spustí nový turn. |
AssistantText |
Textová odpověď prostého asistenta (žádná volání nástroje) |
ToolCall |
Zpráva asistenta s voláním nástroje a odpovídajícími zprávami výsledků nástroje, je považována za atomickou jednotku. |
Summary |
Zhuštěná zpráva vytvořená komprimací souhrnu. |
Spouštěče
A CompactionTrigger je delegát, který vyhodnotí, jestli má komprimace pokračovat na základě aktuálních MessageIndex metrik:
public delegate bool CompactionTrigger(MessageIndex index);
Třída CompactionTriggers poskytuje běžné tovární metody.
| Spouštěč | Aktivuje se, když |
|---|---|
CompactionTriggers.Always |
Pokaždé (bezpodmínečně). |
CompactionTriggers.Never |
Nikdy (deaktivuje komprimaci). |
CompactionTriggers.TokensExceed(maxTokens) |
Zahrnutý počet tokenů překračuje prahovou hodnotu. |
CompactionTriggers.MessagesExceed(maxMessages) |
Zahrnutý počet zpráv překračuje prahovou hodnotu. |
CompactionTriggers.TurnsExceed(maxTurns) |
Zahrnutý počet otáček uživatele překračuje prahovou hodnotu. |
CompactionTriggers.GroupsExceed(maxGroups) |
Zahrnutý počet skupin překračuje prahovou hodnotu. |
CompactionTriggers.HasToolCalls() |
Existuje alespoň jedna skupina volání nástrojů, která není vyloučena. |
Zkombinujte triggery s CompactionTriggers.All(...) (logickým operátorem AND) nebo CompactionTriggers.Any(...) (logickým operátorem OR):
// Compact only when there are tool calls AND tokens exceed 2000
CompactionTrigger trigger = CompactionTriggers.All(
CompactionTriggers.HasToolCalls(),
CompactionTriggers.TokensExceed(2000));
Aktivační událost vs. cíl
Každá strategie má dva predikáty:
-
Aktivační událost – řídí , kdy začíná komprimace. Pokud se spouštěč vrátí
false, strategie bude zcela přeskočena. -
Cíl – řídí , kdy se komprimace zastaví. Strategie postupně vyloučí skupiny a po každém kroku znovu vyhodnotí cíl a zastaví se, jakmile se cíl vrátí
true.
Pokud není zadán žádný cíl, použije se výchozí hodnota inverzní funkce triggeru – komprimace se zastaví, jakmile se podmínka triggeru už neaktivuje.
Komprimace funguje na plochém seznamu Message objektů. Zprávy jsou opatřeny poznámkami s jednoduchými metadaty skupin a strategie tyto poznámky upraví, aby se skupiny označovaly jako vyloučené před promítnutím seznamu zpráv do modelu.
Skupiny zpráv
Zprávy jsou seskupené do atomických jednotek. Každé skupině je přiřazeno GroupKind:
| Druh | Description |
|---|---|
system |
Systémové zprávy. Během komprimace se vždy zachová. |
user |
Jedna zpráva uživatele. |
assistant_text |
Textová odpověď prostého asistenta (žádná volání funkce) |
tool_call |
Zpráva asistenta s voláními funkcí a odpovídajícími zprávami výsledků nástroje, které jsou považovány za nedělitelné jednotky. |
Strategie komprimace
A CompactionStrategy je protokol – jakýkoli async volatelný objekt, který přijme list[Message] a změní ho na místě, vrátí True při jakékoli změně:
class CompactionStrategy(Protocol):
async def __call__(self, messages: list[Message]) -> bool: ...
Tokenizátor
Strategie podporující tokeny přijímají implementaci TokenizerProtocol . Vestavěné CharacterEstimatorTokenizer používá heuristiku čtyři znaky na token:
from agent_framework._compaction import CharacterEstimatorTokenizer
tokenizer = CharacterEstimatorTokenizer()
Pokud potřebujete přesné počty tokenů pro kódování konkrétního modelu, předejte vlastní tokenizátor.
Strategie komprimace
Všechny strategie dědí z abstraktní CompactionStrategy základní třídy. Každá strategie zachovává systémové zprávy a respektuje hranici MinimumPreserved, která chrání nejnovější nesystémové skupiny před odstraněním.
Komprimační strategie se importují z agent_framework._compaction.
TruncationCompactionStrategy
Strategie zkracování
Nejjednodušší přístup: Odebere nejstarší nesystémové skupiny zpráv, dokud nebude splněna cílová podmínka.
- Respektuje hranice atomických skupin (volání nástroje a výsledné zprávy se odeberou společně).
- Nejvhodnější pro striktní backstopy rozpočtu tokenů.
- Výchozí hodnotou
MinimumPreservedje32.
// Drop oldest groups when tokens exceed 32K, keeping at least 10 recent groups
TruncationCompactionStrategy truncation = new(
trigger: CompactionTriggers.TokensExceed(0x8000),
minimumPreserved: 10);
- Pokud je metrika
tokenizerzadána, je to počet tokenů, jinak se jedná o zahrnutý počet zpráv. - Výchozí hodnotou
preserve_systemjeTrue.
from agent_framework._compaction import CharacterEstimatorTokenizer, TruncationStrategy
# Exclude oldest groups when tokens exceed 32 000, trimming to 16 000
truncation = TruncationStrategy(
max_n=32_000,
compact_to=16_000,
tokenizer=CharacterEstimatorTokenizer(),
)
StrategieZhušťováníPosuvnýmiOkny
Strategie Posuvného Okna
Odebere starší obsah konverzace, aby se zachovalo pouze nejnovější okno výměny, které respektuje logické jednotky konverzací místo počtu libovolných zpráv. Systémové zprávy se zachovají po celou dobu.
- Nevhodnější pro předvídatelné vymezení délky konverzace.
Odebere nejstaršího uživatele a jejich přidružené skupiny odpovědí, které fungují na hranicích logického otáčení, nikoli na jednotlivých skupinách.
- Zatáčka začíná zprávou uživatele a zahrnuje všechny následné asistenty a skupiny volání nástrojů až do další zprávy uživatele.
-
MinimumPreservedvýchozí hodnota je1(zachovává alespoň nejnovější nesystémovou skupinu).
// Keep only the last 4 user turns
SlidingWindowCompactionStrategy slidingWindow = new(
trigger: CompactionTriggers.TurnsExceed(4));
Udržuje pouze nejnovější keep_last_groups nesystémové skupiny s výjimkou všech starších skupin.
- Výchozí hodnotou
preserve_systemjeTrue.
from agent_framework._compaction import SlidingWindowStrategy
# Keep only the last 20 non-system groups
sliding_window = SlidingWindowStrategy(keep_last_groups=20)
ToolResultCompactionStrategy
Seskupí starší volání nástrojů do kompaktních souhrnných zpráv tak, aby byl zachován přehledný záznam bez nadbytečných informací.
- Nedotýká se uživatelských zpráv ani odpovědí prostého asistenta.
- Nejvhodnější jako počáteční strategie pro uvolnění místa pomocí podrobných výsledků nástrojů.
- Nahrazuje skupiny volání s více zprávami (volání asistenta + výsledky nástrojů) krátkým shrnutím, jako je
[Tool calls: get_weather, search_docs]. -
MinimumPreservedvýchozí hodnota je2, aby interakce nástroje aktuálního otáčení zůstaly viditelné.
// Collapse old tool results when tokens exceed 512
ToolResultCompactionStrategy toolCompaction = new(
trigger: CompactionTriggers.TokensExceed(0x200));
- Převádí do kompaktních souhrnných zpráv, jako je například
[Tool results: get_weather: sunny, 18°C]. - Nejnovější skupiny volání nástrojů
keep_last_tool_call_groupszůstanou nedotčené.
from agent_framework._compaction import ToolResultCompactionStrategy
# Collapse all but the newest tool-call group
tool_result = ToolResultCompactionStrategy(keep_last_tool_call_groups=1)
ShrnutíCompactionStrategy
Shrnutí Strategie
Pomocí LLM shrnuje starší části konverzace a nahrazuje je jedinou souhrnnou zprávou.
- Výchozí výzva zachovává klíčová fakta, rozhodnutí, předvolby uživatelů a výsledky volání nástrojů.
- K sumarizaci vyžaduje samostatného klienta LLM – doporučuje se menší a rychlejší model.
- Nejlepší pro zachování konverzačního kontextu a výrazně se snižuje počet tokenů.
- Můžete zadat vlastní výzvu k shrnutí.
- Chrání systémové zprávy a nejnovější
MinimumPreservednesystémové skupiny (výchozí:4). - Odešle starší zprávy do samostatného
IChatClients výzvou k shrnutí a pak vloží shrnutí jakoMessageGroupKind.Summaryskupinu.
// Summarize older messages when tokens exceed 1280, keeping the last 4 groups
SummarizationCompactionStrategy summarization = new(
chatClient: summarizerChatClient,
trigger: CompactionTriggers.TokensExceed(0x500),
minimumPreserved: 4);
Můžete zadat vlastní výzvu k shrnutí:
SummarizationCompactionStrategy summarization = new(
chatClient: summarizerChatClient,
trigger: CompactionTriggers.TokensExceed(0x500),
summarizationPrompt: "Summarize the key decisions and user preferences only.");
- Dojde ke spuštění, když počet nesystémových zpráv překročí
target_count + threshold. - Uchovává nejnovější
target_countzprávy; shrnuje všechno starší. -
SupportsChatGetResponseVyžaduje klienta.
from agent_framework._compaction import SummarizationStrategy
# Summarize when non-system message count exceeds 6, retaining the 4 newest
summarization = SummarizationStrategy(
client=summarizer_client,
target_count=4,
threshold=2,
)
Zadejte vlastní výzvu k shrnutí:
summarization = SummarizationStrategy(
client=summarizer_client,
target_count=4,
prompt="Summarize the key decisions and user preferences only.",
)
Strategie kompaktního potrubí
Složí více strategií do sekvenčního potrubí. Každá strategie pracuje na základě výsledku té předchozí, což umožňuje vrstvenou kompresi od jemné po agresivní.
- Vlastní aktivační událost kanálu je
CompactionTriggers.Always– každá podřízená strategie vyhodnocuje svou vlastní aktivační událost nezávisle. - Strategie se provádějí v pořadí, takže nejprve umístěte nejmílejší strategie.
PipelineCompactionStrategy pipeline = new(
new ToolResultCompactionStrategy(CompactionTriggers.TokensExceed(0x200)),
new SummarizationCompactionStrategy(summarizerChatClient, CompactionTriggers.TokensExceed(0x500)),
new SlidingWindowCompactionStrategy(CompactionTriggers.TurnsExceed(4)),
new TruncationCompactionStrategy(CompactionTriggers.TokensExceed(0x8000)));
Tento kanál:
- Sbalí staré výsledky nástrojů (mírné).
- Shrnuje starší úseky konverzací (v mírné míře).
- Udržuje pouze poslední 4 dotazy uživatelů (agresivní).
- Zahodí nejstarší skupiny, pokud stále překračují rozpočet (nouzová pojistka).
StrategieKomprimaceVoláníSelektivníhoNástroje
Plně vyloučí starší skupiny volání nástrojů, přičemž ponechá jenom poslední keep_last_tool_call_groups.
- Nedotýká se zpráv uživatele ani prostého asistenta.
- Nejlepší je, když chatovač nástrojů dominuje používání tokenů a není nutná úplná historie nástrojů.
from agent_framework._compaction import SelectiveToolCallCompactionStrategy
# Keep only the most recent tool-call group
selective_tool = SelectiveToolCallCompactionStrategy(keep_last_tool_call_groups=1)
StrategieSloženéhoTokenovéhoRozpočtu
Sestavuje několik strategií do sekvenční pipeline řízené rozpočtem tokenů. Každá podřízená strategie se spouští v daném pořadí a předčasně se zastaví, jakmile je rozpočet uspokojen. Vestavěná záloha vylučuje nejstarší skupiny, pokud strategie samy nemohou dosáhnout cíle.
- Strategie se provádějí v pořadí; nejprve umístěte nejjemnější strategie.
-
early_stop=True(výchozí) se zastaví, jakmile je tokenová kvóta dosažena.
from agent_framework._compaction import (
CharacterEstimatorTokenizer,
SelectiveToolCallCompactionStrategy,
SlidingWindowStrategy,
SummarizationStrategy,
TokenBudgetComposedStrategy,
ToolResultCompactionStrategy,
)
tokenizer = CharacterEstimatorTokenizer()
pipeline = TokenBudgetComposedStrategy(
token_budget=16_000,
tokenizer=tokenizer,
strategies=[
ToolResultCompactionStrategy(keep_last_tool_call_groups=1),
SummarizationStrategy(client=summarizer_client, target_count=4, threshold=2),
SlidingWindowStrategy(keep_last_groups=20),
],
)
Tento procesní řetězec:
- Sbálí výsledky starých nástrojů (šetrně).
- Shrnuje starší rozsahy konverzací (mírně).
- Udržuje pouze posledních 20 skupin (agresivních).
- Vrátí se zpět k vyloučení podle nejstaršího, pokud je stále nad rozpočtem (záchranná záloha).
Použití komprimace s agentem
Zabalte strategii komprimace do CompactionProvider, a zaregistrujte ji jako AIContextProvider. Předat buď jednu strategii, nebo PipelineCompactionStrategy konstruktoru.
Registrace pomocí rozhraní API pro tvůrce
Zaregistrujte poskytovatele na ChatClientBuilder pomocí UseAIContextProviders. Poskytovatel běží uvnitř smyčky volání nástroje a komprimuje zprávy před každým voláním LLM.
IChatClient agentChatClient = openAIClient.GetChatClient(deploymentName).AsIChatClient();
IChatClient summarizerChatClient = openAIClient.GetChatClient(deploymentName).AsIChatClient();
PipelineCompactionStrategy compactionPipeline =
new(
new ToolResultCompactionStrategy(CompactionTriggers.TokensExceed(0x200)),
new SummarizationCompactionStrategy(summarizerChatClient, CompactionTriggers.TokensExceed(0x500)),
new SlidingWindowCompactionStrategy(CompactionTriggers.TurnsExceed(4)),
new TruncationCompactionStrategy(CompactionTriggers.TokensExceed(0x8000)));
AIAgent agent =
agentChatClient
.AsBuilder()
.UseAIContextProviders(new CompactionProvider(compactionPipeline))
.BuildAIAgent(
new ChatClientAgentOptions
{
Name = "ShoppingAssistant",
ChatOptions = new()
{
Instructions = "You are a helpful shopping assistant.",
Tools = [AIFunctionFactory.Create(LookupPrice)],
},
});
AgentSession session = await agent.CreateSessionAsync();
Console.WriteLine(await agent.RunAsync("What's the price of a laptop?", session));
Návod
Pro chatovacího klienta sumarizace používejte menší, levnější model (například gpt-4o-mini) a snižte tak náklady při zachování souhrnné kvality.
Pokud potřebujete pouze jednu strategii, předejte ji přímo CompactionProvider bez zabalení do PipelineCompactionStrategy:
agentChatClient
.AsBuilder()
.UseAIContextProviders(new CompactionProvider(
new SlidingWindowCompactionStrategy(CompactionTriggers.TurnsExceed(20))))
.BuildAIAgent(...);
Registrace prostřednictvím ChatClientAgentOptions
Poskytovatel může být také zadán přímo na ChatClientAgentOptions.AIContextProviders:
AIAgent agent = agentChatClient
.AsBuilder()
.BuildAIAgent(new ChatClientAgentOptions
{
AIContextProviders = [new CompactionProvider(compactionPipeline)]
});
Poznámka:
Při registraci přes ChatClientAgentOptions není CompactionProviderzapojen během smyčky volání nástroje. Poskytovatelé kontextu na úrovni agenta běží před uložením historie chatu, takže všechny syntetické souhrnné zprávy vytvořené pomocí CompactionProvider mohou být součástí trvalé historie při použití ChatHistoryProvider. Pokud chcete komprimovat pouze kontext požadavku za provozu a zachovat původní uloženou historii, zaregistrujte poskytovatele na ChatClientBuilder přes UseAIContextProviders(...).
Ad hoc komprimace
CompactionProvider.CompactAsync použije strategii na libovolný seznam zpráv bez aktivní relace agenta:
IEnumerable<ChatMessage> compacted = await CompactionProvider.CompactAsync(
new TruncationCompactionStrategy(CompactionTriggers.TokensExceed(8000)),
existingMessages);
CompactionProvider je zprostředkovatel kontextu, který používá strategie komprimace před a po každém spuštění agenta. Přidejte ho spolu s poskytovatelem historie v seznamu agenta context_providers .
-
before_strategy— spouští se před voláním modelu, komprimace zpráv již načtených do kontextu. -
after_strategy— spustí se po volání modelu a zprávy uložené poskytovatelem historie jsou komprimovány, aby příští krok začal ve zmenšené podobě. -
history_source_idsource_id— poskytovatel historie, jehož uložené zprávyafter_strategyby měly být zkompaktněny (výchozí hodnota je"in_memory").
Registrace u agenta
from agent_framework import Agent, CompactionProvider, InMemoryHistoryProvider
from agent_framework._compaction import (
CharacterEstimatorTokenizer,
SlidingWindowStrategy,
SummarizationStrategy,
TokenBudgetComposedStrategy,
ToolResultCompactionStrategy,
)
tokenizer = CharacterEstimatorTokenizer()
pipeline = TokenBudgetComposedStrategy(
token_budget=16_000,
tokenizer=tokenizer,
strategies=[
ToolResultCompactionStrategy(keep_last_tool_call_groups=1),
SummarizationStrategy(client=summarizer_client, target_count=4, threshold=2),
SlidingWindowStrategy(keep_last_groups=20),
],
)
history = InMemoryHistoryProvider()
compaction = CompactionProvider(
before_strategy=pipeline,
history_source_id=history.source_id,
)
agent = Agent(
client=client,
name="ShoppingAssistant",
instructions="You are a helpful shopping assistant.",
context_providers=[history, compaction],
)
session = agent.create_session()
print(await agent.run("What's the price of a laptop?", session=session))
Návod
Pokud chcete snížit náklady a zachovat souhrnnou kvalitu, použijte menší, levnější model (například gpt-4o-mini) pro klienta souhrnu.
Pokud potřebujete jenom jednu strategii, předejte ji přímo jako before_strategy:
compaction = CompactionProvider(
before_strategy=SlidingWindowStrategy(keep_last_groups=20),
history_source_id=history.source_id,
)
Zhutnění uložené historie po každém spuštění
Slouží after_strategy k komprimci zpráv uložených poskytovatelem historie, aby budoucí změny začínaly omezeným kontextem:
compaction = CompactionProvider(
before_strategy=SlidingWindowStrategy(keep_last_groups=20),
after_strategy=ToolResultCompactionStrategy(keep_last_tool_call_groups=1),
history_source_id=history.source_id,
)
Ad hoc komprimace
apply_compaction aplikuje strategii na libovolný seznam zpráv mimo aktivní relaci agenta:
from agent_framework._compaction import apply_compaction, TruncationStrategy, CharacterEstimatorTokenizer
tokenizer = CharacterEstimatorTokenizer()
compacted = await apply_compaction(
messages,
strategy=TruncationStrategy(
max_n=8_000,
compact_to=4_000,
tokenizer=tokenizer,
),
tokenizer=tokenizer,
)
Volba strategie
| Strategie | Agresivita | Zachovává kontext. | Vyžaduje LLM. | Nejlepší pro |
|---|---|---|---|---|
ToolResultCompactionStrategy |
Nízká úroveň | Vysoká – sbalí pouze výsledky nástrojů. | Ne | Uvolnění místa z podrobného výstupu nástroje |
SummarizationCompactionStrategy |
Středně | Střední – nahrazuje historii souhrnem. | Ano | Dlouhé konverzace, kde záleží na kontextu |
SlidingWindowCompactionStrategy |
Vysoko | Nízká – poklesy celých otáček | Ne | Pevné omezení počtu otáček |
TruncationCompactionStrategy |
Vysoko | Nízká – pokles nejstarších skupin | Ne | Nouzové zajištění rozpočtu pro tokeny |
PipelineCompactionStrategy |
Configurable | Závisí na podřízených strategiích. | Závisí | Vrstvené komprimace s několika náhradními funkcemi |
| Strategie | Agresivita | Zachovává kontext. | Vyžaduje LLM. | Nejlepší pro |
|---|---|---|---|---|
ToolResultCompactionStrategy |
Nízká úroveň | Vysoká úroveň – zabalí výsledky nástroje do souhrnů. | Ne | Znovuzískání prostoru z příliš podrobného výstupu nástroje |
SelectiveToolCallCompactionStrategy |
Nízká–střední | Střední – zcela vylučuje staré skupiny volání nástrojů. | Ne | Odebrání historie nástrojů v případě, že už nejsou potřeba výsledky |
SummarizationStrategy |
Středně | Střední – nahrazuje historii souhrnem. | Ano | Dlouhé konverzace, kde záleží na kontextu |
SlidingWindowStrategy |
Vysoko | Nízká – pokles nejstarších skupin | Ne | Omezení počtu striktních skupin |
TruncationStrategy |
Vysoko | Nízká – pokles nejstarších skupin | Ne | Nouzové zprávy nebo záchranné mechanismy rozpočtu tokenů |
TokenBudgetComposedStrategy |
Configurable | Závisí na strategiích dětí. | Závisí | Vrstvené kompaktní vrstvení s omezením počtu tokenů a několika alternativními postupy |