用 FastAPI 搭建一个 RAG 后端需要哪些接口码海寻道 · 大模型、智能体与 RAG 工程组件系列第 41 篇一个 RAG 后端不只是一个/chat接口。要支持文件上传、异步解析、知识库管理、问答、引用、任务状态和权限控制应该先设计清楚资源和接口边界再接入模型与向量数据库。一、先按资源拆接口认证与用户 ├── /api/v1/auth 知识库 ├── /api/v1/knowledge-bases 文档 ├── /api/v1/documents 任务 ├── /api/v1/jobs 问答 ├── /api/v1/chat └── /api/v1/conversations资源型 API 负责管理事实和状态Agent、RAG 和大模型属于服务内部的执行链路不应把所有业务都塞进一个路由函数。二、推荐的核心接口接口设计先固定资源关系再决定具体路径。生产环境建议使用/api/v1这类版本前缀并为每次请求生成request_id或沿用上游trace_id。接口版本、错误码和响应字段一旦被前端使用就应通过兼容期和变更记录管理不能只靠修改路由代码。知识库POST /api/v1/knowledge-bases GET /api/v1/knowledge-bases GET /api/v1/knowledge-bases/{kb_id} PATCH /api/v1/knowledge-bases/{kb_id} DELETE /api/v1/knowledge-bases/{kb_id}文档POST /api/v1/knowledge-bases/{kb_id}/documents GET /api/v1/knowledge-bases/{kb_id}/documents GET /api/v1/documents/{document_id} DELETE /api/v1/documents/{document_id} POST /api/v1/documents/{document_id}/reindex任务GET /api/v1/jobs/{job_id} POST /api/v1/jobs/{job_id}/cancel POST /api/v1/jobs/{job_id}/retry对话POST /api/v1/chat/completions GET /api/v1/conversations/{conversation_id} DELETE /api/v1/conversations/{conversation_id}三、FastAPI 路由层应该做什么路由层负责解析请求和响应模型鉴权和租户上下文参数校验调用应用服务返回统一错误和状态码。不建议在路由函数中直接写 Embedding、Milvus 和复杂事务逻辑router.post(/chat/completions)asyncdefchat(request:ChatRequest,user:CurrentUserDepends(get_user)):scopeawaitpermission_service.scope_for(user)returnawaitrag_service.answer(request,scope)业务逻辑放在rag_service路由更容易测试和替换。四、请求和响应模型frompydanticimportBaseModel,FieldclassChatRequest(BaseModel):knowledge_base_id:strmessage:strField(min_length1,max_length8000)conversation_id:str|NoneNonetop_k:intField(default5,ge1,le20)stream:boolFalseclassCitation(BaseModel):document_id:strtitle:strpage:int|NoneNonesnippet:strclassChatResponse(BaseModel):answer:strcitations:list[Citation]trace_id:str请求模型还应限制字符串长度、分页上限、top_k、模型名称和过滤条件。不要把向量过滤表达式、tenant_id或权限字段直接交给客户端这些字段由认证上下文和服务端策略生成。对于创建文档、提交任务和发送消息的接口支持Idempotency-Key避免网络重试造成重复任务。客户端传来的top_k仍需受到服务端上限约束不能让用户任意扩大召回和模型上下文成本。五、文件上传不要同步解析接口只完成校验文件和用户权限保存原始文件到对象存储写入 PostgreSQL 文档记录创建任务并发布消息返回202 Accepted和job_id。router.post(/documents,status_code202)asyncdefupload_document(file:UploadFile,kb_id:str,user:CurrentUserDepends(get_user),):documentawaitdocument_service.create_upload(kb_id,file,user)return{document_id:document.id,job_id:document.job_id}解析、OCR、切分和索引由异步 Worker 完成前端通过任务接口查看进度。上传接口的成功只表示“文件已接收并创建任务”不表示文档已经可检索。响应中应返回document_id、upload_id、job_id、当前状态和查询地址任务状态由数据库维护Worker 通过版本号或乐观锁更新避免旧任务把新版本覆盖回去。六、统一错误格式{error:{code:DOCUMENT_NOT_READY,message:文档仍在解析中,trace_id:trace-001,details:null}}错误码供前端和监控使用展示文案可以由前端根据语言环境转换。不要把数据库堆栈、密钥和内部路径直接返回给用户。错误还应区分客户端可修正、权限拒绝、依赖暂时不可用和服务端未知异常。对 429、503 等暂时性错误返回retry_after对流式接口已经发送部分内容后的失败则通过事件发送最终error或cancelled状态并把运行结果持久化。七、RAG 问答接口内部流程请求进入 ↓ 鉴权与租户范围 ↓ 加载会话上下文 ↓ 查询改写 ↓ Embedding ↓ Milvus / pgvector 检索 ↓ Reranker 与去重 ↓ Prompt 组装 ↓ 大模型生成 ↓ 引用回查与审计每一步应有 trace_id 和耗时记录便于区分是检索慢、模型慢还是数据库回查慢。八、同步响应还是流式响应短回答可以返回 JSON长回答和聊天体验可以提供 SSE。建议保持同一个业务接口的请求语义使用streamtrue选择响应方式或提供独立的/chat/stream接口。流式接口仍要保存最终消息和引用不能因为客户端断开就丢失服务端事实。接口层还要明确取消语义客户端断开、主动点击停止和服务端超时不是同一种状态。取消请求应沿run_id传播到模型、检索、工具和异步任务无法立即中断的下游调用要标记为cancelling并由后台完成收尾。九、接口安全清单所有资源接口都校验用户和租户范围文件上传检查大小、类型、哈希和恶意内容问答接口限制消息长度、Top K 和模型预算数据库和向量过滤由服务端生成写操作具备幂等键长任务返回 job_id不阻塞请求错误响应不泄露内部信息记录 trace_id、审计和调用成本。结语FastAPI RAG 后端应该围绕知识库、文档、任务和对话设计资源接口把路由、业务服务、异步 Worker 和模型链路分层。接口先稳定内部组件才有替换和扩展空间。下一篇将转向前端比较 Vue、React 和 Next.js 如何设计 AI 应用交互。参考资料FastAPI 官方文档FastAPI 官方文档Request FilesFastAPI 官方文档Response Model本文为“码海寻道”原创技术文章。FastAPI、Pydantic 和相关 SDK 会随版本变化正式项目请以目标版本文档为准。