AI 助手后端实现 · 从零构建 RAG 服务
一条按实现顺序组织的后端阅读路线:从 FastAPI 入口,到 Markdown 切片、pgvector 检索,再到 LangGraph 流式问答。
读者与范围
默认你已了解 TypeScript / HTTP / JSON 和关系型数据库的基本概念,熟悉至少一种后端框架的请求模型。这里不解释 Python 语法、FastAPI 入门、Docker 安装或 SSE 是什么;重点放在这个工程为什么这样分层,以及关键代码怎样串起来。
如果你正在从前端转全栈,不需要先系统学完 Python。把类型注解当成 TypeScript 的 type,把 dataclass / Pydantic model 当成 DTO,把 FastAPI 的 Depends 当成依赖注入,先跟调用链读,遇到不熟悉的语法再看签名。
这个系列不追求覆盖所有 RAG 话题。它只回答一个问题:一个可运行、可测试、边界清楚的个人站 RAG 后端,最小版本应该怎样从零搭起来。
系列地图
| 编号 | 文章 | 核心问题 |
|---|---|---|
| 01 | 项目地图:从浏览器到 FastAPI | 代码放在哪,一次请求经过哪些层 |
| 02 | Python 工程:uv、src layout 与质量门 | 怎样让安装、导入和测试可复现 |
| 03 | 应用骨架:配置、启动与接口契约 | 配置、校验、错误和健康检查怎样收敛 |
| 04 | 内容加载:把 Markdown 变成 Document | 哪些内容能进入索引,slug 和草稿怎样处理 |
| 05 | 切片:结构优先,长度兜底 | 怎样切出可检索、可引用的片段 |
| 06 | 向量与入库:接口、维度与索引元数据 | 怎样把切片可靠地写进 pgvector |
| 07 | 检索:一条 SQL 与可引用结果 | 相似度怎样算,来源信息从哪里来 |
| 08 | 生成:LangGraph 与 SSE | 检索、生成、拒答怎样编排成流 |
| 09 | 测试:三档依赖,三种证据 | 哪些用 fake,哪些必须连真实服务 |
| 10 | 全栈联调:Nuxt 代理、SSE 与访问控制 | 浏览器怎样接入,为什么还不能公开 |
建议顺序是 01 → 10。只想跑通链路,可以读 01 → 03 → 06 → 07 → 08;只关心 RAG 核心,可以读 04 → 08。
前端转全栈怎么读
先走 01 → 03 → 08 → 10,把“浏览器请求 → Nuxt 代理 → FastAPI → 数据库/模型 → SSE 回传”这条全栈链路串起来;再回头读 04–07,看 RAG 内部怎样处理内容。下面这些概念可以先按前端经验类比,读到具体代码时再校正:
| 前端经验 | 这里的对应 | 注意 |
|---|---|---|
npm / package.json |
uv / pyproject.toml |
依赖、脚本、工具配置集中管理 |
TypeScript interface |
dataclass / Pydantic model |
运行时校验由 Pydantic 负责 |
| Express middleware | FastAPI Depends / exception handler |
依赖注入和错误映射在框架层 |
fetch 读 JSON |
fetch 读 SSE 文本流 |
连接建立后错误只能用事件表达 |
| Vitest mock | dependency_overrides / fake |
替换外部边界,不绕过路由和校验 |
| ORM model | 当前是 SQL + dataclass DTO | 没有 ORM,也没有 migration 工具 |
当前实现边界
已经实现:内容入库、pgvector 检索、LangGraph 流式问答、前端 /chat 页面与同源代理、三档测试。尚未实现:登录鉴权、配额、每 IP 限流、会话持久化、系统化回答评测、生产环境部署。第 10 篇会把这张边界表展开。
代码地图
backend/
src/backend/
app.py FastAPI 应用、路由、SSE 编码
config.py Settings 与启动校验
db.py 连接、建表、重置
ingest.py 全量入库命令
repository.py 检索 SQL 与 ChunkHit
agent/
content.py Markdown → Document
chunking.py Document → Chunk
embeddings.py Embedding 提供方
chat.py 对话模型工厂
graph.py retrieve → generate/refuse
tests/
chat_fakes.py 测试替身
test_*.py 接口、配置、集成、live
content/ 在仓库根,前端构建和后端入库都直接读它。frontend/ 和 backend/ 是两个独立项目,不共享运行时。
本地运行
cd backend
docker compose -f ../infra/docker-compose.dev.yml up -d
uv sync
cp .env.example .env
uv run python -m backend.ingest --recreate
uv run uvicorn backend.app:app --reload --port 8000
默认使用确定性假向量,只验证管线。接真实模型时设置 EMBEDDING_PROVIDER=openai 及对应变量,然后重新入库;/api/chat 还需要 CHAT_MODEL。
阅读约定
每篇按“结论 → 问题与设计 → 关键代码 → 验证 → 边界”组织,不展开基础语法。代码以当前仓库为准;未实现的能力会明确写成边界,不把“能跑”写成“可公开上线”。
当前 01–10 都是初稿,draft: true。系列就是所在文件夹 02-AI助手后端实现,00-目录.md 是系列第一篇,也是普通长文。文章 slug 规则是 <英文系列>-<两位序号>-<英文主题词>,本系列以 ai-backend- 开头,例如 ai-backend-01-project-map、ai-backend-05-chunking。