knowledge-platform/docs/api/API_CONTRACT.md
2026-09-02 16:00:42 +08:00

98 lines
3.9 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# REST API Contract
Version all public APIs under `/api/v1`.
Initial domains: auth, users/groups, knowledge-bases, documents, compiled-knowledge, search, evaluations, jobs, audit-logs, providers and MCP administration.
Use OpenAPI as executable source of truth once implementation starts. Provider-specific concepts must not leak into public contracts.
## Demo v0.1 P0
DEMO-009 公开以下最小接口。`docs/demo/DEMO_SCOPE.md` 中的 `/api/*` 逻辑路径按本契约统一
版本化为 `/api/v1/*`。
下表描述当前已实现的同步 Demo 契约;它将在 `DEMO-015` 完成时由后文的异步契约替代。
| Method | Path | 行为 |
|---|---|---|
| `POST` | `/api/v1/documents` | multipart 单文件上传并同步执行完整入库流水线 |
| `GET` | `/api/v1/documents` | 按创建时间倒序返回文档列表 |
| `GET` | `/api/v1/documents/{document_id}` | 返回单个文档状态与安全错误信息 |
| `DELETE` | `/api/v1/documents/{document_id}` | 直接删除向量、Metadata、解析产物和原始文件 |
| `POST` | `/api/v1/search` | Dense Top20、Reranker、TopK、来源补全 |
上传字段名为 `file`,支持 PDF、DOCX、TXT 和 Markdown。成功返回 `201` 和 Document;
Demo 同步流水线完成后状态为 `ready`。Document 响应不暴露 `storage_key`、Provider 配置或
索引实现。
Search 请求:
```json
{
"query": "产品A退款周期是多少?",
"top_k": 5
}
```
Search 响应:
```json
{
"results": [
{
"document_id": "6e5ec370-5a45-4eb7-95d7-e84267ad8752",
"filename": "产品A说明书.pdf",
"page": 12,
"section": "退款政策",
"chunk_id": "76ba1c30-bff7-44e5-9989-fb8372f54f46",
"content": "……",
"score": 0.82,
"rerank_score": 0.94
}
]
}
```
公开错误语义:请求校验失败返回 `422`,不支持的上传类型返回 `415`,文件过大返回 `413`,
文档不存在返回 `404`,运行时 Provider 未配置返回 `503`。上游 Provider 或持久化异常只返回
经过收敛的 `5xx` 信息,不回显凭证、请求正文或厂商响应。
## Demo Admin 客户端路由
DEMO-010 提供 `/admin/upload`、`/admin/documents` 和 `/admin/search` 三个客户端路由,
`/admin` 默认展示上传页。它们是同源静态页面,不是新增业务 API,也不改变上述公开 REST
契约;所有业务操作仍调用 `/api/v1`。
## Planned async ingestion contract(DEMO-015/016,尚未实现)
| Method | Path | 行为 |
|---|---|---|
| `POST` | `/api/v1/documents` | 单文件接收;持久化 Source、Document、Job 后返回 `202` |
| `POST` | `/api/v1/ingestion-batches` | multipart 多文件接收,返回批次及逐文件 Document/Job 标识 |
| `GET` | `/api/v1/ingestion-batches/{batch_id}` | 返回批次汇总和逐文件最新状态 |
| `GET` | `/api/v1/jobs/{job_id}` | 返回阶段、状态、attempt、最大尝试次数和安全错误信息 |
单文件与批量上传都不等待解析、Chunk、Embedding 或索引完成。批量响应示意:
```json
{
"batch_id": "d21f8012-4c4e-4bb4-89af-e11c0f9f470e",
"items": [
{
"filename": "退款政策.md",
"document_id": "6e5ec370-5a45-4eb7-95d7-e84267ad8752",
"job_id": "7adc4278-1157-4c3d-95a4-6926ad77a04e",
"status": "queued"
}
]
}
```
Job 公开状态为 `queued | running | retrying | succeeded | failed | cancelled`,并通过 `stage`
表示 `parsing | cleaning | chunking | embedding | indexing`。错误字段只返回有界、安全摘要。
批次允许逐文件部分接收/失败,不以一个文件的处理结果回滚其他文件。文件数量、单文件大小和
请求总大小均由服务端配置限制。
自动重试是服务端 Job 行为,不要求客户端再次上传,也不新增公开手动重试接口。每次重试前
清理派生数据但保留原始文件和稳定的 Document ID;达到次数上限或清理失败后进入 `failed`。