大模型应用开发 / 系统课时

实现文档管理接口

实现文档管理接口

本节实现 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,同时记录切片数量、向量数量和失败原因等信息。这样可以把耗时操作从用户请求中分离,提高系统稳定性。

常见问题与验证

文档接口最常见的问题包括文件类型校验缺失、重复上传处理不一致以及删除时未清理向量数据。删除操作需要同时处理原始文件、元数据和向量库中的关联记录。

可以通过接口调用验证完整流程:上传一个测试文件,轮询状态直到完成,再查询列表确认存在,最后执行删除并确认资源清理。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

实现文档管理接口

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通