From 11b6171e2132f7828e2310456558e542c7dc15f2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E5=88=98=E8=88=AA=E5=AE=87?= <3364451258@qq.com> Date: Tue, 7 Jul 2026 15:04:45 +0800 Subject: [PATCH] =?UTF-8?q?docs(test-guide):=20=E9=87=8D=E5=86=99=E4=B8=BA?= =?UTF-8?q?=E5=AE=8C=E6=95=B4=E7=9A=84=E9=A1=B9=E7=9B=AE=E4=BD=BF=E7=94=A8?= =?UTF-8?q?=E4=B8=8E=E6=B5=8B=E8=AF=95=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 替换原有的通用向量数据库入门内容，新增项目简介、核心概念、快速上手流程、CLI与HTTP API使用方法、配置说明、嵌入提供商选择、安全配置、架构概览、GPU加速、测试命令和常见问题等完整文档内容，适配作为项目的使用指南与测试手册。 --- md_docs/test-guide.md | 250 ++++++++++++++++++++++++++++++++++++++---- 1 file changed, 229 insertions(+), 21 deletions(-) diff --git a/md_docs/test-guide.md b/md_docs/test-guide.md index f8210a6..da665e5 100644 --- a/md_docs/test-guide.md +++ b/md_docs/test-guide.md @@ -1,35 +1,243 @@ -# 向量数据库入门指南 +# md-vector-db 测试指南 -## 什么是向量数据库 +> 本文档既用于测试向量数据库的入库和检索功能，也作为新用户的上手指南。 -向量数据库是一种专门用于存储和检索向量嵌入的数据库。 +## 项目简介 -## 为什么需要向量数据库 +md-vector-db 是一个轻量级 Markdown 文档向量数据库——将 `.md` 文件自动分块、嵌入、存入 ChromaDB，通过语义检索快速查找相关内容。提供 **CLI 命令行工具**和 **HTTP API** 两种使用方式。 -传统的数据库只能做精确匹配，而向量数据库可以做语义相似度搜索。 +## 核心概念 -## 常用的向量数据库 +### 向量嵌入 -- ChromaDB：轻量级，适合小项目 -- Qdrant：高性能，适合生产环境 -- Milvus：分布式，适合大规模数据 +向量嵌入是将文本转换成固定长度的浮点数数组，使语义相近的文本在向量空间中距离更近。例如： -## ChromaDB 快速上手 +| 查询 | 匹配结果 | 相似度 | +|------|----------|--------| +| "如何配置 GPU" | GPU 加速配置说明 | 0.85 | +| "python 入门" | Python 基础知识 | 0.82 | +| "数据库安装" | 安装与配置指南 | 0.79 | -安装 ChromaDB： +### 文档分块 + +长文档不能直接嵌入——模型有最大输入长度限制，且大段文本会稀释语义。md-vector-db 使用**混合分块策略**： + +1. **按标题拆分**：先在 `#`/`##`/`###` 标题边界切分 +2. **按段落拆分**：章节超过 1000 字符时，在段落边界（双换行）继续切 +3. **硬切兜底**：单个段落仍超限时，按标点符号硬切，同时保留 100 字符重叠 + +### ChromaDB Collection + +Collection 是 ChromaDB 的数据容器，类似关系数据库的"表"。不同知识库存入不同 collection 实现数据隔离： ```bash -pip install chromadb +uv run md-vector-db ingest docs/readme.md -C project_a # 项目 A 的知识库 +uv run md-vector-db ingest docs/readme.md -C project_b # 项目 B 的知识库 ``` -创建 collection 并添加数据： +## 快速开始 -```python -import chromadb -client = chromadb.PersistentClient(path="./data") -collection = client.get_or_create_collection("my_docs") -collection.add( - documents=["这是第一篇文档", "这是第二篇文档"], - ids=["doc1", "doc2"], -) +### 1. 安装与配置 + +```bash +git clone git@lhy-git.liuhangyv.top:Serendipity/md-vector-db.git +cd md-vector-db +uv sync +cp .env.example .env ``` + +配置文件 `config.yaml` 控制嵌入模式、分块参数和服务端口： + +```yaml +embed: + mode: local # 本地模型（默认, 无需 API Key） + local_model: BAAI/bge-small-zh-v1.5 # 中文优化, 512 维 + +chunk: + max_size: 1000 # 分块最大字符数 + overlap: 100 # 相邻块重叠字符数 + +server: + host: 127.0.0.1 + port: 8000 +``` + +### 2. 入库文档 + +```bash +# 单文件入库（本篇测试指南） +uv run md-vector-db ingest md_docs/test-guide.md + +# 目录批量入库 +uv run md-vector-db ingest-dir ./md_docs/ + +# 指定 collection +uv run md-vector-db ingest md_docs/test-guide.md -C test_kb + +# 通过管道直接入库内容 +echo "# 测试文档\n这是一段测试内容。" | uv run md-vector-db ingest - --name pipe-test.md +``` + +### 3. 语义搜索 + +```bash +# 基础搜索 +uv run md-vector-db search "如何配置向量数据库" -k 5 + +# 指定 collection +uv run md-vector-db search "GPU 加速" -k 3 -C test_kb + +# JSON 输出（供 MCP 等工具消费） +uv run md-vector-db search "分块策略" -k 3 --json +``` + +输出示例： + +``` +--- 结果 1 (相似度: 0.8231) --- +来源: test-guide.md +章节: 文档分块 +## 文档分块 +长文档不能直接嵌入——模型有最大输入长度限制... + +--- 结果 2 (相似度: 0.6104) --- +来源: readme.md +章节: 快速开始 +... +``` + +### 4. 启动 HTTP 服务 + +```bash +uv run md-vector-db serve --port 8000 +``` + +浏览器打开 `http://localhost:8000/docs` 查看 Swagger UI。 + +API 调用示例： + +```bash +# 入库 +curl -X POST http://localhost:8000/api/v1/ingest \ + -H "Content-Type: application/json" \ + -d '{"content": "# 测试\n这是测试文档。", "file_name": "api-test.md"}' + +# 搜索 +curl -X POST http://localhost:8000/api/v1/search \ + -H "Content-Type: application/json" \ + -d '{"query": "测试文档", "top_k": 3}' + +# 查看集合 +curl http://localhost:8000/api/v1/collections + +# 健康检查 +curl http://localhost:8000/api/v1/health + +# 删除文档 +curl -X DELETE http://localhost:8000/api/v1/documents/api-test.md +``` + +### 5. 查看统计 + +```bash +uv run md-vector-db stats +uv run md-vector-db stats -C test_kb --json +``` + +## 嵌入 Provider 选择 + +| Provider | 类型 | 默认模型 | 向量维度 | 适用场景 | +|----------|------|----------|----------|----------| +| `local` | 本地 GPU/CPU | BAAI/bge-small-zh-v1.5 | 512 | 离线、免费、低延迟 | +| `openai` | OpenAI 兼容 API | text-embedding-3-small | 1536 | 高质量、多语言 | +| `dashscope` | 阿里云 DashScope | text-embedding-v4 | 1536 | 国内部署、中文优化 | + +切换 Provider 只需修改 `config.yaml`： + +```yaml +embed: + mode: api + provider: openai + api_base: https://api.siliconflow.cn/v1 # 硅基流动等 OpenAI 兼容服务 + model: BAAI/bge-large-zh-v1.5 +``` + +然后在 `.env` 中设置 `EMBED_API_KEY=sk-xxx`。 + +## 安全配置 + +### API Key 认证 + +在 `.env` 中设置 `MD_VECTOR_API_KEY=your-secret-key`，所有写操作（入库/删除）和搜索都需要在请求头中携带： + +```bash +curl -H "x-api-key: your-secret-key" http://localhost:8000/api/v1/search ... +``` + +不设置则跳过认证（适合本地开发）。 + +### 速率限制 + +默认每个 IP 每 60 秒最多 30 个请求，可在 `auth.py` 中调整。 + +### 路径遍历防护 + +所有文件操作入口（CLI / API / 脚本）统一通过 `is_safe_path()` 拒绝绝对路径和 `..` 目录穿越。 + +## 架构概览 + +``` +src/ +├── core/ # 核心逻辑（零框架依赖） +│ ├── config.py # YAML + .env → dataclass 配置 +│ ├── db.py # ChromaDB 线程安全封装 +│ ├── embedder.py # 策略模式：Local / OpenAI / DashScope +│ ├── ingest.py # MarkdownSplitter + DocumentIngestor +│ ├── search.py # Searcher 语义检索 +│ └── security.py # is_safe_path 路径遍历防护 +├── server/ # FastAPI HTTP 层 +│ ├── app.py # 路由 + CORS + 安全头中间件 +│ ├── auth.py # API Key 认证 + 速率限制 +│ └── deps.py # AppState 依赖注入 +└── cli/ + └── main.py # Typer CLI（5 个命令） +``` + +**数据流**：MD 文件 → `MarkdownSplitter.split()` → `batch_embed()` → `ChromaDB collection.add()` → `Searcher.search()` + +**依赖方向**：`config ← db ← embedder ← ingest/search ← server/cli` + +## GPU 加速 + +本地嵌入模式自动检测 CUDA 设备。实测性能（RTX 4060 Laptop, bge-small-zh-v1.5）： + +| 文件大小 | chunks | CPU | GPU | +|----------|--------|-----|-----| +| 60 KB | 320 | 数分钟 | 0.7s | +| 96 KB | 729 | 卡死 | 1.8s | + +如果 GPU 不可用，自动回退 CPU。 + +## 测试 + +```bash +uv run pytest tests/ -v # 全部测试 (70 个) +uv run pytest tests/test_security.py -v # 安全模块测试 +uv run pytest tests/test_deps.py -v # 依赖注入测试 +uv run pytest tests/ -v -k "search" # 按名称过滤 +uv run pytest tests/ --cov=src --cov-report=term-missing # 覆盖率 +``` + +## 常见问题 + +**Q: `uv sync` 失败，提示找不到 torch？** +A: 项目配置了从本地 wheel 目录获取 CUDA 版 torch。Linux/Mac 用户可移除 `pyproject.toml` 中的 `[tool.uv]` 配置段后重试。 + +**Q: 第一次运行下载模型很慢？** +A: 国内用户自动使用 `hf-mirror.com` 镜像。也可设置 `HF_MIRROR` 环境变量指定其他镜像。 + +**Q: 如何清空 collection 重新入库？** +A: 使用 `delete_document` API 逐个删除，或直接删除 `data/` 目录后重启服务。 + +**Q: 支持非 Markdown 文件吗？** +A: 当前仅支持 `.md`。通过实现 `Splitter` 接口（Protocol）可扩展支持 PDF、HTML 等格式。