57 lines
2.1 KiB
Markdown
57 lines
2.1 KiB
Markdown
# Demo REST API 使用说明
|
||
|
||
## 范围
|
||
|
||
DEMO-009 将已经完成的同步入库和检索服务公开为版本化 REST API。API 层只负责输入校验、
|
||
错误映射和响应序列化,不重复实现 Parser、Embedding、VectorStore 或 Reranker 业务逻辑。
|
||
|
||
本任务不包含 Admin Console、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. 执行 `uv run alembic upgrade head`;
|
||
5. 新旧索引迁移按 `docs/development/INDEX_REBUILD.md` 构建、验证并激活 Profile;
|
||
6. 执行 `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
|
||
```
|
||
|
||
检索:
|
||
|
||
```bash
|
||
curl -H 'Content-Type: application/json' \
|
||
-d '{"query":"产品A退款周期是多少?","top_k":5}' \
|
||
http://127.0.0.1:8000/api/v1/search
|
||
```
|
||
|
||
Demo 上传请求会一直等待 Parse、Clean、Chunk、Embedding 和 OceanBase Upsert 完成。大文
|
||
件或云端调用较慢时,请求耗时会相应增加;异步任务属于 Demo 后置能力。
|
||
|
||
## 删除一致性
|
||
|
||
删除按以下顺序执行:
|
||
|
||
1. 删除所有已记录 Index Profile 以及当前 Profile 的 OceanBase 行;
|
||
2. 删除 OceanBase canonical 关系表中的 ChunkIndexState、Chunk 和 Document;
|
||
3. 删除解析 JSON 与不可变原始文件。
|
||
|
||
向量清理失败时保留 canonical Metadata 和原始文件。Metadata 提交后若文件清理失败,接口
|
||
返回明确的 `500`,可能留下不可访问的孤立文件;这是 Demo 直接删除的已知边界,正式 V1
|
||
应通过可重试清理任务和审计记录强化。
|