编程导航教程

一、项目介绍

这是一套以 AI 工程化 + 文档渲染 + 异步任务编排 为核心的项目教程，基于 FastAPI + LangChain + LangGraph + python-pptx + React 开发，用户只需要输入一句主题、粘贴一段长文本，或者上传 PDF、Word、Markdown、TXT 文档，就能先得到一份可修改的大纲，再并发生成完整页面，最终导出原生可编辑的 PPTX 文件。

4 大核心能力

1）多种输入生成大纲

项目支持从主题、长文本和文档三种入口创建 PPT。用户可以控制页数、排版模式、文字量、语气和目标受众，不需要一开始就把提示词写得很复杂。

模型不会直接越过用户生成最终页面，而是先产出结构化大纲。标题、页面目标和要点都能修改，也可以增删页面、调整顺序，再决定是否开始生成。

2）异步并发生成

一份 10 页 PPT 如果串行调用模型，很容易让请求等待一分钟以上。项目把每一页拆成独立任务，通过 ARQ Worker 并发执行，用 Redis 保存任务状态并传递事件，前端通过 SSE 实时接收进度。

生成过程中，已经完成的页面可以立即预览，失败页面可以单独重试，用户也可以软取消剩余任务，不需要整份重来。

3）在线编辑

生成后的内容会回到结构化模型里编辑，编辑器左侧是页面缩略图，中间是 16:9 画布，右侧提供 AI 修改、主题、版式和图片面板。

文字可以直接编辑；灵活排版页面支持拖动分隔线、调整内容块尺寸、跨容器移动和更换排布；主题切换后，Web 预览和 PPTX 导出会读取同一份主题数据。

4）原生 PPTX 导出

AI 输出的文字长度不可预测，直接导出很容易出现溢出、缺页或整页被渲染成图片的问题。项目在导出前检查结构、文字占用、数字来源和页面边界，把问题分成 error 和 warning：error 阻断导出，warning 提醒用户核对但允许继续。

通过检查后，后端用 python-pptx 逐块构造文本框、表格、图表和图片，再回读生成的文件进行验证。这样得到的 PPTX 不是一张铺满全页的截图，而是能继续修改的原生对象。

为什么做这个项目？

1）业务场景足够真实

从汇报材料、课程讲义到方案介绍，PPT 都是高频需求。真正难的不是让模型写出几段文案，是把不可控的生成结果稳定地变成可编辑、可校验、可导出的文档。

2）技术链路有区分度

项目同时覆盖模型结构化输出、LangGraph 工作流、异步队列、SSE、前端编辑器、文档渲染和质量门禁。它不是给现成接口套一个页面，每一层都有明确的工程问题需要解决。

3）适合写进简历并接受追问

你可以讲清楚为什么不让模型直接输出 HTML 或 PPTX，为什么需要统一内容模型，为什么使用异步队列，Web 和 PPTX 如何同源渲染，以及如何证明导出的文件真的可编辑。这些都比 “调用大模型生成内容” 更经得住面试追问。

二、项目优势

项目收获

本项目紧跟 AI 时代、选题新颖、技术丰富。区别于增删改查的烂大街项目，这套教程讲解的是一个已经能够运行的完整项目，重点不是带你照着代码从零敲一遍，而是把每个关键决策背后的动机、替代方案和踩坑讲清楚，帮你成为 AI 时代企业的香饽饽，给你的简历和求职大幅增加竞争力！

AI 全栈项目，技术丰富，学完后你会在 AI 工程化、异步编排、文档渲染、前端编辑器、工程质量 5 个方向获得完整实践：

从这个项目中你可以学到：

• 如何基于 LangChain LCEL + with_structured_output 实现 AI 结构化输出，保证模型输出始终可用？

• 如何基于 LangGraph 构建自纠环工作流，系统性提升单页生成质量？

• 如何设计 AI 工具调用机制，让模型通过 bind_tools 调用编辑工具修改页面？

• 如何使用 ARQ + asyncio.Semaphore 实现页级并发生成，控制模型调用频率？

• 如何通过 Redis pub/sub + SSE 实现实时进度推送和断线重连恢复？

• 如何设计内容、布局、主题三分离的数据模型，让 Web 和 PPTX 同源渲染？

