44.文件上传任务队列与知识库管理一套完整API如何设计
文件上传、任务队列与知识库管理一套完整 API 如何设计码海寻道 · 大模型、智能体与 RAG 工程组件系列第 44 篇知识库 API 的难点不在于写出一个上传接口而在于把文件、文档版本、异步任务、向量索引和用户操作串成可追踪的生命周期。一、从用户动作倒推接口用户通常需要创建或选择知识库上传一个或多个文件查看解析进度查看文档状态和错误重新处理或删除文档搜索和问答查看引用来源。因此接口不应只围绕文件而要围绕knowledge_base、document、job和run建模。确认接口应校验上传对象是否属于当前用户和租户并重新核对大小、MIME、哈希和病毒扫描状态。大文件可以使用分片或多段上传但服务端必须记录分片状态、校验和和过期时间未完成的临时对象要由生命周期任务清理。二、推荐资源关系Tenant └── KnowledgeBase └── Document ├── DocumentVersion ├── ProcessingJob └── Chunk / Vector Index一个文件可能有多个版本一个版本可能有多次处理任务。不要用一个file_status字段覆盖所有生命周期。三、创建知识库和上传流程POST /api/v1/knowledge-bases{name:财务制度库,description:内部财务制度和报销规则,embedding_profile:zh-embedding-v2}上传可以采用预签名 URLPOST /api/v1/knowledge-bases/{kb_id}/upload-sessions{filename:travel-policy.pdf,content_type:application/pdf,size_bytes:2048000,sha256:...}服务端返回短时上传地址和upload_id。客户端上传完成后调用确认接口POST /api/v1/upload-sessions/{upload_id}/complete服务端重新检查对象存在、大小、哈希和租户范围再创建文档版本和处理任务。四、任务接口和状态GET /api/v1/jobs/{job_id} POST /api/v1/jobs/{job_id}/cancel POST /api/v1/jobs/{job_id}/retry GET /api/v1/jobs/{job_id}/events状态示例{job_id:job-001,document_id:doc-001,status:running,stage:embedding,progress:65,processed:130,total:200,error:null}任务状态由服务端维护前端可以轮询或使用 SSE 订阅。不能只依赖前端上传回调判断任务完成。建议把状态转换限制为明确的状态机例如queued → running → succeeded失败进入failed取消进入cancelled每次转换记录job_id、attempt、worker_id、错误码、时间和输入版本。只有解析、切分、向量写入和可检索检查都通过文档才进入published或ready。五、文档管理接口GET /api/v1/knowledge-bases/{kb_id}/documents GET /api/v1/documents/{document_id} GET /api/v1/documents/{document_id}/versions POST /api/v1/documents/{document_id}/reindex DELETE /api/v1/documents/{document_id}列表接口应支持分页、状态过滤、标题搜索和排序。分页参数需要设置上限避免一次返回整个知识库。六、文档发布和索引状态建议区分文件状态uploaded / deleted 处理状态queued / running / failed / completed 索引状态pending / indexing / ready / stale 发布状态draft / published / archived只有满足解析成功、向量可检索、权限元数据完整的版本才可以发布为published。发布操作应具备幂等性和审计记录。七、删除和重建不能只删一张表删除文档时要同步处理PostgreSQL 文档状态 对象存储原始文件 解析结果和临时文件 Milvus / pgvector Chunk Redis 缓存 异步任务和事件通常先做软删除和禁止新检索再由后台执行向量和文件清理。删除失败要进入补偿任务不能默默留下可访问的旧索引。八、幂等键和并发控制客户端重试上传确认、用户重复点击重试和消息重复消费都可能造成重复任务。推荐请求支持Idempotency-Key文档版本使用唯一约束任务状态更新带版本号同一文档同一版本只允许一个活动索引任务Worker 根据事件 ID 和业务键幂等处理。同一文档的解析、删除、发布和重建要使用版本号或分布式锁控制顺序。队列至少一次投递意味着 Worker 可能重复执行处理器必须以document_id version stage判断是否已完成并把业务提交与 ACK 顺序固定下来。九、问答接口如何与知识库资源关联POST /api/v1/chat/completions{knowledge_base_ids:[kb-001],conversation_id:conv-001,message:差旅住宿标准是什么,stream:true}服务端要检查用户是否能访问这些知识库并在检索时注入租户、部门和发布版本过滤。不能因为请求体带了kb-001就默认用户拥有权限。十、API 分层示意API Router ↓ 鉴权、校验、状态码 Application Service ↓ 事务、权限、业务规则 Repository / Gateway ├── PostgreSQL ├── Object Storage ├── Redis ├── Queue └── Milvus这样可以在测试中替换外部依赖也可以避免路由层直接耦合多个基础设施。结语一套完整的知识库 API应该围绕知识库、文档版本、处理任务、索引状态和问答运行设计。文件上传只是入口真正的工程质量体现在幂等、权限、状态、一致性、删除和恢复。下一篇将进入多租户如何隔离用户、团队、文档和向量数据。参考资料FastAPI 官方文档Amazon S3 官方文档Presigned URLsHTTP Semantics202 Accepted本文为“码海寻道”原创技术文章。文件、任务和索引删除涉及数据安全正式上线前应进行失败补偿和恢复演练。

