Wiki Notes

Appearance

项目模板与脚手架专题 ​

版本：v1.1

最后更新：2026-07-08

适用对象：需要为文本助手、RAG、Agent、语音、多模态或企业 Copilot 项目提供统一启动骨架的研发、平台和交付同学

很多人学 AI 会反复遇到一个问题：

  • 单个 Demo 会写
  • 真到新项目落地时，又从零搭一遍

这说明缺的往往不是“会不会用模型”，而是：

  • 有没有稳定的项目模板
  • 有没有可复用的工程骨架
  • 有没有一套启动新项目的默认做法

根据 2026-07-08 可访问的 OpenAI Production best practices、Evaluation best practices、Agents、File search、Background mode 等资料，以及企业 MLOps / LLMOps 工程经验，一个好的 AI 脚手架至少应该做到一件事：

  • 把“应该默认存在的工程约束”前置到项目第一天，而不是拖到功能做完后补。

1. 为什么 AI 项目特别需要脚手架 ​

脚手架的价值不是“偷懒”，而是减少重复犯错。

很多 AI 项目真正反复重做的不是业务逻辑，而是这些基础设施：

  • 环境变量管理
  • 模型调用封装
  • Prompt 存放位置
  • trace 与日志
  • eval 入口
  • 本地运行方式
  • 部署说明

1.1 没有脚手架时，团队通常会重复遗漏什么 ​

最常见被拖到后面的内容包括：

  • Prompt 版本管理
  • schema 校验
  • 失败重试
  • 评测目录
  • 示例数据
  • 安全与脱敏
  • 人工接管说明

1.2 脚手架真正提供的不是代码，而是默认决策 ​

例如：

  • Prompt 放哪
  • 配置怎么分层
  • tool schema 怎么登记
  • eval 放哪一层
  • 发布脚本放哪

如果这些问题每个项目都重新争论一次，团队速度会越来越慢。

2. 一个好的脚手架应该帮你提前解决什么 ​

最小目标通常不是“把所有场景都抽象掉”，而是先把最容易反复踩坑的部分固化。

2.1 统一目录结构 ​

至少要让团队知道：

  • 业务代码放哪
  • Prompt 放哪
  • tool 放哪
  • eval 放哪
  • 文档放哪

2.2 统一配置入口 ​

例如：

  • .env.example
  • 环境配置
  • 模型配置
  • feature flags
  • tenant / deployment 差异配置

2.3 统一观测与错误处理 ​

例如：

  • trace
  • request ID
  • 错误分类
  • retry policy
  • timeout policy

2.4 统一评测入口 ​

至少应该有：

  • 本地 smoke eval
  • CI 里的最小回归
  • 线上失败样例回流位置

2.5 统一启动与交接文档 ​

至少包括：

  • 如何启动
  • 如何配置模型
  • 如何切换环境
  • 如何运行测试
  • 如何做一次发布

3. AI 项目常见的五类模板 ​

3.1 纯文本问答应用 ​

适合：

  • 文本助手
  • Prompt 应用
  • 内部机器人

最小结构通常包括：

  • src/
  • prompts/
  • config/
  • tests/
  • evals/

这类项目的关键不是“目录多”，而是：

  • Prompt 与输出协议要足够清晰

3.2 RAG 项目 ​

通常额外需要：

  • ingestion/
  • chunking/
  • retrieval/
  • vector_store/
  • knowledge/
  • evals/rag/

因为 RAG 项目除了生成链路，还要管理：

  • 文档入库
  • 索引更新
  • 引用验证

3.3 Agent 项目 ​

通常额外需要：

  • tools/
  • workflows/
  • memory/
  • guardrails/
  • handoff/
  • approvals/

Agent 项目最值得前置的不是“多几个目录”，而是：

  • tool contract
  • state contract
  • approval contract

3.4 Realtime Voice 项目 ​

通常额外需要：

  • audio/
  • session/
  • streaming/
  • turn_detection/
  • latency_metrics/

这类项目的脚手架必须更早考虑：

  • 流式状态
  • 语音中断
  • 低延迟监控

3.5 多模态项目 ​

通常额外需要：

  • vision/
  • ocr/
  • media_pipeline/
  • assets/
  • safety/

因为这类项目会额外碰到：

  • 文件格式
  • 中间产物
  • 资源存储
  • 媒体安全检查

4. 一个通用 AI 项目骨架应该长什么样 ​

一个更通用、也更适合继续演化的骨架通常像这样：

text
project/
|- src/
|  |- app/
|  |- llm/
|  |- prompts/
|  |- tools/
|  |- retrieval/
|  |- workflows/
|  |- guardrails/
|  `- observability/
|- evals/
|- tests/
|- scripts/
|- docs/
|- examples/
|- .env.example
|- README.md
`- package.json / pyproject.toml

4.1 如果团队更偏服务化，还建议再拆 ​

例如：

  • api/
  • workers/
  • jobs/
  • webhooks/

4.2 如果团队做企业交付，建议额外保留 ​

例如：

  • runbooks/
  • release/
  • sample_data/
  • incident_playbooks/

这样交接时不会只剩代码。

5. 脚手架里最值得被模板化的“默认项” ​

不是所有东西都适合抽象，但有一些能力非常适合做成默认项。

5.1 模型调用封装 ​

至少应该统一：

  • 请求入口
  • 超时
  • 重试
  • tracing
  • token 统计

