fix: CLI 路径检查改用 is_safe_cli_path(允许绝对路径),更新文档

This commit is contained in:
2026-07-10 15:45:22 +08:00
parent ec3898ecb7
commit f7801b45a7
4 changed files with 40 additions and 23 deletions
+10 -9
View File
@@ -4,14 +4,14 @@ Markdown 文档向量数据库 — 将 Markdown 文件自动分块、嵌入、
## 功能特性
- **文档入库**: 支持单文件、目录批量导入 Markdown 文档,自动按标题+段落智能分块
- **文档入库**: 支持单文件、目录批量导入多种格式文档,自动按标题+段落智能分块
- **语义检索**: 自然语言查询,返回最相关的文档片段及来源定位(文件名、章节标题)
- **多 Provider**: 本地模型 + 云端 APIOpenAI、阿里云 DashScope、硅基流动等 OpenAI 兼容服务)
- **GPU 加速**: 本地模型自动检测 CUDARTX 4060 实测:729 chunks 嵌入仅 1.8s
- **多集合**: 支持多项目数据隔离,不同知识库存入不同 ChromaDB collection
- **HTTP API**: FastAPI 提供 RESTful 接口,附带 Swagger 文档
- **安全**: 可选 API Key 认证、速率限制、路径遍历防护
- **多格式文档**: 支持 `.md` / `.txt` / `.pdf` / `.html`,按扩展名自动选择分块器,可通过 `Splitter` Protocol 扩展
- **多格式文档**: 支持 `.md` / `.txt` / `.pdf` / `.html` / `.epub`,按扩展名自动选择分块器,可通过 `Splitter` Protocol 扩展
- **去重**: 同一文件重复入库自动覆盖旧版本(基于路径 SHA256 哈希)
## 快速开始
@@ -52,7 +52,7 @@ embed:
# 单文件
uv run md-vector-db ingest docs/intro.md
# 批量导入目录(递归扫描所有 .md 文件
# 批量导入目录(递归扫描所有支持的文档格式
uv run md-vector-db ingest-dir ./md_docs/
# 指定集合(多项目数据隔离)
@@ -151,8 +151,8 @@ for r in resp.json()["results"]:
| 命令 | 说明 |
| --------------------------- | -------------------------------------------------------- |
| `ingest <文件路径>` | 入库单个 .md 文件,支持`-C` 指定集合 |
| `ingest-dir <目录路径>` | 递归入库目录下所有 .md 文件 |
| `ingest <文件路径>` | 入库单个文件(自动识别格式),支持`-C` 指定集合 |
| `ingest-dir <目录路径>` | 递归入库目录下所有支持的文档格式 |
| `search <查询> -k <数量>` | 语义检索,`-k` 默认 10、最大 100`--json` JSON 输出 |
| `stats` | 显示 chunks 总数、源文件列表 |
| `serve -p <端口>` | 启动 HTTP 服务(默认 8000 |
@@ -224,6 +224,7 @@ md-vector-db/
│ │ ├── db.py # ChromaDB 封装(线程安全)
│ │ ├── embedder.py # 嵌入器(Local/OpenAI/Dashscope
│ │ ├── ingest.py # 混合分块 + 入库
│ │ ├── security.py # 路径遍历防护
│ │ ├── search.py # 语义检索
│ │ └── splitters/ # 文档分块器包
│ │ ├── base.py # Splitter(Protocol) + BaseTextSplitter(ABC)
@@ -242,15 +243,15 @@ md-vector-db/
├── data/ # ChromaDB 持久化目录
├── md_docs/ # 待入库文档目录
├── scripts/
│ ├── serve.py # 快速启动脚本
│ └── ingest_obsidian.py # 批量入库 Obsidian 知识库
└── tests/ # 测试(115+ 个)
│ ├── serve.py # 快速启动脚本
│ └── ingest_obsidian.py # 批量入库 Obsidian 知识库
└── tests/ # 测试(120 个)
```
## 测试
```bash
uv run pytest tests/ -v # 全部测试 (115+ 个)
uv run pytest tests/ -v # 全部测试 (120 个)
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 # 覆盖率