• 如何用 python-pptx 构造原生可编辑的 PPTX，处理中文字体和 emoji？

• 如何用受约束的 contenteditable 实现结构化编辑器，保证光标稳定？

• 如何通过 revision 乐观锁 + 按页串行保存队列处理编辑冲突？

• 如何用 FontTools 做字形级文字溢出检测，配合 warning/error 分级门禁？

• 如何从 OpenAPI 生成前端 TypeScript 类型，消灭前后端接口漂移？

• 如何用布局树 + solver 实现灵活排版，并保证前后端求解器双端一致？

此外，还能学会很多 AI 工程化、系统架构设计、技术方案对比的方法，提升排查问题、自主解决 Bug 的能力。每一期还附带扩展方向，有能力的同学可以进一步拉开和别人的区分度，无限进步！

编程导航系列项目优势

编程导航原创项目系列以 实战 为主，带大家学习技术知识，并立即实践运用到项目中，做到学以致用。

此外，还提供如下服务：

• 详细的文字教程或直播笔记

• 完整的项目源码

• 1 对 1 答疑解惑

• 专属项目交流群

• ⭐️ 现成的简历写法（直接写满简历）

• ⭐️ 项目的扩展思路（拉开和其他人的差距）

• ⭐️ 项目相关面试题、题解和真实面经（提前准备，面试不懵逼）

• ⭐️ 前端 + Java 后端万用项目模板（快速创建项目）

比起看网上的教程学习，鱼皮项目系列的优势：从学知识 => 实践项目 => 复习笔记 => 项目答疑 => 简历写法 => 面试题解的一条龙服务

从需求分析、技术选型、项目设计、项目初始化、Demo 编写、前后端开发实现、项目优化、部署上线等，每个环节我都 从理论到实践 给大家讲的明明白白、每个细节都不放过！

对比维度	跟学鱼皮项目	自学网上免费项目	⭐️ 鱼皮项目优势
项目选题	✅ 选题新颖，刻意避开网上热门项目	传统项目场景（博客、商城、管理系统）	增加区分度，提高简历通过率
学习人数	✅ 少，不容易撞车	百万以上，烂大街	增加区分度，提高简历通过率
教学方式	✅ 全程直播，带你敲每一行代码、带你踩坑和解决 Bug，不漏过每一个细节	录制课程，视频虽然看起来简短、一帆风顺，但你遇到错误无从下手	降低学习门槛，减少学习时长
直播笔记	✅ 详细的官方笔记 + 精选学员优质笔记	有笔记，但未经筛选	学到更多知识细节
视频内容	✅ 项目教程 + 经验分享	项目教程	学到更多编程经验
项目源码	✅ 完整源码仓库 + 每章的提交记录 + 定期更新	只有代码包、不更新	节省时间，避免踩坑
项目答疑	✅ 各项目交流群 + 答疑解惑 + 常见问题整理	无免费的答疑服务，遇到问题自行解决	节省时间
简历写法	✅ 现成的简历写法	无	节省时间、提高简历通过率
项目扩展	✅ 给出扩展思路 + 学员作品共享	无	开拓思路、拉开和其他人的差距
项目面试	✅ 项目相关面试题、题解和真实面经	无	提前准备，面试不懵逼

编程导航已有 **近 30 套项目教程！**每个项目的学习重点不同，几乎全都是前端 + 后端的 全栈项目。

详细请见：https://codefather.cn/course（在该页面右侧有教程推荐和学习建议）

往期项目介绍视频：https://bilibili.com/video/BV1YvmbYbEgS

三、业务流程

核心业务流程

一次完整的使用过程是：注册登录 → 创建项目 → 输入主题或材料 → 生成并确认大纲 → 并发生成页面 → 在线编辑 → 质量检查 → 导出 PPTX。

这里有两个刻意保留的人工节点。

第一个是确认大纲。大纲决定整份 PPT 的叙事顺序，如果方向错了，后面并发生成得越快，浪费的模型调用越多。因此项目先让用户修改标题、目标和要点，再开始生成页面。

第二个是导出前检查，避免把明显有问题的文件直接交给用户。

一次生成请求的全链路

从系统内部看，一次生成会经过下面几步：

