69 lines
1.8 KiB
Markdown
69 lines
1.8 KiB
Markdown
# 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
|
|
```
|