相关新闻

Spring AI结构化输出实战:从JSON Schema到Bean绑定的全攻略

Spring AI结构化输出实战:从JSON Schema到Bean绑定的全攻略

如果你做过几个真实的Spring AI项目,大概率会遇到同一个尴尬场景:模型回答写得很漂亮,但你要把回答里的字段存进数据库、推进审批流、做统计,却发现只能靠正则去抠。我最初做客服工单自动分类时就被“返回1002还是1002.0”这种问题…

2026/11/18 3:15:39 阅读更多 →
FastAPI工程化落地:从类型驱动到生产部署全链路实践

FastAPI工程化落地:从类型驱动到生产部署全链路实践

1. 这不是又一个“Hello World”式FastAPI教程FastAPI,这三个字母在2023年之后的Python后端圈子里,已经不再是“新锐框架”的代名词,而是成了“默认选项”的同义词。我带过三届校招新人,也给五家不同行业的客户做过技术选型咨询&a…

2026/11/18 3:15:39 阅读更多 →
OpenRig:Codex本地代理与YAML驱动的AI工具链调度方案

OpenRig:Codex本地代理与YAML驱动的AI工具链调度方案

1. OpenRig 是什么:一个被误读但极具潜力的本地化 AI 工具链调度平台 OpenRig 这个名字在当前技术社区里,正经历一场典型的“语义漂移”——它既不是某个广为人知的开源项目官方名称,也不是某家大厂发布的标准化产品,而是一类基于…

2026/11/16 0:41:19 阅读更多 →

最新新闻

Electron桌面应用开发实战:从环境搭建到打包发布全流程

Electron桌面应用开发实战:从环境搭建到打包发布全流程

做前端这些年,我大部分时间都在跟浏览器标签页打交道,直到第一次把桌面应用跑起来,才发现原来自己一直被限制在地址栏和刷新按钮围起来的框框里。Electron这个词,最开始是在某段时间频繁出现在同事的讨论里,一个用HTML…

2026/11/17 8:22:52 阅读更多 →
滑盖智能锁T109深度解析:结构原理、安装调试与故障排查

滑盖智能锁T109深度解析:结构原理、安装调试与故障排查

简介:亚太天能T109滑盖智能锁产品说明书是一份PDF格式的官方技术文档,主要面向智能锁安装人员、终端用户及售后维护者,帮助快速掌握产品安装、配置与常见故障处理。全包仅1个PDF文件,大小4.37MB,内容结构清晰&#xff…

2026/11/17 12:46:04 阅读更多 →
PMSM弱磁控制原理与Simulink建模:高速AGV驱动系统设计指南

PMSM弱磁控制原理与Simulink建模:高速AGV驱动系统设计指南

上个月我在调试一台高速AGV的驱动系统,整车要求空载跑到8m/s,电机转速已经拉到额定点,驱动器的输出电压也顶到了母线电压极限附近。再往上踩速度指令,转速纹丝不动,三相电流反而开始震荡。那会儿我的第一反应就是&…

2026/11/17 12:46:04 阅读更多 →
C++核心知识点:从内存管理到STL的实战指南

C++核心知识点:从内存管理到STL的实战指南

C 这门语言我前前后后折腾了十几年,用它写过嵌入式驱动、做过游戏服务端,也搭过基础组件库。每次看到新人一头扎进"C 核心知识点"这个搜索词,我其实挺感慨的——这门语言的难点从来不是语法多,而是知识点之间的耦合太深…

2026/11/17 11:26:33 阅读更多 →
T109滑盖智能锁怎么装?安装调试与故障排查全攻略

T109滑盖智能锁怎么装?安装调试与故障排查全攻略

简介:亚太天能T109滑盖智能锁产品说明书以PDF格式发布,适合智能锁用户、安装人员与售后维修人员阅读。内容围绕T109系列指纹密码刷卡锁展开,先介绍前面板、后面板、锁体、机械钥匙、电池盒盖等部件名称与功能,再给出完整安装步骤&…

2026/11/17 12:46:05 阅读更多 →
LLM知识降熵:从信息垄断到理解权下放

LLM知识降熵:从信息垄断到理解权下放

你有没有过这种经历:翻开源码注释、论文摘要或者一份专业报告,每个字都认识,连在一起却像天书。想找人聊聊,身边要么没人懂,要么懂的懒得跟你解释。后来我试着把同一段内容丢给一个大语言模型,几秒钟之后&a…

2026/11/17 12:46:05 阅读更多 →

日新闻

周新闻

月新闻