# 异步上下文压缩过滤器

**作者:** [Fu-Jie](https://github.com/Fu-Jie) | **版本:** 1.0.0 | **许可证:** MIT

> **重要提示**：为了确保所有过滤器的可维护性和易用性，每个过滤器都应附带清晰、完整的文档，以确保其功能、配置和使用方法得到充分说明。

本过滤器通过智能摘要和消息压缩技术，在保持对话连贯性的同时，显著降低长对话的Token消耗。

---

## 核心特性

-   ✅ **自动压缩**: 基于消息数量阈值自动触发上下文压缩。
-   ✅ **异步摘要**: 在后台生成摘要，不阻塞当前对话的响应。
-   ✅ **持久化存储**: 支持 PostgreSQL 和 SQLite 数据库，确保摘要在服务重启后不丢失。
-   ✅ **灵活保留策略**: 可自由配置保留对话头部和尾部的消息数量，确保关键信息和上下文的连贯性。
-   ✅ **智能注入**: 将生成的历史摘要智能地注入到新的上下文中。

详细的工作原理和流程请参考 [工作流程指南](WORKFLOW_GUIDE_CN.md)。

---

## 安装与配置

### 1. 环境变量

本插件的运行依赖于数据库，您**必须**在 Open WebUI 的环境变量中配置 `DATABASE_URL`。

-   **PostgreSQL 示例**:
    ```
    DATABASE_URL=postgresql://user:password@host:5432/openwebui
    ```
-   **SQLite 示例**:
    ```
    DATABASE_URL=sqlite:///path/to/your/data/webui.db
    ```

### 2. 过滤器顺序

建议将此过滤器的优先级设置得相对较高（数值较小），以确保它在其他可能修改消息内容的过滤器之前运行。一个典型的顺序可能是：

1.  **前置过滤器 (priority < 10)**
    -   例如：注入系统级提示的过滤器。
2.  **本压缩过滤器 (priority = 10)**
3.  **后置过滤器 (priority > 10)**
    -   例如：对最终输出进行格式化的过滤器。

---

## 配置参数

您可以在过滤器的设置中调整以下参数：

### 核心参数

| 参数 | 默认值 | 描述 |
| :--- | :--- | :--- |
| `priority` | `10` | 过滤器执行顺序，数值越小越先执行。 |
| `compression_threshold_tokens` | `64000` | **(重要)** 当上下文总 Token 数超过此值时，将在后台触发摘要生成。建议设置为模型最大上下文窗口的 50%-70%。 |
| `max_context_tokens` | `128000` | **(重要)** 上下文的硬性上限。如果超过此值，将强制移除最早的消息（保留受保护消息除外）。防止 Token 溢出。 |
| `keep_first` | `1` | 始终保留对话开始的 N 条消息。第一条消息通常包含重要的系统提示或环境变量，建议至少保留 1 条。 |
| `keep_last` | `6` | 始终保留对话末尾的 N 条消息，以确保最近对话的连贯性。 |

### 摘要生成配置

| 参数 | 默认值 | 描述 |
| :--- | :--- | :--- |
| `summary_model` | `None` | 用于生成摘要的模型 ID。**强烈建议**配置一个快速、经济且上下文窗口较大的模型（如 `gemini-2.5-flash`）。如果留空，将尝试使用当前对话的模型。 |
| `max_summary_tokens` | `16384` | 生成摘要时允许的最大 Token 数。 |
| `summary_temperature` | `0.1` | 控制摘要生成的随机性，较低的值结果更稳定。 |

### 高级配置

#### `model_thresholds` (模型特定阈值)

这是一个字典配置，允许您为特定的模型 ID 覆盖全局的 `compression_threshold_tokens` 和 `max_context_tokens`。这对于混合使用不同上下文窗口大小的模型非常有用。

**默认配置包含了主流模型（如 GPT-4, Claude 3.5, Gemini 1.5/2.0, Qwen 2.5/3, DeepSeek V3 等）的推荐阈值。**

**配置示例：**

```json
{
  "gpt-4": {
    "compression_threshold_tokens": 8000,
    "max_context_tokens": 32000
  },
  "gemini-2.5-flash": {
    "compression_threshold_tokens": 734000,
    "max_context_tokens": 1048576
  }
}
```

#### `debug_mode`

-   **默认值**: `true`
-   **描述**: 是否在 Open WebUI 的控制台日志中打印详细的调试信息（如 Token 计数、压缩进度、数据库操作等）。生产环境建议设为 `false`。

---

## 故障排除

-   **问题：数据库连接失败**
    -   **解决**：请确认 `DATABASE_URL` 环境变量已正确设置，并且数据库服务运行正常。

-   **问题：摘要未生成**
    -   **解决**：检查 `compression_threshold_tokens` 是否已达到，并确认 `summary_model` 配置正确。查看日志以获取详细错误。

-   **问题：初始的系统提示丢失**
    -   **解决**：确保 `keep_first` 的值大于 0，以保留包含重要信息的初始消息。

-   **问题：压缩效果不明显**
    -   **解决**：尝试适当提高 `compression_threshold_tokens`，或减少 `keep_first` / `keep_last` 的值。
