18. 最终综合项目的目录模板
- 定义问题、基线和成功指标
- 实现数据—模型—评估—服务闭环
- 形成可复现、可审查的技术报告
- 完成训练或 RAG 主线
- 掌握评估与服务基础
本章产物完整仓库、模型或索引产物、评估报告、服务演示和复盘。
综合项目不是把前面所有技术堆在一起，而是围绕一个清晰问题建立最小、可证明的闭环。推荐题目是“带精确引用的技术文档助手”，因为它同时覆盖检索、生成、工具、评估、服务和权限，又不要求从零训练大模型。
18.1 先写项目契约
实现前在 README 顶部回答：
用户：谁会使用？
任务：输入和期望输出是什么？
范围：只支持哪些文档、语言和问题？
不做：哪些能力明确排除？
成功：质量、延迟、安全分别达到什么？
失败：何时拒答、转人工或回滚？示例成功标准：
| 维度 | 指标 | 门槛示例 | 数据来源 |
|---|---|---|---|
| 检索 | Recall@5 | 预先定义 | 人工标注 query—document |
| 回答 | 关键事实正确率 | 预先定义 | 独立 test cases |
| 引用 | claim 被引用支持 | 预先定义 | 双人复核或明确 rubric |
| 拒答 | 无证据问题正确拒答 | 预先定义 | 不可回答集 |
| 性能 | TTFT/P95 | 目标硬件实测 | 固定长度与并发基准 |
| 安全 | 越权读取 | 必须为 0 | 跨 Workspace 测试 |
门槛应在看最终结果之前确定；否则容易根据已有结果移动目标。
18.2 推荐目录
llm-capstone/
├── README.md
├── pyproject.toml
├── configs/
│ ├── train.yaml
│ ├── inference.yaml
│ └── eval.yaml
├── data/
│ ├── README.md
│ ├── train.jsonl
│ ├── valid.jsonl
│ └── test.jsonl
├── src/
│ ├── data.py
│ ├── train.py
│ ├── infer.py
│ ├── rag.py
│ ├── tools.py
│ └── server.py
├── eval/
│ ├── cases.jsonl
│ ├── run_eval.py
│ └── rubric.md
├── tests/
│ ├── test_data.py
│ ├── test_tools.py
│ └── test_api.py
├── artifacts/
└── reports/每个目录的责任：
configs/：可审查的参数，不把关键配置藏在命令历史。data/README.md：来源、许可、字段、切分、哈希和已知偏差。src/：生产逻辑；Notebook 只用于探索和解释。eval/：独立于服务的评估，保存逐样本结果。tests/：数据契约、工具权限、API 错误路径和回归用例。artifacts/：本地生成且可追溯的索引、Adapter、checkpoint。reports/：基线、实验、失败分析和发布决策。
18.3 四个里程碑
M1｜可测量基线。 不做微调，只完成关键词检索、固定模型或规则回答和 30 条测试集。提交原始输出与错误分类。
M2｜检索闭环。 加入 chunk、embedding 或 rerank 之前先保留 BM25；分别报告检索和生成指标。权限过滤必须发生在候选返回之前。
M3｜服务闭环。 提供健康检查、生成接口、超时、取消、错误 schema 和基本指标。使用固定请求集测量 P50/P95，不只手工点一次。
M4｜发布评审。 比较 M1 与最终方案，运行不可回答、安全、性能和回归集；根据预设门槛给出发布或不发布结论。
每个里程碑都必须能单独演示和回退。若 M2 失败，M1 仍应可运行；这比最后一天才集成所有组件更容易教学和排错。
18.4 最小 API 与测试契约
GET /healthz 进程与模型是否就绪
POST /v1/query 问题、Workspace、检索参数
GET /metrics 本地或受保护的指标POST /v1/query 至少测试：正常问题、空问题、超长输入、无证据、非法参数、取消、超时和跨 Workspace 文档。若工具包含写操作，还要增加幂等键、审批和重复请求测试。
18.5 项目纪律
- 数据、模型大文件不要直接提交 Git。
- 配置与代码提交。
- 密钥只从环境或安全凭证系统读取。
- 每个模型版本都能追溯到数据、代码和配置。
- 微调前先做 prompt/RAG baseline。
- 上线前必须有离线评估和回滚方案。
18.6 最终评分 Rubric
| 项目 | 权重 | 满分标准 |
|---|---|---|
| 问题与边界 | 10 | 用户、范围、风险和成功门槛明确 |
| 数据与检索 | 15 | 来源可追溯、无泄漏、检索独立评估 |
| 模型与方法 | 15 | 有 baseline，架构选择有证据而非堆技术 |
| 评估 | 20 | 逐样本、对照、失败类型和不确定性完整 |
| 系统工程 | 15 | API、错误路径、超时、权限和可观察性 |
| 安全与隐私 | 10 | 越权、注入、敏感日志与回滚经过测试 |
| 可复现性 | 10 | 新环境可按 README 重建关键结果 |
| 技术表达 | 5 | 结论准确，清楚区分事实、实验与推断 |
一票否决：测试数据泄漏、使用无许可数据、凭据写入仓库、跨 Workspace 越权，或无法说明最终结果来自哪个模型/索引/配置版本。
18.7 答辩问题
- 为什么你的问题需要 LLM，而不是搜索、规则或普通分类器？
- 哪个 baseline 最强？最终方案在哪些样本上仍然更差？
- 如果删除 RAG、Adapter 或 Agent 循环，指标分别怎样变化？
- 一个回答的引用如何证明支持具体 claim？
- 并发增加时瓶颈首先出现在哪里？
- 如何证明用户 A 不能检索用户 B 的文档？
- 明天模型仓库或文档更新，怎样回归和回滚？
能够用仓库中的原始证据回答这些问题，才算完成综合项目。
参考实现：技术文档助手离线 M1/M2。它可以先在无模型、无 GPU 的条件下完成检索与证据链，再按 M3/M4 清单接入真实生成和服务。