1. FastAPI 接收生成请求，先把项目和页面状态写入 PostgreSQL

2. API 将任务放入 Redis 队列并立即返回，不占住 HTTP 连接

3. ARQ Worker 领取任务，按并发上限执行多个单页 LangGraph 工作流

4. 单页经过生成、结构检查、业务检查和最多一轮修复

5. 图片管线并行尝试 AI 生图、图库检索和占位图降级

6. Worker 将进度事件写入 Redis，前端通过 SSE 更新页数和状态

7. 页面结果落库后，编辑器读取同一份 Deck 数据进行渲染和编辑

8. 导出时先跑质量规则，再用 python-pptx 渲染并回读验证

同步请求和异步链路的差异，可以从这张时序对比图直观看出来：

解决方案实战

整套项目涉及的实战内容可以分成 5 组。

AI 技术实战：

• LangChain LCEL 链式调用和结构化输出

• LangGraph 工作流和条件边

• AI 工具调用（bind_tools + 手写工具循环）

• 大模型结构化输出和 Pydantic 校验

• 提示词硬约束、错误分层和修复轮次

• LLM Protocol、多模型切换和超时处理

• AI 生图、图库检索和降级策略

• AI 多轮对话记忆

异步及数据实战：

• ARQ 异步任务队列

• Redis pub/sub、任务状态和缓存

• PostgreSQL 持久化和 Alembic 迁移

• SQLAlchemy 异步访问

• SSE 实时进度和断线恢复

渲染编辑：

• React 在线编辑器

• 容器查询单位和响应式缩放

• 布局树、solver 和拖拽编辑

• Recharts 图表渲染

• python-pptx 和 OOXML

质量安全实战：

• FontTools 字体度量

• 导出质量门禁和回读验证

• OpenAPI 单源类型生成

• JWT 鉴权和项目归属校验

• 固定语料回归测试

部署存储实战：

• Docker Compose 编排 PostgreSQL 和 Redis

• 本地存储和 COS 对象存储切换

• API、Worker、前端多进程部署

• Nginx 静态资源和反向代理

四、功能模块

用户项目模块

• 用户注册、登录和 JWT 身份认证

• 查看自己的 PPT 项目列表

• 创建项目、删除项目和更新项目配置

• 按用户隔离项目，越权访问统一返回不存在

输入解析模块

• 从一句主题生成

• 粘贴长文本生成

• 上传 PDF、DOCX、Markdown、TXT

• 控制页数、排版模式、文字密度、语气和受众

• 保存原始来源片段，供页面引用和数字来源检查

大纲模块

• 用 LangGraph 生成结构化大纲

• 修改页面标题、目标和要点

• 增删页面和拖拽排序

• 自动保存大纲 revision

• 确认大纲后创建待生成页面

页面生成模块

• 页级任务并发生成

• 结构检查、业务校验和修复轮次

• 失败页面单独重试

• 生成过程软取消

• 通过 SSE 推送进度、成功、失败和完成事件

在线编辑模块

• 文字、列表、卡片、KPI、表格和图表编辑

• 页面新增、复制、删除和排序

• 自动保存、乐观更新和 409 冲突处理

• ⭐️ AI 指令编辑（工具调用 + 多轮对话）

• 锁定人工修改块，防止 AI 覆盖

• 撤销、重做、缩放和全屏演示

主题布局模块

• 米白商务、深蓝科技、曜石鎏金、清新学术 4 套主题

• 固定布局和灵活排版两种模式

• 一键更换页面排布

• 拖动分隔线调整行列比例

• 内容、布局、主题共享同一份 JSON 定义

图片模块

• 根据页面语义生成 ImageRequest

• 调用 AI 图片模型生成配图

• 失败时降级到 Unsplash 检索

• 图源都不可用时由渲染器绘制主题占位图

• 支持替换、重新生成和上传图片

导出质量模块

• 文本溢出、越界、来源数字和结构完整性检查

• warning 和 error 分级

• 原生文本框、表格、图表和图片导出

• 中文字体、emoji 和文本自适应处理

• 导出后检查页数、画布、边界和原生对象类型

• 固定语料 × 3 套主题回归门禁

五、技术选型

后端

核心框架：

• FastAPI：异步接口支持完善，OpenAPI 可以直接生成前端类型

