7.0
热点
AI SCORE
开源项目2025-05-15 21:40
Min.js: 文档压缩优化LLM上下文利用率
Hacker News · github.com#LLM优化#工具#开源
Editor brief · 编辑速览
开源工具对技术文档进行智能压缩，适配LLM有限上下文窗口。为处理大规模文档的程序员提供实用优化方案。
llm-min.txt：面向 LLM 上下文的 Min.js 风格技术文档压缩 🤖 📜 目录 什么是 llm-min.txt，为什么它很重要？理解 llm-min.txt：一种面向机器优化的格式 🧩 它真的有效吗？影响效果可视化 快速开始 🚀 输出目录结构 📂 选择合适的 AI 模型（为什么选择 Gemini）🧠 工作原理：深入了解（src/llm_min）⚙️ 下一步是什么？未来计划 🔮 常见问题（FAQ）❓ 想帮忙吗？参与贡献 🤝 许可证 📜
什么是 llm-min.txt，为什么它很重要？
理解 llm-min.txt：一种面向机器优化的格式 🧩
它真的有效吗？影响效果可视化
输出目录结构 📂
选择合适的 AI 模型（为什么选择 Gemini）🧠
工作原理：深入了解（src/llm_min）⚙️
下一步是什么？未来计划 🔮
常见问题（FAQ）❓
想帮忙吗？参与贡献 🤝
什么是 llm-min.txt，为什么它很重要？
如果你使用过 AI 编程助手（例如 GitHub Copilot、Cursor 或其他由大语言模型——LLM——驱动的工具），很可能遇到过它们不了解编程库最新更新的情况。之所以存在这种知识缺口，是因为 AI 模型都有一个“知识截止日期”——在此时间点之后的新信息，它们尚未学习。由于软件发展迅速，这一限制可能导致过时的建议和无法运行的代码。
为应对这一挑战，已经出现了几种创新方案：
llms.txt 一项由社区推动的计划，贡献者创建专门为 AI 使用而格式化的参考文件（llms.txt），其中包含最新的库信息。
llms.txt 一项由社区推动的计划，贡献者创建专门为 AI 使用而格式化的参考文件（llms.txt），其中包含最新的库信息。
Context7 一项动态向 AI 提供上下文信息的服务，通常会对文档进行智能摘要。
Context7 一项动态向 AI 提供上下文信息的服务，通常会对文档进行智能摘要。
这些解决方案虽然很有价值，但也存在一些局限：
llms.txt 文件可能变得异常庞大——有些甚至超过 800,000 个 token（词片段）。如此大的体量可能超出许多 AI 系统的上下文窗口承载能力。许多较短的 llms.txt 变体仅包含指向官方文档的链接，要求 AI 另行获取并处理这些文档。即使是内容全面的版本（llms-full.txt），其长度通常也超出了大多数 AI 助手单次能够处理的范围。此外，这些文件不一定总能反映绝对最新的文档内容。
llms.txt 文件可能变得异常庞大——有些甚至超过 800,000 个 token（词片段）。如此大的体量可能超出许多 AI 系统的上下文窗口承载能力。
许多较短的 llms.txt 变体仅包含指向官方文档的链接，要求 AI 另行获取并处理这些文档。即使是内容全面的版本（llms-full.txt），其长度通常也超出了大多数 AI 助手单次能够处理的范围。此外，这些文件不一定总能反映绝对最新的文档内容。
Context7 的运作方式有些像“黑盒”——它虽然实用，但其具体的信息筛选方法对用户而言并不完全透明。它主要处理 GitHub 代码仓库或现有的 llms.txt 文件，而不是任意软件包。
Context7 的运作方式有些像“黑盒”——它虽然实用，但其具体的信息筛选方法对用户而言并不完全透明。它主要处理 GitHub 代码仓库或现有的 llms.txt 文件，而不是任意软件包。
llm-min.txt 提供了一种全新的方案：
受到 Web 开发中 min.js 文件（移除了不必要内容的 JavaScript）的启发，llm-min.txt 将类似的理念应用于技术文档。我们不再向 AI 输入一份庞大且冗长的手册，而是借助另一个 AI，将文档提炼成高度压缩、结构严密的摘要。最终生成的 llm-min.txt 文件只保留理解库的使用方式所必需的核心信息，并采用面向 AI 助手而非人类读者优化的格式进行封装。
现代 AI 的推理能力非常擅长这种提炼过程，能够创建效率极高的知识表示，以最少的 token 消耗提供最大的价值。
理解 llm-min.txt：一种面向机器优化的格式 🧩
llm-min.txt 文件使用结构化知识格式（Structured Knowledge Format，SKF）——这是一种紧凑且面向机器优化的格式，旨在让 AI 高效解析，而非方便人类阅读。该格式将技术信息组织成彼此独立、高度结构化且关系明确的各个部分。
SKF 格式的关键要素：
头部元数据：每个文件都以必要的上下文信息开头：# IntegratedKnowledgeManifest_SKF：格式标识符和版本 # SourceDocs: [...]：原始文档来源 # GenerationTimestamp: ...：创建时间戳 # PrimaryNamespace: ...：顶层包/命名空间，这对于理解导入路径至关重要
头部元数据：每个文件都以必要的上下文信息开头：
三个核心结构化部分：内容被组织为不同的功能类别：# SECTION: DEFINITIONS（前缀：D）：描述库的静态方面：具有全局唯一 ID 的规范组件定义（例如 D001:G001_MyClass）相对于 PrimaryNamespace 的命名空间路径 包含参数和返回类型的方法签名 包含类型和访问修饰符的属性/字段 继承或接口实现等静态关系 重要提示：这一部分实际上充当了文件的术语表，因为传统的术语表（G 部分）会在生成过程中使用，但为了节省空间，会被刻意从最终输出中省略。# SECTION: INTERACTIONS（前缀：I）：记录库中的动态行为：方法调用（INVOKES）组件使用模式（USES_COMPONENT）事件的产生/消费 错误抛出与处理逻辑，并引用具体的错误类型 # SECTION: USAGE_PATTERNS（前缀：U）：提供具体的使用示例：核心功能的常见工作流 涉及对象创建、配置、方法调用和错误处理的分步操作序列 每个模式都有一个描述性名称（例如 U_BasicCrawl），并包含带编号的步骤（U_BasicCrawl.1、U_BasicCrawl.2）
三个核心结构化部分：内容被组织为不同的功能类别：
具有全局唯一 ID 的规范组件定义（例如 D001:G001_MyClass）
相对于 PrimaryNamespace 的命名空间路径
包含参数和返回类型的方法签名
包含类型和访问修饰符的属性/字段
继承或接口实现等静态关系
重要提示：这一部分实际上充当了文件的术语表，因为传统的术语表（G 部分）会在生成过程中使用，但为了节省空间，会被刻意从最终输出中省略。
方法调用（INVOKES）
组件使用模式（USES_COMPONENT）
事件的产生/消费
错误抛出与处理逻辑，并引用具体的错误类型
核心功能的常见工作流
涉及对象创建、配置、方法调用和错误处理的分步操作序列
每个模式都有一个描述性名称（例如 U_BasicCrawl），并包含带编号的步骤（U_BasicCrawl.1、U_BasicCrawl.2）。
基于行的结构：每个条目各占一行，并遵循精确的格式约定，以便机器可靠解析。
基于行的结构：每个条目各占一行，并遵循精确的格式约定，以便机器可靠解析。
SKF 格式示例（简化版）：
# IntegratedKnowledgeManifest_SKF/1.4 LA
# SourceDocs: [example-lib-docs]
# GenerationTimestamp: 2024-05-28T12:00:00Z
# PrimaryNamespace: example_lib
# SECTION: DEFINITIONS (Prefix: D)
# Format_PrimaryDef: Dxxx:Gxxx_Entity [DEF_TYP] [NAMESPACE "relative.path"] [OPERATIONS {op1:RetT(p1N:p1T)}] [ATTRIBUTES {attr1:AttrT1}] ("Note")
# ---
D001:G001_Greeter [CompDef] [NAMESPACE "."] [OPERATIONS {greet:Str(name:Str)}] ("A simple greeter class")
D002:G002_AppConfig [CompDef] [NAMESPACE "config"] [ATTRIBUTES {debug_mode:Bool("RO")}] ("Application configuration")
# ---
# SECTION: INTERACTIONS (Prefix: I)
# Format: Ixxx:Source_Ref INT_VERB Target_Ref_Or_Literal ("Note_Conditions_Error(Gxxx_ErrorType)")
# ---
I001:G001_Greeter.greet INVOKES G003_Logger.log ("Logs greeting activity")
# ---
# SECTION: USAGE_PATTERNS (Prefix: U)
# Format: U_Name:PatternTitleKeyword
# U_Name.N:[Actor_Or_Ref] ACTION_KEYWORD (Target_Or_Data_Involving_Ref) -> [Result_Or_State_Change_Involving_Ref]
# ---
U_BasicGreeting:Basic User Greeting
U_BasicGreeting.1:[User] CREATE (G001_Greeter) -> [greeter_instance]
U_BasicGreeting.2:[greeter_instance] INVOKE (greet name='Alice') -> [greeting_message]
# ---
# END_OF_MANIFEST
llm-min-guideline.md 文件（与 llm-min.txt 一同生成）提供了详细的解码说明和模式定义，使 AI 能够正确理解 SKF 格式。它是不可或缺的配套文档，解释了整个文件中使用的表示法、字段含义和关系类型。
llm-min.txt 在保留 AI 助手所需核心知识的同时，实现了大幅度的 token 缩减。下图比较了原始库文档（llm-full.txt）与压缩后的 llm-min.txt 版本之间的 token 数量：
这些结果表明，token 缩减幅度通常在 90%～95% 之间，某些情况下甚至超过 97%。这种极致压缩与高度结构化的 SKF 格式相结合，使 AI 工具能够比处理原始文本更高效地摄取和处理库文档。
在我们的 samples 目录中，你可以亲自查看这些令人印象深刻的结果：
sample/crawl4ai/llm-full.txt：原始文档（未压缩）
sample/crawl4ai/llm-min.txt：压缩后的 SKF 表示
sample/crawl4ai/llm-min-guideline.md：格式解码配套文件，也可参见 llm-min-guideline.md
大多数压缩文件包含约 10,000 个 token，完全处于现代 AI 助手的处理能力范围内。
只需在 AI 驱动的 IDE 对话中引用这些文件，就能看到你的助手立即掌握该库的详细知识：
建立基准测试是必要的，但极其困难。LLM 代码生成具有随机性，生成代码的质量取决于多种因素。crawl4ai、google-genai 和 svelte 都是当前 LLM 无法为其生成正确代码的软件包。使用 llm-min 将大幅提高代码生成的成功率。
开始使用 llm-min 非常简单：
对于普通用户（推荐）：pip install llm-min # Install required browser automation tools playwright install
对于普通用户（推荐）：
pip install llm-min
# Install required browser automation tools
playwright install
对于贡献者和开发者：# Clone the repository (if not already done) # git clone https://github.com/your-repo/llm-min.git # cd llm-min # Create and activate a virtual environment python -m venv .venv source .venv/bin/activate # On Windows: .venv\Scripts\activate # Install dependencies with UV (faster than pip) uv sync uv pip install -e . # Optional: Set up pre-commit hooks for code quality # uv pip install pre-commit # pre-commit install
对于贡献者和开发者：
# Clone the repository (if not already done)
# git clone https://github.com/your-repo/llm-min.git
# cd llm-min
# Create and activate a virtual environment
python -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
# Install dependencies with UV (faster than pip)
uv sync
uv pip install -e .
# Optional: Set up pre-commit hooks for code quality
# uv pip install pre-commit
# pre-commit install
llm-min 使用 Google 的 Gemini AI 生成压缩文档。你需要一个 Gemini API 密钥才能继续：
最佳实践：创建名为 GEMINI_API_KEY 的环境变量，并将其值设置为你的密钥：# Linux/macOS export GEMINI_API_KEY=your_api_key_here # Windows (Command Prompt) set GEMINI_API_KEY=your_api_key_here # Windows (PowerShell) $env:GEMINI_API_KEY="your_api_key_here"
最佳实践：创建名为 GEMINI_API_KEY 的环境变量，并将其值设置为你的密钥：
# Linux/macOS
export GEMINI_API_KEY=your_api_key_here
# Windows (Command Prompt)
set GEMINI_API_KEY=your_api_key_here
# Windows (PowerShell)
$env:GEMINI_API_KEY="your_api_key_here"
替代方案：通过 --gemini-api-key 命令行选项直接提供密钥。
替代方案：通过 --gemini-api-key 命令行选项直接提供密钥。
你可以从 Google AI Studio 或 Google Cloud Console 获取 Gemini API 密钥。
选择以下输入源之一：
# 📦 Process the "typer" Python package, save to "my_docs" folder
llm-min -pkg "typer" -o my_docs -p 50
# 🌐 Process the FastAPI documentation website
llm-min -u "https://fastapi.tiangolo.com/" -o my_docs -p 50
# 📁 Process documentation files in a local folder
llm-min -i "./docs" -o my_docs
# 📁 Process local files with custom output name and version
llm-min -i "./my-project-docs" -o my_docs -n "my-project" -V "1.2.3"
# 📁 Process a project's entire documentation directory structure
llm-min -i "/path/to/project/documentation" -o project_docs --verbose
使用 --input-folder 时，llm-min 将：
递归扫描指定目录中的文档文件
处理以下扩展名的文件：.md（Markdown）、.txt（纯文本）、.rst（reStructuredText）
将找到的所有文件合并为单一内容流
完全跳过 Web 抓取（因此速度更快，也不需要互联网连接）
将合并后的原始内容保存在 llm-full.txt 中，并生成压缩后的 llm-min.txt
这尤其适用于：
无法在线获取的内部或专有文档
你正在开发的本地项目文档
互联网访问受限时的离线处理
采用各种格式的自定义文档
你还可以将 llm-min 直接集成到 Python 应用程序中：
from llm_min import LLMMinGenerator
import os
# Configuration for the AI processing
llm_config = {
"api_key": os.environ.get("GEMINI_API_KEY"), # Use environment variable
"model_name": "gemini-2.5-flash-lite-preview-06-17", # Recommended model
"chunk_size": 600000, # Characters per AI processing batch
"max_crawl_pages": 200, # Maximum pages to crawl (only for web crawling)
"max_crawl_depth": 3, # Link following depth (only for web crawling)
}
# Initialize the generator (output files will go to ./my_output_docs/[source_name]/)
generator = LLMMinGenerator(output_dir="./my_output_docs", llm_config=llm_config)
# 📦 Generate llm-min.txt for a Python package
try:
generator.generate_from_package("requests")
print("✅ Successfully created documentation for 'requests'!")
except Exception as e:
print(f"❌ Error processing 'requests': {e}")
# 🌐 Generate llm-min.txt from a documentation URL
try:
generator.generate_from_url("https://fastapi.tiangolo.com/")
print("✅ Successfully processed FastAPI documentation!")
except Exception as e:
print(f"❌ Error processing URL: {e}")
try: # Read and combine all documentation files from a local folder import pathlib docs_folder = pathlib.Path("./my-project-docs")
# Collect content from supported file types
content = ""
for ext in [".md", ".txt", ".rst"]:
for file_path in docs_folder.rglob(f"*{ext}"):
with open(file_path, encoding="utf-8") as f:
content += f"# File: {file_path.name}\n\n"
content += f.read() + "\n\n---\n\n"
# Process the combined content
generator.generate_from_text(
input_content=content,
source_name="my-project",
library_version="1.0.0" # Optional
)
print("✅ Successfully processed local documentation!")
except Exception as e: print(f"❌ Error processing local files: {e}")
要查看完整的命令行选项列表，请运行：
llm-min --help
输出目录结构 📂
llm-min 完成处理后，会创建以下组织清晰的目录结构：
your_chosen_output_dir/ └── name_of_package_or_website/ ├── llm-full.txt # Complete documentation text (original content) ├── llm-min.txt # Compressed SKF/1.4 LA structured summary └── llm-min-guideline.md # Essential format decoder for AI interpretation
例如，运行 `llm-min -pkg "requests" -o my_llm_docs` 会生成：
my_llm_docs/ └── requests/ ├── llm-full.txt # Original documentation ├── llm-min.txt # Compressed SKF format (D, I, U sections) └── llm-min-guideline.md # Format decoding instructions
重要提示：`llm-min-guideline.md` 文件是 `llm-min.txt` 至关重要的配套文件。它提供了详细的模式定义和格式说明，AI 需要这些信息才能正确解读结构化数据。将 `llm-min.txt` 与 AI 助手配合使用时，请务必同时提供该指南文件。
选择合适的 AI 模型（为什么选择 Gemini）🧠
llm-min 使用 Google 的 Gemini 系列 AI 模型处理文档。虽然你可以通过 `--gemini-model` 选项指定某个 Gemini 模型，但我们强烈建议使用默认模型：`gemini-2.5-flash-lite-preview-06-17`。
该模型为文档压缩提供了最佳的能力组合：
高级推理：擅长理解复杂的技术文档，并提取 SKF 格式所需的关键结构关系。
高级推理：擅长理解复杂的技术文档，并提取 SKF 格式所需的关键结构关系。
出色的上下文窗口：输入容量达到 100 万个 token，可以一次处理大块文档，从而实现更加连贯、全面的分析。
出色的上下文窗口：输入容量达到 100 万个 token，可以一次处理大块文档，从而实现更加连贯、全面的分析。
成本效益：与其他拥有大上下文窗口的模型相比，它在能力和价格之间实现了出色的平衡。
成本效益：与其他拥有大上下文窗口的模型相比，它在能力和价格之间实现了出色的平衡。
默认模型经过精心选择，能够针对各种文档风格和技术领域，为 llm-min 压缩流程提供最佳结果。
工作原理：深入了解内部机制（src/llm_min）⚙️
llm-min 工具采用复杂的多阶段流程，将冗长的文档转换为紧凑、针对机器优化的 SKF 清单：
输入处理：llm-min 会根据你的命令行选项，从相应来源收集文档：包（`--package "requests"`）：自动发现并抓取该包的文档网站；URL（`--doc-url "https://..."`）：直接抓取指定的文档网站；本地文件夹（`--input-folder "./docs"`）：递归扫描 `.md`、`.txt` 和 `.rst` 文件，并合并其内容。
输入处理：llm-min 会根据你的命令行选项，从相应来源收集文档：
包（`--package "requests"`）：自动发现并抓取该包的文档网站
URL（`--doc-url "https://..."`）：直接抓取指定的文档网站
本地文件夹（`--input-folder "./docs"`）：递归扫描 `.md`、`.txt` 和 `.rst` 文件，并合并其内容
文本准备：收集到的文档会经过清理，并被切分成便于处理的文本块。原始文本会保存为 `llm-full.txt`。
文本准备：收集到的文档会经过清理，并被切分成便于处理的文本块。原始文本会保存为 `llm-full.txt`。
三步 AI 分析流水线（Gemini）：这是生成 SKF 清单的核心，由 `compacter.py` 中的 `compact_content_to_structured_text` 函数协调执行：第 1 步：生成全局术语表（仅供内部使用）：使用 `SKF_PROMPT_CALL1_GLOSSARY_TEMPLATE` 提示词分析每个文档块，识别关键技术实体，并生成带有临时 Gxxx ID 的文档块局部术语表片段。随后通过 `SKF_PROMPT_CALL1_5_MERGE_GLOSSARY_TEMPLATE` 提示词合并这些片段，解决重复项并创建统一的实体列表。之后，`re_id_glossary_items` 函数会为这些合并后的实体分配全局连续的 Gxxx ID（G001、G002 等）。整个处理过程中，这份全局术语表会保留在内存中，但为了节省空间，不会包含在最终的 `llm-min.txt` 输出中。第 2 步：生成定义与交互（D 与 I）：对于第一个文档块（或只有一个文档块的情况），AI 会结合全局术语表，使用 `SKF_PROMPT_CALL2_DETAILS_SINGLE_CHUNK_TEMPLATE` 生成初始的 D 项和 I 项。对于后续文档块，则使用 `SKF_PROMPT_CALL2_DETAILS_ITERATIVE_TEMPLATE`，同时提供全局术语表和此前生成的 D&I 项作为上下文，以避免重复。处理每个文档块时，新识别出的 D 项和 I 项会不断累积，并被分配连续的全局 ID（D001、D002 等，以及 I001、I002 等）。第 3 步：生成使用模式（U）：与第 2 步类似，第一个文档块使用 `SKF_PROMPT_CALL3_USAGE_SINGLE_CHUNK_TEMPLATE`，接收全局术语表、所有累积的 D&I 项以及当前文档块的文本。后续文档块则使用 `SKF_PROMPT_CALL3_USAGE_ITERATIVE_TEMPLATE`，它还会接收此前生成的 U 项，以便延续模式并避免重复。使用模式通过描述性名称标识（例如 `U_BasicNetworkFetch`），并包含带编号的步骤（例如 `U_BasicNetworkFetch.1`、`U_BasicNetworkFetch.2`）。
三步 AI 分析流水线（Gemini）：这是 SKF 清单生成的核心，由 co