feat: 第三优先级完善 — CI/CD、PyPI、pre-commit、CHANGELOG、贡献指南、基准测试、ADR

2026-07-11 20:13:36 +08:00
parent 7e0b9553c8
commit 2ddb6de92f
13 changed files with 483 additions and 12 deletions
@@ -0,0 +1,68 @@
+# md-vector-db API 参考文档
+
+## REST API
+
+- **Base URL**: `http://localhost:8000/api/v1`
+- **认证**: `X-API-Key` Header（取决于 `MD_VECTOR_API_KEY` 环境变量）
+- **速率限制**: 60s 窗口内最多 30 请求
+
+### GET /health — 健康检查
+
+无需认证。
+
+```json
+{
+  "status": "ok",
+  "checks": {
+    "chromadb": {"status": "ok", "count": 1240},
+    "embedder": {"status": "ok", "dimension": 512}
+  }
+}
+```
+
+### GET /collections — 列出集合
+
+需 API Key。返回 `{"collections": [{"name": "...", "count": N}, ...]}`。
+
+### POST /search — 语义检索
+
+| 字段 | 类型 | 必填 | 约束 |
+|------|------|------|------|
+| query | string | ✅ | 1-2000 字符 |
+| top_k | int | ❌ | 1-100，默认 10 |
+| collection | string | ❌ | ≤128 字符 |
+
+返回 `{"results": [...], "collection": "..."}`，每条结果含 `id`, `content`, `source_file`, `section_title`, `heading_level`, `score`。
+
+### POST /ingest — 入库文档
+
+| 字段 | 类型 | 必填 | 约束 |
+|------|------|------|------|
+| file_path | string | 二选一 | 安全路径 |
+| content | string | 二选一 | ≤500KB |
+| file_name | string | 推荐 | 1-255 字符 |
+| collection | string | ❌ | ≤128 字符 |
+
+返回 `{"status": "ok", "chunks": N, "file": "...", "collection": "..."}`。
+
+### DELETE /documents/{file_name} — 删除文档
+
+查询参数: `collection` (可选)。
+
+| 状态码 | 含义 |
+|--------|------|
+| 200 | 删除成功 |
+| 400 | file_name 不合法 |
+| 401 | API Key 无效 |
+| 404 | 文档不存在 |
+
+## CLI 命令
+
+```bash
+md-vector-db ingest <文件> --incremental --force
+md-vector-db ingest-dir <目录> -C <集合>
+md-vector-db search "<查询>" -k 10 --mode hybrid --json
+md-vector-db stats -C <集合>
+md-vector-db export -o output.json -f json
+md-vector-db serve -p 8000
+```