knowledge-platform/docs/development/REST_API_SETUP.md
2026-09-02 20:18:58 +08:00

67 lines
2.4 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.

# Demo REST API 使用说明
## 范围
DEMO-009 将入库和检索服务公开为版本化 REST API,DEMO-015 将单文件入库切换为持久化异步
Job。API 层只负责输入校验、
错误映射和响应序列化,不重复实现 Parser、Embedding、VectorStore 或 Reranker 业务逻辑。
当前不包含 ACL/RBAC、软删除、批量上传或 Hybrid Search。
## 启动前提
1. 按 `docs/development/BOS_SETUP.md` 配置 BOS;
2. 按 `docs/development/OCEANBASE_VECTOR_SETUP.md` 配置 OceanBase Vector 和千帆 Embedding;
3. 按 `docs/development/RERANKER_SETUP.md` 配置 Reranker;
4. 按 `docs/development/ASYNC_INGESTION_SETUP.md` 配置 RabbitMQ 并启动 Worker;
5. 执行 `uv run alembic upgrade head`;
6. 新旧索引迁移按 `docs/development/INDEX_REBUILD.md` 构建、验证并激活 Profile;
7. 执行 `make run`。
`/healthz` 和 OpenAPI 可以在没有云端凭证时启动和访问。业务依赖在首次访问 P0 业务接口时
延迟创建;配置不完整时返回 `503`,不会将凭证名以外的配置值暴露给客户端。
OpenAPI 地址:`/api/v1/openapi.json`
Swagger UI:`/api/v1/docs`
## 示例
上传并异步排队:
```bash
curl -F 'file=@./policy.md;type=text/markdown' \
http://127.0.0.1:8000/api/v1/documents
```
使用响应中的 `job_id` 查询进度:
```bash
curl http://127.0.0.1:8000/api/v1/jobs/<job-id>
```
检索:
```bash
curl -H 'Content-Type: application/json' \
-d '{"query":"产品A退款周期是多少?","top_k":5}' \
http://127.0.0.1:8000/api/v1/search
```
上传只等待不可变源文件、Document 与 Job 持久化,成功返回 `202`。Worker 后台执行 Parse、
Clean、Chunk、Embedding 和 OceanBase Upsert;客户端通过 Job 状态判断何时可检索。
## 删除一致性
删除按以下顺序执行:
1. 删除所有已记录 Index Profile 以及当前 Profile 的 OceanBase 行;
2. 删除 OceanBase canonical 关系表中的 ChunkIndexState、Chunk 和 Document;
3. 删除解析 JSON 与不可变原始文件。
`queued`、`running` 或 `retrying` Job 对应的 Document 返回 `409`,避免删除与 Worker 并发。
向量清理失败时保留 canonical Metadata 和原始文件。Metadata 提交后若文件清理失败,接口
返回明确的 `500`,可能留下不可访问的孤立文件;这是 Demo 直接删除的已知边界,正式 V1
应通过可重试清理任务和审计记录强化。