TreeSearch：结构感知的文档检索（不靠向量，也不切 Chunk）

如果你做过知识库检索/代码库检索，大概率遇到过同一个矛盾：

关键词检索（BM25/grep）很快、很准，但对“问句式问题”不够友好；
向量检索能吃语义，但常常把文档切碎（chunk），结果上下文断裂、引用困难、还要额外付 embedding 成本。

TreeSearch给了一个非常工程化的答案：

把文档解析成“树结构”，再用 SQLite FTS5 做关键词匹配与排序，保留结构、毫秒级检索万级文档/大型代码库，且无需向量 embedding、无需分 chunk。

1) TreeSearch 一句话解释

TreeSearch 是一个结构感知的文档检索库：

将文档解析为树结构（章节层级/类函数结构/JSON 嵌套等）；
通过 SQLite FTS5 做跨文档关键词匹配与打分；
返回的不是“碎片 chunk”，而是带标题/路径锚点的结构节点，避免上下文丢失。

原文强调的关键点：

无需向量 embedding、无需分 chunk
毫秒级检索万级文档和大型代码库
支持 Markdown、纯文本、代码、HTML/XML/JSON/CSV，以及可选 PDF/DOCX

2) 它解决什么问题：为什么“结构感知”重要

原文给出的核心对比非常清晰：

传统 RAG：文档 → 切 chunks → 向量化 → 检索 → ❌ 上下文断裂
TreeSearch：文档 → 解析为树结构（章节层级）→ 结构化检索 → ✅ 保留完整语义

当你的语料本来就有结构（标题层级、目录、类/函数、JSON 嵌套），把它切碎再检索，常见后果就是：

找到了“相关句子”，但不知道它属于哪一节；
需要补上下文时，只能“再多塞几个 chunk”，成本和噪音一起上升；
结果不可解释、不好引用。

TreeSearch 的取舍是：优先保证结构与定位稳定，再用快速的 FTS5/预过滤把检索做快。

3) 核心思路：文档 → 树 → FTS5

从原文描述来看，它的工作方式可以理解为一条流水线：

输入文档 (MD/TXT/Code/JSON/CSV/HTML/XML/PDF/DOCX)

→ ParserRegistry 分派解析器

→ 解析结构、构建树、可选生成摘要

→ 写入 SQLite（FTS5 倒排索引，支持增量与 WAL）

→ 搜索时：FTS5/Grep 预过滤 → 跨文档打分 → 排序结果

输出：带分数和文本的排序节点，并在 tree 模式下额外返回“层级路径”。

原文还给了两个工程细节（很关键）：

Source-type 路由：代码文件会走 GrepFilter + FTS5，提升符号/关键词定位精度；
可选 ripgrep 加速：若系统安装了 rg，会自动调用加速行级匹配；没装则降级纯 Python。

4) 快速开始：目录/文件/glob 混用

安装：

pip install -U pytreesearch

最小示例（直接传目录，递归发现支持文件）：

from treesearch import TreeSearch

# 直接传入目录 —— 自动递归发现所有支持的文件
ts = TreeSearch("project_root/", "docs/")
results = ts.search("认证系统如何工作？")
for doc in results["documents"]:
    for node in doc["nodes"]:
        print(f"[{node['score']:.2f}] {node['title']}")
        print(f" {node['text'][:200]}")

三种输入类型可自由组合（目录、文件、glob）：

ts = TreeSearch("src/", "docs/*.md", "README.md")
results = ts.search("认证配置")

内存模式（不落盘 .db，适合临时脚本/快速搜索）：

ts = TreeSearch("docs/", db_path=None)
results = ts.search("语音通话")

原文给的性能描述：即使处理数千文档也很出色（例如 5,000 个文档 < 10ms），代价是进程退出索引丢失；要持久化增量索引则使用默认 db_path 或指定文件路径。

5) 两种检索模式：auto / tree / flat

TreeSearch 提到三种模式：

search_mode="auto"（默认）：智能选择 tree vs flat
search_mode="tree"：更适合论文/长文档/深层标题层级技术文档
search_mode="flat"：更适合代码搜索、关键词密集查询

Tree 模式（最适合论文和文档）

原文描述其工作方式为：锚点检索 → 树遍历 → 路径聚合。

from treesearch import TreeSearch

# Tree 模式：锚点检索 → 树遍历 → 路径聚合
ts = TreeSearch("papers/", "docs/")
results = ts.search("实验方法", search_mode="tree")

# Tree 模式返回排序节点（与 flat 模式相同）
for doc in results["documents"]:
    for node in doc["nodes"]:
        print(f"[{node['score']:.2f}] {node['title']}")

# 额外返回：树遍历路径，展示结果之间的层级关系
for path in results["paths"]:
    chain = " > ".join(p["title"] for p in path["path"])
    print(f"[{path['score']:.2f}] {chain}")
    print(f" {path['snippet'][:200]}")

Auto Mode 的选择逻辑（原文三层策略）

类型映射：每种 source_type 有明确 tree 收益标识（_TREE_BENEFIT）
深度校验：只有实际树深度 ≥ 2 才算“真正有层级”
比例阈值：≥ 30% 文档受益于 tree → tree；否则 → flat

原文列出的默认路由（节选）：

Markdown：有标题层级且深度 ≥ 2 → tree
JSON：有嵌套且深度 ≥ 2 → tree
Code：flat
PDF/DOCX/CSV/Text/JSONL：flat

6) 为什么不用传统 RAG：与向量检索对比

原文的对比表可以概括为：

