00 · 系列总览与学习路线：我们最终要做出什么

本系列是「司南 AI 中台」的保姆级教程，以真实开源项目 lianghui32/sinan-ai-platform 为唯一蓝本。每一步都讲三件事：要做什么、怎么做、为什么这么做。代码片段全部来自仓库真实源码，命令全部实测可复现。

一、最终成品：一个企业级 AI 中台长什么样

"司南"（指南针的前身）取"指向企业知识的那根针"之意。它是一个跨境电商企业级 AI 中台，部署后打开浏览器 http://127.0.0.1:8005，你能看到：

1. 岗位助手对话——运营、产品、数据分析各有一个"人设"助手；提问后逐字流式输出，如果助手绑定了知识库，回复下方会列出"《文件名》第 N 段（相关度）"的引用来源。
2. 知识库——管理员上传 txt/md/docx/csv 文档，系统自动分块、建索引；支持 TF-IDF / BM25 / 混合三种检索模式切换。
3. 工作流——用 JSON 定义一个 DAG（有向无环图），把"读 CSV → 条件判断 → 代码计算 → 调用模型生成报告"串成自动流水线；每个节点的输入输出、耗时在界面上逐节点可见。
4. 管理后台——用户与权限、助手配置、模型设置（填 OpenAI 兼容端点的 Key 即可接真实大模型）、用量统计、审计日志。

底层还有一条统一 LLM 网关：重试、降级、限流、token 计量、调用审计全部收敛到一个入口——这是企业级和玩具项目的分水岭。

二、这套教程你能学到什么

不是"抄代码"，而是跟着一次真实的工程决策走一遍：

• 需求分析：把"公司要个 AI 平台"翻译成可验证的功能清单与非功能需求（01 篇）
• 架构设计：三层解耦（模型 Provider / 岗位助手 / 知识库）、技术选型的理由与放弃的方案（02 篇）
• 后端开发：FastAPI 应用工厂、SQLite 无 ORM 的数据库层、pbkdf2 账号体系、LLM 网关、纯 numpy 的混合检索 RAG、带 AST 沙箱的 DAG 工作流引擎（03–09 篇）
• 前端开发：不用 React、不用打包工具的原生 JS 单页应用，5 套主题，SSE 流式渲染（10 篇）
• 测试：107 项 pytest 是怎么组织的，"评估脚本进 CI 当回归护栏"是什么意思（11 篇）
• 部署：Dockerfile 逐行讲解、docker-compose 加固、GitHub Actions CI、上线安全清单（12 篇）

三、你需要什么基础

• 会装软件、会开命令行（Windows PowerShell 或 macOS/Linux 终端均可）
• Python 语法看得懂（函数、字典、类），不用精通
• 没写过 Web 后端？没关系，本系列从"第一个接口"讲起
• 不需要：机器学习背景、向量数据库经验、Docker 经验——都会讲

四、环境准备清单（现在就装好）

参考实现环境：Windows 10（10.0.19045）+ PowerShell 5.1 + Python 3.13，python -m pytest tests -q 实测 107 passed in 54.35s。macOS/Linux 用户命令差异处会单独标注。

小白的第一个坑：Windows 上如果 python 命令弹出微软商店，说明没加入 PATH。安装时勾选 "Add Python to PATH"，或直接用 py 命令代替。

五、系列目录与学习路线

学习节奏建议：03–05 是地基（必按顺序）；06–09 相对独立，但依赖 04/05；10–12 收尾。每天 1–2 篇，一周多可以完整走完。

六、怎么读这个系列

每篇结构固定：本篇目标 → 做什么/怎么做/为什么 → 动手清单 → 常见坑。三个建议：

1. 一定要动手敲，不要复制粘贴完就跑。敲的过程就是理解取舍的过程。
2. 遇到报错先读完整输出。教程里所有报错处理习惯（读文件行号、看断言）本身就是教学内容。
3. 对照仓库。每篇都标注了对应源码文件（如 app/knowledge.py），建议把仓库克隆到本地对照阅读：git clone https://github.com/lianghui32/sinan-ai-platform.git。

下一篇我们从最容易被跳过、却决定成败的一步开始：需求分析。