Prompt Compressor（语义压缩）

Aidy 内置了语义压缩能力，通过静态配置 plugins.prompt_compressor.* 与 route 级 plugin_config.prompt_compressor 配置。

语义压缩调用 LLMLingua-2 服务对 prompt 中冗余 token 进行压缩，在不显著损失语义的前提下降低 LLM 输入 token 消耗。

启用条件

Prompt Compressor 插件只有在同时满足以下条件时，才会被挂进请求链路：

静态配置 plugins.prompt_compressor.enable = true
静态配置中已提供 service_url
当前 route 配置了 plugin_config.prompt_compressor，且 enabled = true

如果以上任一条件不满足，Prompt Compressor 不会进入当前 route 的请求链路。

Prompt Compressor 当前只挂在 chat 的 forward hook 上，不处理 embeddings、models 等其他请求。

链路位置

Prompt Compressor 在以下插件之后执行：

semantic-cache（语义缓存命中时跳过压缩，节省延迟）

在以下插件之前执行：

guard（Guard 检测压缩后即将送往 LLM 的真实内容，避免检测与转发不一致）

完整链路：SemanticCache → PromptCompressor → Guard → Upstream LLM

静态配置

对应 TOML 配置节 [plugins.prompt_compressor]：

字段	类型	默认值	说明
`enable`	bool	false	全局开关
`service_url`	string	—	LLMLingua-2 服务地址，例如 `http://10.0.181.199:8089`
`timeout_ms`	int	10000	压缩服务调用超时（毫秒），默认 10s
`verbose_log`	bool	false	是否开启详细日志

示例：

[plugins.prompt_compressor]
enable = true
service_url = "http://10.0.181.199:8089"
timeout_ms = 10000
verbose_log = false

路由配置

route 级配置用于指定特定 route 的压缩策略，plugin_key 为 prompt_compressor，配置值对应：

常见配置场景

场景	推荐配置
Agent + 长系统提示	`target_ratio: 0.5, compress_roles: ["system"], min_token_threshold: 500`
RAG + 检索上下文	`target_ratio: 0.4, compress_roles: ["system", "user"], force_retain_last_n: 1`
多轮对话	`target_ratio: 0.6, compress_roles: ["system", "assistant"], force_retain_last_n: 2`
低延迟优先	`target_ratio: 0.7, min_token_threshold: 1000`

运行时行为

插件进入链路后，会按以下顺序工作：

预检查：估算当前请求 token 数；低于 min_token_threshold 时直接 Skip，不调用压缩服务
消息提取：按 compress_roles 过滤需要压缩的消息；保留最后 force_retain_last_n 条用户消息不压缩
调用 LLMLingua-2：对每条可压缩消息调用 POST /v1/compress；压缩后 token 数 ≥ 原始时丢弃（保留原文）
回填：将压缩后内容写回 RequestIR，后续插件和上游 LLM 看到的是压缩后的内容
设置响应头与日志：写入压缩状态头和 ext_fields

压缩状态

Compressed

压缩成功
设置 X-Prompt-Compressor-Status: Compressed
设置 X-Prompt-Compressor-Saved-Tokens: <节省的 token 数>
设置 X-Prompt-Compressor-Ratio: <压缩比>

Skip

以下情况会跳过压缩（不调用 LLMLingua-2 服务，无附加延迟）：

估算 token 数 < min_token_threshold
无可压缩消息（所有消息角色均不在 compress_roles 中，或用户消息全部被 force_retain_last_n 保留）

Bypass

以下情况会 Bypass（发送原始 prompt，请求正常继续）：

LLMLingua-2 服务不可达
压缩服务响应超时（timeout_ms）
压缩服务返回非 200
压缩结果为空

Bypass 时会记录 warn 级日志，不影响请求最终结果。

核心原则：压缩永远不阻塞请求，所有失败均降级为 Bypass 发送原始 prompt。

响应头

Header	值	条件
`X-Prompt-Compressor-Status`	`Compressed` / `Skip` / `Bypass`	始终设置
`X-Prompt-Compressor-Saved-Tokens`	如 `1960`	压缩成功时
`X-Prompt-Compressor-Ratio`	如 `3.31`	压缩成功时

请求日志

ext_fields.prompt_compressor 使用以下 Proto：

LLMLingua-2 服务

语义压缩调用的外部服务接口为：

POST /v1/compress

请求体：

{
  "prompt": "<待压缩文本>",
  "rate": 0.5
}

响应体：

{
  "compressed_prompt": "<压缩后文本>",
  "origin_tokens": 45,
  "compressed_tokens": 22,
  "ratio": 0.489
}

健康检查：

GET /healthz

响应：{"ok": true}（ok: false 表示模型还在加载）

当前服务部署地址：http://10.0.181.199:8089

启用条件​

链路位置​

静态配置​

路由配置​

常见配置场景​

运行时行为​

压缩状态​

Compressed​

Skip​

Bypass​

响应头​

请求日志​

LLMLingua-2 服务​