维度	传统 RAG	TreeSearch
预处理	分块 + 向量嵌入	解析标题/结构 → 构建树
检索	向量相似度	FTS5 关键词匹配（无需 LLM）
多文档	需要向量库路由	FTS5 跨文档打分
结构	分块后丢失	保留树形层级
依赖	向量数据库 + 嵌入模型	仅 SQLite（无嵌入、无向量库）

一句话：TreeSearch 不是“更聪明的 embedding”，而是“保留结构的检索”。

7) 能力边界与工程特性

支持的文件类型

原文明确列出支持：Markdown、纯文本、代码文件（Python AST + 正则、Java/Go/JS/C++ 等）、HTML、XML、JSON、CSV；以及可选 PDF、DOCX。

可选解析器依赖：

PyMuPDF（PDF）
python-docx（DOCX）
beautifulsoup4（HTML）

（原文示例：pip install pytreesearch[all]）

目录扫描的“智能默认值”

自动发现多种文件后缀（如 .py/.md/.json/.java/.go/.ts/.pdf/.docx 等）
自动跳过 .git/node_modules/__pycache__/dist/build 等
安装 pathspec 后尊重 .gitignore（原文：pip install pathspec）
单目录安全上限 10,000 文件（可用 max_files 配置调整）

结构化索引与 FTS5

原文提到：

SQLite FTS5 引擎（WAL 模式、增量更新）
“MD 结构感知列”（标题/摘要/正文/代码/前言）
列权重加权
CJK 分词（提到 jieba）

8) 典型场景

场景 1：技术文档问答（最强场景）

问题：公司内部 100+ 文档，传统搜索找不准。

from treesearch import build_index, search

# 1. 构建索引 — 直接传目录（只需运行一次）
docs = await build_index(
  paths=["docs/", "specs/"],
  output_dir="./indexes"
)

# 2. 搜索 — 毫秒级响应
result = await search(
  query="如何配置 Redis 集群？",
  documents=docs,
)

# 3. 结果 — 完整章节，不是碎片
for doc in result["documents"]:
  print(f"文档: {doc['doc_name']}")
  for node in doc["nodes"]:
    print(f" 章节: {node['title']}")
    print(f" 内容: {node['text'][:200]}...")

原文给出“为什么比传统 RAG 好”的理由：

找到的是完整章节，不是碎片
带章节标题作为上下文锚点
支持查看父/子章节层级导航

场景 2：代码库检索

目标：在大代码库里找“登录相关类和方法”，而不是只 grep 行。

docs = await build_index(
  paths=["src/", "lib/"],
  output_dir="./code_indexes"
)

result = await search(
  query="用户登录 authentication",
  documents=docs,
)

原文强调：

结构感知：返回类/方法/签名/（可含 docstring）
精准定位：能定位到行号

场景 3：长文本 QA（论文/书籍）— Tree 模式

docs = await build_index(paths=["paper.pdf"])

result = await search(
  query="实验方法 methodology",
  documents=docs,
  search_mode="tree",
)

for path in result["paths"]:
  chain = " > ".join(p["title"] for p in path["path"])
  print(f"[{path['score']:.2f}] {chain}")

原文强调 tree 模式优势：

章→节→小节的层级路径返回
适合定位“第几章第几节说了什么”

9) 评测与 Benchmark

QASPER（学术论文）

Tree 模式 MRR 最优（0.4988 vs 0.4235 Embedding vs 0.4033 FTS5）
Tree 模式 Recall@5 比 Embedding 高 35%
Tree 模式 Hit@5 0.7660 vs Embedding 0.6383
查询速度：亚毫秒级（原文示例：0.8ms / 1.2ms）

FinanceBench（SEC 财报）

FTS5 模式 MRR 最优（0.3969 vs 0.2206 Embedding）
Precision@1 = 0.3000（Embedding 为 0.1000）
索引时间显著更快（0.24s vs 406s）

CodeSearchNet（Python）

MRR 与 Embedding 接近（0.8400 vs 0.8483）
Precision@1 TreeSearch 更高（0.8200 vs 0.7800）
查询速度快（原文示例：1.7ms vs 166ms）

原文也给了可复现实验命令（略）。

10) 最佳实践与注意事项（工程视角）

结合原文信息点，这里给出“不会和原文冲突”的实践建议：

把“结构”当成你的检索第一公民
- Markdown 用标题层级；规范文档结构能直接提升 tree 模式收益。
代码检索优先用 flat + 预过滤
- 原文明确：代码文件 tree 收益为否，flat 更适配；并且有 GrepFilter/rg 加速路径。
先用 auto，再按语料调参
- auto 有深度校验与比例阈值，避免“混入少量 MD 误触 tree”的老问题。
大目录先设置 max_files / 跳过目录
- 原文有 10,000 文件安全上限，建议先做路径收敛再全量索引。
要持久化就用 db_path / index_dir
- 临时搜索用内存模式；长期知识库就落盘索引，便于增量更新。

11) 结语

TreeSearch 的价值可以概括成一句话：

在结构化文档里，检索应该返回“正确的位置 + 正确的上下文”，而不是“一个看起来相关的碎片”。

如果你的目标是做企业文档/技术文档/代码库的“零成本、可解释、可结构导航”的检索，TreeSearch 这类路线值得认真评估。

项目地址：

https://github.com/shibing624/TreeSearch

#AI工程 #知识库 #企业知识库 #信息检索 #检索系统 #RAG #向量检索 #BM25 #SQLite #FTS5 #文档解析 #结构化数据 #代码检索 #技术文档 #工程效率 #开发工具