大模型应用开发 / 系统课时
实现文档管理接口
实现文档管理接口
本节实现 RAG 知识库中的文档管理能力,包括上传文档、查询处理状态、获取文档列表和删除文档。通过统一接口封装文件生命周期,让前端或其他服务可以稳定调用知识库管理功能。
学习目标
- 理解文档管理接口在 RAG 系统中的职责划分。
- 掌握上传、查询、列表和删除接口的基本实现方式。
- 学会通过返回状态信息定位文档处理过程。
设计文档管理接口
文档管理接口负责连接用户操作和知识库处理流程。上传接口接收文件并创建任务,后台负责解析、切片和向量化;状态查询接口用于反馈当前处理阶段;列表和删除接口管理已有知识资源。
接口设计需要保持结果明确,避免调用方只能根据 HTTP 状态码判断成功或失败。通常返回文档 ID、处理状态、错误信息等字段,方便前端展示和后续排查。
实现文档接口
下面使用 FastAPI 展示一个简化实现。示例中的存储逻辑使用内存结构代替数据库,实际项目中可以替换为关系数据库或对象存储。
python
from fastapi import FastAPI, UploadFile, File, HTTPException
from datetime import datetime
app = FastAPI()
# 示例存储,生产环境应替换为数据库
documents = {}
@app.post("/documents")
async def upload_document(file: UploadFile = File(...)):
doc_id = str(len(documents) + 1)
documents[doc_id] = {
"name": file.filename,
"status": "processing",
"createdAt": datetime.utcnow().isoformat()
}
return {"id": doc_id, "status": "processing"}
@app.get("/documents/{doc_id}")
def get_document_status(doc_id: str):
if doc_id not in documents:
raise HTTPException(status_code=404, detail="document not found")
return documents[doc_id]
@app.get("/documents")
def list_documents():
return list(documents.values())
@app.delete("/documents/{doc_id}")
def delete_document(doc_id: str):
if doc_id not in documents:
raise HTTPException(status_code=404, detail="document not found")
del documents[doc_id]
return {"deleted": True}预期结果
text
启动服务后,可以通过 /documents 完成文档创建、查询、列表查看和删除操作。
上传成功返回文档 id,查询接口返回对应处理状态。对接 RAG 处理流程
实际 RAG 项目中,上传接口通常不会直接完成解析和向量写入,而是创建异步任务。文档状态可以设计为 pending、processing、completed、failed 等阶段。
当处理任务完成后,状态接口返回 completed,同时记录切片数量、向量数量和失败原因等信息。这样可以把耗时操作从用户请求中分离,提高系统稳定性。
常见问题与验证
文档接口最常见的问题包括文件类型校验缺失、重复上传处理不一致以及删除时未清理向量数据。删除操作需要同时处理原始文件、元数据和向量库中的关联记录。
可以通过接口调用验证完整流程:上传一个测试文件,轮询状态直到完成,再查询列表确认存在,最后执行删除并确认资源清理。
按自己的节奏,确认真正理解。