153 lines
8.2 KiB
Markdown
153 lines
8.2 KiB
Markdown
---
|
||
title: "ContextCompressor CJK token estimation undercounted by 4x"
|
||
date: 2026-07-03
|
||
module: core/compressor
|
||
component: assistant
|
||
tags:
|
||
- cjk
|
||
- token-estimation
|
||
- context-compression
|
||
- react-engine
|
||
- heuristic
|
||
problem_type: logic_error
|
||
severity: high
|
||
symptoms:
|
||
- "estimate_tokens() uses len(content) // 4 (ASCII heuristic), undercounting CJK tokens by ~4x since CJK chars are ~1 char per token"
|
||
- "Context compression triggers too late for CJK-heavy conversations, risking context window overflow"
|
||
- "_summarize() pre-truncation uses max_chars = max_input_tokens * 4, allowing CJK text to send 4x the token budget to the LLM"
|
||
- "ReActEngine._should_compress() fallback inherits the same flawed len // 4 estimation for compressors without should_compress()"
|
||
root_cause: logic_error
|
||
resolution_type: code_fix
|
||
---
|
||
|
||
## Problem
|
||
|
||
`ContextCompressor.estimate_tokens()` 使用 `len(content) // 4`（ASCII 启发式，4 字符 ≈ 1 token）估算 token 数。对 CJK（中文/日文/韩文）文本而言，1 个字符 ≈ 1 token，因此该估算器将 CJK token 数低估约 4 倍。这导致 CJK 为主的会话压缩触发过晚，存在上下文窗口溢出风险。`_summarize()` 的预截断 `max_chars = max_input_tokens * 4` 进一步放大了问题——允许 CJK 文本向 LLM 发送 4 倍 token 预算的输入。
|
||
|
||
## Symptoms
|
||
|
||
- CJK 为主的会话在远超预期阈值（约 4 倍）后才触发压缩，`should_compress()` 返回 `False` 而实际 token 已超出 `model_context_limit`
|
||
- `_summarize()` 可能向 LLM 发送 4 倍 token 预算的 CJK 文本（P1 缺陷——可能触发上下文上限 / 400 错误）
|
||
- 中文长会话面临上下文窗口溢出 / 请求失败的高风险
|
||
- 压缩流程依赖递归深度 `_compression_depth`，难以观测与调试，缺乏结构化日志
|
||
|
||
## What Didn't Work
|
||
|
||
旧的 `len(content) // 4` 估算器基于 ASCII/拉丁语平均比例（约 4 字符/token）。对纯 CJK 文本（1 字符 ≈ 1 token），该估算产生约 4 倍偏低的估计。例如：4000 个中文字符会被估算为 1000 token，但实际约 4000 token。这导致：
|
||
|
||
- `should_compress()` 的 headroom 阈值（`model_context_limit * 0.8`）直到实际 token 已 4 倍超出预期阈值才触发
|
||
- `_summarize()` 中 `max_chars = max_input_tokens * 4` 在预算为 3200 token 时放行 12800 字符（≈12800 CJK token）— 此 P1 缺陷由 ce-code-review 捕获 (session history)
|
||
- 旧的递归式 `compress()` 依赖 `_compression_depth` 计数器，流程难以阅读，且 `_compress_aggressive()` 接收已压缩的 `compressed` 列表，存在 summary-of-summary（F-010）风险
|
||
|
||
## Solution
|
||
|
||
**1. 新增 CJK 感知的 token 估算器**（`src/agentkit/core/compressor.py`）：
|
||
|
||
```python
|
||
def _is_cjk(char: str) -> bool:
|
||
"""Check if a character is CJK (1 token ≈ 1 char)."""
|
||
cp = ord(char)
|
||
return (
|
||
0x4E00 <= cp <= 0x9FFF # CJK Unified Ideographs
|
||
or 0x3040 <= cp <= 0x30FF # Hiragana + Katakana
|
||
or 0xAC00 <= cp <= 0xD7AF # Hangul Syllables
|
||
)
|
||
|
||
|
||
def estimate_text_tokens(text: str) -> int:
|
||
"""Estimate token count: CJK 1:1, other characters 4:1."""
|
||
cjk_count = 0
|
||
non_cjk_count = 0
|
||
for char in text:
|
||
if _is_cjk(char):
|
||
cjk_count += 1
|
||
else:
|
||
non_cjk_count += 1
|
||
return cjk_count + non_cjk_count // 4
|
||
```
|
||
|
||
`estimate_tokens()` 改用 `estimate_text_tokens()`：
|
||
|
||
```python
|
||
def estimate_tokens(self, messages: list[dict]) -> int:
|
||
"""Estimate total tokens in message list (CJK 1:1, ASCII 4:1)"""
|
||
return sum(estimate_text_tokens(str(m.get("content", ""))) for m in messages)
|
||
```
|
||
|
||
**2. 修复 `_summarize()` 预截断**（P1 缺陷，由 ce-code-review 捕获）：
|
||
|
||
```python
|
||
# 修改前（CJK 可 4 倍超预算）:
|
||
max_chars = max_input_tokens * 4
|
||
|
||
# 修改后（CJK 1:1 精确，ASCII 4:1 保守）:
|
||
max_chars = max_input_tokens
|
||
conversation_text = conversation_text[:max_chars] + "\n...[truncated]"
|
||
```
|
||
|
||
**3. `ReActEngine._should_compress()` 回退路径同步使用 `estimate_text_tokens`**（`src/agentkit/core/react.py` 约 1750 行）：
|
||
|
||
```python
|
||
# Fallback: fixed threshold for compressors without headroom support
|
||
estimated_tokens = sum(
|
||
estimate_text_tokens(str(m.get("content", ""))) for m in conversation
|
||
)
|
||
return estimated_tokens > self._DEFAULT_COMPRESS_THRESHOLD
|
||
```
|
||
|
||
**4. 重写 `compress()` 为线性流程**，移除递归式 `_compression_depth`：
|
||
|
||
```python
|
||
async def compress(self, messages: list[dict]) -> list[dict]:
|
||
"""Linear flow: summarize -> aggressive -> truncate."""
|
||
tokens_before = self.estimate_tokens(messages)
|
||
if tokens_before <= self._max_tokens:
|
||
return messages
|
||
# ... 分离 system/old/recent ...
|
||
# Step 1: summarize
|
||
# Step 2: aggressive (F-010: 传入原始 messages 而非 compressed，避免 summary-of-summary)
|
||
if self.estimate_tokens(compressed) > self._max_tokens:
|
||
compressed = await self._compress_aggressive(messages)
|
||
# Step 3: truncate as last resort
|
||
if self.estimate_tokens(compressed) > self._max_tokens:
|
||
compressed = self._truncate(compressed)
|
||
# Step 4: 结构化日志
|
||
self._log_compression(tokens_before, tokens_after, len(messages), len(compressed), strategy)
|
||
return compressed
|
||
```
|
||
|
||
**5. 新增 `_log_compression()` 结构化日志**：
|
||
|
||
```python
|
||
logger.info(
|
||
"context compressed: %d -> %d tokens (%.1f%%), messages: %d -> %d, strategy: %s",
|
||
tokens_before, tokens_after, ratio * 100,
|
||
msg_count_before, msg_count_after, strategy,
|
||
)
|
||
```
|
||
|
||
## Why This Works
|
||
|
||
**根本原因**：CJK 字符在主流 tokenizer（BPE/WordPiece/SentencePiece）中近似 1:1 映射为 token，而 ASCII/拉丁文约 4 字符/token。`len(content) // 4` 把这 4 倍差异抹平了，导致 CJK 估算系统性偏低。
|
||
|
||
修复后的 `estimate_text_tokens()` 对 CJK 字符按 1:1 计数、对非 CJK 保留 4:1，既纠正了 CJK 偏差又维持了 ASCII 行为。`_summarize()` 的 `max_chars = max_input_tokens` 对 CJK 精确（1:1）、对 ASCII 保守（截断到 1/4 预算但安全），彻底消除了"4 倍超预算"路径。
|
||
|
||
`headroom_threshold=0.8` 吸收了纯 CJK 仍可能存在的 10-20% 估算偏差（`ponytail:` 注释已标注上限与升级路径——`litellm.token_counter` 或 provider 专用 tokenizer）。
|
||
|
||
**可维护性改进**：线性 `compress()` 流程（summarize → aggressive → truncate）移除了递归深度计数器，单次读取即可理解全部降级路径；`_compress_aggressive()` 接收原始 `messages` 而非已压缩的 `compressed`，规避了 F-010 的 summary-of-summary；`_log_compression()` 提供结构化观测字段（before/after/ratio/msg_count/strategy），使压缩行为可调试、可告警。
|
||
|
||
## Prevention
|
||
|
||
- **字符集感知的估算启发式**：任何 token 估算逻辑必须考虑字符集差异。`len // 4` 仅对 ASCII 成立；CJK/emoji/其他多字节脚本需分别处理。涉及多语言输入时，优先使用 `litellm.token_counter` 或 provider 专用 tokenizer（当前 `estimate_text_tokens` 的 `ponytail` 注释已标注此升级路径）
|
||
- **修改估算逻辑时审计所有依赖的截断点**：本次修复同步审计了 `estimate_tokens()`、`_summarize()` 预截断、`ReActEngine._should_compress()` 回退路径。`_truncate()` 仍用 `len(content) > self._max_tokens * 4` 判断（OQ21 延期项），后续需同步迁移至字符集感知逻辑
|
||
- **测试覆盖字符集矩阵**：新增测试覆盖纯 CJK、纯 ASCII、CJK+ASCII 混合、平假名/片假名、谚文等场景（`tests/unit/test_context_compressor.py`），验证估算器在各字符集下的正确性
|
||
- **避免 summary-of-summary**：多级压缩时，后续阶段应接收原始输入而非前级压缩产物，防止信息逐级失真（F-010 教训）
|
||
- **结构化日志先行**：压缩是黑盒操作，必须输出 before/after token、压缩比、消息数、策略等结构化字段，便于线上问题定位
|
||
|
||
## References
|
||
|
||
- Plan: `docs/plans/2026-07-02-003-feat-context-compressor-cjk-prefix-enhancement-plan.md`（3 轮 ce-doc-review，收敛到 U1 + U3）
|
||
- PR #21: `feat/context-compressor-cjk`（commits `be45fe4` + `3a05c4d`）
|
||
- Upstream context: `docs/plans/2026-06-24-004-feat-long-horizon-reliability-optimization-plan.md`（headroom 压缩引入点）
|
||
- Residual: OQ21（`_truncate()` `* 4` 一致性，P2 manual 跟进）
|