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

设计 RAG 服务接口

设计 RAG 服务接口

生产级 RAG 不只有一个问答接口,还需要接收文档、触发索引更新、查询异步任务和收集用户反馈。本节把这些能力拆成稳定的 HTTP 契约,使前端、后台任务和 RAG 核心可以独立演进。

学习目标

  • 划分问答、文档、索引、任务与反馈接口职责
  • 为同步请求和异步任务设计稳定的响应结构
  • 在接口中预留版本、引用、幂等和错误处理边界

按资源职责拆分接口

问答请求通常需要立即返回结果,适合同步接口;文档解析和大规模索引更新耗时不可控,应创建异步任务,再通过任务接口查询状态。反馈则应关联一次具体问答,方便后续评估模型、提示词和检索效果。

能力 推荐接口 典型返回
问答 POST /v1/qa 回答、引用、查询 ID
文档导入 POST /v1/documents 文档 ID、任务 ID
索引更新 POST /v1/index-jobs 任务 ID
任务查询 GET /v1/tasks/{task_id} 状态、进度、错误
用户反馈 POST /v1/feedback 接收状态

RAG 服务接口与内部组件的数据流关系

用一个最小服务固定契约

下面使用 FastAPI 实现五类接口的最小骨架。示例暂不接真实向量库和模型,重点是固定请求、响应与任务状态边界;后续替换内部实现时,客户端契约可以保持不变。

python
from typing import Literal
from uuid import uuid4

from fastapi import FastAPI, HTTPException, Response
from pydantic import BaseModel, Field

app = FastAPI(title="RAG Service", version="1.0.0")
TASKS: dict[str, dict] = {}


class AskRequest(BaseModel):
    question: str = Field(min_length=1)
    top_k: int = Field(default=5, ge=1, le=20)


class DocumentRequest(BaseModel):
    source_uri: str


class IndexRequest(BaseModel):
    document_ids: list[str]


class FeedbackRequest(BaseModel):
    query_id: str
    rating: Literal[-1, 1]
    comment: str | None = None


@app.post("/v1/qa")
def ask(req: AskRequest):
    query_id = str(uuid4())
    return {
        "query_id": query_id,
        "answer": "示例回答",
        "citations": [{"document_id": "doc-001", "chunk_id": "chunk-03"}],
    }


@app.post("/v1/documents", status_code=202)
def import_document(req: DocumentRequest):
    document_id = str(uuid4())
    task_id = str(uuid4())
    TASKS[task_id] = {"status": "queued", "progress": 0}
    return {"document_id": document_id, "task_id": task_id}


@app.post("/v1/index-jobs", status_code=202)
def create_index_job(req: IndexRequest):
    task_id = str(uuid4())
    TASKS[task_id] = {"status": "queued", "progress": 0}
    return {"task_id": task_id}


@app.get("/v1/tasks/{task_id}")
def get_task(task_id: str):
    task = TASKS.get(task_id)
    if task is None:
        raise HTTPException(status_code=404, detail="task not found")
    return {"task_id": task_id, **task}


@app.post("/v1/feedback", status_code=204)
def submit_feedback(req: FeedbackRequest):
    # 生产环境应把反馈写入持久化存储,并关联 query_id。
    return Response(status_code=204)

这段代码依赖 fastapi、pydantic 和 uvicorn。保存为 app.py 后,可启动本地服务进行契约验证。

bash
uvicorn app:app --host 127.0.0.1 --port 8000

预期输出

text
INFO:     Uvicorn running on http://127.0.0.1:8000

日志中的进程号、启动时间等动态内容可能因环境不同而变化。

验证问答与异步任务

先验证同步问答接口。生产实现可以替换内部模型和检索器,但建议始终返回稳定的 query_id 和结构化 citations,不要让客户端解析自然语言中的引用编号。

bash
curl -s http://127.0.0.1:8000/v1/qa -H "Content-Type: application/json" -d '{"question":"什么是 RAG?","top_k":5}'

预期输出

json
{"query_id":"<ID>","answer":"示例回答","citations":[{"document_id":"doc-001","chunk_id":"chunk-03"}]}

其中 <ID> 是每次请求动态生成的查询标识,实际值会不同。

文档导入和索引更新使用 202 Accepted,表示服务器已经接受任务,但工作尚未完成。客户端拿到 task_id 后应查询任务接口,而不是保持一个长连接等待所有解析、切分和索引操作结束。

固定生产接口的关键边界

接口版本最好直接进入路径,例如 /v1,这样需要破坏性修改时可以并行提供新版。创建文档或索引任务时还应支持幂等键,避免客户端超时重试后重复导入同一份数据。

任务状态建议限制为少量稳定值,例如 queued、running、succeeded 和 failed。失败结果应提供机器可识别的错误码和安全的错误说明,但不要把模型密钥、数据库连接信息或完整内部堆栈直接返回给客户端。

反馈接口同样不要只保存一段评论。至少关联 query_id、正负评价和可选说明,服务端再通过查询 ID 找回当时的提示词版本、索引版本、召回结果和模型配置,才能把线上反馈真正转化为评测数据。

一个稳定的 RAG API 应让同步问答保持短路径,把文档处理和索引构建放入异步任务,并用查询 ID、任务 ID、结构化引用和反馈关系串起整个生命周期。内部检索与生成实现可以持续变化,而外部调用方不必跟着频繁改造。

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

目录与阅读设置

阅读设置

17

记录一个想法

设计 RAG 服务接口

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

登录哪都通