EPUB Summary

简介

EPUB Summary 是一个创新的电子书智能处理工具，它能够根据你的个性化阅读意图，自动提取和压缩 EPUB 电子书中的相关内容。与传统的文本摘要工具不同，它使用先进的知识图谱技术和多智能体系统，能够理解书籍的叙事结构，保留最重要的内容，同时大幅压缩文件体积。

核心特性

• 🎯 意图驱动压缩：根据你的阅读意图定制化提取内容，而非简单的机械摘要
• 🧠 知识图谱构建：将书籍内容解构为认知块，并构建语义连接关系
• 🔗 主题链检测：使用拓扑指纹算法自动识别叙事主题链
• ✨ 多轮迭代优化：通过多个 AI 审阅者迭代优化压缩结果
• 📊 精细保留控制：四级保留度系统（逐字/详细/重点/相关）确保关键信息不丢失
• ⚡ 高性能并发：异步处理架构，支持章节和 LLM 请求的并发处理
• 💾 智能缓存：基于内容哈希的 LLM 响应缓存，节省 API 调用成本

工作原理

EPUB Summary 采用多层次的知识表示和处理流程：

原始 EPUB
    ↓
文本分片 (Fragments, ~800 tokens)
    ↓
认知块提取 (Chunks + 保留度标注)
    ↓
知识图谱构建 (Nodes + Edges + 工作记忆)
    ↓
主题链检测 (Snake Detection 贪心算法)
    ↓
多审阅者迭代压缩 (最多 10 轮优化)
    ↓
压缩后的 EPUB

关键技术

1. 拓扑指纹算法：通过"墨水扩散"模型计算节点在知识图谱中的拓扑位置，用于主题相似度判断
2. Wave Reflection 工作记忆：基于生成衰减的算法，动态选择上下文中最相关的历史信息
3. 多智能体审阅系统：为每条主题链创建专属的 AI 审阅者，从不同角度评估压缩质量
4. 两阶段贪心合并：先合并单节点，再合并主题链，平衡效率与质量

安装

环境要求

• Python 3.11 或更高版本
• OpenAI API 密钥（或兼容的 API，如 DeepSeek）
• 对本仓库的读权限（私有仓库）

在项目中集成

在使用 epub-summary 的项目中，按以下步骤集成：

1. 下载 wheel 文件

# 在项目根目录
mkdir -p libs
cd libs
gh release download v0.0.1 -R oomol/epub-summary -p "*.whl"
cd ..

2. 配置依赖

在项目的 pyproject.toml 中添加：

[tool.poetry.dependencies]
python = "^3.11"
epub-summary = {path = "libs/epub_summary-0.0.1-py3-none-any.whl"}

3. 安装依赖

poetry install

4. 提交 wheel 文件到 Git

git add libs/epub_summary-0.0.1-py3-none-any.whl
git commit -m "Add epub-summary v0.0.1"

更新版本：

# 下载新版本
cd libs
gh release download v0.0.2 -R oomol/epub-summary -p "*.whl"
cd ..

# 更新 pyproject.toml 中的路径
# epub-summary = {path = "libs/epub_summary-0.0.2-py3-none-any.whl"}

# 重新安装
poetry install

说明：wheel 文件作为项目源码的一部分签入 Git，所有团队成员和 CI 环境无需额外配置即可使用。

快速开始

1. 配置 LLM API

在项目根目录创建 format.json 配置文件：

{
  "key": "your-api-key-here",
  "url": "https://api.openai.com/v1",
  "model": "gpt-4",
  "timeout": 360.0,
  "temperature": 0.8,
  "top_p": 0.6
}

提示：项目支持任何 OpenAI 兼容的 API，例如 DeepSeek、Azure OpenAI 等。

2. 准备 EPUB 文件

将要处理的 EPUB 文件放入 tests/assets/ 目录（或修改 main.py 中的路径）。

3. 运行示例

python main.py

4. 自定义使用

编辑 main.py 或直接调用 API：

import asyncio
from pathlib import Path
from epub_summary import summary

async def main():
    await summary(
        # 阅读意图：描述你想从书中提取什么内容
        intention=(
            "压缩此书，重点关注主角的成长历程和关键转折点。"
            "对于重要对话必须原文保留，背景描写可以大幅压缩。"
        ),

        # 文件路径
        input_epub_file=Path("input.epub"),
        output_epub_file=Path("output.epub"),

        # 并发控制
        llm_concurrent=12,          # LLM 并发请求数
        chapter_concurrent=6,       # 章节并发处理数

        # LLM 配置
        llm_api_key="your-api-key",
        llm_base_url="https://api.openai.com/v1",
        llm_model="gpt-4",
        llm_timeout=360.0,
        llm_temperature=0.8,
        llm_top_p=0.6,

        # 工作路径
        workspace_path=Path("workspace"),
        log_dir=Path("logs"),
        cache_dir=Path("cache"),

        # 压缩参数（可选）
        compression_ratio=0.2,      # 目标压缩比（保留 20%）
        max_iterations=10,          # 最大迭代次数
        max_clues=6,                # 最大线索（主题链）数量

        # 进度回调（可选）
        on_progress=lambda progress: print(f"处理进度: {progress * 100:.1f}%"),
    )

if __name__ == "__main__":
    asyncio.run(main())

核心参数说明

intention（阅读意图）

这是最重要的参数，决定了压缩的方向和质量。好的意图描述应该：

• 明确说明关注什么内容
• 指定哪些内容必须保留
• 说明哪些内容可以压缩或删除

示例：

