常见问题与最佳实践
这页是速查版 FAQ：每个问题都按「结论 + 立刻可做」给出。
产品与功能
Q1：GeekAI-PPT 和普通 PPT 模板有什么区别？
结论： 模板只给样式，GeekAI-PPT 是「结构 + 内容 + 画面」一体生成。
建议： 先写清主题，再让 AI 规划大纲，最后再生成页面。
Q2：是否必须上传文档才能生成 PPT？
结论： 不必须。只写主题也能生成。
建议： 有现成方案/讲义时再上传，能明显减少后续改字成本。
Q3：支持哪些文档格式？
结论： 常见是 PDF / DOCX / TXT / MD。
建议： 以页面上传控件实际支持为准。
Q4：生成的 PPT 是固定风格吗？
结论： 默认科技风，可定制。
建议： 开发者改 image_gen.py 的 style prompt，或做多模板切换。
质量与效果
Q5：如何让生成的大纲更符合我的预期？
结论： 主题越具体，大纲越准。
建议：
- 主题写成“对象 + 目标 + 范围”
- 在规划页直接删改条目
- 文档尽量分段、分标题
Q6：为什么有些页面文字很多，看起来有点「挤」？
结论： 文字过多通常是大纲阶段没瘦身。
建议： 先回大纲删子项，再重生成；坚持“一页一个观点”。
Q7：如何提升图片的美观与统一性？
结论： 统一性主要由风格 prompt 决定。
建议： 固定一套品牌风格词，关键页多生成几版后再统一选。
性能与稳定性
Q8：生成速度很慢或者经常失败，怎么办？
结论： 80% 是上游限流或一次生成太多页。
建议：
- 先按页/小批量
- 看后端日志是否超时
- 检查上游配额与限流
Q9：请求经常超时或浏览器提示 502/504？
结论： 多数是代理超时配置过低。
建议： 调大 proxy_read_timeout，并减少单次批量任务。
部署与配置
Q10：前端能打开，但提示「无法连接后端」？
结论： 一般是 API 地址配错或后端没启动。
建议：
- 看后端日志
- 核对
VITE_API_BASE_URL - 核对 Nginx 反代路径和端口
Q11：如何在内网或私有环境中部署？
结论： 支持内网私有化。
建议： Docker 部署 + 本地持久化 storage + 访问控制。
安全与隐私
Q12：上传的文档和生成的图片会被上传到云端吗？
结论： 默认数据落本地；外连仅发生在模型调用。
建议： 要更稳妥就内网部署 + 自建/专用模型网关。
Q13：如何避免在课堂或公共环境中泄露 API Key？
结论： 不要把真实 Key 下发给学生终端。
建议： 服务端统一配置 .env，使用低权限教学专用 Key。
开发与扩展
Q14：我想给演示文稿增加新的字段，改哪里？
结论： 后端四步 + 前端三步。
建议：
- 后端：
models.py->database.py->repository.py->main.py - 前端：
services/->stores/-> 页面组件 - 细节看 二次开发与架构说明
Q15：如何调试与替换上游模型服务？
结论： 先最小脚本验证，再回填项目。
建议：
- 先单独测请求/响应
- 再改
llm_planner.py、image_gen.py - 最后改
.env的BASE_URL、MODEL_*
最佳实践（短版）
- 先搭主线，再补细节：先用 AI 规划大纲，确认结构后再生成与微调
- 一页一观点：无论 AI 自动生成还是你后期修改，都尽量保证一页 PPT 只讲一个重点
- 少量多次迭代：对关键页面多尝试几个版本，再人工挑选，而不是一次性生成全部后全部推翻
- 配置分环境管理：开发、测试、生产分别使用不同的
.env与 API Key - 教学与团队协作时注意安全：使用单独的低权限密钥，并避免将密钥写入代码仓库