大模型应用开发 / 系统课时
设计 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 |
接收状态 |

用一个最小服务固定契约
下面使用 FastAPI 实现五类接口的最小骨架。示例暂不接真实向量库和模型,重点是固定请求、响应与任务状态边界;后续替换内部实现时,客户端契约可以保持不变。
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 后,可启动本地服务进行契约验证。
uvicorn app:app --host 127.0.0.1 --port 8000预期输出
INFO: Uvicorn running on http://127.0.0.1:8000日志中的进程号、启动时间等动态内容可能因环境不同而变化。
验证问答与异步任务
先验证同步问答接口。生产实现可以替换内部模型和检索器,但建议始终返回稳定的 query_id 和结构化 citations,不要让客户端解析自然语言中的引用编号。
curl -s http://127.0.0.1:8000/v1/qa -H "Content-Type: application/json" -d '{"question":"什么是 RAG?","top_k":5}'预期输出
{"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、结构化引用和反馈关系串起整个生命周期。内部检索与生成实现可以持续变化,而外部调用方不必跟着频繁改造。