• Pydantic：既用于接口契约，也用于约束模型结构化输出

• SQLAlchemy 2：使用异步会话访问 PostgreSQL

• Alembic：管理数据库版本迁移

AI 和工作流：

• ⭐️ LangGraph：把生成、检查、修复和条件路由显式组织成图

• ⭐️ LangChain（langchain-core + langchain-openai）：LCEL 链式调用 + with_structured_output 保证结构化输出，bind_tools 实现工具调用

• Protocol：隔离模型、图片和存储的具体厂商实现

• httpx：异步调用模型服务、图库和其他外部接口

异步任务：

• ⭐️ ARQ：基于 Redis 的轻量异步任务队列，和项目的 asyncio 技术栈一致

• ⭐️ Redis：同时承担任务队列、事件 pub/sub、状态快照和取消标记

• SSE：生成是服务端单向推送，协议比 WebSocket 更简单

文档处理和导出：

• ⭐️ python-pptx：直接构造原生 PowerPoint 对象

• pdfplumber：提取 PDF 文本

• python-docx：读取 DOCX 文档

• markdown-it-py：解析 Markdown

• ⭐️ FontTools：读取字体 cmap 和 advance width，估算真实排版宽度

数据和存储：

• PostgreSQL：保存用户、项目、大纲、页面和 revision

• 本地文件系统：开发环境保存上传文档和生成图片

• COS：生产环境可以通过 Storage Protocol 切换到对象存储

前端

核心技术：

• React 19：构建项目列表、大纲工作台和在线编辑器

• TypeScript：约束复杂的 Deck、Block、LayoutTree 和编辑状态

• React Router：管理登录、项目列表、创建和工作台路由

• TanStack Query：处理服务端数据缓存、乐观更新和失效刷新

• Zustand：保存登录状态等轻量全局状态

渲染和样式：

• Tailwind CSS 4：构建编辑器界面和主题面板

• ⭐️ Recharts：渲染柱状图、折线图和饼图

• ⭐️ CSS Container Query Units：让同一页在缩略图、画布和全屏下等比缩放

• Lucide React：提供统一的界面图标

⭐️ 工程化：

• Vite：开发服务器和生产构建

• openapi-typescript：从 FastAPI OpenAPI 生成接口类型

• oxlint：前端静态检查

• 前后端黄金样本：验证 solver 和 normalize 的双端一致性

工具

开发和运行：

• uv：Python 依赖和虚拟环境管理

• npm：前端依赖管理

• Docker Compose：启动 PostgreSQL 和 Redis

• Makefile：统一安装、迁移、运行、测试和回归命令

质量检查：

• pytest：后端单元测试和接口测试

• Ruff：Python 静态检查和格式约束

• 固定回归脚本：验证可编辑性和溢出比例

六、架构设计

项目不是让前端直接调用模型，而是把输入、工作流、任务、领域模型和渲染拆成清楚的层次。架构图如下：

七、准备工作

AI 基础知识

开始前最好先了解下面几个概念：

• 大模型上下文窗口、temperature 和超时

• Prompt 中的硬约束和软建议

• JSON 结构化输出和 schema 校验

• Agent、工作流和普通单次调用的区别

• Token 成本、并发限制和重试策略

不需要提前精通 LangGraph。教程会从项目里的大纲线性图开始，再进入单页自纠环和异步编排。

本地环境

项目需要：

• Python 3.12 或更高版本

• Node.js 20 或更高版本

• uv 0.6 或更高版本

• Docker，用于运行 PostgreSQL 和 Redis

本地端口统一使用 39xxx 段：PostgreSQL 为 39432、Redis 为 39379、API 为 39800、前端为 39173，尽量避开机器上已有服务的默认端口。

模型 Key

最小配置只需要准备 LLM_API_KEY。默认模型接口兼容 DeepSeek，也可以通过环境变量切换 Base URL 和模型名。

图片能力是可选的：

• 配置 IMAGE_API_KEY 后可以调用 AI 生图

• 配置 UNSPLASH_ACCESS_KEY 后可以搜索图库

• 两者都不配置，核心流程仍能运行，图片槽位会走主题占位图降级

密钥只应写进本地 backend/.env，不要提交到 Git 仓库。

