大模型应用开发 / 系统课时
设计服务接口
设计服务接口
本篇将完成 RAG 知识库服务的接口设计,明确文档上传、索引更新、知识检索、问答和健康检查等核心能力的请求与响应边界,为后续 FastAPI 实现提供稳定契约。
学习目标
- 理解知识库服务中不同接口的职责划分。
- 掌握请求参数、响应结构和状态设计方法。
- 能够为 RAG 应用设计可扩展的 API 契约。
划分知识库服务接口
RAG 应用通常包含数据进入、数据处理、知识查询和系统运行状态四类操作。接口设计需要让调用方只关注业务能力,而不直接依赖文档解析、向量化、检索等内部实现。常见接口可以划分如下:
| 接口 | 作用 | 调用场景 |
|---|---|---|
| 文档上传 | 接收原始资料 | 管理员导入知识 |
| 索引更新 | 生成或刷新向量数据 | 文档变更后同步 |
| 知识检索 | 返回相关片段 | 应用查询上下文 |
| 问答接口 | 生成最终答案 | 用户交互 |
| 健康检查 | 判断服务状态 | 运维监控 |
定义接口数据结构
接口的数据结构需要稳定表达输入和输出。以问答接口为例,请求中包含用户问题和可选配置,响应中返回答案、引用内容以及处理信息。
python
from pydantic import BaseModel
from typing import List
class AskRequest(BaseModel):
# 用户输入的问题
question: str
top_k: int = 5
class SourceItem(BaseModel):
document_id: str
content: str
class AskResponse(BaseModel):
answer: str
sources: List[SourceItem]预期输出
text
AskRequest 可以校验用户问题和检索数量。
AskResponse 可以统一返回答案与知识来源。设计接口路径
接口路径应体现资源关系,避免把内部实现暴露给调用方。例如文档资源使用 /documents,查询能力使用 /search,问答能力使用 /ask。示例接口规划如下:
text
POST /documents/upload
POST /documents/reindex
POST /search
POST /ask
GET /health预期结果
text
调用方可以通过固定路径访问知识库能力。
服务内部可以自由调整解析、向量化和模型调用流程。处理接口扩展边界
随着知识库规模增长,接口需要预留扩展字段。例如检索接口可能增加过滤条件、租户信息或权限范围,但不应频繁破坏已有调用方。设计时需要注意:
- 请求字段增加时优先提供默认值。
- 响应字段增加时避免改变已有字段含义。
- 长耗时任务可以返回任务 ID,通过状态接口查询进度。
按自己的节奏,确认真正理解。