docs: comprehensive README with quickstart, API reference, provider guide, and architecture
This commit is contained in:
@@ -1,3 +1,249 @@
|
||||
# md-vector-db
|
||||
|
||||
Markdown 文档向量数据库，支持文档入库、语义检索，可通过 HTTP API 供其他项目调用。
|
||||
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
|
||||
|
||||
Reference in New Issue
Block a user