内容
# 压缩层用于LLM应用
**上下文压缩层，用于LLM应用**
> 65–94% 更少的令牌。零质量损失。Claude、GPT、Gemini、Bedrock 和本地LLM的直接代理。
[](https://pypi.org/project/copium-ai/)
[](https://pypi.org/project/copium-ai/)
[](LICENSE)
[](https://github.com/iKislay/copium/actions)
[](https://copium-docs.vercel.app/docs)
<p>
<a href="https://copium-docs.vercel.app/docs">文档</a> ·
<a href="#get-started-60-seconds">安装</a> ·
<a href="#proof">证明</a> ·
<a href="#compared-to">替代方案</a> ·
<a href="#connect-your-ai-agent">代理指南</a> ·
<a href="https://github.com/iKislay/copium">GitHub</a>
</p>
---
## 这是什么？
你是否遇到过AI编码助手（如Claude Code、Cursor、Copilot等）在会话中途变慢，开始遗忘之前读取的内容，或者任务执行变差？这是由于上下文窗口已满。您的代理读取的每个文件、运行的每个命令、处理的每个工具输出都会累积成一个提示，该提示每次消息都需要从头开始读取。您每次都为此付费。
Copium 位于您的代理和AI提供商之间，压缩所有内容后再发送。它是一个本地代理 - 您的数据从未离开您的机器。相同的答案，令牌数量的一小部分。
实际的收益是巨大的：在50K+会话中**节省1.4亿令牌**的生产环境中。
---
## 快速入门（60秒）
```bash
# 安装
pip install "copium-ai[proxy]"
# 或使用uv（推荐）
uv tool install "copium-ai[proxy]"
# 启动代理
copium run # 监听 http://localhost:8082
# 将您的代理指向它（选择下面的工具）
export ANTHROPIC_BASE_URL=http://localhost:8082 # Claude Code
export OPENAI_API_BASE=http://localhost:8082/v1 # Cursor / Aider / OpenCode
# 实时查看节省的令牌
copium dashboard
# 或在浏览器中打开 http://localhost:8787/dashboard
```
就这样。无需配置文件。无需代码更改。Copium会自动压缩每个请求。
---
## 连接您的AI代理
### Claude Code
```bash
copium wrap claude
```
此单个命令启动代理并配置Claude Code通过它路由。当完成时，`copium unwrap claude`恢复所有内容。
或者，手动设置：
```bash
copium run &
export ANTHROPIC_BASE_URL=http://localhost:8082
claude # 或 claude-code，或 claude --dangerously-skip-permissions
```
### Cursor
```bash
copium run &
# 在Cursor设置 → OpenAI API基准URL：
# http://localhost:8082/v1
```
或通过环境：
```bash
export OPENAI_API_BASE=http://localhost:8082/v1
cursor .
```
### OpenCode
OpenCode使用OpenAI兼容的API格式：
```bash
copium run &
export OPENAI_BASE_URL=http://localhost:8082/v1
opencode
```
或在OpenCode配置中永久设置：
```json
{
"openai": {
"baseURL": "http://localhost:8082/v1"
}
}
```
### Aider
```bash
copium wrap aider
# 或手动：
aider --openai-api-base http://localhost:8082/v1
```
### Codex（OpenAI）
```bash
copium wrap codex
# 自动修补 ~/.codex/config.toml
# 撤销：copium unwrap codex
```
### GitHub Copilot
```bash
copium wrap copilot
```
这将Copilot路由到Copium，同时保留现有的身份验证。支持BYOK和订阅模式。
### Mistral / Vibe
```bash
copium wrap vibe
```
### 任意HTTP客户端/自定义应用
如果您的工具允许您设置基准URL或API端点：
```
http://localhost:8082 → Anthropic兼容
http://localhost:8082/v1 → OpenAI兼容
http://localhost:8082/bedrock → AWS Bedrock
http://localhost:8082/vertex → Vertex AI（Google Cloud）
```
### 作为Python库
如果您不想要代理，只想在内联压缩消息：
```python
import json
from copium import compress
# 适用于您发送给LLM的任何消息列表
data = json.load(open("data.json")) # 例如500项JSON数组
result = compress([{"role": "user", "content": json.dumps(data)}])
print(f"节省 {result.compression_ratio:.1%} 令牌")
# → 节省64.8%令牌
```
### 作为MCP服务器
```bash
pip install "copium-ai[mcp]"
```
然后添加到您的MCP客户端配置：
```json
{
"mcpServers": {
"copium": {
"command": "copium",
"args": ["mcp"]
}
}
}
```
暴露三个工具：`copium_compress`, `copium_retrieve`, `copium_stats`.
---
## 它是如何工作的？
您不需要理解这一点即可使用Copium。但如果您好奇：
```
您的代理/应用
（Claude Code，Cursor，Aider，OpenCode，您自己的代码...）
| 提示，工具输出，日志，RAG结果，文件
v
+----------------------------------------------------+
| Copium （本地运行 - 您的数据保留在此） |
| ------------------------------------------------- |
| 内容路由器→智能破碎机 | 压缩器
| 会话重复 | 错误压缩器
| 缓存对齐器 | TOON编码器
| 差异响应 | 输出压缩器
+----------------------------------------------------+
| 压缩提示（相同含义，更少的令牌）
v
LLM提供商 （Anthropic，OpenAI，Gemini，Ollama，Bedrock...）
```
每个组件针对特定类型的浪费：
| 组件 | 删除内容 | 典型节省 |
|---|---|---|
| **内容路由器** | 将每个块路由到最佳压缩器 | 20–60% |
| **智能破碎机** | 压缩JSON数组，重复的工具输出 | 40–95% |
| **会话重复** | 会话回合之间的重新发送文件内容 | 30–70% |
| **错误压缩器** | 详细堆栈跟踪→结构化错误卡 | 50–80% |
| **TOON编码器** | JSON数组→管道分隔表格 | 15–40% |
| **缓存对齐器** | 为提供商KV缓存命中稳定前缀 | 10–20% |
| **差异响应** | 发送重复工具调用的差异 | 最高95% |
| **输出压缩器** | 修剪详细助手响应 | 15–40% |
管道在~52ms的中位数开销中运行。您的代理不会注意到它的存在。
---
## 证明
### 真实内容类型的压缩
| 内容类型 | 之前（令牌） | 之后（令牌） | 节省 |
|---|---:|---:|---:|
| JSON数组（100项） | 3,163 | 297 | **90.6%** |
| 构建日志（200行） | 2,412 | 148 | **93.9%** |
| Shell输出（200行） | 3,238 | 469 | **85.5%** |
| JSON数组（500项） | 9,526 | 1,614 | **83.1%** |
| 重复工具输出 | 10,000 | 1,500 | **85%** |
| Git差异 | 3,000 | 300 | **90%** |
### 质量保留 - LLM准确性基准
最重要的事情：AI是否仍然给出正确的答案？
| 基准 | 基线（无压缩） | 使用Copium | 差异 |
|---|---:|---:|---|
| HTML提取（F1） | 0.958 | 0.919 | −0.039 |
| HTML召回 | — | **0.982** | 98.2%内容保留 |
| JSON针查找 | 4/4 | **4/4** | 87.6%压缩下100%准确率 |
| GSM8K（数学） | 0.870 | **0.870** | +/−0.000 |
| TruthfulQA（事实） | 0.530 | **0.560** | +0.030（改进） |
运行这些：
```bash
pip install "copium-ai[evals]" && pytest tests/test_evals/ -v -s
```
### 生产遥测（250+实例，50K+会话）
| 指标 | 值 |
|---|---|
| 总共节省令牌 | **14亿** |
| 中位数代理开销 | **52毫秒** |
| 中位数压缩（所有请求） | 4.8% |
| 重度工具使用会话 | **40–80%** |
大多数请求是短的对话回合 - 中位数4.8%的压缩对于这些是准确的。而Copium产生自身价值的地方是长代理会话中积累的工具输出、日志和搜索结果：那里可以看到40–94%。
---
## 何时有帮助？
**您将看到真正的收益如果：**
- 每天运行AI编码代理（Claude Code，Cursor，Codex等）
- 使用本地LLM，需要在上下文限制内
- 处理详细工具输出 - 构建日志，JSON，搜索结果，git差异
- 想要在量化模型（Q4_0，Q8_0）上扩展上下文窗口寿命
- 使用Copilot或其他订阅服务，并希望充分利用每个回合
**帮助不大如果：**
- 仅发送短的对话提示（中位数节省：4.8％）
- 已经使用提供商的原生压缩并且不需要更多
- 在一个沙盒环境中工作，本地进程无法运行
---
## 与替代方案比较
Copium **本地运行**，涵盖 **每个** 内容类型，与每个主要框架一起工作，并支持云和本地LLM。
| | 范围 | 部署 | 本地LLM | 可逆 |
|---|---|---|:---:|:---:|
| **Copium** | 所有上下文 - 工具，RAG，日志，文件，历史记录 | 代理，库，MCP | ✅ | ✅（CCR） |
| [Kompact](https://github.com/kompact) | 提示文本和模式 | Python库 | ❌ | ❌ |
| [Claw Compactor](https://github.com/claw) | 提示文本和结构 | Python库 | ❌ | ❌ |
| [Headroom](https://github.com/chopratejas/headroom) | 所有上下文 | 代理，库，中间件，MCP | ❌ | ✅（CCR） |
| [ContextZip](https://github.com/contextzip) | 会话历史记录/JSONL | Python CLI | ✅ | ✅（静态） |
| [RTK](https://github.com/rtk-ai/rtk) | CLI命令输出 | CLI包装器 | ✅ | ❌ |
| [lean-ctx](https://github.com/yvgude/lean-ctx) | CLI命令，MCP工具 | CLI包装器，MCP | ✅ | ❌ |
| [Compresr](https://compresr.ai), [Token Co.](https://thetokencompany.ai) | 发送到他们API的文本 | 主机API调用 | ❌ | ❌ |
| OpenAI压缩 | 会话历史记录 | 提供商原生 | ❌ | ❌ |
<details>
<summary><b>vs Kompact</b></summary>
Kompact是一个Python库，严格专注于压缩提示文本和JSON模式。Copium是一个完整的架构，处理流式工具输出，多轮会话重复和提供者缓存。
| | Copium | Kompact |
|---|---|---|
| **架构** | 代理，MCP，库 | 仅限库 |
| **工具输出** | SmartCrusher（统计） | 正则表达式/文本截断 |
| **会话重复** | ✅ 跨回合检索 | ❌ |
| **性能** | Rust核心逻辑 | 纯Python |
| **安全性** | 可逆（CCR） | 有损 |
</details>
<details>
<summary><b>vs Claw Compactor</b></summary>
Claw Compactor是一个高质量的14阶段管道，用于压缩提示，但仅限于库部署，不可逆压缩。Copium结合类似质量门控的管道，但包装在一个零代码代理中，可逆失败安全。
| | Copium | Claw Compactor |
|---|---|---|
| **零代码用法** | ✅ 代理库 | ❌ 仅限库 |
| **可逆性** | ✅ 压缩-缓存-检索 | ❌ 不可逆 |
| **质量门控** | ✅ 自动还原 | ❌ 手动 |
| **提供商支持** | 通用（Anthropic，Bedrock等） | 手动注入 |
</details>
<details>
<summary><b>vs Headroom</b></summary>
Copium和Headroom都压缩AI代理上下文。关键差异：
| | Copium | Headroom |
|---|---|---|
| **本地LLM支持** | ✅ （Ollama，VLLM，llama.cpp） | ❌ |
| **KV缓存精度检测** | ✅ （自动检测Q4_0/Q8_0/FP16） | ❌ |
| **上下文分页** | ✅ （LLM上下文的虚拟内存） | ❌ |
| **遥测** | 默认关闭（需手动开启） | 默认开启（需手动关闭） |
| **CCR完整性检查** | ✅ （SHA-256验证）| ❌ |
</details>
<details>
<summary><b>vs ContextZip</b></summary>
ContextZip处理静态对话存档（例如 `.jsonl` 文件）以压缩过去的会话。Copium实时处理代理的实时流量。
| | Copium | ContextZip |
|---|---|---|
| **目标** | 实时HTTP流量（代理） | 静态会话文件（.jsonl） |
| **机制** | 实时压缩/路由 | 事后重复数据删除 |
| **用例** | 代理运行时 | 存档或恢复过去的聊天记录 |
</details>
<details>
<summary><b>vs RTK</b></summary>
RTK要求您手动包装个别CLI命令（`rtk git status`）。Copium包装整个代理（`copium wrap claude`），自动捕获和压缩每个工具输出，无需更改命令输入方式。
</details>
<details>
<summary><b>vs Provider-native compaction</b></summary>
提供商压缩（OpenAI，Anthropic）仅压缩**对话历史记录**。Copium压缩**所有内容** - 工具输出，日志，RAG结果，文件 - 并将每种内容类型路由到最佳压缩器，然后再发送到提供商。
</details>
---
## 本地LLM支持
如果您运行Ollama，VLLM或llama.cpp，Copium有一个您在其他地方找不到的特定功能：**KV缓存精度检测**。
当量化模型的KV缓存太满时，精度会直线下降 - 并不是逐渐下降，而是精度突然下降：
```
Q4_0 KV Cache at 32K context = 2% accuracy (vs 37.9% for FP16)
```
Copium检测您的模型的量化类型，并在您接近临界点之前开始积极压缩。
```bash
copium doctor # 检测您的本地LLM设置并提出建议
```
它还支持**冷/热上下文分页** - 有效地为LLM的上下文窗口提供虚拟内存，将上下文减少高达93%。
---
## 配置
在项目根目录中创建`copium.json`以自定义行为：
```json
{
"mode": "optimize",
"cache_aligner": { "enabled": true },
"session_dedup": {
"enabled": true,
"similarity_threshold": 0.85
},
"error_compressor": {
"enabled": true,
"max_stack_frames": 0,
"preserve_security_warnings": true
}
}
```
禁用特定转换：
```bash
curl -H "X-Copium-Disable: toon,code_compressor" \
http://localhost:8082/v1/chat/completions
```
环境变量：
```bash
export COPIUM_PORT=8082
export COPIUM_HOST=0.0.0.0
export COPIUM_LOG_LEVEL=debug
export COPIUM_CCR_TTL_SECONDS=1800 # 压缩数据缓存时间
```
### 压缩预设
```bash
copium proxy --preset minimal # 仅结构转换；最安全
copium proxy --preset standard # 全栈；推荐（默认）
copium proxy --preset aggressive # 最大节省；更激进
copium proxy --preset local-llm # 为Ollama/VLLM/llama.cpp优化
copium proxy --preset lossless # 零质量损失转换
# 检查任意预设而不启动代理：
copium preset aggressive
```
### 查看您的节省
```bash
copium stats # 全部总结
copium stats --period session # 当前会话
copium stats --json # 机器可读输出
```
---
## 架构（好奇的人）
完整的请求管道：
```
请求 → 缓存对齐器 → 差异响应 → 会话重复 → KV缓存检测 → 内容路由器 → 错误压缩器 → 分页 → 输出压缩器 → TOON编码器 → 提供商
```
**内容路由器**决定为每段内容使用哪个压缩器。它检测内容类型（JSON数组，日志输出，代码，HTML，搜索结果，git差异）并将其路由到相应的转换器。转换决策会记录以确保透明度。
**智能破碎机**使用统计分析 - 基于方差的变更点检测，Kneedle算法用于优化K，BM25 + 嵌入相关性评分 - 来压缩工具输出数组，同时保留LLM实际需要的项目。它永远不会生成文本；输出仅包含原始数组中的项目。
**CCR（压缩-缓存-检索）**使压缩可逆。当SmartCrusher将1000项数组压缩为20项时，原始的1000项存储在本地（SHA-256验证）。LLM接收检索标记。如果它需要更多数据，它调用`copium_retrieve(hash, query)`并获取相关子集。最坏情况：LLM检索所需内容。最佳情况：它永远不需要。
**会话重复**跟踪整个对话期间的内容哈希（确切的SHA-256 +近似重复的MinHash）。如果在第3次回合中读取的文件在第15次回合中再次出现，只需发送一个引用标记到LLM。代理的查找开销小于毫秒。
**TOON编码器**将JSON数组转换为管道分隔的表格 - 相同的语义内容，令牌数量减少。`[{"name": "alice", "age": 30}, {"name": "bob", "age": 25}]`变为 `name | age\nalice | 30\nbob | 25`。LLM读取两者完美；表格使用的令牌减少60-80%。
**缓存对齐器**稳定提示前缀，以便提供商KV缓存实际命中。Anthropic和OpenAI提供前缀缓存（巨大的成本降低），但单个字符更改会使缓存失效。缓存对齐器将动态内容移动到系统消息的末尾，以便稳定的前缀保持稳定。
---
## 集成
| 您的设置 | 使用方法 |
|---|---|
| 任意Python应用 | `compress(messages)` |
| Anthropic / OpenAI SDK | `CopiumClient(original_client=...)` |
| Vercel AI SDK | Copium中间件 |
| LiteLLM | 回调集成 |
| LangChain | `CopiumChatModel(your_llm)` |
| Agno | `CopiumAgnoModel(your_model)` |
| MCP客户端 | `pip install "copium-ai[mcp]"` |
| 任意HTTP客户端 | `copium run`（代理模式） |
| Claude Code | `copium wrap claude` |
| Codex | `copium wrap codex` |
| Cursor | 在设置中将API基准URL设置为 |
| OpenCode | `export OPENAI_BASE_URL=http://localhost:8082/v1` |
| Aider | `copium wrap aider` |
| GitHub Copilot | `copium wrap copilot` |
| Mistral Vibe | `copium wrap vibe` |
| AWS Bedrock | `http://localhost:8082/bedrock` |
| Google Vertex AI | `http://localhost:8082/vertex` |
| Ollama | `copium run --backend ollama` |
---
## 文档
| 开始这里 | 更深入 |
|---|---|
| [快速入门](https://copium-docs.vercel.app/docs/quickstart) | [架构](https://copium-docs.vercel.app/docs/architecture) |
| [代理](https://copium-docs.vercel.app/docs/proxy) | [压缩工作原理](https://copium-docs.vercel.app/docs/compression) |
| [MCP工具](https://copium-docs.vercel.app/docs/mcp) | [基准测试](https://copium-docs.vercel.app/docs/benchmarks) |
| [配置](https://copium-docs.vercel.app/docs/configuration) | [限制](https://copium-docs.vercel.app/docs/limitations) |
| [迁移指南](https://copium-docs.vercel.app/docs/migration) | [预设](https://copium-docs.vercel.app/docs/configuration#presets) |
---
## 贡献
```bash
git clone https://github.com/iKislay/copium.git && cd copium
uv sync && uv run pytest
```
参见 [CONTRIBUTING.md](CONTRIBUTING.md)。
---
## 许可证
Apache 2.0 - 参见 [LICENSE](LICENSE)。
---
## 致谢
- **Pichay** （arXiv:2603.09023）- LLM上下文的虚拟内存分页
- **r/LocalLLaMA** 社区 - 识别和压力测试精度下降问题
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器