CompactPrompt

CompactPrompt

CompactPrompt 会缩短你发送给 AI 模型的文本，同时保留其含义。这样可以降低运行成本、加快响应速度，并减少输入超出模型限制的可能性。常见用法只需调用一个函数，无需机器学习背景。

背景

AI 模型会读取输入（即 提示词），并返回响应。服务提供商根据处理的文本量收费，文本量以 token 衡量（每个 token 大约相当于四分之三的单词）；每个模型也都有输入长度上限。因此，包含指令、文档、表格和示例的长提示词会增加成本、降低响应速度，甚至可能无法输入。

CompactPrompt 会缩短提示词，同时保留重要信息，让你留住核心内容，去掉冗余。

入门

安装库：

pip install compactprompt

缩短提示词：

from compactprompt import CompactPrompt

result = CompactPrompt.compact(
    "Please could you very kindly go ahead and provide a really concise "
    "summary of the quarterly report."
)

print(result.text)
print(f"{result.ratio:.1f}x smaller "
      f"({result.tokens_before} -> {result.tokens_after} tokens)")

输出：

a really concise summary of the quarterly report.
1.7x smaller (22 -> 13 tokens)

填充语 “Please could you very kindly go ahead and” 会被删除，而含义保持不变。

功能

CompactPrompt 提供多种缩短提示词的方法。可以单独使用，也可以组合使用。下文会先用通俗的语言介绍每种方法，之后提供可选的技术说明。

删除价值较低的措辞

删除几乎不承载含义的词语，例如对话中的填充语，同时保留有意义的词语。这种方法有损：删除的词语无法恢复，但结果可以直接使用。

from compactprompt import CompactPrompt

# Remove approximately 40% of the tokens
result = CompactPrompt.compact(prompt, ratio=0.4)

# Or target a specific size
result = CompactPrompt.compact(prompt, budget=64)

技术详情

每个词语都会获得一个信息分数，该分数结合了词语的普遍稀有程度（静态自信息）和其在上下文中的可预测程度（小型语言模型计算的动态自信息）。分数较低的词语会被删除。使用 spaCy 一并删除完整的语法短语，以确保结果仍然通顺，并保护名称和数字。此方法实现了 CompactPrompt 论文中的融合规则。

可逆地缩短重复短语

短语重复出现时，会被替换为简短的占位符，并通过一个键记录每个占位符所代表的内容。这种方法无损：随时都可以还原出完全一致的原文。

import compactprompt as cp

doc = "operating cash flow rose. operating cash flow fell. operating cash flow held."
abbr = cp.abbreviate(doc, n=3)

print(abbr.text)        # '@0 rose. @0 fell. @0 held.'
print(abbr.dictionary)  # {'@0': 'operating cash flow'}
print(abbr.restore())   # the exact original

保留 abbr.dictionary，以便稍后再次展开占位符。

缩减数值数据的大小

大型数字表格会占用许多 token。此方法通过降低精度来节省空间，同时确保舍入误差不超过已知上限。

import compactprompt as cp

q = cp.quantize([1.0, 2.5, 3.3, 4.8, 9.2, 10.0], bits=8)
q.reconstruct()   # the rounded values
q.max_error       # the guaranteed maximum error

选择有代表性的示例

向模型展示少量示例时，效果会更好。如果你有许多候选示例，此方法会选出数量较少且多样化的子集，同时仍能体现完整范围，让你发送有代表性的少数示例，而不是全部示例。

from compactprompt import select_examples

chosen = select_examples(my_examples)
chosen.examples

选择文本精简方式

文本精简步骤可以由三种可互换的引擎中的任意一种执行。它们都会缩短文本；区别在于如何判断要删除哪些内容，以及运行所需的条件。通过 engine 参数选择引擎——代码的其他部分无需更改。

引擎	方式	要求
内置（默认）	为每个单词评分，并删除最不重要的单词。在本地运行。	无
LLMLingua	Microsoft 推出的成熟工具，使用小型模型判断要删除哪些内容。	下载模型
Caveman	以简洁的风格改写文本，同时保留代码、链接和标题。	可访问语言模型

CompactPrompt.compact(prompt)                       # built-in, no extra install
CompactPrompt.compact(prompt, engine="llmlingua")   # pip install 'compactprompt[llmlingua]'
CompactPrompt.compact(prompt, engine="caveman")     # pip install 'compactprompt[caveman]'

内置引擎和其他核心功能实现了 CompactPrompt 研究论文 中的方法。LLMLingua 和 Caveman 是本库集成的独立开源工具；请参阅致谢。

精简文件和技能

CompactPrompt 也可以精简完整的 Markdown 文件——文档、CLAUDE.md、笔记和 Claude Code 技能（SKILL.md）——而不仅仅是字符串。它还可以先检查文件或文件夹，报告可节省的内容。

