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

设计服务接口

设计服务接口

本篇将完成 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,通过状态接口查询进度。
按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

设计服务接口

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

登录哪都通