From eda080bc054adcd2e8355f116634e940da9230b8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=88=98=E8=88=AA=E5=AE=87?= <3364451258@qq.com> Date: Fri, 10 Jul 2026 14:27:11 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=9B=B4=E6=96=B0=E6=96=87=E6=A1=A3?= =?UTF-8?q?=E8=AE=B0=E5=BD=95=E5=A4=9A=E6=A0=BC=E5=BC=8F=E6=94=AF=E6=8C=81?= =?UTF-8?q?=E7=89=B9=E6=80=A7?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- CLAUDE.md | 33 +++++++++++++++++++++++++-------- README.md | 4 ++++ 2 files changed, 29 insertions(+), 8 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 5975042..1f0a8db 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -31,12 +31,19 @@ uv run python scripts/ingest_obsidian.py ## 架构 ``` -core/ # 核心逻辑（不依赖 server/cli） -├── config.py # YAML → dataclass, load_dotenv() 加载 .env -├── db.py # VectorDB: 线程安全的 ChromaDB 封装 -├── embedder.py # 策略模式: LocalEmbedder / OpenAIEmbedder / DashscopeEmbedder -├── ingest.py # MarkdownSplitter(混合分块) + DocumentIngestor(分批嵌入) -└── search.py # Searcher: 语义检索 + 源文件管理 +├── core/ # 核心逻辑（不依赖 server/cli） +│ ├── config.py # YAML → dataclass, load_dotenv() 加载 .env +│ ├── db.py # VectorDB: 线程安全的 ChromaDB 封装 +│ ├── embedder.py # 策略模式: LocalEmbedder / OpenAIEmbedder / DashscopeEmbedder +│ ├── ingest.py # DocumentIngestor: 按扩展名自动选择 Splitter +│ ├── search.py # Searcher: 语义检索 + 源文件管理 +│ └── splitters/ # 文档分块器包 +│ ├── base.py # Splitter(Protocol) + BaseTextSplitter(ABC) +│ ├── markdown.py # MarkdownSplitter: 标题+段落混合分块 +│ ├── text.py # TextSplitter: 纯文本段落切分 +│ ├── pdf.py # PDFSplitter: pymupdf 提取文字 +│ ├── html.py # HTMLSplitter: bs4 去标签 +│ └── registry.py # 扩展名 → Splitter 自动选择 server/ # FastAPI HTTP 层 ├── app.py # Depends(get_state) 依赖注入, 速率限制中间件 @@ -46,7 +53,9 @@ server/ # FastAPI HTTP 层 cli/main.py # Typer CLI，5 个命令 + --config 选项 ``` -**数据流**: MD 文件 → `MarkdownSplitter.split()` → `batch_embed()` → `ChromaDB collection.add()` → `Searcher.search()` +**数据流**: 文件 → `get_splitter(path)` 自动选择 → `Splitter.split()` → `batch_embed()` → `ChromaDB collection.add()` → `Searcher.search()` + +**支持的格式**: `.md` / `.txt` / `.pdf` / `.html` — 安装可选依赖: `uv sync --extra all` **依赖方向**: `config` ← `db` ← `embedder` ← `ingest`/`search` ← `server`/`cli` @@ -111,10 +120,18 @@ cli/main.py # Typer CLI，5 个命令 + --config 选项 | 集合名 | 来源 | 文件数 | chunks | 说明 | |--------|------|--------|--------|------| +| `novel_taohou` | `D:\Code\doing_exercises\exercise\Novel\我有太后罩着，你们有什么\原有章节剧情` | 220 | 670 | 小说章节（GPU bge-small-v1.5） | | `obsidian_blog` | `D:\Code\Obsidian` | 51 | 3,611 | 博客笔记（GPU bge-small-v1.5） | | `default` | 测试文件 | 2 | ~30 | test-guide.md + stdin-doc.md | -搜索时务必用 `-C obsidian_blog` 指定博客集合，否则只会搜到 default 中的测试数据。 +搜索时务必用 `-C` 指定集合，否则只会搜到 default 中的测试数据。 + +**小说搜索示例**： +```bash +uv run md-vector-db search "张莽和孙太后的关系" -k 3 -C novel_taohou +uv run md-vector-db search "抄家事件" -k 5 -C novel_taohou +uv run md-vector-db search "文谦变法" -k 3 -C novel_taohou +``` ## 已知问题 / 注意事项 diff --git a/README.md b/README.md index 81ba7fc..be2f275 100644 --- a/README.md +++ b/README.md @@ -11,6 +11,7 @@ Markdown 文档向量数据库 — 将 Markdown 文件自动分块、嵌入、 - **多集合**: 支持多项目数据隔离，不同知识库存入不同 ChromaDB collection - **HTTP API**: FastAPI 提供 RESTful 接口，附带 Swagger 文档 - **安全**: 可选 API Key 认证、速率限制、路径遍历防护 +- **多格式文档**: 支持 `.md` / `.txt` / `.pdf` / `.html`，按扩展名自动选择分块器，可通过 `Splitter` Protocol 扩展 - **去重**: 同一文件重复入库自动覆盖旧版本（基于路径 SHA256 哈希） ## 快速开始 @@ -21,6 +22,9 @@ Markdown 文档向量数据库 — 将 Markdown 文件自动分块、嵌入、 git clone git@lhy-git.liuhangyv.top:Serendipity/md-vector-db.git cd md-vector-db uv sync + +# 安装 PDF + HTML 支持（可选） +uv sync --extra all ``` ### 2. 配置