跳到主要内容
Ed. notes

AI 助手后端实现 · 从零构建 RAG 服务

长文 · 2026-11-11 · 合集第 1 / 11 篇

  • 后端
  • FastAPI
  • RAG
第 1 / 11 篇 · 查看全部章节 → 当前: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。