📚 30 秒快速上手

from docseek import DocSearch

# 1. 初始化（自动使用内置分词器 + BM25）
search = DocSearch(persist_directory="./my_docs")

# 2. 摄入文档
search.ingest("./notes/")

# 3. 查询
results = search.query("智能家居", top_k=5)

# 按文件名过滤
results = search.query("配置步骤", filter={"file_name": "README.md"})

# 按章节路径过滤
results = search.query("饮食建议", filter={"section_path": "健康"})

文档雷达 (docseek)

功能概述

面向 AI agent 的文档检索服务，提供：

• Markdown 优先切片：按标题层级自动切片，保留上下文
• TF-IDF 语义检索：默认模式，无需额外依赖
• 内置 BM25 混合检索：内置 BM25Okapi 算法，无需 rank_bm25
• 内置中文分词器：基于词典的正向最大匹配，无需 jieba
• 稀疏矩阵存储：内存优化，减少 40-60% 内存占用
• 元数据过滤：支持按文件名、章节路径、文件扩展名过滤
• 多 base_path 支持：列表格式，支持多个基准路径
• 持久化存储：JSON 格式，重启后数据不丢失
• 增量更新：支持单个文件添加/删除

使用场景

Invoke when:

• 用户需要搜索文档中与查询语句相似的内容
• 用户要求查询知识库、笔记库
• 用户需要处理 Markdown 格式的文档
• 用户需要进行语义搜索而非关键词匹配
• 用户需要管理文档检索索引（添加、查询、统计）
• 用户需要按文件名或章节过滤搜索结果

核心接口

DocSearch - 主入口

from docseek import DocSearch

# 初始化（指定持久化目录）
search = DocSearch(persist_directory="./my_vector_db")

# 多 base_path 支持
search = DocSearch(
    persist_directory="./data",
    base_path=["/app/对话", "/app/设定"]
)

ingest - 摄入文档

# 摄入单个文件
result = search.ingest("path/to/document.md")

# 摄入整个目录
result = search.ingest("./my_notes/")

# 返回值示例
{
    "status": "success",
    "message": "成功处理 10 个文件",
    "files_processed": 10,
    "chunks_added": 156,
    "files_failed": []
}

query - 语义查询

# 基本查询
results = search.query("智能家居监测系统功能", top_k=5)

# 按文件名包含匹配过滤
results = search.query(
    "安装配置步骤",
    top_k=3,
    filter={"source_file": "README"}
)

# 按章节路径包含匹配过滤
results = search.query(
    "饮食建议",
    top_k=3,
    filter={"section_path": "健康饮食"}
)

# 按文件扩展名过滤
results = search.query(
    "配置方法",
    top_k=3,
    filter={"file_ext": ".md"}
)

# 按完整文件名过滤
results = search.query(
    "使用说明",
    top_k=3,
    filter={"file_name": "使用指南.md"}
)

# 返回值示例
[
    {
        "content": "[安装] 配置步骤\n1. 安装依赖包...",
        "similarity": 0.8234,
        "source_file": "/path/to/README.md",
        "relative_path": "README.md",
        "file_link": "computer://README.md",
        "section_path": "安装 > 配置步骤",
        "title": "配置步骤",
        "level": 2
    },
    ...
]

remove - 移除文档

result = search.remove("path/to/document.md")
# {"status": "success", "message": "移除了 12 个切片", "removed": 12}

stats - 获取统计

stats = search.stats()
# {
#     "total_documents": 156,
#     "total_files": 10,
#     "vocab_size": 2345,
#     "use_sparse": True,
#     "memory_mb": 128.5,
#     "cache_stats": {"size": 50, "hits": 120, "misses": 30},
#     "persist_directory": "./my_vector_db",
#     "persist_files": {
#         "vectors.json": 45678,
#         "index.json": 1234,
#         "tfidf_model.json": 8901,
#         "bm25_index.json": 2345
#     }
# }

rebuild - 重建索引

result = search.rebuild()

配置选项

持久化文件说明

数据存储在指定目录（默认 ./docseek_data）：

依赖说明

零依赖运行（默认）：

• numpy（计算 TF-IDF 向量）

内置功能：

• 🔤 内置中文分词器：基于词典的正向最大匹配，200+ 常用词 + 技术术语
• ⚡ 内置 BM25Okapi：完整的 BM25 算法实现，无需 rank_bm25

可选依赖（安装后自动使用）：

• pip install jieba — 中文分词（升级分词效果）
• pip install sentence-transformers — 真实语义向量
• pip install rank-bm25 — BM25 加速（与内置 BM25 二选一）
• pip install python-docx — Word 文档支持
• pip install PyPDF2 — PDF 文档支持

安装 sentence-transformers 后：

search = DocSearch(use_real_embedding=True)

内存优化

• 稀疏矩阵存储：TF-IDF 向量使用稀疏格式，减少 40-60% 内存
• 分批索引构建：文档数超过 500 时自动分批处理
• 内存水位监控：内存占用超过 500MB 时提示保存检查点
• max_features 优化：默认 3000（从 5000 降低），进一步减少内存

Markdown 切片策略

1. 按 # 标题层级自动切片（h1→h2→h3）
2. 每个切片包含父级标题作为上下文
3. 代码块、表格不被切断
4. 超长切片按段落再分割
5. 提取 YAML frontmatter 作为 metadata

示例：

# 文档标题
## 第一章
### 1.1 小节
正文内容...

---

切片结果：

• 切片1: [文档标题] 第一章\n### 1.1 小节\n正文内容...
• section_path: 文档标题 > 第一章 > 1.1 小节

触发词

• /docseek
• /文档雷达
• /文档搜索

使用示例

1. 初始化并摄入文档

from docseek import DocSearch

# 创建检索服务，指定持久化目录
search = DocSearch(persist_directory="/data/knowledge_base")

# 摄入文档（支持 Markdown、Word、PDF、TXT）
search.ingest("./notes/")

2. 查询相关文档

# 查询与问题相关的文档片段
results = search.query("如何配置系统", top_k=5)

for r in results:
    print(f"[{r['similarity']:.2f}] {r['title']}")
    print(f"  来源: {r['source_file']}")
    print(f"  内容: {r['content'][:100]}...")
    print()

3. 按章节过滤

# 只在"健康饮食"章节中搜索
results = search.query(
    "营养建议",
    filter={"section_path": "健康饮食"}
)

4. 管理文档库

# 查看统计
stats = search.stats()
print(f"文档总数: {stats['total_documents']}")
print(f"内存占用: {stats['memory_mb']}MB")

# 移除文档
search.remove("path/to/outdated.md")

# 重建索引
search.rebuild()