新建代码仓库

建议把项目放进自己的 Git 仓库，并从第一天保留提交记录。后续每完成一期，可以单独提交内容模型、Web 渲染、PPTX 导出、异步队列等模块，面试前也更容易回看设计演进。

第一次运行的核心命令如下：

▼
bash
复制代码

cp backend/.env.example backend/.env

▼
text
复制代码

make up

▼
text
复制代码

make install

▼
text
复制代码

make migrate

▼
text
复制代码

make dev-api

▼
text
复制代码

make dev-worker

▼
text
复制代码

make dev-web

▼
text
复制代码

API、Worker 和前端需要分别运行。忘记启动 Worker 时，任务会成功入队，但页面生成进度会一直停在 0%。

AI 学习资源

1、AI 面试题

建议大家在学习 AI 项目的过程中，持续阅读 AI 大模型相关的面试题，巩固知识点。这块鱼皮已经帮大家拿捏了，我们的程序员面试刷题神器面试鸭搞了个 AI 大模型面试题库，建议没事就阅读一些题目来学习学习。

2、开源 AI 知识库

由于 AI 技术日新月异，建议大家平时多关注 AI 相关的资讯动态，比如 鱼皮开源的 AI 知识库，汇总了热门的 AI 大模型和工具，比如 Deepseek 使用指南、提示词技巧分享、知识干货、应用场景、AI 变现、行业资讯、教程资源等一系列内容，帮助你快速掌握 AI 技术，走在时代前沿。

3、免费 AI 交流

编程导航提供了 免费的 AI 学习交流社区，大家可以畅所欲言！

八、学习大纲

教程共 11 期，按照 “统一模型 → AI 工作流及编辑 → 高级排版 → 部署上线” 逐步深入。

第一阶段 - 数据模型和双端渲染

第 1 期：项目总览

• 项目介绍和核心能力

• 业务流程和功能模块

• 技术选型和架构设计

• 准备工作和学习路线

第 2 期：统一内容模型

• 为什么不让模型直接输出 HTML 或 PPTX

• 内容、布局、主题三分离

• 共享 JSON 和六类基础内容块

• 归一化坐标和扩展新块类型

第 3 期：Web 渲染

• 缩略图、编辑画布和全屏演示的统一渲染

• pt 到 cqw 的换算

• BlockView 渲染分发

• Recharts 图表的等比缩放

第 4 期：原生可编辑 PPTX 导出

• 截图、转换器和直接构造三种方案对比

• python-pptx 原生对象渲染

• 中文字体、emoji 和 autofit

• 导出后回读验证

第二阶段 - AI 工作流和在线编辑

第 5 期：结构化输出和降级设计

• 模型输出的格式、结构和业务三层错误

• LLM Protocol 和强类型输入输出

• 五层校验漏斗

• 图片三级降级链

第 6 期：LangGraph 工作流

• 大纲线性工作流

• 单页生成、检查和修复自纠环

• 修复轮次上限

• 来源文本的上下文裁剪

第 7 期：异步编排

• ARQ 队列和页面并发

• 页级、项目级状态流转

• 幂等、断点续跑和软取消

• Redis pub/sub + SSE 实时进度

第 8 期：在线编辑器

• 受约束的 contenteditable

• 自动保存队列和乐观锁

• 撤销、重做和冲突处理

• AI 块级编辑和 locked 保护

第三阶段 - 高级排版和部署

第 9 期：灵活排版

• 布局树和绝对坐标的取舍

• ratios、grow、gap 和 solver

• 双端 solver 一致性

• 候选排版、坏树兜底和拖拽移动

第 10 期：质量护栏

• FontTools 字形度量

• CJK 字级和拉丁整词折行

• warning / error 分级门禁

• OpenAPI 类型生成和固定语料回归

第 11 期：部署上线

• 从零跑通项目和常见问题

• Docker Compose 和生产部署规划

• 环境变量、JWT 和项目隔离

• 本地存储切换 COS、冒烟测试和扩展方向

完成这 11 期后，你不仅能操作一个 AI PPT 工具，还能完整解释它为什么这样设计、哪里容易失败，以及怎样把一个模型 Demo 做成可持续运行的工程项目。