# 示例 1：关注人物关系
intention = "重点保留人物之间的互动和对话，社会背景可以简化"

# 示例 2：关注特定主题
intention = "提取所有与技术实现相关的内容，理论部分可以概括"

# 示例 3：混合要求
intention = (
    "压缩此书，重点关注作者的核心观点和论证过程。"
    "对于首次提出的概念定义必须原文保留，案例可以精简。"
)

压缩参数

• compression_ratio：目标压缩比（0.0-1.0），默认约 0.2（保留 20%）
• max_iterations：最大优化迭代次数，默认 10
• max_clues：提取的最大主题链数量，默认 6

并发控制

• llm_concurrent：同时发起的 LLM API 请求数，建议 8-16
• chapter_concurrent：同时处理的章节数，建议 4-8

注意：过高的并发可能导致 API 限流，请根据你的 API 配额调整。

进度回调

• on_progress：可选的进度回调函数，接收一个 0.0-1.0 之间的浮点数表示当前进度
  • 可用于在 UI 中显示进度条、记录日志等
  • 传入 None 则禁用进度回调（默认）

示例：

# 简单的进度打印
on_progress=lambda p: print(f"进度: {p*100:.1f}%")

# 更新进度条（假设使用 tqdm）
from tqdm import tqdm
pbar = tqdm(total=100)
on_progress=lambda p: pbar.update(p * 100 - pbar.n)

# 发送到 Web 界面
on_progress=lambda p: send_to_frontend({"progress": p})

目录结构

epub-summary/
├── epub_summary/              # 核心库
│   ├── topologization/        # 知识图谱构建
│   │   ├── topologize.py      # 主流程
│   │   ├── chunk_extraction.py # 认知块提取
│   │   ├── snake_detector.py  # 主题链检测
│   │   ├── graph.py           # 图数据结构
│   │   └── wave_reflection.py # 工作记忆算法
│   ├── editor/                # 压缩与审阅
│   │   ├── compress.py        # 压缩主流程
│   │   ├── clue.py            # 线索提取
│   │   └── markup.py          # 文本标记
│   ├── epub/                  # EPUB 读写
│   ├── data/                  # AI 提示词模板
│   ├── llm.py                 # LLM 客户端
│   ├── summation.py           # 顶层 API
│   └── text.py                # 文本工具
├── tests/                     # 测试文件
├── main.py                    # 示例脚本
├── format.json               # LLM API 配置（需手动创建）
├── workspace/                 # 运行时工作区
├── cache/                     # LLM 响应缓存
└── output/                    # 输出结果

技术架构

依赖库

• LLM：OpenAI Python SDK
• EPUB 处理：ebooklib
• 图算法：NetworkX
• 异步 IO：aiofiles, asyncio
• 文本处理：tiktoken, spacy, resource-segmentation
• 模板引擎：Jinja2
• 工具库：json-repair

数据持久化

• SQLite：存储知识图谱（chunks, edges, fragments）
• 文件系统：缓存 LLM 响应（基于 SHA-512 哈希）

日志系统

每次 LLM 请求都会生成独立的日志文件，包含：

• 请求的完整提示词
• 响应内容
• Token 统计
• 耗时信息

日志文件位于 output/logs/ 目录，便于调试和分析。

适用场景

• 学术研究：从长篇论文或专著中提取特定主题的论述
• 阅读辅助：根据兴趣定制化压缩长篇小说（如只关注某个角色的故事线）
• 知识管理：从技术书籍中提取关键知识点和代码示例
• 文献综述：从多本书中提取相同主题的不同表述

开发指南

安装开发依赖

poetry install --with dev

代码格式化

# 使用 ruff 格式化
ruff format .

# 检查代码风格
ruff check .

类型检查

pyright

运行测试

pytest

可视化知识图谱

项目提供了基于 Cytoscape.js 的交互式可视化工具，可以在浏览器中查看和探索知识图谱：

from epub_summary import generate_visualization

# 生成 HTML 可视化
generate_visualization(
    workspace_path="workspace",     # summary() 函数的 workspace_path
    output_path="visualization"     # 输出目录
)

# 可视化文件将生成在 visualization/ 目录，包含：
# - index.html: 章节列表索引页
# - chapter_*.html: 每个章节的知识图谱可视化
# 用浏览器打开 index.html 即可查看

可视化功能特性：

• 交互式图谱：使用 Cytoscape.js 渲染，支持缩放、拖拽、筛选
• 节点详情：点击节点可查看认知块的完整内容和保留度
• 边关系：可视化节点之间的语义连接
• 按章节浏览：每个章节生成独立的可视化页面
• 主题链高亮：清晰展示检测到的叙事主题链

使用场景：

• 调试和分析知识图谱构建效果
• 理解主题链检测结果
• 验证压缩过程中的节点保留逻辑

性能优化建议

1. 调整并发数：根据你的机器性能和 API 限额调整 llm_concurrent 和 chapter_concurrent
2. 使用缓存：重复运行时，缓存会自动复用之前的 LLM 响应
3. 选择合适的模型：对于简单任务，使用 gpt-3.5-turbo 即可；复杂任务推荐 gpt-4 或 DeepSeek V3
4. 分批处理：对于超大型书籍（>500 章），建议分批处理

作者

Tao Zeyu - i@taozeyu.com

致谢

本项目的灵感来源于认知科学和知识图谱领域的研究成果，特别感谢：

• 认知块（Cognitive Chunk）理论
• 图神经网络中的拓扑指纹方法
• 多智能体系统的协同优化思想

---

如有问题或建议，欢迎提交 Issue 或 Pull Request！