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

2.7 KiB
Raw Blame History

Demo REST API 使用说明

范围

DEMO-009 将入库和检索服务公开为版本化 REST API,DEMO-015 将单文件入库切换为持久化异步 Job,DEMO-016 增加批量接收与聚合查询。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

示例

上传并异步排队:

curl -F 'file=@./policy.md;type=text/markdown' \
  http://127.0.0.1:8000/api/v1/documents

使用响应中的 job_id 查询进度:

curl http://127.0.0.1:8000/api/v1/jobs/<job-id>

批量上传并查询聚合进度:

curl -F 'files=@./policy.md;type=text/markdown' \
  -F 'files=@./manual.pdf;type=application/pdf' \
  http://127.0.0.1:8000/api/v1/ingestion-batches

curl http://127.0.0.1:8000/api/v1/ingestion-batches/<batch-id>

检索:

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 应通过可重试清理任务和审计记录强化。