docs: 更新 README/CLAUDE 文档 + 配置 uv CUDA 兼容
- README: 补充 GPU 加速章节、多集合、CLI 新选项 (-C/--json) - CLAUDE: 修正 uv run 可用说明、补充 [tool.uv] 配置文档 - pyproject.toml: 添加 [tool.uv] 配置, 通过 find-links + unsafe-best-match 让 uv 从本地 CUDA wheel 解析 torch, 不再覆盖 GPU 环境 - uv.lock: 更新 lockfile, Windows 平台锁定 torch 2.6.0+cu124
This commit is contained in:
@@ -7,9 +7,11 @@ Markdown 文档向量数据库 — 将 Markdown 文件自动分块、嵌入、
|
||||
- **文档入库**: 支持单文件、目录批量导入 Markdown 文档，自动按标题+段落智能分块
|
||||
- **语义检索**: 自然语言查询，返回最相关的文档片段及来源定位（文件名、章节标题）
|
||||
- **多 Provider**: 本地模型 + 云端 API（OpenAI、阿里云 DashScope、硅基流动等 OpenAI 兼容服务）
|
||||
- **GPU 加速**: 本地模型自动检测 CUDA（RTX 4060 实测：729 chunks 嵌入仅 1.8s）
|
||||
- **多集合**: 支持多项目数据隔离，不同知识库存入不同 ChromaDB collection
|
||||
- **HTTP API**: FastAPI 提供 RESTful 接口，附带 Swagger 文档
|
||||
- **安全**: 可选 API Key 认证、速率限制、路径遍历防护
|
||||
- **去重**: 同一文件重复入库自动覆盖旧版本
|
||||
- **去重**: 同一文件重复入库自动覆盖旧版本（基于路径 SHA256 哈希）
|
||||
|
||||
## 快速开始
|
||||
|
||||
@@ -44,19 +46,26 @@ embed:
|
||||
|
||||
```bash
|
||||
# 单文件
|
||||
uv run python -m src.cli.main ingest docs/intro.md
|
||||
uv run md-vector-db ingest docs/intro.md
|
||||
|
||||
# 批量导入目录（递归扫描所有 .md 文件）
|
||||
uv run python -m src.cli.main ingest-dir ./md_docs/
|
||||
uv run md-vector-db ingest-dir ./md_docs/
|
||||
|
||||
# 指定集合（多项目数据隔离）
|
||||
uv run md-vector-db ingest docs/intro.md -C my_project
|
||||
|
||||
# 查看统计
|
||||
uv run python -m src.cli.main stats
|
||||
uv run md-vector-db stats
|
||||
```
|
||||
|
||||
### 4. 搜索
|
||||
|
||||
```bash
|
||||
uv run python -m src.cli.main search "如何配置向量数据库" -k 5
|
||||
# 搜索（注意指定集合，默认为 default）
|
||||
uv run md-vector-db search "如何配置向量数据库" -k 5 -C my_project
|
||||
|
||||
# JSON 输出（供 MCP 等工具消费）
|
||||
uv run md-vector-db search "Docker 部署" -k 3 -C obsidian_blog --json
|
||||
```
|
||||
|
||||
输出示例:
|
||||
@@ -77,7 +86,7 @@ uv run python -m src.cli.main search "如何配置向量数据库" -k 5
|
||||
### 5. 启动 HTTP 服务
|
||||
|
||||
```bash
|
||||
uv run python -m src.cli.main serve --port 8000
|
||||
uv run md-vector-db serve --port 8000
|
||||
```
|
||||
|
||||
浏览器打开 `http://localhost:8000/docs` 查看 Swagger UI，可直接在页面中调试所有 API。
|
||||
@@ -91,8 +100,8 @@ uv run python -m src.cli.main serve --port 8000
|
||||
| `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`） |
|
||||
| `POST` | `/api/v1/ingest` | API Key | 入库文档（`file_path` 或 `content` + `file_name`，可选 `collection`） |
|
||||
| `POST` | `/api/v1/search` | API Key | 语义检索（`query` + `top_k`，可选 `collection`） |
|
||||
| `DELETE` | `/api/v1/documents/{file_name}` | API Key | 按文件名删除所有关联 chunks |
|
||||
|
||||
### 调用示例
|
||||
@@ -134,14 +143,14 @@ for r in resp.json()["results"]:
|
||||
|
||||
## CLI 命令参考
|
||||
|
||||
所有命令均支持 `--config/-c` 指定配置文件路径。
|
||||
所有命令均支持 `--config/-c`（配置文件）、`--collection/-C`（集合名，默认 `default`）。
|
||||
|
||||
| 命令 | 说明 |
|
||||
|------|------|
|
||||
| `ingest <文件路径>` | 入库单个 .md 文件 |
|
||||
| `ingest <文件路径>` | 入库单个 .md 文件，支持 `-C` 指定集合 |
|
||||
| `ingest-dir <目录路径>` | 递归入库目录下所有 .md 文件 |
|
||||
| `search <查询> -k <数量>` | 语义检索，`-k` 指定返回条数（默认 10，最大 100） |
|
||||
| `stats` | 显示 collection 名称、chunks 总数、源文件列表 |
|
||||
| `search <查询> -k <数量>` | 语义检索，`-k` 默认 10、最大 100，`--json` JSON 输出 |
|
||||
| `stats` | 显示 chunks 总数、源文件列表 |
|
||||
| `serve -p <端口>` | 启动 HTTP 服务（默认 8000） |
|
||||
|
||||
---
|
||||
@@ -182,6 +191,7 @@ MD_VECTOR_API_KEY=secret # HTTP API 访问密钥（不设置则跳过认证
|
||||
|
||||
| provider | 默认 API 地址 | 默认模型 | 维度 |
|
||||
|----------|--------------|---------|------|
|
||||
| `local` | 本地（sentence-transformers） | `BAAI/bge-small-zh-v1.5` | 512 |
|
||||
| `openai` | `https://api.openai.com/v1` | `text-embedding-3-small` | 1536 |
|
||||
| `dashscope` | 阿里云 DashScope | `text-embedding-v4` | 1536 |
|
||||
|
||||
@@ -220,16 +230,18 @@ md-vector-db/
|
||||
├── data/ # ChromaDB 持久化目录
|
||||
├── md_docs/ # 待入库文档目录
|
||||
├── scripts/
|
||||
│ └── serve.py # 快速启动脚本
|
||||
│ ├── serve.py # 快速启动脚本
|
||||
│ └── ingest_obsidian.py # 批量入库 Obsidian 知识库
|
||||
└── tests/ # 测试（46 个）
|
||||
```
|
||||
|
||||
## 测试
|
||||
|
||||
```bash
|
||||
uv run pytest tests/ -v # 全部测试
|
||||
uv run pytest tests/ -v # 全部测试 (46 个)
|
||||
uv run pytest tests/test_embedder.py -v # 嵌入器测试
|
||||
uv run pytest tests/ -v -k "search" # 按名称过滤
|
||||
uv run pytest tests/ -v --cov=src --cov-report=term-missing # 覆盖率
|
||||
```
|
||||
|
||||
## 架构
|
||||
@@ -244,6 +256,25 @@ uv run pytest tests/ -v -k "search" # 按名称过滤
|
||||
|
||||
---
|
||||
|
||||
## GPU 加速
|
||||
|
||||
本地嵌入模式自动检测 CUDA 设备，优先使用 GPU。实测性能对比（RTX 4060 Laptop，bge-small-zh-v1.5）：
|
||||
|
||||
| 文件大小 | chunks | CPU 耗时 | GPU 耗时 |
|
||||
|----------|--------|----------|----------|
|
||||
| 60KB | 320 | 数分钟至卡死 | 0.7s |
|
||||
| 96KB | 729 | 卡死 | 1.8s |
|
||||
|
||||
**GPU 环境前提**：安装 CUDA 版 torch。本项目 `pyproject.toml` 已配置从本地 wheel 目录获取 CUDA 版 torch，`uv sync` 即可。
|
||||
|
||||
```toml
|
||||
[tool.uv]
|
||||
find-links = ["D:/settings/Language/Python/库"] # 本地 CUDA wheel
|
||||
index-strategy = "unsafe-best-match" # 允许跨源查找
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## License
|
||||
|
||||
MIT
|
||||
|
||||
Reference in New Issue
Block a user