5.2 Prompt 管理方式 ​

至少应该统一：

  • Prompt 存放位置
  • 版本命名方式
  • 变量注入方式
  • 本地调试方式

5.3 结构化输出与 schema 校验 ​

建议默认就支持：

  • JSON Schema
  • tool arg validation
  • 失败后统一收口

5.4 评测入口 ​

建议默认就有：

  • smoke
  • regression
  • safety

三类入口，而不是让每个项目自己发明测试命令。

5.5 trace 与日志 ​

建议默认就带：

  • request ID
  • trace ID
  • model info
  • tool info
  • latency
  • token usage

6. 不同项目类型的优先级为什么不同 ​

脚手架不是越大越好，而是要先覆盖该类型项目最容易出问题的层。

6.1 RAG 项目优先级 ​

更值得优先模板化的是：

  • ingestion
  • chunking
  • metadata
  • retrieval evals
  • citation checks

6.2 Agent 项目优先级 ​

更值得优先模板化的是：

  • tool registry
  • workflow state
  • approvals
  • guardrails
  • failure handling

6.3 Realtime 项目优先级 ​

更值得优先模板化的是：

  • session state
  • interruption handling
  • latency metrics
  • audio pipeline

6.4 企业内部 Copilot 项目优先级 ​

更值得优先模板化的是：

  • auth
  • tenant context
  • retrieval filters
  • audit logging
  • fallback UI

7. 一个新项目启动时的推荐顺序 ​

很多团队会先冲着“页面和功能”写，最后再补工程骨架。

更稳妥的顺序通常是：

  1. 定义项目类型
  2. 选择骨架模板
  3. 明确 Prompt、tool、retrieval 的放置规则
  4. 接入最小 trace 与日志
  5. 接入最小 eval
  6. 再开始堆业务场景

这样做的价值是：

  • 后面迭代不会不断返工目录与基础设施

8. 模板级默认项和项目级自定义项应该怎么分 ​

这是很多团队脚手架越做越重的根因。

8.1 适合放模板里的 ​

例如：

  • 调用封装
  • trace
  • config loader
  • eval runner
  • schema helpers
  • error taxonomy

8.2 适合留给项目定制的 ​

例如：

  • 业务场景样例
  • Prompt 具体内容
  • 高风险动作定义
  • 租户策略
  • 知识域规则

一句话理解：

  • 模板负责“把地打平”
  • 项目负责“把房子盖起来”

9. 脚手架设计时最容易漏掉什么 ​

9.1 Prompt 版本管理 ​

很多项目一开始只把 Prompt 当字符串常量。

后面最容易出现的问题就是：

  • 到底哪句改坏了，不知道

9.2 Evals 目录 ​

很多团队会先把功能写出来，等上线前才想起评测。

但 eval 目录和样例结构越晚补，后面越难沉淀。

9.3 安全与脱敏 ​

企业项目很容易在 Demo 阶段忽略：

  • 日志脱敏
  • 样例数据脱敏
  • 高风险工具默认关

9.4 失败和人工接管路径 ​

脚手架里如果完全没有：

  • fallback
  • retry
  • approval
  • handoff

后面做成真正可交付系统会补得很痛苦。

9.5 示例与本地开发说明 ​

没有 examples/ 和明确 README 的脚手架，团队接手成本会明显变高。

10. 什么时候不要过度脚手架化 ​

脚手架也有反噬风险。

10.1 模板太早抽象业务 ​

最常见表现是：

  • 业务还没稳定
  • 模板已经抽了三层抽象

结果谁都不会改。

10.2 把所有项目类型硬塞进一个超大模板 ​

这通常会导致：

  • 新人难理解
  • 无关代码太多
  • 升级困难

10.3 把“模板化”误当成“平台化” ​

模板的目标是：

  • 提供起点

平台的目标是：

  • 提供共享运行能力

这两件事有关联，但不是同一件事。

11. 一套更实用的模板族谱 ​

比起追求一个万能模板，更实用的做法通常是维护一个模板族谱。

例如：

  • starter-chat
  • starter-rag
  • starter-agent
  • starter-realtime-voice
  • starter-multimodal

然后再共用一组平台包：

  • shared-observability
  • shared-evals
  • shared-tooling
  • shared-auth

这样既能复用，也不至于把所有项目绑死。

12. 脚手架和 LLMOps、交付清单是什么关系 ​

这三者可以这样理解：

12.1 脚手架 ​

解决的是：

  • 项目第一天怎么起步

12.2 LLMOps ​

解决的是：

  • 项目后续怎么持续迭代、评测、发布和回滚

12.3 交付清单 ​

解决的是：

  • 项目上线前哪些证据必须补齐

如果脚手架一开始没把最小工程骨架带上，后面的 LLMOps 和交付就会明显更吃力。

13. 常见反模式 ​

13.1 只有代码骨架，没有运行骨架 ​

即：

  • 目录有了
  • eval、trace、release、runbook 都没有

13.2 模板里没有示例数据和示例命令 ​

结果是：

  • 能看
  • 不能跑

13.3 每个项目复制一份工具封装后各自魔改 ​

最后难以统一升级和修复。

13.4 脚手架默认项太少 ​

这样“模板”只剩空目录，没有真正节省工程成本。

13.5 脚手架默认项太多 ​

这样“模板”会变成无法理解的框架负担。

14. 推荐搭配阅读 ​

15. 重点官方资源 ​