5.0 KiB
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-015 已将单文件上传切换为持久化异步 Job;批量提交仍留给 DEMO-016。
| Method | Path | 行为 |
|---|---|---|
POST |
/api/v1/documents |
multipart 单文件接收;持久化 Source、Document、Job 后返回 202 |
GET |
/api/v1/documents |
按创建时间倒序返回文档列表 |
GET |
/api/v1/documents/{document_id} |
返回单个文档状态与安全错误信息 |
DELETE |
/api/v1/documents/{document_id} |
直接删除向量、Metadata、解析产物和原始文件 |
GET |
/api/v1/jobs/{job_id} |
返回阶段、状态、attempt、最大尝试次数和安全错误信息 |
POST |
/api/v1/search |
Dense Top20、Reranker、TopK、来源补全 |
上传字段名为 file,支持 PDF、DOCX、TXT 和 Markdown。成功返回 202、Document 字段及
job_id、job_status=queued、max_attempts;响应不等待 Parse、Clean、Chunk、Embedding 或
Index。Document 响应不暴露 storage_key、Provider 配置或索引实现。
Search 请求:
{
"query": "产品A退款周期是多少?",
"top_k": 5
}
Search 响应:
{
"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,
文档或 Job 不存在返回 404,活动 Job 的文档删除返回 409,运行时 Provider 未配置返回
503。上游 Provider 或持久化异常只返回经过收敛的 5xx 信息,不回显凭证、请求正文或
厂商响应。
Demo Admin 客户端路由
DEMO-010 提供 /admin/upload、/admin/documents 和 /admin/search 三个客户端路由,
/admin 默认展示上传页。它们是同源静态页面,不是新增业务 API,也不改变上述公开 REST
契约;所有业务操作仍调用 /api/v1。
当前公共知识库部署边界(PLAN-002)
当前阶段所有 Document 属于同一个公共知识可见域,不新增用户、知识库或 ACL 字段,也不把 这些完整未实现能力伪装为默认放行。Admin 写接口只允许部署在企业受控网络或统一接入网关后; Ingress 是否进一步认证属于部署配置,但前端隐藏按钮或隐藏路由不构成安全控制。
集群重启、扩缩容和滚动部署不得改变本契约或要求浏览器重新注入 Provider 配置。数据库、BOS、 模型与队列凭据由服务端 Secret 提供,任何 API 响应都不得返回这些值。
异步入库契约(DEMO-015 已实现;DEMO-016 批量部分待实现)
| Method | Path | 行为 |
|---|---|---|
POST |
/api/v1/documents |
已实现:单文件接收并返回 Document/Job 标识 |
POST |
/api/v1/ingestion-batches |
multipart 多文件接收,返回批次及逐文件 Document/Job 标识 |
GET |
/api/v1/ingestion-batches/{batch_id} |
返回批次汇总和逐文件最新状态 |
GET |
/api/v1/jobs/{job_id} |
已实现:返回持久化 Job 状态 |
单文件响应示意:
{
"id": "6e5ec370-5a45-4eb7-95d7-e84267ad8752",
"filename": "退款政策.md",
"media_type": "text/markdown",
"size_bytes": 1024,
"status": "uploaded",
"error_message": null,
"created_at": "2026-09-02T12:00:00Z",
"updated_at": "2026-09-02T12:00:00Z",
"job_id": "7adc4278-1157-4c3d-95a4-6926ad77a04e",
"job_status": "queued",
"max_attempts": 3
}
DEMO-016 的批量响应示意:
{
"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。