From 8042cf288b4098b54e74ccd7e2e884269c079ed4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=88=98=E8=88=AA=E5=AE=87?= <3364451258@qq.com> Date: Sun, 5 Jul 2026 01:50:05 +0800 Subject: [PATCH] docs: comprehensive README with quickstart, API reference, provider guide, and architecture --- README.md | 248 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 247 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 3c66f05..a3392bc 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,249 @@ # md-vector-db -Markdown 文档向量数据库，支持文档入库、语义检索，可通过 HTTP API 供其他项目调用。 \ No newline at end of file +Markdown 文档向量数据库 — 将 Markdown 文件自动分块、嵌入、存入 ChromaDB，通过语义检索快速查找相关内容。提供 **CLI 命令行工具**和 **HTTP API** 两种使用方式供其他项目集成。 + +## 功能特性 + +- **文档入库**: 支持单文件、目录批量导入 Markdown 文档，自动按标题+段落智能分块 +- **语义检索**: 自然语言查询，返回最相关的文档片段及来源定位（文件名、章节标题） +- **多 Provider**: 本地模型 + 云端 API（OpenAI、阿里云 DashScope、硅基流动等 OpenAI 兼容服务） +- **HTTP API**: FastAPI 提供 RESTful 接口，附带 Swagger 文档 +- **安全**: 可选 API Key 认证、速率限制、路径遍历防护 +- **去重**: 同一文件重复入库自动覆盖旧版本 + +## 快速开始 + +### 1. 安装 + +```bash +git clone git@lhy-git.liuhangyv.top:Serendipity/md-vector-db.git +cd md-vector-db +uv sync +``` + +### 2. 配置 + +```bash +# 复制环境变量模板（API 密钥等） +cp .env.example .env +``` + +编辑 `config.yaml` 选择嵌入模式: + +```yaml +embed: + mode: local # 本地模型（默认，无需联网） + # 或使用云端 API： + # mode: api + # provider: openai # openai | dashscope + # api_base: https://api.siliconflow.cn/v1 # 可选：覆盖默认 API 地址 + # model: BAAI/bge-large-zh-v1.5 # 可选：覆盖默认模型名 +``` + +### 3. 入库文档 + +```bash +# 单文件 +uv run python -m src.cli.main ingest docs/intro.md + +# 批量导入目录（递归扫描所有 .md 文件） +uv run python -m src.cli.main ingest-dir ./md_docs/ + +# 查看统计 +uv run python -m src.cli.main stats +``` + +### 4. 搜索 + +```bash +uv run python -m src.cli.main search "如何配置向量数据库" -k 5 +``` + +输出示例: + +``` +--- 结果 1 (相似度: 0.8231) --- +📄 来源: setup-guide.md +📑 章节: 配置向量数据库 +## 配置向量数据库 +编辑 config.yaml 中的 embed 段来选择嵌入模式... + +--- 结果 2 (相似度: 0.6104) --- +📄 来源: faq.md +📑 章节: 常见问题 +... +``` + +### 5. 启动 HTTP 服务 + +```bash +uv run python -m src.cli.main serve --port 8000 +``` + +浏览器打开 `http://localhost:8000/docs` 查看 Swagger UI，可直接在页面中调试所有 API。 + +--- + +## HTTP API + +| 方法 | 路径 | 需要认证 | 说明 | +|------|------|----------|------| +| `GET` | `/` | — | 重定向到 `/docs` (Swagger UI) | +| `GET` | `/api/v1/health` | — | 健康检查（验证 ChromaDB + Embedder 可用性） | +| `GET` | `/api/v1/collections` | — | 列出集合和已入库的源文件 | +| `POST` | `/api/v1/ingest` | API Key | 入库文档（`file_path` 或 `content` + `file_name`） | +| `POST` | `/api/v1/search` | API Key | 语义检索（`query` + `top_k`） | +| `DELETE` | `/api/v1/documents/{file_name}` | API Key | 按文件名删除所有关联 chunks | + +### 调用示例 + +```bash +# 入库内容 +curl -X POST http://localhost:8000/api/v1/ingest \ + -H "Content-Type: application/json" \ + -H "x-api-key: your-secret-key" \ + -d '{"content": "# 服务配置\n端口设置为 8080。", "file_name": "config.md"}' + +# 语义搜索 +curl -X POST http://localhost:8000/api/v1/search \ + -H "Content-Type: application/json" \ + -H "x-api-key: your-secret-key" \ + -d '{"query": "端口设置", "top_k": 5}' + +# 删除文档 +curl -X DELETE http://localhost:8000/api/v1/documents/config.md \ + -H "x-api-key: your-secret-key" +``` + +### 其他项目集成示例 + +```python +# Python +import httpx + +resp = httpx.post( + "http://localhost:8000/api/v1/search", + json={"query": "向量数据库", "top_k": 5}, + headers={"x-api-key": "your-secret-key"}, +) +for r in resp.json()["results"]: + print(f"[{r['score']:.2f}] {r['source_file']} — {r['section_title']}") +``` + +--- + +## CLI 命令参考 + +所有命令均支持 `--config/-c` 指定配置文件路径。 + +| 命令 | 说明 | +|------|------| +| `ingest <文件路径>` | 入库单个 .md 文件 | +| `ingest-dir <目录路径>` | 递归入库目录下所有 .md 文件 | +| `search <查询> -k <数量>` | 语义检索，`-k` 指定返回条数（默认 10，最大 100） | +| `stats` | 显示 collection 名称、chunks 总数、源文件列表 | +| `serve -p <端口>` | 启动 HTTP 服务（默认 8000） | + +--- + +## 配置说明 + +### config.yaml + +```yaml +chroma: + persist_dir: ./data # ChromaDB 数据存储目录 + collection_name: markdown_docs # 集合名称 + +embed: + mode: local # local（本地模型） | api（云端 API） + local_model: BAAI/bge-small-zh-v1.5 # 本地模型名 + provider: openai # api 模式下的服务商 + api_base: "" # 覆盖默认 API 地址 + model: "" # 覆盖默认模型名 + +chunk: + max_size: 1000 # 分块最大字符数 + overlap: 100 # 相邻 chunk 重叠字符数 + +server: + host: 0.0.0.0 # 服务监听地址 + port: 8000 # 服务监听端口 +``` + +### .env 环境变量 + +```bash +EMBED_API_KEY=sk-xxx # 嵌入 API 密钥（api 模式必需） +MD_VECTOR_API_KEY=secret # HTTP API 访问密钥（不设置则跳过认证） +``` + +### Provider 速查 + +| provider | 默认 API 地址 | 默认模型 | 维度 | +|----------|--------------|---------|------| +| `openai` | `https://api.openai.com/v1` | `text-embedding-3-small` | 1536 | +| `dashscope` | 阿里云 DashScope | `text-embedding-v4` | 1536 | + +使用 OpenAI 兼容的第三方服务（硅基流动、智谱、DeepSeek 等）只需设置 `provider: openai` 并覆盖 `api_base` 和 `model`: + +```yaml +embed: + mode: api + provider: openai + api_base: https://api.siliconflow.cn/v1 + model: BAAI/bge-large-zh-v1.5 +``` + +--- + +## 项目结构 + +``` +md-vector-db/ +├── config.yaml # 主配置文件 +├── .env.example # 环境变量模板 +├── pyproject.toml +├── src/ +│ ├── core/ # 核心逻辑（不依赖 server/cli） +│ │ ├── config.py # YAML + .env → dataclass +│ │ ├── db.py # ChromaDB 封装（线程安全） +│ │ ├── embedder.py # 嵌入器（Local/OpenAI/Dashscope） +│ │ ├── ingest.py # 混合分块 + 入库 +│ │ └── search.py # 语义检索 +│ ├── server/ # FastAPI HTTP 层 +│ │ ├── app.py # 路由 + 中间件 +│ │ ├── deps.py # 依赖注入（AppState） +│ │ └── auth.py # 认证 + 速率限制 +│ └── cli/ +│ └── main.py # Typer CLI +├── data/ # ChromaDB 持久化目录 +├── md_docs/ # 待入库文档目录 +├── scripts/ +│ └── serve.py # 快速启动脚本 +└── tests/ # 测试（46 个） +``` + +## 测试 + +```bash +uv run pytest tests/ -v # 全部测试 +uv run pytest tests/test_embedder.py -v # 嵌入器测试 +uv run pytest tests/ -v -k "search" # 按名称过滤 +``` + +## 架构 + +**数据流**: MD 文件 → `MarkdownSplitter.split()` (标题→段落分块) → `batch_embed()` (分批嵌入) → `ChromaDB collection.add()` → `Searcher.search()` 查询 + +**依赖方向**: `config` ← `db` ← `embedder` ← `ingest` / `search` ← `server` / `cli` + +**分块策略（混合切分）**: 先按 `#`/`##`/`###` 标题拆分 → 章节超过 1000 字符则按段落边界继续拆 → 单个段落仍超限则按标点符号硬切，所有拆分保留 100 字符重叠。 + +**线程安全**: 所有 ChromaDB 写操作（add/delete）通过 `threading.Lock` 保护，支持 FastAPI 多请求并发。 + +--- + +## License + +MIT