大语言模型应用：从 Prompt 到 RAG 与 Agent 的工程实践
0. 元信息
- 主题路径：
docs/topics/llm-applications/ - 主分类：数据与人工智能
- 辅助分类：工程技术
- 适合对象：具备 Python 与 HTTP/API 基础、希望做出 LLM 应用的学习者
- 建议周期：8～12 周（每周 8～12 小时，含编码、评测、复盘）
- 前置知识：
network-and-http、lang-python；会使用命令行、JSON、环境变量和 Git - 最终目标：能独立交付一个带检索、工具调用、评测、监控和成本边界的可运行 LLM 应用
1. 学习路线
LLM 基础与生态
→ Prompt 工程
→ RAG 基础（Embedding、向量库、检索评测）
→ Agent 与 Function Call
→ LLM 运维与评测
→ 推理与性能
→ 综合项目
每一步都是下一步的前置；先打通最小闭环，再增加框架和规模，不要同时堆叠多个供应商。
2. 阶段周数分配
| 阶段 | 8 周方案 | 12 周方案 | 备注 |
|---|---|---|---|
| 1. LLM 基础与生态 | 0.75 | 1.5 | Token、上下文、模型与 API |
| 2. Prompt 工程 | 1 | 1.5 | 模板、约束、结构化输出 |
| 3. RAG 基础 | 1.5 | 2 | Embedding、向量库、检索评测 |
| 4. Agent 与 Function Call | 1.25 | 1.5 | 工具协议、状态机、恢复 |
| 5. LLM 运维与评测 | 1 | 1.5 | 质量、监控、成本、灰度 |
| 6. 推理与性能 | 1 | 1.5 | 引擎、KV cache、量化、压测 |
| 7. 综合项目 | 1.5 | 2.5 | 首选 RAG + Agent 知识助手 |
3. 九阶段表
| 阶段 | 核心知识 | 实践产出 | 可观察学会标准 |
|---|---|---|---|
| 1. LLM 基础与生态 | Transformer 直觉、Token、上下文窗口、模型/API、开源生态 | API 对话脚本与模型选型记录 | 能解释输入输出、token 预算和模型取舍，并处理超时/限流 |
| 2. Prompt 工程 | 角色、任务分解、约束、少样本、结构化输出、注入防护 | Prompt 模板集与回归样例 | 同一输入能稳定得到指定 schema，能定位提示词回归 |
| 3. RAG 基础 | 文档清洗切分、Embedding、向量库、召回、重排、引用 | 带来源引用的知识库问答 | 能检查召回结果，区分检索错误与生成错误，覆盖空结果 |
| 4. Agent 与 Function Call | 工具 schema、调用协议、Agent loop、状态机、超时、重试、降级 | 可观测工具调用 Agent | 能限制循环与权限，工具失败时恢复或明确失败 |
| 5. LLM 运维与评测 | 人工、A/B、LLM-as-judge、离线集、监控指标、成本、灰度 | 评测集、仪表盘和灰度方案 | 能报告质量、延迟、错误率、token 成本，并按门槛灰度 |
| 6. 推理与性能 | vLLM/TGI/Ollama、KV cache、量化、批处理、吞吐、延迟 | 基准测试报告与调优记录 | 能在固定模型/硬件/并发条件下复现实验并解释变化 |
| 7. 综合项目 | 需求、架构、安全、测试、部署、复盘 | RAG + Agent 客服/知识助手 | 第三方按 README 启动，复现问答、引用和工具失败恢复 |
4. 第一周任务
| 日 | 任务 | 当天交付 |
|---|---|---|
| Day 1 | 配置 Python 环境、API key/本地模型、JSON 与日志；统一用 python -m venv .venv 和 python app.py | 能运行的最小对话脚本与环境说明 |
| Day 2 | 观察 token、上下文和采样参数；记录不同模型输出 | 模型选型表与 3 组输入输出 |
| Day 3 | 写角色、约束、格式化输出 Prompt | 一个返回固定 JSON 的模板 |
| Day 4 | 加入文档读取、切分和简单关键词检索 | 本地文档检索脚本 |
| Day 5 | 接入 Embedding 与向量检索，保留来源 | 第一版 RAG 问答 |
| Day 6 | 为回答设计引用、拒答和空召回分支 | 10 条问题的结果记录 |
| Day 7 | 步骤 A：打通一个带引用的问答闭环；步骤 B：补齐空输入、无结果、超长文本、模型错误四类用例 | 可复现 demo、测试记录和失败清单 |
5. 阶段通用验收
- 不看答案独立重写核心调用或流程；
- 用自己的话解释该组件解决什么问题、为什么有效；
- 画出数据流、检索链路或 Agent 状态转移图；
- 测试空数据、最小值、最大值、异常输入；
- 准备至少 3 组自定义数据并贴出实际输出；
- 记录质量、延迟、token 和成本等相关指标；
- 能修改已有应用并处理失败，而不只是照抄 happy path。
6. 最终验收
- 独立实现：Prompt 模板、文档切分、Embedding 检索、一个 Function Call loop；
- 建立至少 30 条带期望答案/引用的评测样本，覆盖正常、拒答和边界问题；
- 完成 1 个综合项目，包含日志、指标、成本上限和灰度回滚方案；
- 能用 15 分钟讲清模型、RAG、Agent、评测和性能权衡。
7. 综合项目
首选：RAG + Agent 客服/知识助手（必做：知识库检索、引用来源、至少一个业务工具、失败恢复、日志与评测）。
备选：代码助手 / 文档摘要工具。
任何综合项目都必须包含：
- 需求说明；
- 数据流、工具和模型选择理由；
- Prompt、检索和 Agent 算法说明；
- 模块化源码；
- 边界、错误和安全测试；
- 本地或服务化运行说明；
- README；
- 评测与复盘记录。
8. 推荐开源资料
| 角色 | 资料 | 用法 |
|---|---|---|
| 模型/API 查阅 | 各模型供应商官方文档 | 查参数、工具调用、限制和价格，不替代实验 |
| 生态与模型 | Hugging Face | 查模型、Tokenizer、推理生态 |
| RAG 框架对照 | LlamaIndex、LangChain | 最小实现后比较抽象，不盲目绑定 |
| 向量检索 | Qdrant、FAISS | 对照索引、距离和持久化；使用前确认许可证 |
| 推理服务 | vLLM、TGI、Ollama | 在固定基准下比较吞吐、延迟和部署成本 |
| 评测 | Ragas | 辅助 RAG 指标，必须结合人工抽样 |
默认顺序：先用官方 API/本地模型做最小原型 → 自己实现检索与工具调用 → 建评测集 → 再读框架源码和文档 → 压测并复盘。复制开源代码前先确认仓库 LICENSE。
9. 学习资料汇聚（v0.3 自包含）
9.1 背景与动机
LLM 应用的难点不只在生成文本，而在把模型接入真实数据、工具、质量门槛和运行成本。Prompt、RAG、Agent、评测和推理优化共同决定应用是否可靠，适合通过小型端到端项目学习。
9.2 概念地图
flowchart LR
用户 --> Prompt
Prompt --> LLM
文档 --> Chunk[切分]
Chunk --> Embedding --> VectorDB[向量库]
VectorDB --> Retrieve[检索]
Retrieve --> LLM
LLM --> Tool[Function Call]
Tool --> State[Agent 状态机]
State --> LLM
LLM --> Eval[评测与监控]
LLM --> Inference[推理服务]
Prompt 组织输入；RAG 提供外部证据；Agent 负责工具与状态；评测运维约束质量和成本；推理服务决定单位资源下的吞吐与延迟。
9.3 基础知识讲解
主推官方 API/模型文档、Hugging Face 文档和 LlamaIndex/LangChain 文档；前者用于准确接口，后两者用于生态对照。缺失部分由本计划生成：任何框架示例都必须改写成能解释数据流、失败路径和成本的最小程序。
9.4 经典问题与经典案例
| 问题 | 重要性 | 最简答案 |
|---|---|---|
| Prompt 输出不稳定 | 影响下游解析 | 明确 schema、约束和回归样例 |
| RAG 找不到答案 | 生成再强也无法补证据 | 检查切分、Embedding、召回和重排 |
| 模型幻觉 | 可能误导用户 | 要求引用、设置拒答和人工抽样 |
| Agent 无限循环 | 消耗预算并阻塞请求 | 限制步数、超时和重复调用 |
| 工具返回异常 | 业务流程中断 | schema 校验、重试、降级和可观察错误 |
| LLM-as-judge 偏差 | 评测结论失真 | 人工校准、盲测并报告 judge 局限 |
| token 成本失控 | 规模化不可持续 | 预算、缓存、摘要、模型路由和灰度 |
| 延迟过高 | 用户体验下降 | 分解首 token/总延迟，优化 batching、cache 和上下文 |
9.5 学习难点
- 概念难点：Embedding 相似度不是事实正确性；用召回样例分开检查检索与生成。
- 思维难点：Agent 不是“让模型自由发挥”，而是受约束的状态转移；先画 loop 再写代码。
- 工程难点：质量、延迟、成本互相牵制；固定模型、数据和并发后再比较。
9.6 技术标准与接口
Entity
OpenAI-compatible Chat/Responses API、JSON Schema 工具定义、Embedding API、OpenTelemetry 指标接口；具体版本随供应商文档记录。
Scope
API 定义模型调用和工具参数，不保证事实正确、检索质量或业务安全；RAG、Agent 和观测是应用层组合。
Structure
必须掌握 messages、input/output、tool name/arguments、embedding vector、metadata、trace/span、首 token 延迟、总延迟、吞吐和 token usage。
Ecosystem
云端 API、开源模型、Ollama、vLLM、TGI、向量库和 RAG/Agent 框架并存。OpenAI-compatible 是事实互操作接口，不等于统一标准；部署时记录模型、版本、硬件和参数。
Depth Tiers
- L0：知道 Prompt、RAG、Agent、Embedding、推理服务存在；
- L1：看得懂 API、向量检索和工具调用示例；
- L2：能正确调用并处理常见错误；
- L3：能解释质量、成本、延迟并排错；
- L4：能设计可观测、可灰度、可扩展的应用架构。
本计划要求达到 L3，综合项目争取 L4 的局部能力。
Source
以各官方文档的 2026-07-28 快照为准：Hugging Face、vLLM、TGI、Ollama、Qdrant、FAISS、LlamaIndex、LangChain。
10. 常见误区
- 把模型会聊天当成会做应用；
- 只调 Prompt，不建立评测集；
- 认为接入向量库就自动成为 RAG；
- 不保留来源，无法核验答案；
- 让 Agent 无限制调用工具；
- 忽略工具参数校验、权限和超时；
- 只看平均延迟，不看首 token、P95 和错误率；
- 用 LLM-as-judge 单独决定质量；
- 压测时不固定模型、上下文和并发；
- 只比较吞吐，不记录成本和资源占用；
- 把框架抽象当作底层原理；
- 未设置灰度、回滚和预算上限就上线。
11. 所有知识点分类（统一规则）
- 编程语言
- 数据结构与算法
- 计算机基础
- 工程技术
- Web 与后端
- 前端与客户端
- 数据与人工智能
- 项目与职业能力
本计划归属：数据与人工智能 主 + 工程技术 辅。
引用模板：../../template/_TEMPLATE.md
引用设计：../../superpowers/specs/2026-07-28-llm-applications-design.md