microsoft/markitdown --- 微软的"文件→Markdown" 喂料工具
一句话定位: 微软 AutoGen 团队出品的"文件→Markdown" 转换器, 专为 LLM 数据预处理设计.
项目用途
markitdown 解决的痛点很具体: LLM 时代, 喂料素材常常是 PDF / Word / PPT / Excel / 图片 / 音频 / YouTube 链接, 而模型更擅长读"接近纯文本又保留结构" 的 Markdown. 它的目标用户是 RAG / Agent / 文档问答的开发者, 给出的不是"什么都能转" 的通用转换器, 而是"20+ 种输入 → Markdown, 保留 heading / list / table / link" 的轻量 Python 工具. 跟 pandoc 的"高保真排版" 取向相反, 它强调 LLM 友好 + 结构保留.
核心亮点
1. 基于优先级 + Magika 内容识别的可插拔转换链 . MarkItDown 内部维护一张按优先级排序的 converter 注册表, 每次 convert 调用时重排序 (保证优先级变化时立即生效, 排序稳定). 扩展名 / HTTP 头 / URL 都不够时, 调 Google 的 magika.Magika().identify_stream() 跑字节级深度学习分类器, 拿到 mimetype 后再跟 base_guess 做一次兼容性比对, 不一致就把 magika 的猜测也作为候选加进去, 多个猜测依次喂给 converter 链. 整个机制把"格式猜测 + 格式分发" 解耦成两个独立层, 第三方 converter 加进来不用碰 magika.
2. 一份入口, 18 个内置 converter . MarkItDown.__init__ 默认一次性注册 PlainText / Zip / Html / Rss / Wikipedia / YouTube / BingSerp / Docx / Xlsx / Xls / Pptx / Audio / Image / Ipynb / Pdf / OutlookMsg / Epub / Csv 共 18 个. convert() 按入参类型自动分流------str 走 URL / 本地路径二选, Path 走本地, requests.Response 走响应体, 有 .read() 的对象走 stream------同一套逻辑服务 CLI / Python / HTTP URL / 内存二进制流, 不用用户挑 API.
3. 基于 entry_points 的官方插件机制, 含 LLM Vision OCR 与 MCP server . 插件走标准 Python 入口点 markitdown.plugin, 加载时捕获异常只 warn 不抛, 失败插件被静默跳过. 仓库自带三个示例包: markitdown-sample-plugin (RTF converter 骨架模板); markitdown-ocr 把 LLM Vision 当 OCR 用, 复用 MarkItDown 的 llm_client / llm_model 字段给 PDF/DOCX/PPTX/XLSX 内的图片抠字; markitdown-mcp 把 convert_to_markdown(uri) 暴露成 MCP tool, 支持 STDIO / Streamable HTTP / SSE 三种 transport, 默认只绑 localhost.
横向比较
候选池与白名单里都没有"多格式→Markdown" 严格同类的项目, 兜底引用同领域公认大名: textract / pandoc / marker-pdf / docling / unstructured.io 等可参考. 重点拆三家:
- markitdown vs textract: textract 是社区驱动的"什么格式都能抽" 通用抽取库, 输出纯文本丢结构; markitdown 是微软官方维护, 输出 Markdown 保留 heading / list / table / link. 维度: 输出保真度 (markitdown 胜) / 安装体量 (textract 系统级二进制依赖更多) / 协议 (均 MIT).
- markitdown vs pandoc: pandoc 双向 (Markdown ↔ DOCX ↔ PDF ↔ LaTeX ...), 面向人阅读排版; markitdown 单向收口到 Markdown, 偏 LLM 喂料场景. 维度: 方向性 / 目标用户 / PDF 处理路径 (markitdown 走 pdfminer/pdfplumber + 可选 CU, 表格结构保留更稳).
- markitdown vs marker-pdf: marker-pdf 专攻"高质量 PDF→Markdown", 单格式深耕, 适合科研论文转换; markitdown 一套 CLI 同时吃 20+ 种格式, 通用性远胜 marker, 单格式极限质量依赖后端 (默认本地 extractor, 接 Azure Content Understanding 可追平). 维度: 格式广度 / 单格式极限 / 部署成本.
适用场景
- RAG 文档索引预处理 :
markitdown *.pdf -o corpus/, 输出直接切片喂 embedding. - YouTube / 网页 → Markdown 喂 Agent :
MarkItDown().convert("https://www.youtube.com/watch?v=...")让 YouTube converter 拉 transcript. - 混合模态批处理 (OCR + 文本) : 装
markitdown-ocr+ 配置llm_client=OpenAI(), 让扫描件 PDF / 嵌图 PPT 自动抠字, OCR 插件以优先级-1.0抢在 built-in converter 之前接管. - 接 Claude Desktop / IDE MCP client : 装
markitdown-mcp,convert_to_markdown(uri)让本地 LLM agent 直接处理任意 http/file/data URI. - CI 文档校验 : 拿
markitdown docs/spec.pdf > spec.md做 Markdown diff 检查 PDF 版本变更.
局限性 / 风险
保真度不等于排版级: README 自己讲明"the output is often reasonably presentable and human-friendly, it is meant to be consumed by text analysis tools --- and may not be the best option for high-fidelity document conversions", 复杂排版 (多栏 / 浮动文本框 / 特殊字体) 会被压平, 不适合做版式还原. I/O 权限等同于 open() / requests.get(): README 顶部 IMPORTANT 警示明文写出"MarkItDown performs I/O with the privileges of the current process ... Sanitize your inputs in untrusted environments", 不可信 URL / 路径要自己消毒; markitdown-mcp 在 HTTP/SSE 模式下默认只绑 localhost, 不要盲改 host 暴露到公网. 依赖体积: 装 [all] 等于拖一堆可选包, 按 [pdf, docx, pptx] 这种 sub-extra 装, 否则光 import 就吃满磁盘. 插件可被无声覆盖: 任何装了 markitdown.plugin 入口点的包都会被无差别 load, 出错时只 warn 不抛, 不留意 pip list 可能把不受信任的 converter 默默拉进来.
D4Vinci/Scrapling --- 自适应选择器 + 反爬一体的 Python 抓取框架
一句话定位: 把"自适应元素选择器" + "反爬隐身 fetcher" 放在同一个库里的 Python Web 抓取框架, 从一行单请求到多 Session 并发爬虫.
项目用途
Scrapling 想解决爬虫工程师最常踩的两个坑: 页面改版 selector 全失效 和 反爬 WAF 把请求拦掉 . 目标用户是中小规模数据采集工程师 / 研究员 / 个人开发者; 既要写一两次性脚本 (类似 requests + bs4), 又偶尔要搭可暂停恢复 / 可并发 / 可过 Cloudflare 的多页爬虫. 关键差异化在把"自适应元素选择器 (页面结构变了自动找回元素)" 和"反爬隐身 fetcher (curl_cffi TLS 指纹伪造 / Patchright 反指纹浏览器 / Cloudflare Turnstile 自动解题)" 放在同一个库里, 不用自己拼装 requests + bs4 + playwright + scrapy-impersonate.
核心亮点
1. 自适应选择器: 页面改版后自动找回元素 . Selector 在 css() / xpath() 解析时传 adaptive=True, 会先去 SQLite 里取上一次的"元素指纹" (tag / 文本 / 属性 / 父元素 / 兄弟节点 / 路径), 然后用 SequenceMatcher 对当前页面所有元素 算相似度, 选分数最高的几个返回, 容忍 selector 失效. 相似度算法综合比较 tag 相同性 (1 分) / 文本 (SequenceMatcher ratio) / 属性字典 (按 key/value 各 50% 加权) / 关键属性 class / id / href / src / XPath 路径 / 父元素 tag/属性/文本 / 兄弟节点相似度, 最后归一化到 0-100 分. 存储后端默认走 SQLite, Selector 对象可 pickle (注释里解释为什么不直接继承 lxml.html.HtmlElement------lxml 的 Element proxy 不可 pickle).
2. 隐身 Fetcher 链: HTTP → 浏览器 → 反指纹, 一键升级 . 三类 fetcher 走 lazy import, 业务代码按需升级: 轻量 Fetcher (curl_cffi, TLS 指纹伪造, 纯 API / 静态页) → 浏览器 DynamicFetcher (playwright, JS 渲染) → 隐身 StealthyFetcher (patchright + browserforge + apify-fingerprint-datapoints, Cloudflare / 强反爬). 这种"轻量优先, 必要时加重武器" 的设计直接体现在 README 的 Escalation Guide 段: 从 get / FetcherSession 起步, JS 渲染不够就升 fetch / DynamicSession, 被 WAF 拦了再升 stealthy-fetch / StealthySession, 多页并发再上 Spider.
3. Cloudflare Turnstile 自动解题 . StealthySession 内置 Cloudflare 检测 + 模拟点击, 先判定 challenge 类型 (non-interactive / embedded / 默认), 用 frame locator 找到 Turnstile iframe, 算随机偏移坐标, 模拟人类点击 (含随机 delay), 失败自动递归重试. 非交互类 challenge 走更轻路径: 等 <title>Just a moment...</title> 自动消失, 不浪费一次完整 click.
4. Spider 框架: 暂停 / 恢复 + 多 Session + 代理轮换 . Spider 基类把 concurrent_requests / concurrent_requests_per_domain / max_blocked_retries 等做成可覆盖的类字段, 还提供 is_blocked 钩子和 retry_blocked_request 钩子, 用户用子类判断被拦截并自动换 session 重试. crawldir 参数启用 checkpoint, interval 控制周期性落盘, 中断后 start(resume=True) 继续爬. SessionManager + configure_sessions 让用户把不同代理 / 不同 stealth 等级组合成多个 session, 调度器按需切换.
横向比较
| 维度 | Scrapling | scrapy | beautifulsoup4 | playwright |
|---|---|---|---|---|
| 学习曲线 | 低, 一行 fetch 起步 | 重, Item/Pipeline/Middleware 全套 | 极低, 但自己拼 HTTP | 中, 需写 locator |
| 反爬 / TLS 指纹 | 内置 curl_cffi + patchright + Turnstile 解题 | 需 scrapy-impersonate / scrapy-playwright 等三方插件 | 不涉及 | 需 playwright-stealth |
| 自适应选择器 | 核心卖点 | 无 | 无 | 无 |
| 资源占用 | 默认 lxml + curl_cffi, 无浏览器可跑 | 进程模型中等 | 几乎为零 | 起 Chromium, ~200MB/实例 |
| 并发 / 调度 | Spider 框架, pause/resume + 代理轮换 | 原生支持, 生态最成熟 | 无, 自己写 | 无, 自己写 |
候选池 + 白名单都缺严格同类的爬虫库, 同领域还有 scrapy / beautifulsoup4 / playwright / requests-html / httpx 等公认大名的爬虫 / HTML 解析 / 浏览器自动化项目可参考.
适用场景
- 写一次性数据抓取脚本 : 目标站结构稳定,
Fetcher+css一行拉. - 目标站结构经常改版 (电商 / 资讯聚合) : 第一次
auto_save=True存指纹, 改版后adaptive=True自动迁移, 不用每两周改一次 selector. - 过 Cloudflare Turnstile / Interstitial :
StealthyFetcher.fetch(url, headless=True, solve_cloudflare=True). - 中等规模多页爬虫 (1k-100k URL) :
Spider子类 + 多StealthySession+ProxyRotator+ checkpoint 暂停恢复. - 给 LLM agent 当数据采集层 : 装 Scrapling 的 Agent Skill, 让 Claude Code / OpenClaw 直接调用,
Selector的选择器接口对 LLM 友好.
局限性 / 风险
隐身是军备竞赛, 不是银弹: README 自己列了 Hyper Solutions (Akamai / DataDome / Kasada / Incapsula) 赞助商位, 说明 Turnstile 之外的强反爬仍需要商业 API 配合. 底层依赖浏览器 / Chromium 体积: 隐身链路要拉 Patchright + browserforge + apify-fingerprint-datapoints, CI 跑一次安装几百 MB. Spider 把 concurrent_requests / max_blocked_retries 等做成类属性, 多个 Spider 子类继承时若误改基类, 全局生效. 项目当前 Development Status :: 4 - Beta, 跨大版本 API 变化不保证向后兼容, 跟现有 scrapy 生态的互操作尚不完整.
opendataloader-project/opendataloader-pdf --- Java PDF 解析 + 自动无障碍打标签
一句话定位: Java 实现的 PDF 解析 + 自动无障碍标记 (Tagged PDF) 一体化库, 本地模式 0.015 s/页, 混合 AI 模式自评榜榜首 0.907 综合分.
项目用途
opendataloader-pdf 解决的是"PDF → AI/无障碍" 两端的双重痛点: 对 RAG / LLM 数据准备, 它把任意 PDF (数字版 / 扫描版 / 带标签版) 解析为带 bounding box 的结构化数据 (Markdown / JSON / HTML), 让下游做 chunking / 引用 / 答案回指定位都可以直接拿到坐标和阅读顺序, 而不是一坨纯文本; 对 PDF 无障碍合规 (EAA / ADA / Section 508 推动下企业级需求), 它把"未打标签" 的 PDF 自动改写成屏幕阅读器可读的 Tagged PDF, 是同类里第一个端到端开源实现. 目标用户群是 Java 后端要把 PDF 进 LLM 流水线的工程师、需要批量做无障碍整改的内容发布方、给 RAG 系统做高质量文档解析的 AI 团队.
核心亮点
1. XY-Cut++ 阅读顺序算法 (arXiv:2504.10258 落地实现) . 阅读顺序是多栏 / 跨列版式 (双栏论文 / 报刊) 的"老大难"------传统 XY-Cut 在跨栏页眉 / 页脚 / L 形区域上会切错. opendataloader-pdf 的 XYCutPlusPlusSorter 分四阶段处理: sort(...) 入口先做"跨版式元素预屏蔽", 再算密度比选 XY/YX 切分方向, 再递归切, 最后把跨版式元素按 Y 位置合并回主流. Phase 1 跨版式判定基于"宽度 ≥ β × maxWidth" + "至少与 N 个其他元素水平重叠" 两条件, 默认 β=2.0 (几乎关掉, 避免误判) + N=2 (防孤立宽元素误标). Phase 3 用投影法找最佳切缝, MIN_GAP_THRESHOLD=5.0 防止在 1-2 像素噪声处切开. Phase 4 按 Y 坐标把页眉 / 页脚等"事先摘出" 的元素插回主流的正确位置, 还原人类阅读顺序.
2. 双模式架构: 本地 15 ms/页 + 混合 AI 路由 . OpenDataLoaderPDF.processFile(...) 把所有"简单页" 留在 Java 内核本地处理 (典型 0.02 s/页), 复杂页 (密集表格 / 扫描件 / 公式 / AI 生成的图) 路由到 AI 后端. HybridClientFactory 集中管理"按 backend 类型缓存的客户端", 避免每篇文档重建线程池. 当前已实现 BACKEND_DOCLING_FAST (优化版 docling SDK server), 预留 BACKEND_HANCOM / BACKEND_HANCOM_AI / BACKEND_AZURE / BACKEND_GOOGLE 槽位, 多后端扩展是设计目标. "fast-path 在 Java、hard-path 走 AI" 的代价是必须显式 shutdown() 释放 HTTP 客户端线程池------反复单文件调用很慢, 应一次性 batch 传列表 / 文件夹.
3. 端到端开源 PDF 无障碍打标签 (同类里第一个) . AutoTagger.tag(...) 直接返回内存里的 tagged PDDocument (veraPDF 模型), 不写中间文件, 完整流水线: 先 DocumentProcessor.extractContents 拿到带 bbox 的结构化内容, 再 AutoTaggingProcessor.tagDocument 把内容织进 PDDocument 的结构树, 整个过程零磁盘 I/O. 类注释明确点出两种用法: OpenDataLoaderPDF.processFile 跑"提取 + 输出" 完整流水线; AutoTagger.tag(...) 单独要 tagged PDF 时用. 后者"in-memory PDDocument" 设计能被服务端集成进 HTTP 转换服务, 是商业无障碍整改流水线的中枢件. 配合 README 给出的"一次 JVM 启动批 4 个文档 7.95 s" 的实测, 能在企业批量场景下跑得动. 完整 PDF/UA-1/2 导出仍是企业付费项, 但"unstructured → Tagged PDF" 这一步在 Apache 2.0 协议下完全免费.
横向比较
候选池 + 白名单内没有"PDF 解析 / 文档结构化" 严格同类的项目, 兜底引用同领域公认大名: pdfplumber / PyMuPDF (fitz) / pdfminer.six / Apache PDFBox / Tabula / Camelot / Marker (marker-pdf) / Docling 等可参考. 重点拆四家:
- opendataloader-pdf vs pdfplumber: pdfplumber 是 Python 库 (pdfminer.six 之上的 thin wrapper), 适合 Python 数据科学栈; opendataloader-pdf 是 Java 11+ 库, 纯 JVM 内核 / 无 GPU 依赖 / 零 Python 依赖, 适合 Java/Scala/Kotlin 后端流水线 (Spring Boot / Micronaut / Quarkus 服务). 表格抽取两者都覆盖简单带框表, 复杂无框表 pdfplumber 需额外启发式, opendataloader-pdf 走 hybrid AI 路由.
- opendataloader-pdf vs PyMuPDF (fitz): PyMuPDF 是 C 扩展 + Python 绑定, 速度通常更快 (毫秒级单页), 但 API 输出偏向"原始文本块 + 简单 bbox", 没有内置阅读顺序算法、没有"AI-ready" 概念; opendataloader-pdf 牺牲一点点速度换阅读顺序 (XY-Cut++) / 结构化 JSON (每元素带 bbox + 阅读顺序) / hybrid 模式下的 AI 增强.
- opendataloader-pdf vs Docling : Docling (IBM 开源, Python, MIT) 是它 hybrid 后端
BACKEND_DOCLING_FAST实际调用的"上游模型服务"------自评榜上 Docling 0.882 / opendataloaderhybrid 0.907, 差异在 opendataloader 的混合策略 (local 处理简单页 / AI 处理复杂页) 以及 XY-Cut++ 后处理. opendataloader-pdf 把"用 Docling" 封装成了"按页路由 + 统一 JSON schema" 的稳定前端. - opendataloader-pdf vs Marker (marker-pdf): Marker 强项是"PDF → Markdown" (科研论文转换工作流常见), 但 Markdown 不带 bbox / 表格偶尔需要后处理; opendataloader-pdf 主打"结构化数据 + 坐标 + 阅读顺序", 下游做 RAG chunking / 答案回指 / UI 高亮更顺, 且同时走无障碍路线.
- opendataloader-pdf vs Apache PDFBox : 不是竞争, 是栈------PDFBox 是底层 PDF 对象模型 (字体 / path / content stream 级别), opendataloader-pdf 的 Java 核心构建在 PDFBox + veraPDF 之上, 做的是"在 PDFBox 之上加结构识别 + 阅读顺序 + 无障碍标签生成".
适用场景
- RAG 系统的文档摄入层: 把 PDF (论文 / 白皮书 / 合同 / 说明书) 解析为带 bbox 的结构化 JSON, 下游做 chunking + 向量化后能精准回指到原 PDF 坐标.
- 企业级 PDF 无障碍整改: 批量把历史未打标签的 PDF 改成 Tagged PDF, 应对 EAA / ADA / Section 508 合规.
- 混合云端 + 本地架构: 在隐私敏感行业 (金融 / 医疗 / 政府) 跑本地 Java 模式处理 80% 简单页, 剩下 20% 复杂页路由到内部 AI 集群, 既不丢准确率也不外发数据.
- 多语种扫描文档数字化: hybrid + OCR 模式支持 80+ 语言, 对 300 DPI+ 扫描件输出带阅读顺序的 Markdown / JSON.
- 接 LangChain / LlamaIndex : 通过官方 LangChain loader (README 提及) 把 opendataloader-pdf 的输出接入标准 RAG 链, chunk 直接带
bbox字段.
局限性 / 风险
协议分裂风险: 核心数据提取 + 自动打标签免费 Apache 2.0, 但完整 PDF/UA-1 / PDF/UA-2 导出是企业付费项 (README "Capability Matrix")------做合规整改时务必明确边界, 否则跑通了 Tagged PDF 后最后一步仍需付费. 不支持非 PDF 格式: README 明确 Process Word/Excel/PPT: No, markitdown 那种"多格式 → Markdown" 路线不在本项目能力范围, 要做混合文档源仍需拼接别的库. hybrid 模式的运维成本: 需要起一个 AI 后端服务 (默认 opendataloader-pdf-hybrid --port 5002), 客户端和 server 端要保持同版本; JVM 进程每次 spawn 较重, 必须 batch. XY-Cut++ 的几何局限: 是简化版几何实现 (类注释明确"without semantic type priorities"), 对于版式极不规则 (杂志 / 广告页 / 艺术排版) 可能切错到 L 形区域, 需要 hybrid 模式补刀.
chopratejas/headroom --- LLM 上下文压缩中间件
一句话定位 : 在 token 进入大模型前自动削掉 60--95% 冗余的 LLM 上下文压缩中间件, 库 / 代理 / MCP / headroom wrap agent 包装四合一.
项目用途
核心痛点是 AI 编码 agent (Claude Code / Cursor / Codex / Aider) 在长会话中持续累积 tool 输出 / 日志 / RAG 检索结果 / 读取的文件片段, 上下文窗口被快速撑爆, 既贵又慢还容易丢早期信息. 目标用户群: 每天跑 AI 编码 agent 的开发者、需要把 RAG / 工具链接到多家 LLM 提供商 (Anthropic / OpenAI / Bedrock) 的应用开发者、希望"零代码改动" 接入压缩能力的团队 (一行 headroom wrap claude 就让 Claude Code 自动走压缩层). 关键差异化: 不只卖一个压缩算法, 而是给"压缩这件事" 搭了一整套生产级中间件------六种压缩器 (SmartCrusher JSON / CodeCompressor AST / Kompress-base ML / Search / Log / Diff) + 三种部署形态 + 智能路由 + 可逆压缩 (CCR: 原始内容存档, LLM 按需 headroom_retrieve 拿回) + 跨 agent 共享记忆.
核心亮点
1. compress() 一行 API + 可配置策略 + 容错回退 . compress() 是用户面向的最简入口, 接受 OpenAI / Anthropic 格式的 messages, 返回 CompressResult { messages, tokens_before, tokens_after, tokens_saved, compression_ratio, transforms_applied }. 函数尾部 except Exception as e: 块把任何压缩异常降级为"原样返回 + OTel 记录失败"------不会让一个工具输出的压缩失败把整轮对话搞挂. CompressConfig 给上层调用方提供六个独立维度: compress_user_messages (默认 False 保护主体意图) / compress_system_messages / protect_recent (最近 N 条不压, 默认 4) / protect_analysis_context (检测 "analyze / review / debug" 意图时保护代码) / target_ratio (Kompress 保留比例, 0.5=文档安全, 0.2=激进) / kompress_model (可换 HuggingFace 模型或设 'disabled').
2. ContentRouter 智能路由 + 多策略 fallback 链 . ContentRouter.apply() 是压缩编排核心, 三遍走: 串行分类 (frozen / protected / cached / small) → 并行执行 (ThreadPoolExecutor, worker 数 = HEADROOM_COMPRESS_WORKERS, 默认 4) → 串行合并回消息序. _determine_strategy() 给出 ContentType → CompressionStrategy 的映射, 9 种策略枚举 (CODE_AWARE / SMART_CRUSHER / SEARCH / LOG / KOMPRESS / TEXT / DIFF / HTML / MIXED / PASSTHROUGH). fallback 链: 同一段 JSON 走 SMART_CRUSHER 没省下来时自动接 KOMPRESS 兜底, 再不行接 LOG 兜底, 整条链路写进 strategy_chain 字段方便事后审计. SmartCrusher 没装 / 命中空响应, 自动回落到 Kompress ML 压缩, 用户感知不到降级. 内容类型判断也不是纯 Python, 走 Rust 扩展 headroom._core.detect_content_type (magika→unidiff→PlainText), 没有 Python 软回退------遵循项目"no silent fallback" 原则, 装不上就显式抛错而不是假装能用.
3. 两层压缩缓存 + 自适应压缩阈值 . CompressionCache 是双层结构: Tier 1 (skip set, 哈希 → 已知"压不动", 100ns 内 O(1) 跳过) + Tier 2 (result set, 哈希 → 已知压缩结果, 直接复用 compressed text). TTL 默认 30 分钟. 自适应压缩阈值 根据 context_pressure = tokens_before / model_limit 在 min_ratio_relaxed=0.85 (上下文空) 和 min_ratio_aggressive=0.65 (上下文满) 之间线性插值------"上下文富余时拒绝边际收益, 上下文快满时接受任何能省的". Read 工具保护也走自适应窗口: 10 条消息时保护最近 5 条 Read, 100 条消息时保护最近 10 条, 1000 条时保护最近 100 条------保护窗口随会话规模线性增长, 不再"早期 Read 永远不压".
4. CCR 可逆压缩 + Kompress 自研模型 . SmartCrusher 的"行丢弃" (lossy) 路径丢行时, 把原始行哈希塞进哨兵对象挂到数组末尾, 格式 {"_ccr_dropped": "<<ccr:HASH N_rows_offloaded>>"}, LLM 看到哨兵就知道"这段数据被压了, 需要原文就调 headroom_retrieve". Rust 端 headroom._core 把压缩结果存档, LLM 通过 MCP tool headroom_retrieve 按需取回------这意味着 headroom 既能"激进压" 又"不丢信息", 是 LLMLingua 这类纯算法工具做不到的. 文本压缩走自研 kompress-base (ModernBERT, 在 330K 条结构化 tool output 上训练), 首次使用从 HuggingFace 自动下载, 调用 Kompress 前后用 protect_tags / restore_tags 保护 <system-reminder> / <tool_call> / <thinking> 等自定义标签, 不会被压坏语义.
横向比较
| 维度 | headroom | LLMLingua / LongLLMLingua | Selective Context | RECOMP |
|---|---|---|---|---|
| 部署形态 | 库 + 透明代理 + MCP server + headroom wrap agent 包装四合一, 业务代码零改动 |
纯 Python 库 | 纯 Python 库 | 抽取 / 生成两套独立模型, 研究产物 |
| 触发方式 | 默认 transparent proxy 中转, OpenAI/Anthropic/Bedrock 全兼容; 也可内联 compress(messages, model=...) |
调用方代码里显式 compress_prompt() |
同 LLMLingua | 同 LLMLingua, 需加载抽取器或生成器 |
| 算法组合 | 9 种策略按内容类型自动分发, 失败自动 fallback | 单一"按 self-information 砍 token" 算法, 一刀切 | 同 LLMLingua | 抽取式 + 生成式两路独立 |
| 可逆性 | CCR : 丢弃行写哨兵, LLM 调 headroom_retrieve MCP tool 拿回原始 |
不可逆, 砍掉的 token 真没了 | 不可逆 | 抽取式丢原文换摘要, 不可逆 |
| 跨 agent 共享 | SharedContext + Memory (Qdrant / Neo4j backend), Claude/Codex/Gemini 跨 agent dedup |
无 | 无 | 无 |
| 生产化程度 | CacheAligner 探测器保 KV cache prefix 稳定, Prometheus /stats 暴露, headroom wrap 一键接入 Claude Code |
研究代码, 无生产化包装 | 同 LLMLingua | 同 LLMLingua |
候选池 + 白名单都缺 prompt/context compression 严格同类 (e.g. supermemory 是 long-term memory 不压缩 prompt / airllm 是 LLM 推理不压 token / hermes-agent 是 agent 不压 / markitdown 是文件转换不压). 同领域还有 LLMLingua (microsoft/llmlingua) / LongLLMLingua / Selective Context (liyuchengs/Selective_Context) / RECOMP (yuchenlin/RECOMP) / CompLLM / ChunkedLLM 等公认大名的 prompt / context compression 研究/工具可参考.
适用场景
- AI 编码 agent 的 tool 输出爆炸 : Claude Code 跑
grep/cat/pytest时, 单个 tool_result 几万 token 是常态, 接headroom wrap claude一行命令让代理透明中转, 不改 agent 代码即省 60--90%. - 长会话 RAG 检索累计 : 多次 RAG 查询的 chunk 拼起来超 100K token 时, 用
from headroom import compress(messages, model="gpt-4o")走 inline 库, 按 chunk 评分裁剪相关度低的部分. - 多 agent 共用压缩记忆 + 跨 agent 检索 : Claude / Codex / Gemini 一起跑, 用
SharedContext+ Qdrant backend, 三个 agent 共享同一份压缩后的项目知识图谱, 不再"每个 agent 各压一遍浪费算力". - 生产 LLM 网关 : 起一个
headroom proxy --port 8787, 把公司所有 OpenAI / Anthropic 调用都接过来,/stats看按 provider/model/stack 的实时压缩率, Prometheus exporter 直接接 Grafana. - MCP 客户端 (Claude Desktop / Cline) 想在客户端侧做压缩 :
headroom mcp install装好 MCP 服务器, 客户端工具列表里出现headroom_compress/headroom_retrieve/headroom_stats三个 tool, LLM 主动调.
局限性 / 风险
Rust 扩展是硬依赖: headroom._core (PyO3 编译产物) 是 hard import, 没有 Python 回退, 装 prebuilt wheel 失败的话需要本地跑 scripts/build_rust_extension.sh (maturin develop), Windows 用户首次安装摩擦大. LLM 真实"省 token 但能答对" 依赖于 Kompress 模型质量: README 自报的 benchmark (GSM8K ±0.000, TruthfulQA +0.030) 在 N=100 子集上, 真实业务复杂工具链上 accuracy drift 未由项目方长期报告. CCR 缓解了"完全丢信息" 问题, 但如果 LLM 懒得调 headroom_retrieve 拿回原文, 等同于"压了但答案也错了". 压缩带来的延迟 / 算力开销未必能回本: kompress-base (ModernBERT) 跑一轮推理 + 9 策略路由 + 缓存查询, 简单短消息场景下可忽略, 百万级 RAG 检索批量调用时 Kompress 推理 + 路由判断本身就要吃掉几百 ms. 可观察性仍在追功能: 跨 worker 竞态 + 指标计数曾长期 silently broken, 升级前需要看 release notes 确认你用的 proxy 版本是否包含这些修复.
趋势观察
四个项目在同一周 daily trending 上同时冒头, 不是巧合, 是 "AI 应用工程的上下文成本" 在多个环节被同步挤压的信号:
- 喂料层 (markitdown): 喂进去之前先压, 目标是把任意文件统一成"LLM 友好" 的 Markdown, 配套 Azure Content Understanding / MCP server 把转换能力变成可被 agent 调用的 tool.
- 采集层 (Scrapling): 数据源侧的"反爬 + 自适应 selector" 让"获取干净数据" 的成本不再随时间线性增长, 改版后 selector 自动迁移.
- 结构化层 (opendataloader-pdf): PDF 这一类最难的结构化输入, 终于有了一个端到端开源的"解析 + 阅读顺序 + 无障碍标签" 库, 而且不绑 GPU, 纯 Java 内核, 后端可插拔 (Docling / Hancom / Azure / Google 都预留槽位).
- 运行时层 (headroom): 已经在上下文里的 tool 输出 / 日志 / RAG chunk, 用中间件方式透明削掉 60--95%, 业务代码零改动.
拼到一起, 这是一条完整的"AI 应用工程上下文成本" 流水线: 采 (Scrapling) → 喂 (markitdown) → 抽 (opendataloader-pdf) → 压 (headroom). 任何一环成本砍掉一半, 整个 LLM 应用的总成本都能看到量级下降.