Sensei

<div align="center"> <img src="frontend/public/sensei.svg" width="88" height="88" alt="" /> # Sensei ### 您的AI工具，使用极少量的令牌。 _{一个自我托管的工作空间，基于<a href="https://github.com/headroomlabs-ai/headroom">Headroom</a>的压缩理念和<a href="https://github.com/pewdiepie-archdaemon/odysseus">Odysseus</a>的工作空间设计。} [](https://github.com/SenseiIssei/Sensei/actions/workflows/ci.yml) [](https://github.com/SenseiIssei/Sensei/actions/workflows/security.yml) [](LICENSE) [](https://python.org) </div> --- ## 一张图解释 AI工具会向模型发送大量文本。大多数文本都是重复的——文件列表、构建日志、JSON数据块。你为每个字符付费。 Sensei坐在中间，将文本压缩后再发送。模型仍然获得所需的所有信息；你只需为有用的信息付费。 ```mermaid flowchart LR A["🧑‍💻 您的AI工具<br/><sub>Claude Code, Cursor, Aider…</sub>"] B["🥋 Sensei<br/><sub>运行在您的机器上</sub>"] C["☁️ 模型<br/><sub>Anthropic, OpenAI, 或本地</sub>"] A -- "50,000 tokens" --> B B -- "10,000 tokens" --> C C -- "答案" --> B B -- "答案" --> A style B fill:#16a34a,stroke:#22c55e,color:#fff ``` **您的工作方式不会改变。** 使用相同的工具、相同的API密钥、相同的答案。只是账单变小了。 --- ## 账单会小多少？ 这些是实际测量结果，而不是估计值。您可以用一条命令运行它们（参见[给极客们](#-给极客们)）。 ```mermaid xychart-beta title "按内容类型划分的令牌移除情况" x-axis ["构建日志", "JSON输出", "搜索结果", "堆栈跟踪", "正文", "代码"] y-axis "% removed" 0 --> 100 bar [88, 79, 69, 61, 44, 40] ``` **在现实情况下：79% 的令牌减少。** 对于JSON和日志——这是AI编码工具花费大部分预算的地方——没有任何信息丢失。Sensei重构文本，而不是总结它，因此模型看到的是相同的事实。 > **这意味着什么。** 如果您每月在API调用上花费€100，输入端的79％减少是账单中的很大一部分。Sensei为您显示运行总计：`sensei stats`。 --- ## 开始使用 您需要Python 3.11或更新版本。仅此而已。 **1. 安装** ```bash pip install -e ./backend ``` **2. 启动它** ```bash sensei up ``` 您的浏览器会打开并询问您一个问题：您想在自己的计算机上运行模型（免费），还是使用OpenAI等服务（粘贴密钥）。选择一个，点击保存。完成。 **3. 将工具指向它** ```bash sensei wrap claude ``` Claude Code现在通过Sensei运行。所有功能与以前完全相同。 对于`codex`、`aider`、`cursor-agent`、`cline`、`continue`、`opencode`、`goose`和`crush`也是如此——只需替换名称。 **或用作MCP服务器** 如果您的工具使用[MCP](https://modelcontextprotocol.io)，Sensei可以直接连接——无需更改基准URL： ```jsonc { "mcpServers": { "sensei": { "command": "sensei", "args": ["mcp"] } } } ``` 代理获得三个工具：压缩blob后再放入上下文中，根据需要获取确切的原始数据，并检查已保存的内容。需要`pip install "sensei[mcp]"`。 <details> <summary><b>更喜欢Docker？</b></summary> ```bash git clone https://github.com/SenseiIssei/Sensei.git && cd Sensei docker compose up -d ``` 然后打开 <http://localhost:7000/app/>. </details> --- ## 它是什么样子 > **需要截图。** 这些图片还不在仓库中。如果您运行Sensei，截图设置屏幕和聊天窗口将是一个有用的贡献——将它们放入`docs/screenshots/`并打开PR。参见[`docs/screenshots/README.md`](docs/screenshots/README.md)。 以下是命令行显示的内容，这是实际输出： ```console $ sensei models 您的机器 系统 Windows 11 (AMD64) CPU 16 cores RAM 15.3 GB GPU 未检测到 — 模型将在CPU上运行 预算 7.7 GB 可用于模型 建议适用于此机器 Qwen2.5 Coder 7B 7B 4.6 GB 舒适地适应 代码补全和审查。与网关配对。 Llama 3.2 3B 3B 2.0 GB 舒适地适应 普通聊天，硬件适中。合理的下限。 GLM-5.2 744B MoE 390.6 GB 太大 从这里开始： sensei models --pull qwen2.5-coder:7b ``` 某些东西无法正常工作？Sensei会告诉您如何处理： ```console $ sensei doctor [+] Python 3.12.10 在 Windows AMD64 [+] 配置文件 D:\Sensei\.env [!] Ollama 未安装 -> 可选。对于免费的本地推理：https://ollama.com [x] 模型访问 无本地模型和API密钥 — Sensei无法回答任何问题 -> 安装Ollama（免费，本地）或运行`sensei up`并在设置向导中粘贴API密钥。 [+] 端口 127.0.0.1:7000 是空闲的 [+] 绑定地址 127.0.0.1 ``` --- ## 您的数据仍然属于您 这比令牌节省更重要，因此值得具体说明。 | | | |---|---| | 🔒 **仅在您的机器上运行** | Sensei监听`127.0.0.1`。除非您故意更改，否则您的网络上的任何内容都无法访问它。 | | 🚫 **没有遥测数据** | 没有分析数据，没有崩溃报告，没有“匿名使用数据”。不在任何构建中，不在任何标志后面。 | | 📡 **没有第三方请求** | 接口不会从任何人加载字体、脚本或跟踪器。此功能在每次提交时自动检查。 | | 🔑 **您的密钥仍然属于您** | Sensei将您的API密钥转发给您选择的提供商，而不是其他人。它在磁盘上加密，永远不会以纯文本写入。 | | ✂️ **机密信息剥离** | 可选地，Sensei在提示离开您的计算机之前会删除密码、令牌和密钥。 | | 📴 **离线工作** | 如果服务器未运行，界面仍然打开并告诉您如何启动它。 | --- ## 常见问题 <details> <summary><b>这会让AI变差吗？</b></summary> 对于日志和JSON——大部分编码工具发送的内容——不会。Sensei将这些文本重写为更密集的形式，包含相同的事实，而不是总结它们。对于正文，它会删除填充内容（“需要注意的是” → 没有），这是模型通常忽略的文本类型。 如果模型确实需要原始数据，它可以要求它：Sensei保留了它压缩的所有内容的本地副本，并按需返回。 </details> <details> <summary><b>我需要更改我的代码或工具吗？</b></summary> 不。`sensei wrap claude`为该程序设置了一个环境变量并启动它。不会写入您的shell配置文件，不会在您的工具中安装任何内容，关闭它会恢复所有内容。 </details> <details> <summary><b>我仍然需要API密钥吗？</b></summary> 仅当您想使用托管模型时。Sensei可以使用[Ollama](https://ollama.com)完全在您自己的计算机上运行——`sensei models`会告诉您哪些模型实际上适合您的内存。 </details> <details> <summary><b>它是免费的吗？</b></summary> 是的。MIT许可，无付费层级，无功能保留。参见[原则](ROADMAP.md#principles)。 </details> <details> <summary><b>如果我不喜欢它怎么办？</b></summary> `pip uninstall sensei`。Sensei将其数据存储在您运行它的目录下的点目录中；删除它们，什么也不会留下。 </details> --- ## 给极客们 <details> <summary><b>架构</b></summary> Sensei是一个FastAPI服务，支持OpenAI和Anthropic线协议，因此任何具有可配置基准URL的工具都可以路由到它而不发生变化。 ```mermaid flowchart TB subgraph client["客户端"] CC["Claude Code<br/><sub>ANTHROPIC_BASE_URL</sub>"] CX["Codex / Cursor / Aider<br/><sub>OPENAI_BASE_URL</sub>"] WEB["Web UI"] CLI["CLI · Qt app · VS Code ext"] end subgraph sensei["Sensei"] GW["网关<br/><sub>/v1/chat/completions · /v1/messages</sub>"] RT["内容路由器<br/><sub>检测类型，选择压缩器</sub>"] subgraph comp["压缩器"] SC["SmartCrusher<br/><sub>JSON → CSV模式</sub>"] LC["LogCompressor<br/><sub>分类 + 去重</sub>"] CD["CodeCompressor<br/><sub>注释、导入</sub>"] TC["TextCompressor<br/><sub>填充、模板</sub>"] end CA["CacheAligner<br/><sub>保持前缀字节精确</sub>"] CCR["CCR存储<br/><sub>原始数据，可检索</sub>"] RED["DLP红外<br/><sub>剥离机密</sub>"] end PROV["提供商<br/><sub>Anthropic · OpenAI · Ollama · 11 more</sub>"] CC --> GW CX --> GW WEB --> GW CLI --> GW GW --> RT RT --> SC & LC & CD & TC SC & LC & CD & TC --> CA CA --> RED RED --> PROV RT -.存储原件.-> CCR CCR -.按需.-> PROV style sensei fill:#0a0a0f,stroke:#22c55e style comp fill:#111827,stroke:#374151``` 系统故意保持字节相同。提供商基于精确的前缀匹配缓存，因此更改它将使缓存失效，并节省的延迟比压缩节省的更多。 </details> <details> <summary><b>每个压缩器的工作原理</b></summary> **SmartCrusher — JSON.** 数组对象具有相同的键，每个元素重复每个键名。它被重写为一个头部加行，这就是CSV的内容，并且会删除冗余的链接/自我/引用键。无损。 ``` [{"id":1,"name":"a","url":"…"},{"id":2,"name":"b","url":"…"}, …20 more] ↓ id|name|url 1|a|… 2|b|… ``` **LogCompressor — 构建和测试输出.** 保留头部、尾部、每个错误/警告/摘要模式匹配的行，以及每个错误后的几行上下文。相同的行在标准化时间戳、十六进制地址和UUID后折叠，因此一千个几乎相同的工人行变成一个，并带有计数。 **CodeCompressor — 源代码.** 剥离注释、文档字符串、空行和尾部空格，并按语言折叠连续的导入块。每个语言使用正则驱动程序而不是完整的解析，以速度为目标且零依赖。 **TextCompressor — 正文.** 短语替换（“为了” → “to”）、填充移除、模板句子剥离和行级去重。 **CCR — 可逆压缩.** 每个原始数据都写入本地缓存，键控为id。如果模型决定需要未触摸的文本，它会按id请求并获取。 </details> <details> <summary><b>MCP服务器</b></summary> `sensei mcp`通过stdio使用Model Context Protocol，涵盖不允许您重定向基准URL的工具 - 以及代理想要压缩特定blob的情况。 | 工具 | 它做什么 | |---|---| | `sensei_compress` | 压缩文本。返回压缩表单、 `ccr_id`、令牌计数和节省百分比。可选地强制使用`content_type`压缩器。 | | `sensei_retrieve` | 交换`ccr_id`以获取字节相同的原件。 | | `sensei_stats` | 总节省加上CCR缓存状态。 | `sensei_retrieve`使此功能安全而不是默认情况下有损压缩。如果模型决定压缩表单缺少某些内容，它会请求原始数据而不是猜测。服务器的指令告诉客户端确切这一点，因为模型可能不知道一个模型不具备的功能。 通过端到端验证对抗真正的MCP客户端——582 → 287令牌，40记录的JSON数组，原始字节相同。 ```bash pip install "sensei[mcp]" sensei mcp # stdio;通常您的客户端会启动这个，而不是您 ``` </details> <details> <summary><b>性能</b></summary> 压缩位于每个请求的热路径上，因此其自身成本很重要。在86 kB代理回合——系统提示、交换、大量JSON工具结果、构建日志和源代码： | | 之前优化 | 之后 | |---|---|---| | 中位数 | 8.14毫秒 | **4.68毫秒** | | p95 | 12.53毫秒 | **6.31毫秒** | | 冷启动 | 9.34毫秒 | 6. | 6.91毫秒 | 可选的Rust加速器（`sensei_core`，PyO3，abi3）使JSON热路径大约快两倍。CI构建轮子并在每次提交时用整个测试套件重新运行它，因此“与Python路径相同”得到验证而不是断言。 </details> <details> <summary><b>重现数字</b></summary> ```bash python backend/benchmarks/compression_benchmark.py ``` 实际的`tiktoken`（`cl100k_base`）计数在固定工具输出、日志、堆栈跟踪、源代码和正文的语料库上。 `--json` 提供机器可读的输出， `--min-aggregate 75` 以非零退出，如果压缩质量低于某个阈值 - 这是夜间CI运行的内容，因此压缩质量的回归在生成之前失败，而不是在几个月后才注意到。 </details> <details> <summary><b>安全模型</b></summary> Sensei假设运行它的机器是受信任的，并且可以访问端口的任何人都是授权的。其他一切都由此而来： - 绑定到`127.0.0.1`。公开它是一种刻意的行为，如果您不启用身份验证，`sensei doctor`会将其报告为失败。 - API密钥存储在AES-256-GCM加密的保险箱中，而不是在`.env`中。 - 可选的DLP红外线减少了API密钥、令牌、私钥、JWT和可选的PII从提示中剥离。 - 可选的每个用户身份验证、JWT会话、OIDC SSO和RBAC在管理端点上。 - `run_python`默认情况下关闭。启用时，它是一个带有超时限制的子进程，而不是容器 - 文档明确说明了这一点。 完整的范围和报告流程： [SECURITY.md](SECURITY.md)。 </details> <details> <summary><b>仓库布局</b></summary> ``` backend/ FastAPI服务、压缩管道、CLI、测试 sensei/ compression/ SmartCrusher、LogCompressor、CodeCompressor、TextCompressor、 CacheAligner、CCR、ContentRouter routers/ gateway、chat、RAG、agent、settings、setup、stats、… security/ auth、crypto、vault、redaction、RBAC、OIDC、sessions cli/ up · wrap · doctor · models · stats · chat benchmarks/ 压缩基准 frontend/ React 19 + Tailwind 4 + Vite 8，PWA rust/sensei_core/ 可选的PyO3加速器 extensions/vscode VS Code扩展 training/ Sensei-Compressor微调脚手架 deploy/ nginx · Caddy · Traefik · systemd docs/ 配置参考（从pydantic模型生成）、计划 ``` </details> <details> <summary><b>CI实际执行的操作</b></summary> 每个操作都固定到一个提交SHA。在每个拉取请求上： - 跨{Linux，macOS，Windows} × Python {3.11，3.12，3.13}运行后端测试 - `ruff` lint和格式化，使用固定的规则集，以便新的ruff版本不会使无关的PR失败 - Rust加速器构建并重新运行整个套件以证明字节相同 - 三个操作系统上的Playwright - 450 kB JavaScript预算 - 配置参考从pydantic模型重新生成并比较 - 构建的UI检查第三方来源和绝对根URL，这些URL将使页面在/app/下安装时空白 - Docker镜像构建并进行健康检查 - pip-audit，npm审计，cargo审计，CodeQL，gitleaks，Trivy，SBOM，Scorecard 夜间：压缩基准测试回归底线，Rust/Python输出差异比较，套件对抗急切升级的依赖项。 </details> --- ## 站在别人的肩膀上 Sensei没有发明任何东西。这些项目做了艰苦的工作，而且这两个项目都值得您花费时间，而不仅仅是使用Sensei： ### 🪶 [Headroom](https://github.com/headroomlabs-ai/headroom) · Apache-2.0 **这个项目存在的原因。** Headroom已经发现，减少代理令牌账单的方法不是总结上下文，而是注意到大多数代理发送的内容在结构上是冗余的，并无损地重构它。表格JSON压缩、日志分类、缓存对齐的前缀和可逆压缩带有检索工具都是Headroom的想法。 如果您想要上下文压缩作为一个成熟的独立产品，拥有比Sensei更大的表面积——输出令牌整形、学习散文压缩器、LangChain和LiteLLM适配器、适用于十几个工具的代理包装器—— **请使用Headroom**。它非常出色，并且比这个更成熟。 Sensei的角度不同：压缩是自托管工作空间的一部分，您拥有端到端的所有权，MIT许可，提供聊天界面，RAG，代理和桌面应用程序。 ### 🏛️ [Odysseus](https://github.com/pewdiepie-archdaemon/odysseus) · AGPL-3.0 **事物的形状。** Odysseus——由Felix Kjellberg创建——认为自托管的AI工作空间应该感觉像一个完整的产品，而不是一组脚本：硬件感知的模型建议、真正的编辑器、代理、内存、安全默认值，假设您实际上会部署它。“我的机器实际上能运行什么？”这个想法来自它的Cookbook。 Sensei是一个 **干净的实现**——没有Odysseus代码被复制，这让它保持MIT许可，而不是继承AGPL。如果您想要一个完整的带有电子邮件、日历、文档和图像编辑的工作空间， **Odysseus是一个更完整的答案**。 > 两个项目都不支持这个项目。任何错误都归我们所有。 还值得一提的是：[GLM-5.2](https://github.com/zai-org/GLM-5.2) 是Sensei的默认值所指向的模型，也是压缩调优假设非常大的上下文窗口的原因。 --- ## 贡献 问题和PR欢迎——[CONTRIBUTING.md](CONTRIBUTING.md)有设置。目前最有用的：更多语言的压缩启发式、移动设备优化和[此页面的截图](docs/screenshots/README.md)。 <div align="center"> _{MIT · 由<a href="https://github.com/SenseiIssei">@SenseiIssei</a>构建} </div>