此功能在设计上是安全的：YAML frontmatter 会原样保留，围栏代码块和链接绝不会被修改；如果结果会更改标题、代码块或 URL，则会被拒绝；除非指定 --apply，否则不会写入任何内容（指定后会先保存 .bak 备份）。看起来像代码、配置或机密的文件会自动跳过。

从命令行使用：

# See where the savings are (read-only)
compactprompt review ./skills

# Preview the compaction of one skill (writes nothing)
compactprompt compact ./skills/my-skill/SKILL.md --engine builtin

# Apply it (saves SKILL.md.bak, then rewrites the file)
compactprompt compact ./skills/my-skill/SKILL.md --engine caveman --apply

必须指定 --engine——每次都要选择 builtin、llmlingua 或 caveman（会改写正文的 caveman 通常最适合人类可读的文件）。

从 Python 使用：

from compactprompt import review_file, compact_file

report = review_file("SKILL.md")
print(report.tokens, report.issues)

result = compact_file("SKILL.md", engine="caveman", apply=True)
print(result.tokens_before, "->", result.tokens_after)

Streamlit 应用的 Files & Skills 选项卡也可以交互式地执行相同操作。

可选功能

基本安装无需设置。其他功能依赖额外组件，只需按需安装：

pip install compactprompt                  # core: trimming and reversible shortening
pip install 'compactprompt[ml]'            # numeric reduction and example selection
pip install 'compactprompt[llmlingua]'     # the LLMLingua engine
pip install 'compactprompt[caveman]'       # the Caveman engine
pip install 'compactprompt[mcp]'           # the MCP server for AI agents
pip install 'compactprompt[app]'           # the interactive application
pip install 'compactprompt[all]'           # everything

如果某项功能需要的组件尚未安装，CompactPrompt 会准确告知需要安装什么。

交互式应用

一个小型 Web 应用可让你粘贴提示词并查看精简后的内容，同时显示节省的篇幅：

pip install 'compactprompt[app]'
streamlit run compactprompt_app.py

应用会在浏览器中打开。使用侧边栏选择引擎并设置精简量。

在 AI Agent 中使用

CompactPrompt 随附一个 MCP 服务，让 AI 编码工具（Claude Code、Codex、Cursor、Gemini，以及任何支持 MCP 的 Agent）可以直接检查并精简提示词、文档和技能：

pip install 'compactprompt[mcp]'      # provides the `compactprompt-mcp` command
claude mcp add compactprompt -- compactprompt-mcp   # e.g. for Claude Code

agent-skills/ 目录中也提供了适用于相同工具的轻量级技能/规则文件，以及 install.sh。有关各工具的配置，请参阅其 README。

确认含义得以保留

要检查精简后的提示词是否仍表达相同含义，可以测量原文与结果之间的相似度，其中 1.0 表示含义完全相同：

from compactprompt import cosine_fidelity   # pip install 'compactprompt[embeddings]'

score = cosine_fidelity(original_text, result.text)
print(score.mean)

参考

CompactPrompt.compact(...) 会返回一个包含以下字段的结果对象：

字段	含义
.text	精简后的提示词。
.original	输入内容。
.tokens_before / .tokens_after	精简前后的大小。
.ratio	缩小的倍数（例如，2.3）。
.savings	节省的 token 占比（例如，0.4）。
.dictionary	用于还原精简后短语的键（如有使用）。
.restore()	撤销可逆的精简步骤。

主要选项：

CompactPrompt.compact(
    prompt,
    ratio=0.5,          # how much to remove: 0.5 targets about half the tokens
    budget=None,        # alternatively, a specific target token count
    prune=True,         # trim the wording (default)
    abbreviate=False,   # also shorten repeated phrases (reversible)
    engine="builtin",   # "builtin", "llmlingua", or "caveman"
)

包含高级选项的完整参考文档，请参阅文档。

开发

运行测试：

pip install pytest
pytest

测试套件会针对无依赖核心运行；缺少可选功能所需组件时，相关测试会自动跳过。

在本地构建文档：

pip install 'compactprompt[docs]'
mkdocs serve

引用

此库实现了以下方法论：

@article{choi2025compactprompt,
  title={CompactPrompt: A Unified Pipeline for Prompt and Data Compression in LLM Workflows},
  author={Choi, Joong Ho and Zhao, Jiayang and Shah, Jeel and Sonawane, Ritvika and
          Singh, Vedant and Appalla, Avani and Flanagan, Will and Condessa, Filipe},
  journal={arXiv preprint arXiv:2510.18043},
  year={2025}
}

这是一个独立实现，与论文作者无关。

归属

Caveman 引擎（compactprompt/caveman.py）改编自 Julius Brussee 的 Caveman（MIT）。LLMLingua 引擎使用 Microsoft 的 LLMLingua（MIT）。完整的第三方归属信息和许可声明请参阅 THIRD_PARTY_NOTICES.md。