RAG on 方糖猫Blog

RAG 系统完全笔记：从检索器到生产部署

Sat, 11 Apr 2026 10:00:00 +0800

RAG 系统完全笔记：从检索器到生产部署

最近重刷了吴恩达 DeepLearning.ai 的《Retrieval Augmented Generation》课程，整理了一份从检索器到生产部署的完整笔记。RAG 不只是「把文档塞进向量库然后问大模型」，它的每个环节都有值得细究的工程决策。本文在每个算法之外，也补充了对应的落地工具与最佳实践。

一、RAG 是什么？为什么需要它？

大语言模型（LLM）有两个天然缺陷：

知识有截止日期：训练数据之后发生的事件、私有文档，模型都不知道。
容易 hallucination（幻觉）：没有可靠依据时，模型会一本正经地编造答案。

RAG 的解决思路很简单：在生成答案前，先从外部知识库中检索相关文档，把检索结果作为上下文喂给 LLM。这样模型既能利用最新、最专有的知识，又能基于检索到的内容生成，显著降低幻觉风险。

一个完整的 RAG 系统分为离线索引和在线检索生成两条流水线：

flowchart LR
    subgraph 离线索引
        A[原始文档] --> B[文档分块 Chunking]
        B --> C[Embedding 编码]
        C --> D[(向量数据库)]
    end
    subgraph 在线检索生成
        E[用户查询] --> F[查询改写]
        F --> G[检索器 Retriever]
        D -.-> G
        G --> H[重排序 Re-ranking]
        H --> I[LLM 生成]
        I --> J[最终答案]
    end

落地框架：搭建整条 pipeline 不必从零写，LangChain 和 LlamaIndex 是最主流的两个 RAG 编排框架，检索器、分块器、重排序器、提示词模板都有现成实现；需要精细控制流程状态（如 Agentic RAG）时可以用 LangGraph。入门建议先用 LlamaIndex 快速跑通，再根据瓶颈逐环节替换。

二、检索器：找到正确的文档

检索器是 RAG 系统的第一道关卡。常见检索方式有三种，以及它们的组合。

2.1 元数据过滤

在向量搜索之前，先用结构化条件缩小范围：

作者、发布时间、信源
地区、类别、权限标签

例如，企业知识库中只允许查询「本部门」文档，就可以通过 department_id 元数据过滤。

最佳实践：主流向量库都支持「过滤 + 向量搜索」的混合查询——Elasticsearch 的 filter 子句、Qdrant 的 payload filter、pgvector 配合普通 WHERE 条件都可以。权限过滤一定要放在检索阶段做，而不是检索出来再在应用层过滤，否则 Top-K 里可能挤掉有权限的文档，还会把不该出现的文档内容带进 LLM 上下文。

2.2 关键词搜索

基于词频的检索，计算查询词与文档的匹配程度。

TF-IDF

TF（词频）：查询中的词在一篇文档里出现了多少次。
IDF（逆文档频率）：查询中的词在所有文档中出现的频率的倒数。词越稀有，权重越高。

写成公式：

$$ \mathrm{tf}(t, d) = \frac{f_{t,d}}{\sum_{t’ \in d} f_{t’,d}}, \qquad \mathrm{idf}(t, D) = \log \frac{N}{1 + |{d \in D : t \in d}|} $$

公式中各符号的含义：

$t$（term）：一个词项（term），通常指查询中的某个词。
$d$（document）：一篇文档，即被评分的单篇文档。
$D$（document collection）：整个文档集合（语料库），包含全部 $N$ 篇文档。
$f$：词频计数函数（frequency）。$f_{t,d}$ 表示词 $t$ 在文档 $d$ 中出现的次数，例如「检索」在某文档中出现 3 次，则 $f_{t,d} = 3$。
$\sum_{t’ \in d} f_{t’,d}$：文档 $d$ 中所有词项的出现次数之和，即文档总词数（长度）。分子除以它，就把词频归一化成「占比」，避免长文档天然占优。
$N$：文档集合 $D$ 中的文档总数。
$|{d \in D : t \in d}|$：包含词 $t$ 的文档篇数（document frequency）。分母加 1 是平滑处理，防止词在所有文档中都不出现时除以零。

直观理解：$\mathrm{tf}$ 衡量「这个词在本文档中有多重要」（出现占比越高越重要），$\mathrm{idf}$ 衡量「这个词在整个语料库中有多稀有」（越稀有的词越能区分文档，权重越高），两者相乘就是词的综合权重。

文档 $d$ 对查询 $q$ 的得分即查询中各词的 TF-IDF 之和：

$$ \mathrm{score}(q, d) = \sum_{t \in q} \mathrm{tf}(t, d) \cdot \mathrm{idf}(t, D) $$

BM25

BM25 是 TF-IDF 的改进版，引入了两个可调参数：

$$ \mathrm{score}(q, d) = \sum_{t \in q} \mathrm{idf}(t) \cdot \frac{f_{t,d} \cdot (k_1 + 1)} {f_{t,d} + k_1 \cdot \left(1 - b + b \cdot \dfrac{|d|}{\mathrm{avgdl}}\right)} $$

$k_1$：控制词频对评分的影响（词频饱和曲线），常见取值 $1.2 \sim 2.0$。
$b$：控制文档长度归一化的强度，$|d|$ 是文档长度，$\mathrm{avgdl}$ 是平均文档长度，常见取值 $0.75$。

BM25 在短查询、精确匹配场景中仍然非常有效，比如查找包含特定术语的技术文档。

工业实现：Elasticsearch

BM25 不是纸面算法，它就是 Elasticsearch 的默认评分器（自 ES 5.0 / Lucene 6.0 起，替代了旧的 TF-IDF）。最普通的 match 查询，底层走的就是 BM25：

GET /my-index/_search
{
  "query": {
    "match": {
      "content": "检索增强生成"
    }
  }
}

$k_1$ 和 $b$ 两个参数可以在索引设置里自定义（注意修改 similarity 需要关闭索引或重建索引）：

PUT /my-index
{
  "settings": {
    "similarity": {
      "my_bm25": {
        "type": "BM25",
        "k1": 1.2,
        "b": 0.75
      }
    }
  },
  "mappings": {
    "properties": {
      "content": {
        "type": "text",
        "similarity": "my_bm25"
      }
    }
  }
}

调试时还可以加 "explain": true，ES 会返回每个文档 BM25 打分的详细拆解（tf、idf、长度归一化各自贡献了多少），对排查「为什么这篇文档排在前面」非常有用。

不想维护 ES 集群时，轻量替代方案有 OpenSearch（同源于 Lucene）、纯 Python 的 rank_bm25 库，以及 LangChain 内置的 BM25Retriever。注意中文 BM25 的效果强依赖分词器：ES 建议装 IK Analyzer，并针对领域维护自定义词典（产品名、缩写、术语）。

2.3 语义搜索

将查询和文档都编码成向量，通过 余弦相似度（cosine similarity） 找到语义相近的文档。即使关键词不同，语义接近也能召回。

$$ \cos(\mathbf{q}, \mathbf{d}) = \frac{\mathbf{q} \cdot \mathbf{d}}{|\mathbf{q}| , |\mathbf{d}|} = \frac{\sum_i q_i d_i}{\sqrt{\sum_i q_i^2} \cdot \sqrt{\sum_i d_i^2}} $$

余弦相似度取值在 $[-1, 1]$ 之间，越接近 $1$ 表示语义越相近。实际工程中通常先对向量做 L2 归一化，此时余弦相似度就退化为简单的内积，检索更高效。

落地工具：向量由 Embedding 模型生成，选型参考 Hugging Face 的 MTEB / C-MTEB 榜单：

API 方案：OpenAI text-embedding-3 系列、Cohere Embed、阿里 DashScope 通用文本向量。
自托管方案：BGE-M3（BAAI，中英文效果好，支持稠密 + 稀疏 + 多向量三种输出）、gte-Qwen 系列、E5 系列，均可用 sentence-transformers 或 FlagEmbedding 库本地加载。

最佳实践：查询和文档必须用同一个 Embedding 模型（部分模型对查询和文档有不同前缀，如 E5 的 query: / passage:，不要混用）；更换 Embedding 模型意味着全量重建索引，选型时先在自有数据上做小规模评测再定。

2.4 混合搜索

实际工程中，通常把多种检索方式组合起来：

flowchart LR
    Q[用户查询] --> K[关键词搜索 BM25]
    Q --> S[语义搜索 向量]
    K --> M[结果融合]
    S --> M
    M --> F[元数据过滤]
    F --> R[重排序]
    R --> O[最终上下文]

两路结果分数量纲不同，直接相加不合理，标准做法是 RRF（Reciprocal Rank Fusion）：只看排名不看分数。

$$ \mathrm{RRF}(d) = \sum_{r \in \text{各路检索}} \frac{1}{k + \mathrm{rank}_r(d)} $$

其中 $k$ 是平滑常数，通常取 $60$。文档在任一路排得靠前，融合后得分就高。

落地工具：这套组合在 Elasticsearch 8.x 里一个引擎就能实现——BM25 + kNN 向量检索（底层 HNSW），原生支持 RRF 融合；代码侧则可以用 LangChain 的 EnsembleRetriever（内部同样是 RRF）把 BM25Retriever 和任意向量检索器组合起来。

2.5 检索质量评估

精准度（Precision）：检索出的相关文档 / 检索出的所有文档。反映结果的可信度。
召回率（Recall）：检索出的相关文档 / 所有相关文档。反映结果的完整度。

$$ \mathrm{Precision} = \frac{|\text{相关文档} \cap \text{检索结果}|}{|\text{检索结果}|}, \qquad \mathrm{Recall} = \frac{|\text{相关文档} \cap \text{检索结果}|}{|\text{相关文档}|} $$

平均精准度（MAP）：先对单次查询在相关文档出现的每个位置取精准度平均（AP），再对多次查询求平均。

$$ \mathrm{MAP} = \frac{1}{|Q|} \sum_{q=1}^{|Q|} \mathrm{AP}(q), \qquad \mathrm{AP}(q) = \frac{1}{m_q} \sum_{k=1}^{n} P(k) \cdot \mathrm{rel}(k) $$

其中 $m_q$ 是查询 $q$ 的相关文档总数，$P(k)$ 是前 $k$ 个结果的精准度，$\mathrm{rel}(k)$ 表示第 $k$ 个结果是否相关。

平均倒数排名（MRR）：最相关文档在结果列表中的排名的倒数。排名第一，MRR 就是 1；排名第十，MRR 就是 0.1。

$$ \mathrm{MRR} = \frac{1}{|Q|} \sum_{q=1}^{|Q|} \frac{1}{\mathrm{rank}_q} $$

落地工具：评估的前提是有一批带标注的「黄金测试集」（golden dataset），通常 50-200 条真实用户问题加人工标注的相关文档。标注成本高时可以用 Ragas 的合成数据功能自动生成测试集；Ragas 和 DeepEval 还都提供 context precision / context recall 等无需人工标注、由 LLM 打分的检索评估指标，适合纳入 CI 做回归测试。

三、向量数据库：如何高效存储和检索

向量数据库的核心问题是：给定一个查询向量，如何快速找到最相似的文档向量？

3.1 KNN：精确但慢

KNN（K-Nearest Neighbors）会实时计算查询向量与所有文档向量的距离，结果准确，但当向量数量达到亿级时，计算量不可接受。设向量库有 $N$ 个 $d$ 维向量，暴力检索的复杂度为 $O(Nd)$。

适用场景：向量量在万级以内、或需要精确结果做基准评测时，暴力 KNN 反而最省事——FAISS 的 IndexFlatIP、NumPy 一次矩阵乘法就够，不必引入索引结构。

3.2 ANN：近似但快

ANN（Approximate Nearest Neighbor）通过构建近邻图或索引结构来加速检索，牺牲了极小的准确率，换取了数量级的性能提升。

HNSW（Hierarchical Navigable Small World） 是目前最常用的 ANN 算法之一，采用分层导航图结构，能够在亿级向量库中快速找到近似最近邻：

flowchart TB
    Q[查询向量] --> E[顶层入口点]
    subgraph HNSW["HNSW 分层图"]
        direction TB
        L2["Layer 2（最稀疏，快速定位大致区域）"]
        L1["Layer 1（中间过渡层）"]
        L0["Layer 0（包含全部节点，精确找最近邻）"]
        L2 --> L1 --> L0
    end
    E --> L2
    L0 --> R["Top-K 近似最近邻"]

查询时从最稀疏的顶层开始贪心搜索，逐层向下，每层把入口点收敛到更接近目标的区域，最后在最稠密的第 0 层做精细查找。平均查询复杂度约为 $O(\log N)$。

落地工具：

向量库选型：Milvus、Qdrant、Weaviate（独立向量数据库）、pgvector（已有 PostgreSQL 时的最简方案）、Chroma（轻量嵌入式）、FAISS（Meta 的索引库，无服务化能力）、Elasticsearch kNN（想复用 BM25 生态时）。
HNSW 三个关键参数：M（每个节点的最大连接数，默认 16，越大越准但越耗内存）、ef_construction（建索引时的搜索宽度，默认 100）、ef_search（查询时的搜索宽度，运行时调大它就能在召回率和延迟之间实时权衡，是最常用的调优旋钮）。

四、文档分块：粒度决定召回质量

把长文档切成小块（chunk）是 RAG 的关键步骤。chunk 太大或太小都有问题：

太大：一个向量要表达太多内容，指向性弱，容易引入无关信息。
太小：上下文不足，语义不明确。

4.1 固定大小分块

文本：250 字符左右（例如 225 字符正文 + 25 字符重叠）。
代码：500 字符左右，重叠 50-100 字符。

重叠（overlap）能避免关键信息被切分断掉。

落地工具：LangChain 的 CharacterTextSplitter / RecursiveCharacterTextSplitter、LlamaIndex 的 SentenceSplitter。其中 RecursiveCharacterTextSplitter 是事实上的默认选择：按「段落 → 句子 → 词 → 字符」的优先级递归切分，尽量在大小限制内保留自然边界。

4.2 按特殊字符分块

按换行、段落、标题等自然边界切分，保留文档结构。

落地工具：Markdown 文档用 LangChain 的 MarkdownHeaderTextSplitter 按标题层级切；HTML/PDF 等复杂格式先用 Unstructured 做版面解析再分块；代码可以按语法树切分（LangChain 的 Language 参数基于 tree-sitter）。

4.3 语义分块

按句子处理，判断当前句子与下一个句子的语义相似度。如果不相似，就在当前位置切分。即对相邻句子的向量 $s_i$、$s_{i+1}$，当 $\cos(s_i, s_{i+1}) < \tau$（$\tau$ 为预设阈值）时切分。这样切出来的 chunk 内部语义更连贯。

落地工具：LangChain 的 SemanticChunker（基于 Embedding，可选百分位/标准差阈值）、LlamaIndex 的 SemanticSplitterNodeParser、专用库 chonkie。

4.4 LLM 分块

直接让大模型根据语义边界做分块，效果通常最好，但成本也最高。实践中一般用小型模型（如 GPT-4o-mini 级别）离线跑一遍建索引，在线查询不再产生额外成本。

4.5 上下文感知分块

在分块后补充描述信息，例如 chunk 所属的章节、文档标题等，帮助提升索引相关性。

最佳实践：Anthropic 提出的 Contextual Retrieval 是这个思路的成熟方案——索引入库前，让 LLM 为每个 chunk 生成一段 50-100 token 的上下文说明（「本段出自 XX 文档第三章，讨论……」）拼在 chunk 前面，再做 Embedding 和 BM25 索引，官方报告可将检索失败率降低约 49%（配合重排序可达 67%）。Embedding 前拼接即可，无需改动检索链路。

五、查询改写：让问题更容易被检索

用户的原始查询往往不适合直接做向量检索。常见优化方式：

5.1 LLM 重写查询

让 LLM 在检索前改写查询：去除无关信息、修正术语、扩展同义词。

落地工具：LangChain 提供现成的实现——MultiQueryRetriever（让 LLM 生成多个改写版本并行检索后去重合并）、RePhraseQueryRetriever；LlamaIndex 有 QueryTransform（如 HyDEQueryTransform）。最佳实践：多轮对话里务必先把「指代消解」做掉——用 LLM 把「那它多少钱？」结合历史改写成独立问题再检索，这一步对客服场景提升最明显。

5.2 命名实体识别（NER）

识别查询中的人名、地名、日期、组织、角色等实体，用作：

知识图谱检索
精准 BM25 匹配
元数据过滤

落地工具：通用场景用 spaCy、中文用 HanLP 或 LTP；实体类型不固定（领域专有名词）时用零样本模型 GLiNER，或直接让 LLM 做结构化抽取（JSON 输出），简单且免去训练。

5.3 假设文档嵌入（HyDE）

HyDE（Hypothetical Document Embeddings）的思路是：

flowchart LR
    Q[用户查询] --> L["LLM 生成「理想答案」"]
    L --> E[Embedding 编码]
    E --> V[(向量数据库)]
    V --> D[检索相似的真实文档]
    D --> G[LLM 基于真实文档生成最终答案]

先用 LLM 生成一个「理想答案」。
用这个答案的向量去向量库中检索相似文档。

传统 RAG 搜索的是「与用户查询相似的文档」，而 HyDE 搜索的是「与理想答案相似的文档」，往往召回质量更高。

最佳实践：HyDE 适合开放式、长尾问题，对事实短查询收益有限；生成理想答案时用低 temperature 并生成 2-4 个版本取向量均值，比单个版本更稳；LangChain 的 HypotheticalDocumentEmbedder 和 LlamaIndex 的 HyDEQueryTransform 可直接使用。代价是多一次 LLM 调用的延迟，对时延敏感的场景要权衡。

六、编码与重排序：让相似度更准确

6.1 双向编码（Bi-Encoder）

RAG 默认的编码方式。查询和文档分别编码成向量，然后通过向量相似度匹配：

$$ \mathrm{score}(q, d) = \cos\big(E_q(q), E_d(d)\big) $$

编码可以离线预计算，在线检索只需一次查询编码加向量搜索，速度快，但查询与文档之间没有深度交互。

落地工具：就是 2.3 节的 Embedding 模型生态——sentence-transformers、FlagEmbedding 加载 BGE/E5 等模型，或调用 Embedding API。

6.2 交叉编码（Cross-Encoder）

把查询和每个文档配对，输入一个小型 LLM，输出相关度分数：

$$ \mathrm{score}(q, d) = E_{\mathrm{cross}}([q; d]) $$

准确率更高，但每对 $(q, d)$ 都要过一次模型，计算成本大，通常用于重排序阶段。

落地工具：开源重排序模型首选 bge-reranker-v2 系列（BAAI，中英双语）和 Qwen3-Reranker；API 方案有 Cohere Rerank 和 Jina Reranker。sentence-transformers 的 CrossEncoder 类三行代码即可加载本地模型打分。

6.3 ColBERT

文档中每个词都生成一个向量，而不是整个文档只有一个向量。查询时，把查询词与文档中所有词向量对比，构建相似度矩阵并加和。其核心是 MaxSim 操作：

$$ \mathrm{score}(q, d) = \sum_{i=1}^{|q|} \max_{j=1}^{|d|} ; \mathbf{q}_i \cdot \mathbf{d}_j $$

即查询中每个 token 都在文档里找到最匹配的一个 token，再把最高分相加。兼顾效率和细粒度匹配。

落地工具：训练和使用 ColBERT 模型用官方 ColBERT 仓库或更易用的 RAGatouille；生产检索引擎 Vespa 原生支持张量（多向量）排序；BGE-M3 的 multi-vector 输出也能实现类似的 MaxSim 细粒度匹配。

6.4 重排序（Re-ranking）

先从向量库中粗召回一批候选文档，再用交叉编码或 LLM 做二次排序，过滤掉不相关的结果：

flowchart LR
    Q[查询] --> B["Bi-Encoder 粗召回<br>（快，Top 50）"]
    B --> C["Cross-Encoder / LLM 精排<br>（准，Top 5）"]
    C --> O[送入 LLM 的上下文]

粗召回阶段追求「不漏」，精排阶段追求「排得准」，两个阶段各司其职。

最佳实践：重排序通常是 RAG 系统里性价比最高的单项优化——不动索引、不改 Embedding 模型，只在检索后插一层，召回质量立竿见影。粗召回取 Top 20-50、精排后保留 Top 3-5 是常见配置；用 LangChain 的 ContextualCompressionRetriever 或 LlamaIndex 的 Postprocessor 机制接入，几行代码就能挂在现有链路上。

七、LLM 生成：如何让答案更可靠

7.1 Transformer 基础

LLM 的核心是 Transformer：多头注意力机制 + 前馈网络。缩放点积注意力的公式为：

$$ \mathrm{Attention}(Q, K, V) = \mathrm{softmax}\left(\frac{Q K^{\top}}{\sqrt{d_k}}\right) V $$

其中 $Q$、$K$、$V$ 分别由输入线性变换得到，$d_k$ 是 key 的维度，除以 $\sqrt{d_k}$ 是为了防止点积过大导致 softmax 梯度消失。理解这一点有助于理解上下文窗口、注意力稀释等问题。

7.2 LLM API 关键参数

temperature：采样温度。0 表示贪婪模式，总是选概率最高的 token；大于 1 会让低概率 token 更有可能被选中。其作用是在 softmax 前对 logits 做缩放：

$$ p_i = \frac{\exp(z_i / T)}{\sum_j \exp(z_j / T)} $$

$T \to 0$ 时分布退化为 one-hot（贪婪），$T$ 越大分布越平坦、越随机。

top-k：只从概率最高的前 k 个 token 中采样。
top-p（nucleus sampling）：从累计概率达到 p 的 token 集合中采样。
repetition_penalty：惩罚重复出现的 token。
logit_bias：调整特定 token 的概率。

最佳实践：RAG 问答场景建议 temperature = 0（或 0.1-0.3）以保证答案稳定、贴合检索内容；top-p 与 temperature 一般只调一个，不要同时大幅改动；需要模型输出严格 JSON 时优先用各家的 structured output / JSON mode，而不是靠提示词约束。

7.3 LLM 选型因素

模型大小
发布时间
成本
上下文窗口长度
首 token 延迟（Time to First Token）

落地工具：横向对比可以参考 LMArena（真人盲测偏好榜）和 OpenCompass（中文能力评测较全）；但最终一定要在自有评估集上跑一次——榜单排名和具体业务场景的表现经常有出入。自建服务推理引擎选 vLLM（高吞吐）或 TGI；本地/边缘部署用 Ollama、llama.cpp。

7.4 提示词工程

一个典型的 RAG 提示词结构：

系统提示词
+ 会话历史
+ 检索到的文档
+ 用户问题

优化技巧：

添加回答样例（few-shot）
要求模型展示思考链路（chain-of-thought）
对过长的上下文做裁剪，保留最相关部分

最佳实践：给每个检索到的 chunk 编号并要求模型在答案中标注引用（如 [1][3]），既能溯源又便于自动校验幻觉；明确写「文档中没有答案时直接说不知道」，比含糊的约束更能压住幻觉；上下文窗口紧张时按重排序分数从高到低填充，而不是按文档原始顺序。

7.5 幻觉处理

多次生成对比：让模型多次回答，看是否一致。
强制基于检索文档回答：明确要求模型只根据提供的文档作答，并引用来源。

落地工具：自动化检测可用 Ragas 的 faithfulness 指标（答案是否忠于检索上下文）、SelfCheckGPT（多次采样一致性）；要求引用编号后，还可以在应用层写一个简单的校验器：答案中引用的编号必须真实存在于本次检索结果里，否则丢弃重答。

八、Agentic RAG 与微调

8.1 Agentic RAG

复杂查询可以交给 Agent：

flowchart LR
    Q[复杂查询] --> R[提示词路由]
    R --> P["制定计划<br>（拆分多跳子查询）"]
    P --> X["执行检索 / 工具调用"]
    X --> V{结果是否充分}
    V -- 否 --> P
    V -- 是 --> S[整合答案]
    S --> A[最终回答]

例如，一个多跳问题可以拆分成多个子查询，分别检索后再综合回答；检索不充分时 Agent 还会调整计划继续检索。

落地工具：LangGraph（显式状态机，最可控）、CrewAI / AutoGen（多 Agent 协作）、LlamaIndex 的 AgentWorkflow。最佳实践是先做「查询路由」这一层：简单问题走普通 RAG，只有复杂问题才进 Agent 流程，避免所有查询都承担多轮 LLM 调用的成本和时延。

8.2 微调

当通用模型在某些领域表现不足时，可以用领域数据集微调模型，提升特定任务的准确率和稳定性。

落地工具：参数高效微调用 LoRA / QLoRA（Hugging Face peft 库），一站式训练框架选 LLaMA-Factory（中文社区活跃、零代码 WebUI）或 Axolotl。最佳实践：微调是最后手段——先把提示词工程和检索质量优化到位仍不达标时再考虑；微调 Embedding 模型（用自己业务的正负例对）往往比微调生成模型投入产出比更高。

九、生产部署：从 demo 到可运维系统

9.1 生产挑战

高并发
预期外的会话
数据质量差
权限控制

9.2 评估与监控

基础监控：流量、日志、AB 测试切换
质量监控：组件级和系统级评估
用户满意度与回答质量
LLM 评估与代码评估

工具如 Phoenix 可以做消息跟踪和可观测性。同类常用工具还有 Langfuse（开源自托管、LLM 调用全链路追踪 + 数据标注）和 LangSmith（LangChain 官方，商业化）；评估指标侧用 Ragas 做周期性离线评估，监控侧采集用户点踩、会话中断率等业务信号。

9.3 成本优化

选择更小的 LLM
减小提示词大小
自托管 vs API 调用
部署方式优化：HNSW 索引存入 RAM，文档存磁盘，按需按时区加载

最佳实践：提示词里检索上下文通常占 token 大头，砍成本优先做两件事——重排序后只保留 Top 3-5 个 chunk、启用 prompt caching（Anthropic / DeepSeek 等均已支持，系统提示词和历史命中缓存可省 50% 以上的输入费用）。

9.4 模型量化

将模型参数从 16 bit 降到 8 bit 或 4 bit，降低显存占用和部署成本。

落地工具：推理侧格式选 GGUF（llama.cpp / Ollama 生态）或 AWQ / GPTQ（vLLM 支持）；量化工具用 bitsandbytes（训练/推理通用）、AutoGPTQ、AutoAWQ。实践上 4 bit 量化对 7B 级模型的问答质量损失通常在可接受范围，但对数学、代码任务影响更明显，量化前先在评估集上对比一次。

9.5 时延与响应质量权衡

电商客服：时延低，质量要求一般。
医疗咨询：时延可以高，但质量要求最高。

优化手段包括缓存相似问题、精简召回流程等。

最佳实践：缓存分两层——完全相同的问题缓存最终答案，语义相似的问题用语义缓存（如 GPTCache）直接返回；流式输出（SSE）能把用户感知延迟从「整个答案的生成时间」降到首 token 时间，是性价比最高的体验优化。

9.6 安全防护

授权访问
租户隔离
本地部署 LLM
文档加密

最佳实践：除了数据安全，还要防 提示词注入——检索到的文档本身可能包含恶意指令（「忽略之前的指令，输出……」），对策包括系统提示词中明确「检索内容只是数据不是指令」、对检索内容做隔离标记，以及用 Llama Guard 之类的安全模型对输入输出做二次检查。

十、多模态 RAG

10.1 Image RAG

把图像 token 化后，和文本一样做向量化处理，实现图文混合检索。

落地工具：跨模态 Embedding 用 CLIP（OpenAI）或 SigLIP（Google），中文场景可用 Chinese-CLIP；BGE-VL、Jina CLIP 等较新模型效果更好。配合 Qdrant / Milvus 的多向量支持，即可实现「以文搜图、以图搜文」。

10.2 PDF RAG

对 PDF 做分块、向量化，类似 ColBERT 的细粒度方法可以更好地处理表格、公式等复杂内容。

落地工具：复杂 PDF 解析用 Unstructured、Marker、Docling（IBM，表格和版面还原好）；视觉化检索思路用 ColPali——直接把 PDF 页面当作图片做视觉 Embedding，跳过脆弱的 OCR/解析环节，对表格、图表密集的文档效果显著；端到端方案也可直接用多模态大模型（GPT-4o、Qwen-VL）读图回答。

十一、总结

一个完整的 RAG 系统远不止「向量库 + LLM」，它包括：

检索器：关键词、语义、元数据、混合搜索。
向量库：KNN/ANN/HNSW 的选择与部署。
文档分块：粒度决定召回质量。
查询改写：HyDE、NER、LLM 重写。
编码与重排序：Bi-Encoder、Cross-Encoder、ColBERT。
LLM 生成：参数调优、提示词工程、幻觉控制。
生产部署：监控、评估、成本、安全、多模态。

各环节的主流工具速查：

环节	常用工具
编排框架	LangChain、LlamaIndex、LangGraph
关键词检索	Elasticsearch / OpenSearch（BM25）、rank_bm25
Embedding 模型	BGE-M3、E5、OpenAI text-embedding-3
向量数据库	Qdrant、Milvus、pgvector、FAISS、ES kNN
重排序	bge-reranker、Qwen3-Reranker、Cohere Rerank
评估	Ragas、DeepEval
可观测性	Phoenix、Langfuse、LangSmith
推理部署	vLLM、Ollama、llama.cpp
微调	LLaMA-Factory、peft（LoRA/QLoRA）

RAG 的每一个环节都可以单独调优，也都有成熟的工程实践。真正影响系统效果的，往往不是某个单点技术，而是整个 pipeline 的协同设计。

参考：吴恩达 DeepLearning.ai《Retrieval Augmented Generation (RAG)》课程

AI 工程师的 Prompt 工程：不是玄学，是工程实践

Mon, 23 Mar 2026 19:00:00 +0800

AI 工程师的 Prompt 工程：不是玄学，是工程实践

很多人觉得 Prompt Engineering 就是"怎么跟 AI 说话"，甚至有人把它当成玄学。但在工程实践中，Prompt 本质上是在设计人与大模型之间的接口协议，是 LLM 应用的核心代码之一，需要版本管理、回归测试、性能评估。这篇文章结合两个真实项目——AI 视频生成管线（方糖猫 / GeekCast Engine）和一套我开发的 AI 结对编程 Prompt 规则库（keframework-aidev-promptkit）——分享沉淀下来的 Prompt 工程方法。不罗列模板，只讲可落地、可评估、可迭代的系统能力。

一、Prompt 是接口，不是提示语

很多团队把 Prompt 写在代码的某个字符串里，或者放在在线编辑器的临时文本框里调试。这种方式在小原型阶段没问题，但一旦进入生产环境，就会暴露出三个问题：

不可追溯：某个版本上线后效果变差，你不知道是哪一句提示被改了。
不可回归：更新模型或调整业务逻辑后，旧用例是否还成立？没人说得清。
不可协作：产品、运营、工程师各自改一版，最后没人能说出"正确版本"是什么。

所以在 AI 应用里，Prompt 的地位等同于传统代码：

传统代码	Prompt
需要版本控制	需要版本控制
需要测试	需要回归测试
需要 Code Review	需要效果 Review
会引入 Bug	会引入幻觉、格式错误
有架构分层	也有分层（系统规则 / 模式规则 / 领域规范）
有 CI/CD	有评测集 + 回归流水线

更进一步，可以把 Prompt 看作一个函数签名：

f(context, instruction, constraints, examples) → output

context：模型需要知道的背景信息
instruction：明确要做什么
constraints：输出格式、长度、风格、禁止事项
examples：少量示例，帮助模型快速对齐预期

设计 Prompt 时，首先考虑的不是"这句话够不够自然"，而是输入是否完整、输出是否可解析、边界是否可控。当你开始用接口设计的思路写 Prompt，很多所谓"玄学"就会消失。

我们的做法：每个 Prompt 都是一个独立文件，纳入 Git 管理，有版本历史、有变更日志（CHANGELOG）、有配套评测。

下面先看一个完整的真实样本。

二、真实样本解剖：一个 AI 开发的 Prompt 规则库

keframework-aidev-promptkit 是一套给 AI 结对编程工具（Cline / RooCode / Cursor / Windsurf）使用的 Prompt 规则库。它的目标不是"让 AI 聊天更聪明"，而是让 AI 像一个严格遵守工程规范的高级开发一样工作：读需求、做澄清、出方案、拆计划、写代码、跑测试、留文档，全流程可追溯。

它的目录结构本身就是一套 Prompt 架构：

keframework-aidev-promptkit/
├── prompt_rules/              # 规则源文件（Single Source of Truth）
│   ├── common/                # 所有模式都加载的通用规则
│   │   ├── common_general_rules.md   # 输出语言、状态标记等"宪法"
│   │   └── common_memory.md          # Memory Bank 机制
│   ├── plan_architect/        # PLAN/架构模式专用规则
│   │   └── plan_architect_planning.md
│   ├── act_code/              # ACT/编码模式专用规则
│   │   └── act_code_implement.md
│   └── spec/                  # 技术规范（Java 后端、Vue、数据库、API…）
├── ai_work/spec/              # 规范在项目内的落盘位置（只读引用）
├── docs/                      # 配置指南、开发全流程指南、Review 指南
└── CHANGELOG.md               # Prompt 资产自身的变更日志

用一张图看清它的分层：

graph TD
    subgraph 规则分层["Prompt 规则分层（prompt_rules/）"]
        C["common/<br/>通用规则 + Memory Bank<br/>alwaysApply: true"]
        P["plan_architect/<br/>规划模式规则"]
        A["act_code/<br/>实现模式规则"]
        S["spec/<br/>技术规范（只读上下文）"]
    end

    subgraph 工具适配["工具适配层（复制分发）"]
        ROO[".roo/rules<br/>.roo/rules-code<br/>.roo/rules-architect"]
        CLINE[".clinerules/ACT<br/>.clinerules/PLAN"]
        CURSOR[".cursor/rules/"]
    end

    subgraph 项目内上下文["项目内上下文（ai_work/）"]
        MEM["Memory Bank<br/>project_brief / task_plan<br/>active_context / learnings"]
        SPEC2["ai_work/spec/<br/>技术规范副本（全模式只读）"]
    end

    C --> ROO & CLINE & CURSOR
    P --> ROO & CLINE & CURSOR
    A --> ROO & CLINE & CURSOR
    S --> SPEC2
    C -.定义机制.-> MEM

这个结构里藏着几个关键设计决策，下面逐一拆解。

2.1 决策一：按"加载时机"分层，而不是按主题堆砌

规则分三类的依据是何时生效：

common/：永远生效（规则文件头部带 YAML frontmatter：alwaysApply: true）
plan_architect/：只在 PLAN/架构模式生效
act_code/：只在 ACT/编码模式生效
spec/：不注入 System Prompt，而是落盘为项目文件，由规则要求 AI 按需读取、全程只读

这和软件架构里的分层同理：全局常量、按请求注入的拦截器、按需加载的配置。如果把所有规则塞进一个巨大的 System Prompt，AI 在长会话中会逐渐"遗忘"靠后的指令——规则分层本质是注意力预算管理。

2.2 决策二：规则源文件与工具解耦

同一套规则通过脚本复制到不同工具的约定目录（.roo/、.clinerules/、.cursor/rules/），工具各自加载。这保证：

规则只有一份源文件，改一处全工具生效
工具升级或更换时规则资产不丢失
可以针对某个工具做薄薄的适配层，而不动核心规则

2.3 决策三：Prompt 资产自己有 CHANGELOG

这个仓库维护了 CHANGELOG.md / CHANGELOG_cn.md，记录类似这样的条目：

加强规划与实现阶段文档衔接：plan_architect_planning.md 明确规划输出需结构化、无歧义，直接作为实现输入，且实现必须严格遵循，任何偏离需回溯并更新规划。

注意这条日志的写法：不是"优化了提示词"，而是像 API 变更一样描述行为契约的变化。这就是"Prompt 是代码"在资产管理层面的落地。

三、上下文工程：比提示词本身更重要

大模型的能力边界，很大程度上由上下文决定。同样的模型，给不同的上下文，表现可能天差地别。上下文工程至少包含四件事：会话间的记忆延续、相关性管理、知识缺口补足、超长任务的分段策略。

3.1 Memory Bank：解决会话间记忆清零

AI Coding 工具的根本限制是会话之间记忆清零，单次会话上下文有限。promptkit 的解法是 Memory Bank：一组结构化 Markdown 文件，作为 AI 的唯一事实来源（sole context source）。

graph TD
    PB["project_brief.md<br/>项目范围与目标（事实源头）"] --> PR["design/product_requirements.md<br/>PRD：产品需求"]
    PR --> AR["spec/architecture_spec.md<br/>系统架构、组件关系"]
    AR --> TC["spec/technical_spec.md<br/>技术栈与约束"]
    TC --> TP["task/task_plan.md<br/>任务 backlog 与进度"]
    TP --> AC["task/active_context.md<br/>当前焦点、最近变更、下一步"]
    AC --> LE["task/learnings.md<br/>错误/修复/模式 学习日志"]

读写权限按模式划分——这是最容易被忽视的设计：

文件	PLAN 模式	ACT 模式
`project_brief.md`	可编辑	只读
`design/`（PRD、实现设计）	可编辑	只读
`spec/`（架构、技术规范）	全模式只读	全模式只读
`task/task_plan.md`	可编辑	可编辑
`task/active_context.md`	可编辑	可编辑
`task/learnings.md`	可编辑	可编辑

为什么要这样设计？因为没有一个写代码的 Agent 会自觉地不去改需求文档。如果 ACT 模式可以改 spec/，AI 遇到"规范和代码冲突"时往往会悄悄改规范来迁就代码——这在工程上是灾难。用 Prompt 规则把权限写死，等于给 AI 上了文件系统级别的 ACL。

规则还定义了人类可触发的显式命令：read memory bank / rmb（会话开始恢复全部上下文）、update memory bank / umb（里程碑完成后落盘进度）。这把"上下文管理"从 AI 的隐式行为变成了人和 AI 共享的显式协议。

3.2 相关性优先于信息量

很多人误以为上下文越长越好，于是把整个文档、整段对话历史都塞进去。实际上，无关信息会稀释注意力，降低关键细节的召回概率。 尤其是在长上下文窗口下，模型对中间位置的信息敏感度会下降。

在 RAG 系统里，我们会对检索结果做重排序，只保留最相关的片段；在 Agent 任务中，我们会维护一个精简的"工作记忆"，定期丢弃已经完成、不再影响后续决策的中间结果。Memory Bank 的七个文件刻意保持"简洁而完备"，也是同一个道理。

3.3 用 RAG 补足预训练知识的缺口

大模型的训练数据有截止日期，且不会包含你的私有文档、最新产品资料、内部知识库。直接问模型"我们公司上个月上线了哪些功能"，它要么胡说，要么拒绝回答。

我们在短视频生成平台里搭建了基于 ChromaDB 的本地素材库：把品牌素材、历史优质脚本、风格指南等向量化，生成任务触发时先做语义检索，再把检索结果注入 Prompt。这样模型不是在"回忆"，而是在"依据材料创作"。

3.4 长文本要分段：模型负责局部，应用层负责全局

当任务超出单次 Token 上限，或者单次生成难以保证一致性时，不要硬塞。GeekCast Engine 处理长视频口播稿时，采用了"分段生成 + 本地组装"的策略：

按语义把口播稿切分成若干段
每段独立调用 LLM 生成视觉元素规划
在应用层做冲突检测、风格统一和最终组装

这个思路和分布式系统里的 MapReduce 很像：模型负责局部计算，应用层负责全局协调。

四、工作流即 Prompt：PLAN / ACT 双模式

promptkit 最核心的思想是：不指望 AI 自由发挥，而是把软件工程流程编码进 Prompt。PLAN 和 ACT 两个模式各有一段专属规则，规则里直接画出了执行流程。

4.1 PLAN 模式流程

flowchart TD
    Start([开始]) --> Read[读取全部 Memory Bank 核心文件]
    Read --> Check{上下文完整?}
    Check -->|否| Create[补齐缺失文件/计划]
    Create --> Clarify
    Check -->|是| Clarify["&lt;CLARIFICATION&gt;<br/>反复澄清，消除所有歧义"]
    Clarify --> Reason["&lt;STEP BY STEP REASONING&gt;<br/>分解问题、多方案权衡"]
    Reason --> Present["&lt;REASONING PRESENTATION&gt;<br/>呈现计划：假设、取舍、步骤"]
    Present --> Verify{人确认计划?}
    Verify -->|否| Clarify
    Verify -->|是| Update[更新 Memory Bank<br/>落盘结构化计划]

4.2 ACT 模式流程

flowchart TD
    Start([开始]) --> Read[读取 Memory Bank<br/>spec/ 与 design/ 只读]
    Read --> Analyze["&lt;ANALYZE CODE&gt;<br/>依赖分析 + 端到端流程分析"]
    Analyze --> Plan["&lt;PLAN CODE&gt;<br/>结构化提案，等待确认"]
    Plan --> Sim["&lt;SIMULATION ANALYSIS&gt;<br/>Dry run 推演副作用"]
    Sim --> Valid{模拟通过?}
    Valid -->|否| Fix[修复并重新模拟]
    Fix --> Sim
    Valid -->|是| Impl["&lt;MAKE CHANGES&gt;<br/>单逻辑变更，增量提交"]
    Impl --> Test["&lt;TESTING&gt;<br/>单元测试 + 回归测试"]
    Test --> Update[更新 active_context<br/>与 learnings]

4.3 XML 标签作为"行为锚点"

注意规则里大量使用 <CLARIFICATION>、<SIMULATION ANALYSIS>、<NO BREAKAGE ASSERTION> 这类自定义 XML 标签。这不是装饰，而是一种经过验证的 Prompt 技巧：

标签把"阶段"显式化，AI 输出时会自报当前处于哪个阶段，方便人审查 AI 是否跳步
标签给 LLM 提供了清晰的注意力锚点，比自然语言段落里的祈使句更不容易被忽略
标签名形成词汇表后，人可以缩写指令：“先做 <ANALYZE CODE> 再动手”，沟通成本骤降

举两个有代表性的片段（译注，原文为英文）：

<CLARIFICATION>
- 永远主动追问澄清和细节。
- 识别所有不明确的需求，逐一追问。
- 对所有假设提问，消除全部歧义。
- 提出我没想到的方案，预判我的需求。
- 只有百分之百清晰后，才进入方案阶段。
</CLARIFICATION>

<NO BREAKAGE ASSERTION>
提出变更后，自己运行测试并确认通过。
不要依赖用户来做这件事，并且要确信不会破坏用户现有代码。
</NO BREAKAGE ASSERTION>

可以看到，这些规则写的不是"提示"，而是带强制语气的行为规范——和给新员工发的《开发规范》没有区别。

五、规划到实现的交接协议

Prompt 工程里最难的不是"让 AI 生成好内容"，而是让 AI 的上一轮输出成为下一轮可严格执行的输入。promptkit 对此定义了一套交接协议（Handoff Protocol）。

5.1 结构化计划输出

PLAN 模式的产出必须是 YAML 或 Markdown 表格，每个 phase/step 有固定字段：

id: P3-S2
name: Implement login endpoint
description: Add POST /login endpoint for user authentication
source_requirement: PRD-REQ-12
entry_conditions: [P2 completed, API spec approved]
exit_conditions: [Unit tests pass, Docs updated, Code reviewed]
responsible: AI
test_cases: [test_P3_S2_login]
status: planned
requirement_version: v1.2
change_log:
  - {date: 2024-06-01, author: AI, change: 'Initial creation'}

5.2 全链路可追溯

graph LR
    PRD["PRD-REQ-12<br/>需求条目"] --> STEP["P3-S2<br/>计划步骤"]
    STEP --> CODE["user_login_P3_S2.java<br/>实现代码"]
    STEP --> TEST["test_P3_S2_login.java<br/>测试代码"]
    STEP --> COMMIT["feat(P3-S2): ...<br/>提交信息"]
    STEP --> LOG["change_log<br/>变更记录"]

规则强制：

每个 step 必须引用至少一个 PRD 需求 ID；每条需求必须被至少一个 step 覆盖
代码文件、测试文件、commit message 全部携带 step ID
实现阶段发现计划有问题，必须暂停并回溯更新计划，不允许擅自偏离
每个 phase 的 exit 条件包含"单元测试通过、覆盖率 ≥ 90%"，而不是把测试堆到最后

这套东西眼熟吗？它就是把传统项目管理里的**需求追踪矩阵（RTM）**搬进了 Prompt。AI 输出的结构化程度，决定了它在下一阶段的可控性。

六、从单次问答到 Agent 编排

当你让 AI 做一个复杂任务时，单次 Prompt 往往不够。真正难的不是让模型"回答"，而是让它按照正确的路径完成任务，并在出错时恢复。

6.1 ReAct：让模型"想一步、做一步"

ReAct（Reasoning + Acting）是我们用得最多的模式。它的核心不是一次性生成最终答案，而是让模型在每一步都输出：

Thought：当前怎么想
Action：下一步要调用什么工具
Observation：工具返回了什么结果

flowchart LR
    T["Thought<br/>当前怎么想"] --> A["Action<br/>调用什么工具"]
    A --> O["Observation<br/>工具返回结果"]
    O --> D{任务完成?}
    D -->|否| T
    D -->|是| F["Final Answer<br/>输出最终结果"]

比如一个短视频生成任务，Agent 的规划可能是：

读取用户输入的主题和风格要求
检索素材库，找到匹配的背景音乐和视觉素材
生成脚本初稿
检查脚本长度是否符合平台要求
如果不符合，进行压缩或扩展
输出最终脚本并进入渲染队列

每一步都有明确的输入输出和异常处理路径。这比一个"请帮我生成视频"的大而全 Prompt 可靠得多。

6.2 异常恢复与降级策略

真实生产环境里，模型调用可能失败、工具返回可能异常、生成的 JSON 可能解析失败。我们在 Agent 层设计了：

重试机制：对临时性错误进行指数退避重试
降级策略：如果主模型调用失败，切换到备用模型或简化流程
边界控制：当模型输出偏离预期时，通过约束模板和校验规则及时拦截

这些不是 Prompt 本身能解决的，但好的 Prompt 设计会为这些机制留出接口——比如让模型以固定 JSON 格式输出，就是为了后续程序化处理。

七、控制幻觉与讨好倾向

大模型有两个常见毛病：一是胡说八道还一本正经（幻觉），二是倾向于说你想听的（讨好倾向）。作为工程师，不能指望用户每次都火眼金睛，必须在系统层做防控。

7.1 要求依据，而不是要求答案

当你让模型做判断时，不要只问"对不对"，而要问"为什么对"、“依据是什么”。在 RAG 场景里，我们会让模型引用它使用的素材片段；在代码评审场景里，我们会让模型指出具体行号和修改理由。

一个实用技巧是：让模型先列出置信度，再给出结论。 低置信度的输出可以直接进入人工复核队列。

7.2 用中性提问对抗诱导

避免在 Prompt 里夹带倾向性表述。比如不要问"这个方案是不是很好"，而要问"这个方案的优缺点是什么，适用场景和潜在风险分别是什么"。

在涉及评分、排序、比较的任务里，提前定义清晰的评分标准，并让模型逐项说明得分理由。这比一个总体分数更有信息量，也更容易发现偏差。

7.3 多模型交叉验证

对于关键决策，可以让不同模型分别评估，再对结果做一致性检查。这个方法成本高，但在高风险场景（如医疗、金融、安全审核）里值得考虑。

八、多模态提示：文本只是入口

在短视频生成和口播剪辑项目里，我们大量接触了图像、音频、视频与文本的协同。多模态提示有几个值得注意的工程经验。

8.1 图像理解的"整体-细节"偏差

AI 读图时往往先把握整体构图，对局部细节容易遗漏。如果任务依赖细节（比如识别小字、检测图标），可以：

裁剪放大关键区域后单独输入
提供多张不同角度或不同尺度的图片
在 Prompt 中明确指定"请重点描述左上角的文字"

8.2 图像生成的提示词工程

扩散模型对文本描述非常敏感。直接写"一只猫在草地上"，结果可能平平无奇。更好的做法是用一个文本模型先把需求扩写成结构化描述：

主体：什么猫、姿态、表情
场景：草地类型、光线、天气、时间
风格：写实、插画、赛博朋克、宫崎骏动画
镜头：特写、中景、鸟瞰、景深效果

也可以上传参考图，让模型先描述参考图的风格，再把描述作为提示词用于生成。

8.3 视频生成需要"时间维度"的上下文

相比单张图片，视频多了一个时间轴。生成视频脚本或分镜时，Prompt 里要包含：

每个镜头的起止时间
画面过渡方式
音频与画面的对齐点
字幕出现和消失的节拍

我们在方糖猫里把这些问题模板化，让 Agent 分步骤输出分镜表、配音稿、字幕轴，再交给 Remotion + FFmpeg 渲染流水线执行。

九、另一个视角：生成管线里的 Prompt 迭代

如果说 promptkit 展示的是"规范驱动"的 Prompt 工程，那么 GeekCast Engine 的视觉规划 Prompt 展示的是"数据驱动"的迭代路径。两者互补。

9.1 V1：基础版

请为以下口播文案规划视觉元素。

文案：{script}

可选元素：TitleCard, BRoll, QuoteCard, CodeBlock, ListCard, TalkingHead

请输出 JSON 数组。

问题：LLM 输出解释性文字；JSON 格式不稳定；对每种元素的用途理解不一致。

9.2 V2：结构化版

你是一名专业的口播视频剪辑师。请根据文案为每个句子规划视觉元素。

可用元素及定义：
- TitleCard: 章节开头或核心观点强调
- BRoll: 补充说明画面
- QuoteCard: 名言、数据引用
- CodeBlock: 代码展示
- ListCard: 多要点展示
- TalkingHead: 保持说话人画面

文案：{script}

请输出 JSON 数组，每个元素包含 sentence_index, element_type, reason, suggested_content。
不要输出任何解释性文字。

改进：明确角色、定义每个元素、明确输出格式。

仍有问题：复杂文案处理不好；长文案超出 Token 限制。

9.3 V3：分段 + Schema 约束版

你是一名专业的口播视频剪辑师。请根据文案为每个句子规划视觉元素。

[元素定义...]

请输出严格符合以下 JSON Schema 的数组：
{schema}

注意：
1. 不要输出任何解释性文字
2. 每句文案只选择一种最合适的视觉元素
3. 如果句子包含代码或技术术语，优先使用 CodeBlock
4. 如果句子引用名言或数据，优先使用 QuoteCard

文案：{script}

改进：加入 JSON Schema、增加选择规则、配合后端 Pydantic 校验。

9.4 迭代路径总结

flowchart LR
    V1["V1 基础版<br/>格式不稳定"] -->|问题驱动| V2["V2 结构化版<br/>角色+定义+格式"]
    V2 -->|评测驱动| V3["V3 Schema 约束版<br/>规则+后端校验"]
    V3 -->|失败样本回流| EVAL[评测集扩充]
    EVAL --> V4["下一版本..."]

三次迭代的共同规律：每一版都是先在生产/评测中暴露问题，再有针对性地加约束——而不是一开始就写一个"完美"的长 Prompt。这和 promptkit 用 CHANGELOG 记录行为契约变更，是同一个方法论的两面。

十、Prompt 版本管理与加载

10.1 文件组织

prompts/
├── visual_plan/
│   ├── v1.md
│   ├── v2.md
│   └── v3.md
├── storyboard/
│   ├── v1.md
│   └── v2.md
├── query_rewrite/
│   └── v1.md
└── README.md

每个 Prompt 文件头部包含：版本号、适用模型、使用场景、输入变量说明、输出格式要求、变更记录。

10.2 加载与渲染

import os

class PromptManager:
    def __init__(self, base_path="prompts"):
        self.base_path = base_path

    def load(self, name: str, version: str) -> str:
        path = os.path.join(self.base_path, name, f"{version}.md")
        with open(path, "r", encoding="utf-8") as f:
            return f.read()

    def render(self, name: str, version: str, variables: dict) -> str:
        template = self.load(name, version)
        return template.format(**variables)

10.3 常用设计模式速查

模式	适用场景	要点
角色 + 任务 + 格式	结构化输出	最简单，80% 场景够用
Chain-of-Thought	需要推理的复杂任务	显式列出思考步骤
Few-shot	格式复杂或需要风格	示例控制在 2-3 个
动态 Few-shot	有素材库可检索	从 RAG 召回相似示例拼入 Prompt
ReAct	需要工具调用的 Agent 任务	Thought/Action/Observation 循环
模式化规则注入	AI Coding 场景	按 PLAN/ACT 等模式加载不同规则（见第四节）

动态 Few-shot 的实现：

def build_dynamic_prompt(query: str, examples: list[str]) -> str:
    prompt = "以下是几个类似场景的处理示例：\n\n"
    for i, ex in enumerate(examples, 1):
        prompt += f"示例 {i}：\n{ex}\n\n"
    prompt += f"现在请处理：\n{query}"
    return prompt

十一、评估与回归：没有评测集就没有迭代资格

提示工程最难的部分不是写出第一版 Prompt，而是持续知道它在变差，并及时修复。

11.1 评测数据集

收集一批代表性用例，覆盖正常输入、边界输入、异常输入：

[
  {
    "input": "大家好，今天讲 AI 视频生成...",
    "expected": [
      {"sentence_index": 0, "element_type": "TitleCard"},
      {"sentence_index": 2, "element_type": "CodeBlock"}
    ]
  }
]

11.2 分任务定义可量化的指标

不同任务的关注点不同：

任务类型	核心指标
通用生成任务	格式合规率、语义准确率、字段完整率、Token 消耗、平均延迟
RAG 任务	召回率、准确率、回答相关性
Agent 任务	任务完成率、平均步数、异常恢复率

除了技术指标，还要跟踪业务指标。我们在短视频生成平台里跟踪：渲染成功率、用户二次编辑率、单视频平均 Token 成本。这些指标会反过来指导 Prompt 优化方向。

11.3 回归测试脚本

def run_prompt_regression(prompt_version: str, test_cases: list):
    results = []
    for case in test_cases:
        output = llm_call(case["input"], prompt_version)
        parsed = parse_output(output)

        results.append({
            "case_id": case["id"],
            "format_valid": is_valid_format(parsed),
            "semantic_score": compare_with_expected(parsed, case["expected"]),
            "token_count": count_tokens(output),
            "latency": measure_latency()
        })

    return summarize(results)

11.4 合并门禁

每次修改 Prompt 前：

复制当前版本为新版本
在评测集上跑回归测试
对比新版本和旧版本的指标
只有指标不下降才合并

这套流程和代码的 CI 门禁完全同构。promptkit 的 CHANGELOG + 这里的回归脚本，一个管"规则资产"，一个管"生成资产"，合起来才是完整的 Prompt 版本管理。

十二、成本控制：Prompt 也是成本中心

长 Prompt 和高轮次调用都会直接转化为模型费用。优化 Prompt 不只是为了效果更好，也是为了更便宜。

12.1 模型路由

不是所有任务都需要最强的模型：

任务	模型	原因
简单格式提取	DeepSeek-V3 / GPT-3.5	便宜、够快
复杂创意规划	GPT-4 / Claude 3.5	质量高
代码相关任务	Claude 3.5+	代码能力强

promptkit 的 README 里也有同样的分层建议：讨论需求用带搜索的 Chat 工具，规划设计用分析能力强的模型，编码用代码能力强的模型。按阶段选模型，而不是一个模型打全场。

12.2 Prompt 压缩

删除冗余说明
用更短的变量名
Few-shot 示例控制在 2-3 个
长文案先分段，再分别处理

12.3 缓存

def cached_llm_call(query: str, prompt_version: str):
    key = hash(f"{prompt_version}:{query}")
    cached = redis.get(key)
    if cached:
        return cached

    result = llm_call(query, prompt_version)
    redis.setex(key, 3600, result)
    return result

两个注意点：缓存 key 里必须带 prompt_version——Prompt 变了，缓存就必须失效；同样的思路也适用于其他生成产物，比如我们按文案 hash 缓存 TTS 结果，避免重复合成。

十三、踩过的坑

13.1 Prompt 里塞了太多信息

早期一个 Prompt 要同时做意图分析、视觉规划、素材推荐，结果哪一项都做得不好。

解决：拆成多个专门 Prompt，每个只负责一个任务。promptkit 把 PLAN 和 ACT 拆成两套规则文件，是同一件事。

13.2 过度依赖 LLM 做判断

有些规则明确的判断（比如句子长度、是否包含代码关键字），完全可以用代码做，没必要让 LLM 判断。

解决：规则用代码，创意用 LLM。

13.3 没有记录失败案例

线上遇到解析失败的 Prompt 输出，没有系统收集，导致同样的问题反复出现。

解决：建立失败样本库，定期补充到评测集中。promptkit 的 learnings.md 是同一个思想在 AI Coding 场景的落地——让 AI 把自己犯过的错写下来，下次会话先读。

13.4 忽视不同模型的差异

同一个 Prompt 在 DeepSeek 上表现好，在 GPT-4 上可能出问题。

解决：为不同模型维护微调后的 Prompt 版本；评测集要覆盖所有生产用模型。

13.5 让 AI 自己改规范

AI 遇到"规范与实现冲突"时，倾向于悄悄改规范迁就实现。

解决：把规范目录在规则里声明为全模式只读（promptkit 的 ai_work/spec/ 就是这么做的），规范的变更只能由人发起。

13.6 规划与实现脱节

AI 在 PLAN 模式出了漂亮的方案，到了 ACT 模式就自由发挥，交付物和计划对不上。

解决：用交接协议强制——实现必须引用计划中的 step ID，发现计划不可行必须暂停回溯，不允许擅自偏离（见第五节）。

十四、Prompt 工程的核心原则

把 Prompt 当接口设计：输入完整、输出可解析、边界可控，像设计函数签名一样设计 Prompt
把 Prompt 当代码管理：版本控制、CHANGELOG、测试、Review 缺一不可
按加载时机分层：全局规则 / 模式规则 / 只读规范，分开管理注意力预算
上下文要显式化：Memory Bank 这类结构化上下文文件，比依赖会话记忆可靠得多
相关性优先于信息量：无关上下文会稀释注意力，检索结果要重排序，工作记忆要定期清理
流程编码进 Prompt：不要指望 AI 自觉遵守工程流程，把流程画成它必须执行的步骤
复杂任务编排成步骤：用 ReAct 等模式拆解任务、设计异常恢复，而不是一个大 Prompt 包打天下
要求依据，而非答案：让模型给置信度、引用素材、指出行号，低置信度进人工队列
AI 之间的交接要有协议：结构化输出 + ID 追溯 + 暂停回溯机制
简单任务优先用代码：不要让 LLM 做规则能做的事
输出必须可校验：Schema + 后端校验是底线
用数据驱动优化：评测集、技术指标 + 业务指标、回归门禁
收集失败样本：失败案例是最值钱的评测集增量

十五、总结

Prompt Engineering 不是玄学，也不是简单的"提示词技巧"。它至少是三层东西的组合：

graph TD
    L3["工程管理层<br/>版本控制 / CHANGELOG / 评测回归 / 成本路由"]
    L2["系统设计层<br/>规则分层 / Memory Bank / 双模式工作流 / 交接协议 / Agent 编排"]
    L1["文本技巧层<br/>角色设定 / CoT / Few-shot / Schema 约束"]
    L3 --> L2 --> L1

大多数人讨论的"Prompt 技巧"只在最底层打转；真正把 LLM 应用做稳定的团队，都在上两层下功夫：

系统设计层：Prompt 决定 Agent 能做什么、不能做什么，读写权限、模式切换、交接协议、异常恢复都是架构决策
工程管理层：Prompt 是需要版本、测试、评估、变更日志管理的资产，也是直接的成本中心

方糖猫的视觉规划 Prompt 从 V1 到 V3 提升的是单点输出质量；promptkit 用一套规则库约束的是整个 AI 开发流程的行为。两者路径不同，结论一致：Prompt 工程的天花板不在"会不会写提示词"，而在"有没有把它当工程做"。

所以，不要花太多时间寻找"万能 Prompt"。更值钱的能力是：把业务问题拆解成模型能稳定执行的子任务，再用工程化的方法把它变成可交付、可维护的系统。

如果你也在做 LLM 应用开发或 AI Coding 落地，欢迎交流 Prompt 版本管理、规则分层和回归测试的经验。

RAG 本地素材库：从 Embedding 选型到召回调优

Tue, 10 Feb 2026 11:00:00 +0800

RAG 本地素材库：从 Embedding 选型到召回调优

在我开发的方糖猫 AI 视频平台中，一个核心能力是「根据文案自动匹配视频素材」。用户的文案可能是「讲一个关于坚持的故事」，系统需要从本地素材库中找到最契合的画面。我们最终用 RAG（检索增强生成） 的思路搭建了本地素材库。这篇文章会完整复盘从 Embedding 选型到召回调优的全过程。

一、业务背景：为什么需要 RAG？

短视频生成平台里的素材通常有几类：

图片素材：背景图、人物图、概念图
视频片段：B-roll、转场、动画
文案片段：金句、案例、开场白

早期我们用关键词标签做检索，很快就发现几个问题：

标签覆盖不全。一个海边日落镜头，可能被标注为「海」「日落」「风景」「旅行」，但用户文案写的是「人生低谷后的曙光」，关键词完全对不上。
标签质量参差不齐。不同运营人员打的标签不一致，导致召回结果波动大。
无法跨模态匹配。图片素材没有文字描述，靠文件名搜索基本不可用。

RAG 的思路是：用 Embedding 把素材和查询都映射到同一向量空间，通过语义相似度做召回。这样即使关键词不同，只要语义接近，就能被检索出来。

二、系统设计

整个 RAG 素材库分为三个核心环节：

flowchart LR
    subgraph S1["素材入库"]
        A1["原始素材"] --> A2["内容提取"] --> A3["Embedding"] --> A4["ChromaDB"]
    end
    subgraph S2["查询召回"]
        B1["用户文案"] --> B2["Embedding"] --> B3["Top-K 检索"] --> B4["重排"] --> B5["返回结果"]
    end
    subgraph S3["持续更新"]
        C1["新增素材"] --> C2["增量 Embedding"] --> C3["索引更新"]
    end

2.1 素材入库流程

flowchart LR
    A["图片/视频"] --> B["抽帧/缩略图"] --> C["视觉特征提取（CLIP/ResNet）"] --> D["文本描述生成"] --> E["Embedding"] --> F["写入 ChromaDB"]
    G["文本片段"] --> H["清洗/分块"] --> I["Embedding"] --> F

对于图片和视频，我们会：

视频抽帧为关键帧
用多模态模型生成一句话描述
同时保存原始文件路径、文件类型、使用次数等元数据

2.2 查询召回流程

# 简化版召回流程
def retrieve_materials(query: str, top_k: int = 10):
    # 1. 查询向量化
    query_embedding = embedding_model.encode(query)

    # 2. 向量库初筛
    candidates = chroma_collection.query(
        query_embeddings=[query_embedding],
        n_results=top_k * 3,  # 多召回一些，留给重排
        where={"status": "active"}
    )

    # 3. 重排序
    ranked = reranker.rerank(query, candidates)

    # 4. 返回 Top-K
    return ranked[:top_k]

三、Embedding 选型实测

Embedding 模型的选择直接决定召回质量。我们测试了以下几种：

模型	类型	维度	中文语义	多模态	延迟	成本
text-embedding-ada-002	文本	1536	中等	否	快	低
text-embedding-3-small	文本	1536	较好	否	快	低
BGE-M3	文本	1024	优秀	否	中等	本地
OpenAI CLIP	多模态	512	一般	是	中等	中等
中文 CLIP	多模态	512	较好	是	中等	本地

3.1 文本 Embedding 选型

因为我们的查询主要是中文文案，最终选择了 BGE-M3，原因：

中文语义理解能力明显优于 OpenAI 的 Embedding
支持本地部署，无调用成本
向量维度 1024，检索速度和存储成本可接受

3.2 多模态 Embedding 选型

对于图片/视频素材，CLIP 系列可以把视觉内容和文本映射到同一空间。但实测发现：

通用 CLIP 对中文概念的支持较弱
视频场景下，关键帧的质量直接影响召回效果

最终方案：

关键帧用 中文 CLIP 生成视觉 Embedding
同时用图像描述模型生成一句话中文描述，再用 BGE-M3 生成文本 Embedding
向量库中同时存储两种 Embedding，查询时分别召回再融合

四、向量库设计

我们选用 ChromaDB 作为向量存储，主要考虑：

部署简单，适合小团队
支持元数据过滤（按项目、类型、状态筛选）
Python 生态集成好
支持内存模式和持久化模式，开发方便

4.1 Collection 划分

# 按素材类型分 Collection
image_collection = chroma_client.get_or_create_collection("materials_image")
video_collection = chroma_client.get_or_create_collection("materials_video")
text_collection = chroma_client.get_or_create_collection("materials_text")

分 Collection 的好处是查询更聚焦，也方便针对不同类型的素材调优。

4.2 文档结构设计

documents = [{
    "id": "img_001",
    "embedding": image_embedding,
    "metadata": {
        "type": "image",
        "project_id": "proj_123",
        "tags": ["海边", "日落", "风景"],
        "file_url": "oss://ftmao/materials/img_001.jpg",
        "width": 1920,
        "height": 1080,
        "status": "active",
        "usage_count": 12
    },
    "document": "海边日落，宁静的风景画面"  # 用于可读性和调试
}]

五、召回调优实战

5.1 评测数据集构建

召回调优的前提是有评测数据。我们标注了 200 条查询-素材对：

{
  "query": "人生低谷后重新出发",
  "relevant": ["img_001", "img_015", "vid_008"],
  "irrelevant": ["img_099", "vid_045"]
}

评测指标：

Recall@K：相关素材在 Top-K 中的占比
Precision@K：Top-K 中相关素材的占比
MRR：第一个相关素材的平均排名倒数

5.2 Embedding 调优

通过对比实验，我们发现：

方案	Recall@10	Precision@10	MRR
关键词标签	42%	35%	0.18
BGE-M3 文本 Embedding	68%	54%	0.31
BGE-M3 + 中文 CLIP 融合	79%	63%	0.40
+ 重排序模型	86%	71%	0.48

5.3 查询改写

用户的原始查询往往比较抽象，比如「做一个励志视频」。直接用这个查询做向量检索，召回结果会比较散。

我们的做法是让 LLM 先对查询做改写和扩展：

输入：做一个励志视频
输出：
- 核心语义：励志、奋斗、坚持不懈
- 扩展查询：逆境中成长、永不放弃、追逐梦想、突破自我
- 情绪基调：激昂、温暖、希望

然后用扩展后的多个查询分别检索，最后合并结果。这个策略让 Recall@10 提升了约 8%。

5.4 重排序模型

初筛召回 30 个候选后，用轻量级重排序模型做二次排序。我们用的是 bge-reranker-base，原因：

模型小，CPU 推理足够快
对中文语义匹配效果好
可以 fine-tune 适应平台特定素材

六、工程化细节

6.1 索引更新策略

素材库是动态变化的，每天都有新增、删除、状态变更。我们采用：

增量更新：新增素材立即 Embedding 入库
批量补偿：每天晚上全量校验一次，修复漏入/错入
软删除：素材状态改为 inactive，不立即物理删除，便于恢复和审计

6.2 缓存与去重

热门查询的 Embedding 结果会被缓存到 Redis，缓存 key 是查询文本的 hash。同时 TTS 结果也按文案 hash 去重，避免重复调用。

def get_cached_or_compute(query: str):
    key = f"rag:query:{hashlib.md5(query.encode()).hexdigest()}"
    cached = redis.get(key)
    if cached:
        return json.loads(cached)

    result = retrieve_materials(query)
    redis.setex(key, 3600, json.dumps(result))  # 缓存 1 小时
    return result

6.3 多项目隔离

同一个平台可能服务多个创作者或项目，不同项目的素材库需要隔离。我们通过 project_id 元数据过滤实现：

results = collection.query(
    query_embeddings=[embedding],
    n_results=10,
    where={"project_id": "proj_123", "status": "active"}
)

七、踩过的坑

7.1 向量维度不一致

早期我们同时用了 OpenAI Embedding（1536 维）和 BGE-M3（1024 维），混在一个 Collection 里，结果查询时报维度错误。

解决：严格按模型维度分 Collection，每个 Collection 只存同一模型产出的向量。

7.2 关键帧质量影响召回

视频素材如果关键帧选得不好（比如黑屏、转场瞬间），CLIP 生成的 Embedding 会偏离视频真实内容。

解决：

用场景检测算法选取稳定画面
一个视频保存多个关键帧，查询时合并召回
人工抽检低质量素材

7.3 查询过短导致语义漂移

用户查询只有一个词，比如「奋斗」，召回结果可能包含大量不相关但语义宽泛的素材。

解决：

短查询自动扩展为完整句子
提高重排序模型的权重
对短查询增加元数据过滤

八、当前效果与下一步

目前这套 RAG 素材库已经支撑方糖猫平台的核心素材检索能力，覆盖了图片、视频片段、文案片段三类素材。

已验证的收益：

素材召回质量明显高于关键词检索
新素材无需人工打标签即可被检索到
跨项目复用素材变得可行

下一步计划：

引入用户反馈数据，做在线学习优化
针对视频内容做更细粒度的时序检索
探索多模态大模型直接做端到端素材匹配

九、总结

RAG 不只是 LLM 应用的一个热门概念，对于内容生成类平台来说，它是连接用户意图和内容资产的关键基础设施。

几个关键经验：

Embedding 选型要以业务语言为主。中文场景不要迷信 OpenAI，BGE 系列性价比更高。
一定要有评测数据集。没有数据就没有优化方向。
召回 pipeline 通常是多阶段的：初筛 + 重排 + 业务规则过滤。
工程化比算法更重要。索引更新、缓存、隔离、监控，这些决定系统能不能长期稳定运行。

如果你也在做 RAG 相关的项目，欢迎交流 Embedding 选型和召回调优的经验。

Netflix 图搜索的 AI 进化笔记：从结构化 DSL 到自然语言

Mon, 26 Jan 2026 10:00:00 +0800

Netflix 图搜索的 AI 进化笔记：从结构化 DSL 到自然语言

原文：The AI Evolution of Graph Search at Netflix: From Structured Queries to Natural Language（Alex Hutter、Bartosz Balukiewicz，2026-01-26，Graph Search 系列第四篇，前三篇讲平台本身）目标读者：正在做或准备做 Text-to-SQL / Text-to-Query / 企业内自然语言搜索的工程师。阅读目标：搞清楚 Netflix 这套方案里哪些是 LLM 的活、哪些是确定性工程的活，以及为什么这样分工。

一、要解决的问题：用户不想学你的 DSL

先把背景补齐。Netflix 内部的 Content and Business Products 应用群有几百个 UI，常见操作是过滤一张数据表。底层平台是 Graph Search：每个索引由一个 GraphQL query 定义，过滤条件用一套专门的 Graph Search Filter DSL 表达——字段名加比较或包含运算符（如 ==、IN）组成表达式，再用逻辑运算符（如 AND）拼成复杂语句。

问题在于用户和 DSL 之间隔着一层应用 UI：用户点 facet、填查询构建器，应用再把这些交互翻译成 DSL。这条链路有三个毛病，原文列得很坦白：

每个应用的输入组件都是各写各的，体验不一，对 DSL 的支持程度也不一，用户得逐个应用去学怎么用；
有些索引有几百个可过滤字段，领域专家明明知道自己要什么，却被「填一张巨大的表单」这件事拖住；
最根本的一条：用户用自然语言思考，不用查询构建器思考。 强制他们切换上下文，就是引入摩擦。

注意 Netflix 的定位决策：自然语言搜索是增强而不是替换现有应用，把能力做成工具供各应用按自己的领域风格接入。这个定位直接决定了后面「show your work」的设计——后面细说。

二、先把「正确」拆成三层

这篇文章我认为最有价值的部分，是它没有笼统地说「让 LLM 生成正确的查询」，而是把正确性拆成三层，每层用不同的手段治理：

语法正确（syntactic）：生成的语句能按 DSL 文法解析。这层最简单，纯粹是形式问题。
语义正确（semantic）：生成的语句要尊重字段类型、只能用索引里真实存在的字段（不许幻觉）、字段值若受受控词表约束则只能用词表内的值。这层需要对索引本身的了解。
语用正确（pragmatic）：生成的过滤器真的捕捉到了用户意图吗？这层最难——用户搜「Dark」，是指那部德国科幻剧《暗黑》，还是想找「暗黑风格的剧」？

这个三分法的价值在于：前两层可以确定性校验，第三层不能。 原文承认他们没有对语用正确性做校验，也没有找到什么指令能让 LLM 在这层「表现更好」——唯一的手段是把上下文工程做好，再用产品设计兜住。承认 LLM 做不到什么，比宣称能做更重要。

三、上下文工程：双路 RAG 裁剪上下文

LLM 要生成语义正确的过滤语句，必须知道索引里有哪些字段、什么类型、可取什么值。索引由 GraphQL query 定义，所以大部分元数据可以直接从 GraphQL schema 推导：字段名（来自文档路径）、描述（schema 注释）、类型、合法值（enum 或受控词表）。受控词表（controlled vocabulary）是一类特殊字段类型：由领域专家维护的有限值集合，比如国家列表；词表里的每个值有唯一标识、显示名、描述和别名（AKA，例如「romcom」对应「Romantic Comedy」）。

天真的做法是把全部元数据塞进 prompt。简单场景能跑，但不扩展：几百个字段、上千个词表值全塞进去，延迟线性上升，正确率反而下降（大海捞针问题），而且结果变得不稳定。不给值也不行——LLM 会幻觉出不存在的值。于是 Netflix 用经典的 RAG 模式做上下文裁剪，而且是双路的：

flowchart TD
    Q["用户问题<br/>自然语言"] --> CH["分块<br/>重叠切分策略"]
    subgraph FR["字段 RAG"]
        CH --> VS1["向量检索<br/>字段名 描述 类型的 embedding"]
        VS1 --> TOP1["每块取 top K 字段"]
    end
    subgraph CR["受控词表 RAG"]
        CH --> VS2["向量检索<br/>词表值的 embedding<br/>含别名 AKA"]
        VS2 --> TOP2["每块取 top K 词表值<br/>按词表类型去重"]
    end
    TOP1 --> MG["合并 去重"]
    TOP2 --> MG
    MG --> CTX["裁剪后的上下文<br/>字段定义加匹配到的合法值"]
    CTX --> LLM["LLM 加指令生成 DSL"]
    style CTX fill:#fff3cd

两路各有一个容易忽略的设计细节：

字段 RAG 里，用户问题按重叠策略分块，每块独立向量检索取 top K，再合并去重。分块是为了防止长问题里后半截的意图被前半截的 embedding 稀释。
受控词表 RAG 不只是给字段补合法值，还能反向推断字段：问题里命中了某个词表的值，就说明相关字段该进上下文，哪怕字段 RAG 没把它捞出来。词表本身通过 GraphQL 定期拉取重建索引，跟上领域变化。
原文点了一句：RAG 的效果取决于一堆「杠杆」——reranking 策略、分块策略、embedding 模型的选择——系统性评估留给本系列后两篇。这是诚实的写法，也是大部分 RAG 项目真实的工作量所在。

上下文备好后，指令本身反而朴素（大意）：「给定一个自然语言问题，基于以下索引字段及其元数据，生成语法、语义、语用正确的过滤语句。」语法规则写进指令保证第一层；要求 LLM 把生成内容锚定在提供的上下文里保证第二层；第三层只靠上下文工程间接改善。

四、生成之后：确定性校验兜底

LLM 输出不是终点。Netflix 在返回结果前做确定性校验：

语法层：用为这套 DSL 自建的 AST 解析器解析，解析失败即判定生成有问题。原文提到也评估过 LLM 的结构化输出模式，但自定义 DSL 不被原生支持，效果好坏参半，所以还是走了 AST 路线。
语义层：拿生成的 AST 对照索引元数据校验——字段是否存在、类型是否匹配、词表值是否合法。因为 AST 已经解析出来了、元数据在上下文工程阶段就是现成的，这一步几乎不增加延迟。
幻觉处理：检测到幻觉有两个出口——直接把错误返回给用户提示改写，或者把错误反馈给 LLM 自我纠正。后者增加生成耗时，要限制重试次数、谨慎使用。

这套「LLM 生成 + 确定性校验」的分工是全文我最喜欢的设计决策：LLM 负责它擅长的模糊理解，解析器和元数据负责它做不好的精确约束。 校验不通过不是系统失败，是系统正常工作。

五、信任问题：不校验语用，就展示推理

语用正确性没法自动校验，Netflix 的选择是把判断权交还用户，两个手段：

Show your work。 不把裸 DSL 字符串甩给非技术用户，而是把 AST 反射回现有的 UI 组件：LLM 生成 origin.country 等于 Germany，用户看到的「Country」下拉框就被预选成 Germany。用户一眼能看出系统理解得对不对，不对就用熟悉的 UI 控件微调。这个设计把「黑盒生成」变成了「可检查的初稿」——LLM 产出的不是答案，是表单的一次预填。

显式实体消歧（@mentions）。 像 Slack 一样，输入 @ 时从受控词表里直接搜实体，附带上映年份等元数据帮助确认。「When was @dark produced」里的 @dark 被显式锚定到 Series 词表，直接绕过 RAG 推断步骤、把上下文硬编码进去，语用正确性和用户信任同时提升。这是用一点点用户操作换掉一整段不确定的机器推理，非常划算的交换。

端到端架构把上面所有零件串起来，整体上 LLM 只占据中间一环，前后都是确定性工程：

flowchart LR
    U["用户问题<br/>可选 @mentions"] --> PRE["预处理<br/>字段 RAG 加词表 RAG<br/>裁剪上下文"]
    M["@mentions 显式实体"] -.->|"绕过推断<br/>硬编码上下文"| PRE
    PRE --> GEN["LLM 生成<br/>DSL 过滤语句"]
    GEN --> POST["后处理<br/>AST 语法校验<br/>元数据语义校验"]
    POST -->|"检测到幻觉"| FB["报错或反馈重试<br/>限制次数"]
    FB -.-> GEN
    POST --> AST["返回 AST"]
    AST --> UI["映射为 UI 组件<br/>Chips 和 Facets 预填"]
    style GEN fill:#fff3cd
    style POST fill:#e8f5e9

六、工程实践联想

把这篇的方案翻译成日常可搬的经验，五条：

先给「正确」分层，再谈方案。 语法、语义、语用三层各有各的治理手段，混在一起谈「准确率」只会得到一锅粥的指标。做 LLM 应用的第一件事应该是列出你这个场景的正确性分层，然后标注每层谁能负责——解析器、元数据、还是只能交给用户。
上下文是预算，不是仓库。 几百个字段全塞 prompt 导致正确率下降，这个反直觉结论值得记住：RAG 裁剪不只是为了省 token 和延迟，更是为了正确率。给 LLM 的信息应该按「刚好够用」来裁剪，多给是有代价的。
确定性校验是 LLM 应用的承重墙。 AST 解析器加元数据校验几乎零延迟，却能拦下所有幻觉字段。凡是输出有形式结构的场景（SQL、DSL、配置、代码），都应该配一个确定性校验层；LLM 的结构化输出模式可以作为补充，但自定义 DSL 场景下别指望它替代解析器。
把生成结果反射回 UI，是最便宜的信任工程。 不让用户读 DSL，而是预填他们熟悉的表单控件——生成的对错用户一眼可验，错了顺手就改。这比在 prompt 里再雕百分之几的准确率收益大得多。设计 LLM 功能时先问：用户怎么检查这个输出？
留一个显式消歧的旁路。 @mentions 的思路可以泛化：凡是 RAG 推断不确定的地方，看看能不能用一点低成本的用户输入（选择器、@提及、下拉）把不确定性硬消掉。机器推理不该解决所有问题，尤其是那些用户举手之劳就能解决的问题。

本篇小结

问题：Netflix 内部几百个应用靠 Graph Search Filter DSL 过滤数据，用户被迫逐应用学习查询构建器；自然语言搜索的目标是把「用户学 DSL」反转成「系统懂自然语言」。
框架：正确性拆成语法、语义、语用三层。语法靠 DSL 文法，语义靠索引元数据，语用没有自动校验手段，靠上下文工程加产品设计兜住。
机制：双路 RAG 做上下文裁剪——字段 RAG 按元数据 embedding 检索 top K 字段，受控词表 RAG 检索合法值并能反推字段；指令要求 LLM 锚定上下文生成 DSL。
兜底：AST 解析器做语法校验，元数据做语义校验，幻觉可报错或有限次反馈重试；结构化输出模式评估过但对自定义 DSL 效果参半。
信任：AST 反射回 UI 组件做「show your work」，@mentions 让用户显式锚定实体、绕过 RAG 推断。
分工原则：LLM 只做中间一环的模糊理解，预处理和后处理全是确定性工程——这是全文最值得抄的架构判断。
留白：RAG 杠杆的调优、生产环境评估、NER、意图路由、查询改写都留给系列后两篇，值得跟进。

参考资料

The AI Evolution of Graph Search at Netflix: From Structured Queries to Natural Language（本文，2026-01-26）
Netflix Graph Search 系列前三篇（part 1、2、3，讲平台本身的联邦数据搜索架构，原文开头有链接）
GraphQL schema 内省文档（字段元数据推导的来源）

《AI 工程》学习笔记（下）：RAG、Agent、微调、推理优化与应用架构

Sat, 13 Dec 2025 14:00:00 +0800

《AI 工程》学习笔记（下）：RAG、Agent、微调、推理优化与应用架构

这是 Chip Huyen《AI 工程》读书笔记的下篇，覆盖第 6-10 章。上篇讲了基础模型、评估和提示工程（见《AI 工程》学习笔记（上）），这篇进入"重型"话题：RAG、Agent、微调、数据工程、推理优化，最后收拢到完整的应用架构。

如果说上篇的主题是"怎么知道模型干得好不好"，下篇的主题就是"怎么让它在真实世界里又快又稳地干活"。

一、RAG：先检索，后生成

1.1 为什么 RAG 是第一个要掌握的模式

模型的知识有两个硬限制：上下文窗口装不下（整个代码库、几百本书），以及训练截止后的事情不知道。RAG（检索增强生成）用"开卷考试"的思路同时解决两个问题：

flowchart LR
    subgraph 离线["离线索引（写路径）"]
        DOC[文档库] --> CHUNK[切分 Chunking]
        CHUNK --> EMB[Embedding 向量化]
        EMB --> VDB[(向量数据库<br/>+ BM25 倒排索引)]
    end
    subgraph 在线["在线查询（读路径）"]
        Q[用户问题] --> QE[查询向量化]
        QE --> RET[检索<br/>top-k 相关片段]
        RET --> RER[可选: 重排序 Rerank]
        RER --> GEN["LLM 生成<br/>问题 + 检索片段 → 回答"]
    end
    VDB --> RET

作者的一个重要判断：RAG 系统的成败在检索器，不在生成器。检索不到正确材料，生成模型只能"基于错误的证据一本正经地编"。上篇那个合同审查案例就是活例子。

1.2 两派检索算法

	词项检索（BM25/Elasticsearch）	向量检索（Embedding）
原理	词面匹配 + 词频统计	语义相似度
强项	精确词命中（型号、ID、专有名词）、轻量、可解释	同义改写、跨语言、模糊查询
弱项	“汽车"搜不到"轿车”	精确 ID 反而可能搜偏
成本	极低	索引/查询都要算 embedding

实战结论是混合检索（hybrid search）：BM25 和向量检索各跑一遍，按 RRF（Reciprocal Rank Fusion）之类的方法融合排序。词项检索是非常强的 baseline，书里的建议是先用 BM25 起步，验证检索确实是瓶颈后再上向量检索，而不是反过来。

1.3 踩坑记录

踩坑 1：chunk 一刀切。 按固定 500 token 切分，把表格拦腰切断、把"问题"和"答案"切进不同 chunk，检索回来全是语义残缺的碎片。改法：按文档结构切（标题层级、段落边界），代码按函数/类边界切，表格整存。chunk 之间留 10%-20% 重叠（overlap），缓解边界处上下文丢失。

踩坑 2：只评估端到端，不看召回率。 RAG 至少要分开盯两个指标：检索的 top-k 召回率（正确片段在不在结果里）和生成的忠实度（回答有没有超出检索内容瞎编）。前者低改检索，后者低改 prompt 或模型——混为一谈就会像无头苍蝇。

踩坑 3：元数据过滤用晚了。 知识库里混着 2020 年和 2025 年的制度文档，用户问"年假几天"，检索回来旧制度。给 chunk 打上时间、部门、文档类型等元数据，检索时先过滤再排序，比换更大的 embedding 模型有效得多。

成功案例：我们给一个内部知识库做问答，初期纯向量检索，员工搜报销系统名称"易快报"时召回很差（专有名词语义模糊）。加上 BM25 混合检索后这类 query 的召回率从 61% 提到 93%，整体满意度显著提升。教训：语义检索不是万能升级，词面匹配在专有名词场景不可替代。

二、Agent：让模型当规划者

2.1 从 RAG 到 Agent：一脉相承

书里有个很妙的视角：RAG 是 Agent 的特例——检索器只是模型可用的一件工具。推而广之，给模型配上更多工具（搜索、计算器、数据库、代码执行、API），让它自己规划"先做什么、再做什么"，就成了 Agent。

flowchart TB
    GOAL[任务目标] --> PLAN["规划 Planning<br/>模型分解任务、生成步骤"]
    PLAN --> ACT["执行 Action<br/>调用工具"]
    ACT --> OBS["观察 Observation<br/>读取工具返回"]
    OBS --> REFLECT{"反思 Reflection<br/>结果对吗？目标达成了吗？"}
    REFLECT -- 继续 --> PLAN
    REFLECT -- 完成 --> OUT[最终输出]
    subgraph MEM["记忆系统 Memory"]
        M1[短期: 对话/执行历史]
        M2[长期: 向量库/知识库]
    end
    PLAN -.读取/写入.-> MEM

Agent 由三要素定义：环境（它感知和操作的世界）、工具（它能调用的动作集）、规划能力（模型分析任务、选路径的脑力）。规划是瓶颈——复杂任务需要多步推理，模型的规划能力决定了 Agent 的上限，所以 Agent 类应用对模型能力最敏感。

2.2 失败模式与工程约束

书里对 Agent 的警告很直接：自动化程度越高，失败越灾难性。典型失败模式：

规划错误：任务分解就错了，后面越努力越离谱；
工具调用错误：参数编错、调错工具、幻觉出不存在的 API；
循环失控：反复重试同一个失败动作，token 烧光任务没进展；
复合错误：单步准确率 95% 看着不错，10 步下来整体成功率只有 0.95¹⁰ ≈ 60%。

对应的工程约束（都是血泪换来的常识）：

# 1. 硬性步数上限，防止失控循环
MAX_STEPS = 15

# 2. 每次循环检查预算（步数/token/钱）
for step in range(MAX_STEPS):
    if budget.exceeded():
        return fallback_answer("任务超出预算，转人工处理")
    action = plan_next(state)
    result = execute(action)
    state.update(action, result)

# 3. 不可逆操作（发邮件、删数据、支付）必须人工确认
if action.risk_level == "high":
    require_human_approval(action)

失败案例：某团队的客服 Agent 有"查询订单"和"退款"两个工具。一次上游 LLM 提供商抖动了几次超时，Agent 把超时误判为"查询失败"，触发了它的兜底逻辑——居然直接走了"退款"流程安抚用户。一晚上误退几十单。教训有三：工具的失败语义要精确（超时 ≠ 业务失败）、写操作必须和读操作分级管理、Agent 的所有写操作要留可审计日志。

感悟：Agent 的工程本质是"给概率系统装刹车"。演示 Demo 里 Agent 行云流水，是因为 Demo 只跑了成功路径。生产化的工作量 80% 在失败路径上。

三、微调：什么时候才轮到你上场

3.1 微调 vs RAG：决策树

这是被问得最多的问题，书里给的思路可以画成决策树：

flowchart TB
    Q1{"模型缺的是<br/>知识还是行为？"}
    Q1 -- "缺知识<br/>（不知道你公司的产品、最新政策）" --> RAG["选 RAG<br/>知识更新快、可溯源"]
    Q1 -- "缺行为<br/>（知识够，但格式/风格/领域表达不对）" --> Q2{"提示工程 + few-shot<br/>能教会吗？"}
    Q2 -- 能 --> PE["停在提示工程<br/>最便宜、迭代最快"]
    Q2 -- 不能 --> FT["微调 Finetuning"]
    Q1 -- "都缺" --> BOTH["RAG + 微调组合<br/>常见的企业方案"]

一句话记忆：RAG 给模型"资料"，微调教模型"习惯"。需要频繁更新的知识走 RAG（改数据库就行）；稳定的领域行为（医疗报告的书写规范、固定输出格式）走微调。

不微调的理由同样重要：微调需要高质量标注数据（最难的部分）、引入模型管理复杂度、基础模型升级后可能要重训、还可能损害模型的通用能力（灾难性遗忘）。

3.2 PEFT 与 LoRA：微调的平民化

全参数微调动辄几百 GB 显存，普通团队玩不起。于是有了一类叫 PEFT（Parameter-Efficient Fine-Tuning，参数高效微调） 的技术：共同思路是冻结绝大部分原模型权重，只训练一小撮新增或挑选出来的参数。家族成员包括 Adapter（在层间插小模块）、Prefix/Prompt Tuning（只学一段可训练的"软提示"向量）等，其中目前最主流、事实标准的是 LoRA。

LoRA（Low-Rank Adaptation）的思路是：冻结原模型权重，只训练一对低秩矩阵来近似权重的变化量 ΔW ≈ A·B：

flowchart LR
    X[输入 x] --> W["原始权重 W<br/>（冻结，不训练）"]
    X --> A["低秩矩阵 A<br/>（可训练）"]
    A --> B["低秩矩阵 B<br/>（可训练）"]
    W --> SUM((+))
    B --> SUM
    SUM --> Y[输出 y = Wx + BAx]

好处实打实：

可训练参数量降到 0.1%-1%，显存需求砍掉一个数量级；
模块化：一个基础模型可以挂多个 LoRA"插件"——客服一个、营销一个，推理时按需加载，不用每个场景部署一份完整模型；
推理时可以把 LoRA 权重合并回主干，零额外延迟。

踩坑 4：LoRA rank 不是越大越好。 新手直觉是 rank 越大容量越大，但数据量撑不住时，大 rank 只会过拟合得更快。常见起点是 rank=8-16，配合几百到几千条高质量数据，往往比 rank=128 + 脏数据强。微调的效果上限在数据质量，不在参数量——这直接引出了下一章。

3.3 LoRA 的数学原理：手算一遍就懂了

① 前向传播的公式。 设原始权重 $W \in \mathbb{R}^{d \times d}$（冻结），LoRA 用一对小矩阵乘积来近似权重的变化量：

$$ \Delta W = BA, \quad B \in \mathbb{R}^{d \times r},\ A \in \mathbb{R}^{r \times d},\ r \ll d $$

前向计算变成：

$$ y = Wx + BAx = (W + BA)x $$

参数量对比一目了然：全参数微调要学 $d^2$ 个数（$d=4096$ 时约 1677 万）；LoRA 只学 $2dr$ 个（$d=4096, r=16$ 时约 13.1 万，占 0.8%）。省显存的真正大头其实不在参数本身，而在优化器状态：冻结的 $W$ 没有梯度，Adam 也就不必为它存两份和权重一样大的动量张量——全参数微调时那才是真正吃显存的部分。

② 为什么"低秩"够用。 直觉是：预训练已经把模型放在了一个很好的解附近，微调只需要在少数几个方向上做修正，而不是对 $d^2$ 维空间做任意改动。LoRA 论文的实验支持这一点——权重增量的内在秩（intrinsic rank）很低，rank 取 1、2 在很多任务上就能接近全参数微调的效果。$r$ 就是"允许修改的子空间维数"：$r=1$ 时 $\Delta W$ 的所有列都是 $B$ 的倍数，只能表达"沿一个方向拉伸"；$r$ 越大，能表达的修正模式越丰富。

两个工程细节：初始化时 $A$ 用随机高斯、$B$ 全零，这样训练起点 $BA=0$，模型行为和原模型完全一致；实际实现里增量还会乘缩放系数 $\alpha/r$（$\alpha$ 是超参），让换 rank 时不用重调学习率。

③ 手算：一个 $2 \times 2$ 的完整训练步。 取 $d=2, r=1$，冻结权重设为单位阵，输入 $x = [1, 2]^T$，目标输出 $y^* = [0, 0]^T$。假设 $A = [1, 1]$（$1 \times 2$）、$B = [1, 1]^T$（$2 \times 1$），都只有 2 个可训练参数：

$$ W = \begin{bmatrix} 1 & 0 \\ 0 & 1 \end{bmatrix}, \quad A = \begin{bmatrix} 1 & 1 \end{bmatrix}, \quad B = \begin{bmatrix} 1 \\ 1 \end{bmatrix} $$

前向：先算 $A$ 再算 $B$（注意顺序，别先乘出 $\Delta W$，那是 $d \times d$ 的大矩阵，先算 $Ax$ 只需 $O(dr)$）：

$$ Ax = 1 \times 1 + 1 \times 2 = 3, \quad BAx = B \cdot 3 = \begin{bmatrix} 3 \\ 3 \end{bmatrix}, \quad y = Wx + BAx = \begin{bmatrix} 1 \\ 2 \end{bmatrix} + \begin{bmatrix} 3 \\ 3 \end{bmatrix} = \begin{bmatrix} 4 \\ 5 \end{bmatrix} $$

损失：$L = \frac{1}{2} |y - y^*|^2 = \frac{1}{2}(4^2 + 5^2) = 20.5$。

反向：令 $g = y - y^* = [4, 5]^T$，即 $\partial L / \partial y$。梯度沿链路只流向 $A$ 和 $B$，$W$ 不参与：

$$ \frac{\partial L}{\partial A} = B^T g \cdot x^T = \big([1,1] \cdot [4,5]^T\big) \cdot [1,2] = 9 \times [1, 2] = \begin{bmatrix} 9 & 18 \end{bmatrix} $$

$$ \frac{\partial L}{\partial B} = g \cdot (Ax) = \begin{bmatrix} 4 \\ 5 \end{bmatrix} \times 3 = \begin{bmatrix} 12 \\ 15 \end{bmatrix} $$

更新（学习率 $\eta = 0.1$）：

$$ A_{\text{new}} = \begin{bmatrix} 1 & 1 \end{bmatrix} - 0.1 \begin{bmatrix} 9 & 18 \end{bmatrix} = \begin{bmatrix} 0.1 & -0.8 \end{bmatrix}, \quad B_{\text{new}} = \begin{bmatrix} 1 \\ 1 \end{bmatrix} - 0.1 \begin{bmatrix} 12 \\ 15 \end{bmatrix} = \begin{bmatrix} -0.2 \\ -0.5 \end{bmatrix} $$

再走一遍前向验证：

$$ A_{\text{new}}x = 0.1 \times 1 + (-0.8) \times 2 = -1.5, \quad B_{\text{new}}A_{\text{new}}x = \begin{bmatrix} -0.2 \\ -0.5 \end{bmatrix} \times (-1.5) = \begin{bmatrix} 0.3 \\ 0.75 \end{bmatrix}, \quad y_{\text{new}} = \begin{bmatrix} 1.3 \\ 2.75 \end{bmatrix} $$

新损失 $L_{\text{new}} = \frac{1}{2}(1.3^2 + 2.75^2) \approx 4.63$。一步梯度下降，损失从 20.5 降到 4.63，全程没碰过 $W$ 的一个元素——这就是 LoRA 训练的全部。

④ 推理时合并。 部署时把增量并回主干：

$$ \Delta W = B_{\text{new}}A_{\text{new}} = \begin{bmatrix} -0.2 \\ -0.5 \end{bmatrix} \begin{bmatrix} 0.1 & -0.8 \end{bmatrix} = \begin{bmatrix} -0.02 & 0.16 \\ -0.05 & 0.4 \end{bmatrix}, \quad W_{\text{merged}} = W + \Delta W = \begin{bmatrix} 0.98 & 0.16 \\ -0.05 & 1.4 \end{bmatrix} $$

验证：$W_{\text{merged}} x = [0.98 + 0.32,\ -0.05 + 2.8]^T = [1.3,\ 2.75]^T$，和上面分开算的结果完全一致。合并后就是一个普通矩阵乘法，零额外推理延迟就是这么来的。

（这个玩具例子里 LoRA 是 4 个参数、全参数也是 4 个，省不了——节省只在 $r \ll d$ 的大矩阵上出现。）

四、数据工程：质量、覆盖、数量

第 8 章是全书最"脏活累活"的一章，也是我最推荐反复读的一章。数据集设计三准则：

flowchart TB
    D[数据集三准则] --> Q["质量 Quality<br/>标注准确、格式一致、无噪声"]
    D --> C["覆盖 Coverage<br/>覆盖真实场景的多样性<br/>含边界情况和失败样例"]
    D --> N["数量 Quantity<br/>够用即可，边际收益递减"]
    Q -.->|"少量高质量 > 大量噪声"| LESSON["核心教训"]
    C -.-> LESSON
    N -.-> LESSON

几个反直觉的要点：

少量高质量数据胜过大量噪声数据。LIMA 等研究表明，1000 条精心策划的指令数据可以让模型行为对齐得相当好；
合成数据是主力补给，但必须评估。用大模型生成训练数据已经是标准操作（比如用 GPT-4 造指令数据微调小模型，即蒸馏），但"AI 生成的数据"和"AI 生成的内容"一样需要评估把关。人们更倾向于使用自己能可靠评估的合成数据；
最难的不是标注，是写标注规范。“什么叫好答案"没想清楚的团队，标注出来的数据就是标注员个人偏好的大杂烩。

踩坑 5：合成数据近亲繁殖。 用模型 A 生成数据训练模型 B，再用 B 生成数据训练 C…… 几轮下来多样性塌陷，模型只会说"AI 腔”。书外研究（model collapse）也印证了这点。对策：合成数据里持续掺真实数据、定期用多样性指标（如 n-gram 去重率）体检。

成功案例：一个做 SQL 生成的朋友团队，微调数据从"网上爬的 5 万条 SQL 问答"换成"自己业务库表结构 + 人工审核的 3000 条"，效果反而大幅提升。爬虫数据里大量通用示例和他们的业务 schema 无关甚至冲突。覆盖你的真实分布，比堆量重要得多。

五、推理优化：先懂指标，再谈优化

5.1 延迟的两段式结构

自回归生成决定了延迟不是单一数字：

sequenceDiagram
    participant U as 用户
    participant S as 推理服务
    U->>S: 发送 prompt
    S->>S: Prefill 预填充阶段<br/>并行处理全部输入 token
    S-->>U: 第一个 token (TTFT)
    loop Decode 解码阶段（逐 token 串行）
        S-->>U: 第 2, 3, ... N 个 token (间隔 = TPOT)
    end

TTFT（Time To First Token）：首 token 延迟，由 prefill 阶段决定。长 prompt 的应用（塞了一大段检索内容的 RAG）TTFT 高；
TPOT（Time Per Output Token）：每个输出 token 的间隔，由 decode 阶段决定。长输出的应用（写报告）对 TPOT 敏感；
吞吐量和延迟存在权衡：batch 开大吞吐高、单价低，但单请求延迟上升。

实战含义：流式输出（streaming）是最便宜的"延迟优化"——总时长没变，但用户感知延迟从"整个生成时间"变成了 TTFT。聊天场景不流式输出基本不可接受。

5.2 优化手段地图

flowchart TB
    OPT[推理优化] --> MO["模型级优化<br/>（会改变模型本身）"]
    OPT --> SO["服务级优化<br/>（模型不动，改服务方式）"]
    MO --> Q[量化 Quantization<br/>FP16→INT8/INT4，省显存提速]
    MO --> D[蒸馏 Distillation<br/>大模型教小模型]
    MO --> KV[KV Cache 管理<br/>注意力机制优化]
    SO --> B[连续批处理<br/>Continuous Batching]
    SO --> PC[Prompt 缓存<br/>相同前缀不重算]
    SO --> P[并行策略<br/>张量并行 / 副本并行]
    SO --> PD[Prefill/Decode 分离部署]

对应用开发者（主要用 API 的人）最相关的两条：

① Prompt 缓存（prompt caching）。多轮对话或固定长 system prompt 的场景，重复的前缀不用重复算，省钱省延迟。Anthropic/OpenAI 的 API 都已支持，但要注意缓存按前缀匹配——把变化的内容（时间戳、用户问题）放在 prompt 尾部，稳定内容放头部，否则缓存命中率是零。

踩坑 6：我们就犯过这个错——system prompt 开头嵌了当前时间，每请求都变，prompt cache 从没命中过。把动态部分挪到末尾后，长 system prompt 场景的成本降了约 40%。

② 量化是性价比之王。书里总结"跨场景最有效的技术通常是量化"——INT8 几乎无损，INT4 轻微掉点但显存减半以上。自托管时先用上量化再谈别的。

六、收拢：完整的 AI 应用架构

第 10 章把前面所有技术拼成一张图。一个生产级生成式 AI 应用的典型架构：

flowchart TB
    U[用户] --> GW["模型网关 Model Gateway<br/>认证 / 限流 / 路由 / 审计"]
    GW --> GR1["输入护栏<br/>注入检测 / 敏感词 / PII 脱敏"]
    GR1 --> CTX["上下文增强<br/>RAG 检索 / 记忆 / 用户画像"]
    CTX --> CACHE{"缓存命中？"}
    CACHE -- 是 --> RESP
    CACHE -- 否 --> ROUTER["模型路由<br/>简单问题→小模型<br/>复杂问题→大模型"]
    ROUTER --> LLM[基础模型<br/>+ LoRA 插件]
    LLM --> GR2["输出护栏<br/>事实核查 / 格式校验 / 安全过滤"]
    GR2 --> RESP[响应]
    RESP --> FB["用户反馈采集<br/>点赞/点踩/会话信号"]
    FB --> OBS["可观测平台<br/>指标 / 告警 / 追溯"]
    OBS -.数据飞轮.-> CTX

这张图是按"增量搭建"的顺序理解的——作者的 step-by-step 思路非常实用：

先增强上下文（RAG/记忆），解决"模型不知道"；
加护栏，解决"模型乱说"，护栏可以在输入侧、输出侧，或独立服务；
加网关和路由，解决"多模型管理"：简单 query 走便宜小模型，复杂的走大模型，省钱；
加缓存降延迟降成本；
最后才加 Agent 模式，解决"模型不会做"——这是复杂度最高的一步，放最后。

6.1 可观测性与用户反馈

可观测性的核心问题是"理解系统怎么失败的"。LLM 应用的新失败模式（幻觉、注入、格式漂移）要求新指标：除了传统的延迟/错误率，还要跟踪忠实度评分、护栏拦截率、judge 分数趋势、token 成本曲线。日志里要存完整的 prompt 和上下文，否则 bad case 根本无法复盘。

用户反馈是被工程师系统性低估的金矿。点赞点踩、追问、复制回答、重新生成……这些会话信号是迭代评估集和微调数据的免费来源——这就是数据飞轮：

flowchart LR
    P[产品上线] --> U[用户使用]
    U --> F[反馈信号采集]
    F --> E[回流评估集<br/>发现 bad case]
    E --> I[迭代 prompt/检索/模型]
    I --> P

作者因此说"AI 工程比 ML 工程离产品更近"——反馈机制设计传统上是产品的事，但它是模型改进的数据源头，工程师必须介入。

感悟：这张图最值得记住的不是组件本身，而是搭建顺序。见过太多项目第一天就上 Agent + 多模型路由，结果复杂度爆炸、没人知道错误来自哪一层。每加一个组件，系统能力 +1，但失败模式 +N。够用就好，是 AI 架构的第一美德。

七、思考与感悟（下篇）

检索、工具、微调，本质都是"上下文管理"。 RAG 是把外部知识塞进上下文，工具是把能力塞进上下文，微调是把行为烙进权重。选哪种取决于：变化的频率（天天变→RAG，稳定→微调）、成本（上下文 token 费 vs 训练费）、可靠性要求。
复杂度是敌人，按失败模式的"价格"出牌。 每章读完都有一个共同感受：作者永远在问"这个技术的失败模式是什么"。RAG 的失败在检索，Agent 的失败在规划复合错误，微调的失败在数据，judge 的失败在漂移。工程技术选型 = 选择你承受得起的那种失败。
数据飞轮是唯一持久的护城河。 模型会商品化，框架会趋同，但"真实用户反馈 → 评估集 → 迭代"这个循环积累下来的数据和评估体系，别人抄不走。
先把指标立住，再谈优化。 TTFT/TPOT/召回率/忠实度这些指标的意义在于：它们把"感觉变慢了"“感觉变笨了"变成可以定位、可以回归的数字。没有指标体系的优化都是玄学。

八、面试高频题（下篇）

Q1：RAG 和微调怎么选？ 看缺什么：缺知识选 RAG（更新快、可溯源、成本低）；缺行为/格式/风格选微调；都缺就组合。实践顺序：先提示工程，再 RAG，最后微调——按投入产出排序。补充：微调需要高质量标注数据，且可能损害通用能力。

Q2：RAG 效果差，你的排查顺序是什么？ 组件级评估：① 单独测检索召回率——正确片段在不在 top-k；不在则查 chunking、混合检索、元数据过滤、查询改写；② 召回没问题再测生成忠实度——回答是否忠于检索内容；不忠实则改 prompt、加引用约束或换模型。③ 全程保留 bad case 进评估集。

Q3：词项检索和向量检索各自的适用场景？ 词项检索（BM25）：精确匹配强（ID、型号、专有名词）、轻量可解释，但不理解语义；向量检索：同义改写、模糊查询强，但精确词可能搜偏、成本高。生产上常用混合检索 + 融合排序。

Q4：Agent 的单步准确率 95%，为什么 20 步任务成功率不到 40%？怎么改进？ 错误复合：0.95²⁰ ≈ 36%。改进：缩短链路（任务分解更粗粒度）、加反思与自我纠错、关键步骤验证后再继续、步数/预算上限、高风险动作人工确认、提升单步可靠性（更好的工具描述与参数校验）。

Q5：LoRA 的原理是什么？为什么受欢迎？ 冻结原权重，用低秩分解 ΔW≈A·B 学习权重增量，可训练参数降到 1% 量级。优点：显存省一个数量级；数据效率高；模块化——一个基座挂多个 LoRA 插件按需加载；可合并回主干零额外推理开销。

Q6：TTFT 和 TPOT 的区别？各自受什么影响？怎么优化？ TTFT 由 prefill 决定，受 prompt 长度影响——优化：prompt 缓存、压缩上下文、流式输出改善感知；TPOT 由 decode 决定，逐 token 串行——优化：连续批处理、量化、投机解码、更好的硬件利用率。两者存在吞吐-延迟权衡。

Q7：怎么设计一个 AI 应用的护栏体系？ 分层：输入护栏（注入检测、PII 脱敏、话题边界）、生成约束（结构化输出、引用检索内容）、输出护栏（事实核查、安全过滤、格式校验）、动作护栏（工具最小权限、高危操作人工确认）。护栏可放在网关、推理服务或独立组件，关键指标是拦截率和误杀率。

Q8：模型网关（Model Gateway）解决什么问题？ 统一入口做认证、限流、审计、多模型路由（简单问题走小模型省钱）、故障转移（provider 挂了就切换）、缓存。类比微服务里的 API Gateway——当系统里有多个模型、多个 provider 时，它把横切关注点从业务代码里收走。

全书写在最后

把两篇笔记浓缩成一句话：AI 工程 = 用评估驾驭概率，用上下文注入知识，用架构吸收失败。

这本书值得放在手边反复翻。技术细节会过时（明年 Agent 框架肯定又换了一轮），但书里那些思维框架——组件级评估、失败模式分析、先简单后复杂的搭建顺序、数据飞轮——是长期有效的工程直觉。

LangChain 入门笔记：AI 视频生成实战

Fri, 28 Nov 2025 11:00:00 +0800

LangChain 入门笔记：AI 视频生成实战

最近重新刷了吴恩达和 Harrison Chase 主讲的《LangChain for LLM Application Development》。这门课不长，但把 LangChain 的"为什么存在"讲得很透：它不是让你写更多胶水代码，而是把 LLM 调用、提示工程、上下文管理、工具调用这些重复模式抽象成可组合的组件。这篇文章整理课程里的核心原理，并落到我们最熟悉的 AI 视频生成场景，给出可直接跑的 Demo。

一、LangChain 解决什么问题？

在直接调用 OpenAI / Claude / 国产大模型 API 时，我们通常会写出这样的代码：

import openai

messages = [
    {"role": "system", "content": "你是一位短视频脚本专家。"},
    {"role": "user", "content": "主题是'如何用 LangChain 生成视频脚本'，风格轻松，30 秒左右。"}
]
resp = openai.chat.completions.create(model="gpt-4o", messages=messages)
script = resp.choices[0].message.content

这段代码能跑，但问题很明显：

提示词散落在各处，难以复用和版本管理；
输出是字符串，需要手写解析逻辑；
多轮对话、上下文记忆要自己拼 messages；
一旦涉及"检索素材 → 生成脚本 → 检查合规 → 输出结构化数据"，代码就会迅速膨胀成面条。

LangChain 的核心思想：把 LLM 应用里的常见模式抽象成标准组件，让你像搭积木一样拼装工作流。

可以把它理解成：

LangChain = 模型接口统一层 + 提示模板 + 输出解析 + 记忆 + 链式调用 + 工具/Agent 编排

二、课程核心内容回顾

吴恩达这门课围绕 6 个模块展开，也是 LangChain 最基础的 6 个能力：

模块	作用	视频生成场景映射
Models	统一不同 LLM 的调用接口	切换 GPT-4o / Claude / 国产模型时无需改业务代码
Prompts	模板化管理提示词	脚本生成、分镜描述、标题优化的模板复用
Output Parsers	把自然语言输出转成结构化数据	解析 JSON 分镜、时间轴、素材清单
Memory	维护多轮对话状态	用户反复修改脚本时保留上下文
Chains	把多个 LLM/工具步骤串成链	“主题 → 大纲 → 脚本 → 分镜 → 渲染参数"流水线
Agents	让 LLM 决定调用哪些工具	Agent 自主判断需要检索素材还是生成画面描述

下面逐一看原理和代码。

三、核心组件原理与示例

3.1 Models & Prompts：统一接口与模板复用

LangChain 用 ChatOpenAI、ChatAnthropic 等类封装模型，并用 ChatPromptTemplate 管理提示词模板。

from langchain_openai import ChatOpenAI
from langchain_core.prompts import ChatPromptTemplate

llm = ChatOpenAI(model="gpt-4o", temperature=0.7)

prompt = ChatPromptTemplate.from_messages([
    ("system", "你是一位短视频脚本专家，擅长把技术概念写成{style}风格的口播脚本。"),
    ("human", "主题是：{topic}，时长控制在{duration}秒，需要{scene_count}个分镜。")
])

messages = prompt.invoke({
    "style": "轻松幽默",
    "topic": "LangChain 如何自动生成视频脚本",
    "duration": 30,
    "scene_count": 3
})

response = llm.invoke(messages)
print(response.content)

好处：

提示词与业务数据解耦，模板可复用、可版本化；
切换模型只需改一行 ChatOpenAI → ChatAnthropic；
支持批量 batch、流式 stream、异步 ainvoke 等高级调用方式。

3.2 Output Parsers：从文本到结构化数据

视频生成流程需要结构化输出，例如：

{
  "scenes": [
    {"time": "0-10s", "narration": "...", "visual": "...", "bgm": "..."}
  ],
  "title": "...",
  "tags": ["..."]
}

LangChain 提供 PydanticOutputParser，让模型按指定 Schema 输出。

from pydantic import BaseModel, Field
from langchain_core.output_parsers import PydanticOutputParser
from langchain_core.prompts import PromptTemplate

class Scene(BaseModel):
    time_range: str = Field(description="时间区间，如 0-10s")
    narration: str = Field(description="口播文案")
    visual: str = Field(description="画面描述，用于后续生成图片/视频")
    bgm_mood: str = Field(description="背景音乐情绪")

class VideoScript(BaseModel):
    title: str
    scenes: list[Scene]
    tags: list[str]

parser = PydanticOutputParser(pydantic_object=VideoScript)

prompt = PromptTemplate(
    template="根据主题生成短视频脚本。\n{format_instructions}\n主题：{topic}\n时长：{duration}秒\n",
    input_variables=["topic", "duration"],
    partial_variables={"format_instructions": parser.get_format_instructions()},
)

chain = prompt | llm | parser
result = chain.invoke({"topic": "LangChain 自动生成短视频", "duration": 30})
print(result.model_dump_json(indent=2))

注意：LLM 不一定 100% 返回合法 JSON，生产环境建议加 RetryOutputParser 或兜底解析。

3.3 Memory：多轮修改不再"失忆”

做视频脚本时，用户常会说：“前面不错，但把第二段改得更口语化一点”。没有记忆，LLM 会从头生成，丢失已确认的片段。

from langchain.memory import ConversationBufferMemory
from langchain.chains import ConversationChain

memory = ConversationBufferMemory()
conversation = ConversationChain(llm=llm, memory=memory)

conversation.predict(input="帮我写一个 30 秒的 LangChain 短视频脚本")
conversation.predict(input="第二段太正式了，改成口语化一些")
print(memory.load_memory_variables({}))

LangChain 还提供 ConversationBufferWindowMemory（只保留最近 N 轮）、ConversationSummaryMemory（摘要历史）等，适用于长会话场景。

3.4 Chains：把多个步骤串成流水线

视频生成的一个典型链：

主题 → 生成标题 → 生成脚本 → 生成分镜 → 输出结构化渲染参数

用 LCEL（LangChain Expression Language）可以非常直观地表达：

from langchain_core.runnables import RunnablePassthrough
from langchain_core.output_parsers import StrOutputParser

# 子链 1：生成标题
title_prompt = ChatPromptTemplate.from_template("为'{topic}'写一个 20 字以内的爆款标题")
title_chain = title_prompt | llm | StrOutputParser()

# 子链 2：根据标题和主题生成脚本
script_prompt = ChatPromptTemplate.from_template(
    "标题：{title}\n主题：{topic}\n时长：{duration}秒\n请生成 3 个分镜的脚本。"
)
script_chain = script_prompt | llm | StrOutputParser()

# 组合
full_chain = (
    {"topic": RunnablePassthrough(), "duration": RunnablePassthrough()}
    | RunnablePassthrough.assign(title=title_chain)
    | RunnablePassthrough.assign(script=script_chain)
)

result = full_chain.invoke({"topic": "LangChain 视频生成", "duration": 30})
print(result)

LCEL 的 | 运算符让数据流像 Unix 管道一样清晰，这也是 LangChain 从 0.1 到 0.2/0.3 版本最重要的设计演进。

3.5 RAG：用本地素材库增强脚本生成

做批量短视频时，通常有沉淀的素材库（文案库、分镜库、音乐库）。LangChain 的 RAG 组件可以让模型先检索再生成：

from langchain_community.vectorstores import FAISS
from langchain_openai import OpenAIEmbeddings
from langchain_core.prompts import ChatPromptTemplate
from langchain.chains.combine_documents import create_stuff_documents_chain

# 1. 构建向量库
embeddings = OpenAIEmbeddings()
vectorstore = FAISS.from_texts(
    ["分镜案例 1：开头用悬念钩子...", "爆款标题公式：数字+痛点+解决方案..."],
    embedding=embeddings
)
retriever = vectorstore.as_retriever(search_kwargs={"k": 2})

# 2. 构建 RAG Chain
prompt = ChatPromptTemplate.from_messages([
    ("system", "参考以下素材生成脚本：\n\n{context}"),
    ("human", "主题：{topic}，时长：{duration}秒")
])

rag_chain = create_stuff_documents_chain(llm, prompt) | {
    "topic": lambda x: x["topic"],
    "context": retriever
}

# 实际调用时先检索文档，再塞入 prompt

在方糖猫 AI 短视频平台的工程实现中，我们会把 RAG 检索结果和 LangGraph 状态机结合，实现"检索 → 生成 → 人工审核 → 渲染"的完整闭环。

3.6 Agents：让 LLM 自己决定下一步

当流程不是固定流水线，而是需要动态决策时，Agent 更有优势。例如：

判断用户输入是否需要检索素材库；
根据脚本内容决定调用文生图还是文生视频工具；
调用外部 API 查询热点话题。

from langchain.agents import AgentExecutor, create_openai_tools_agent
from langchain_core.tools import tool

@tool
def generate_image(description: str) -> str:
    """根据画面描述生成一张图片，返回图片 URL。"""
    # 实际接入 DALL·E / Midjourney / Stable Diffusion
    return f"https://fake-img.example.com?prompt={description}"

@tool
def generate_video_clip(description: str, duration: int) -> str:
    """根据画面描述生成一段视频片段，返回视频 URL。"""
    return f"https://fake-video.example.com?prompt={description}&duration={duration}"

tools = [generate_image, generate_video_clip]

agent_prompt = ChatPromptTemplate.from_messages([
    ("system", "你是一位 AI 视频导演，能调用工具生成图片或视频。"),
    ("human", "{input}"),
    ("placeholder", "{agent_scratchpad}")
])

agent = create_openai_tools_agent(llm, tools, agent_prompt)
agent_executor = AgentExecutor(agent=agent, tools=tools, verbose=True)

agent_executor.invoke({
    "input": "我要一个 30 秒关于 LangChain 的短视频，先出 3 张分镜图，再合成视频。"
})

四、Demo：一个可扩展的"AI 视频脚本生成器"

下面把上面所有组件串起来，做一个最小的可运行 Demo。它的输出是一份结构化脚本，后续可以无缝接到 Remotion、FFmpeg 或视频生成 API。

import os
from langchain_openai import ChatOpenAI
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.output_parsers import PydanticOutputParser
from langchain_core.runnables import RunnablePassthrough
from pydantic import BaseModel, Field

os.environ["OPENAI_API_KEY"] = "your-api-key"

llm = ChatOpenAI(model="gpt-4o-mini", temperature=0.7)

class Scene(BaseModel):
    time_range: str
    narration: str
    visual: str
    tool: str = Field(description="生成该分镜所需工具：image 或 video")

class VideoProject(BaseModel):
    title: str
    target_platform: str
    scenes: list[Scene]

parser = PydanticOutputParser(pydantic_object=VideoProject)

title_chain = (
    ChatPromptTemplate.from_template("为'{topic}'写一个适合{platform}的爆款标题")
    | llm
    | StrOutputParser()
)

script_prompt = ChatPromptTemplate.from_template(
    """为平台"{target_platform}"生成短视频脚本。
{format_instructions}
标题：{title}
主题：{topic}
时长：{duration}秒
要求：每个分镜标注用 image（图片）还是 video（视频片段）生成。
"""
)

script_chain = (
    RunnablePassthrough.assign(title=title_chain)
    | script_prompt.partial(format_instructions=parser.get_format_instructions())
    | llm
    | parser
)

project = script_chain.invoke({
    "topic": "LangChain 如何帮助 AI 视频创作",
    "platform": "抖音",
    "target_platform": "抖音",
    "duration": 30
})

print(project.model_dump_json(indent=2, ensure_ascii=False))

下一步可以扩展的方向：

把 Scene.visual 传给 DALL·E / Stable Diffusion / 可灵 / Pika 生成画面；
用 pydub + gTTS 合成配音，或用 CosyVoice 克隆音色；
用 Remotion 或 MoviePy 把图片、视频、字幕、BGM 合成为成片；
接入 LangGraph 做状态持久化和人工审核节点（参考我之前写的 LangGraph 入门笔记）。

五、分布式场景下的运行方案

当 LangChain 应用从本地脚本走向生产环境，单进程运行肯定不够。AI 视频生成是典型的长链路任务：脚本生成、素材检索、文生图、文生视频、配音、渲染，每一步都可能耗时数秒到数分钟。分布式架构的关键是：让 LangChain 推理层保持无状态，把状态交给任务队列和持久化存储。

关键设计点

LangChain 服务无状态化 不保存用户会话到本地内存，所有上下文通过 state 参数或 Redis 传入。这样任意 Worker 都可以处理任意任务，方便水平扩展。
任务队列解耦 用 Celery、RQ 或自研 Worker 消费 RocketMQ/Redis Stream。一个任务对应一次视频生成链路，失败可以重试，不会阻塞 API 网关。
持久化中间状态 把每个阶段的结果（脚本 JSON、分镜图 URL、视频片段 URL）写入数据库。如果 Worker 崩溃，可以从上一个阶段恢复，而不是从头执行。
LangGraph 的分布式友好性 LangGraph 的 State 天然适合持久化。可以配置 checkpointer 把状态快照到 Redis/Postgres，实现断点续跑：

from langgraph.checkpoint.memory import MemorySaver
from langgraph.graph import StateGraph

builder = StateGraph(VideoGenState)
# ... 添加节点和边 ...
graph = builder.compile(checkpointer=MemorySaver())

生产环境建议把 MemorySaver 替换为 PostgresSaver 或 RedisSaver，让不同 Worker 共享状态。

六、服务器异常恢复方案

AI 视频生成链路长、依赖多（LLM API、素材库、视频生成服务、对象存储），任何一环抖动都会导致失败。异常恢复不是简单 try/except，而是要从架构层面保证可观测、可重试、可续跑。

1. 分级重试策略

异常类型	处理方式	示例
LLM API 限流 / 超时	指数退避重试 3 次	`tenacity` 或 LangChain 内置 `max_retries`
第三方服务不可用	降级或转人工审核	视频生成失败时返回占位图 + 提示
Worker 进程崩溃	队列自动重发，幂等消费	Celery `acks_late=True`
数据格式错误	进入死信队列，人工处理	JSON 解析失败

LangChain 调用模型时建议统一封装：

from tenacity import retry, stop_after_attempt, wait_exponential

@retry(stop=stop_after_attempt(3), wait=wait_exponential(multiplier=1, min=2, max=10))
def invoke_with_retry(chain, inputs):
    return chain.invoke(inputs)

2. 幂等性设计

同一个视频生成任务可能因为网络超时被重复投递。给每个任务分配唯一 task_id，在数据库里记录 PENDING → PROCESSING → SUCCESS/FAILURE 状态。Worker 消费前先看状态，避免重复执行。

def process_video_task(task_id: str, inputs: dict):
    if db.get_status(task_id) in ("SUCCESS", "PROCESSING"):
        return db.get_result(task_id)

    db.set_status(task_id, "PROCESSING")
    try:
        result = video_chain.invoke(inputs)
        db.set_status(task_id, "SUCCESS", result=result)
        return result
    except Exception as e:
        db.set_status(task_id, "FAILURE", error=str(e))
        raise

3. 死信队列（DLQ）

重试仍然失败的任务进入死信队列，由告警系统通知运维或产品人员处理。DLQ 里的任务可以手动重跑、补数据或退款。

4. 状态快照与断点续跑

结合 LangGraph 的 checkpointer，每个节点执行完后自动保存状态。Worker 重启后，可以根据 thread_id 恢复到最近的 checkpoint：

config = {"configurable": {"thread_id": task_id}}
# 首次执行
graph.invoke(initial_state, config=config)

# Worker 重启后继续执行
state = graph.get_state(config)
graph.invoke(None, config=config)  # 从 checkpoint 继续

七、如何实现高并发

AI 视频生成场景的高并发，核心矛盾是：LLM API 调用有速率限制，但用户请求可能突增。不能简单堆机器，需要把 IO 等待和计算分离。

1. 异步调用释放线程

LangChain 支持 ainvoke、abatch、astream，配合 asyncio 可以大幅提升吞吐：

import asyncio

async def batch_generate(tasks):
    results = await script_chain.abatch(tasks)
    return results

# 并发处理 20 个脚本生成请求
tasks = [{"topic": t, "duration": 30} for t in topic_list]
results = asyncio.run(batch_generate(tasks))

注意：底层 HTTP 客户端（如 httpx）需要配置连接池，避免每次请求新建连接。

2. 流式响应降低首字节延迟

对于长文本生成，使用 astream 把结果逐步返回给用户，避免长时间阻塞：

async for chunk in chain.astream({"topic": "LangChain 高并发"}):
    print(chunk, end="", flush=True)

3. 限流与背压

模型侧限流：根据 OpenAI/Claude 的 RPM/TPM 限制，用令牌桶算法控制请求速率。
队列侧背压：当队列堆积超过阈值时，API 网关返回 429 Too Many Requests，保护下游 Worker。

import asyncio
from asyncio import Semaphore

sem = Semaphore(10)  # 同时最多 10 个 LLM 调用

async def limited_invoke(inputs):
    async with sem:
        return await chain.ainvoke(inputs)

4. 缓存常用结果

很多提示词是重复的（比如热门模板、常见分镜描述）。可以用 Redis 缓存 prompt_hash → result，命中时直接返回，不走 LLM：

import hashlib

def get_cache_key(inputs: dict) -> str:
    return hashlib.sha256(json.dumps(inputs, sort_keys=True).encode()).hexdigest()

key = get_cache_key(inputs)
if cached := redis.get(key):
    return json.loads(cached)

result = chain.invoke(inputs)
redis.setex(key, 3600, json.dumps(result))

5. 水平扩展与资源隔离

CPU 密集型步骤（如 FFmpeg 渲染、图片后处理）放到独立 Worker 池，避免阻塞 LLM 推理线程。
GPU 密集型步骤（如文生视频）单独部署 GPU 节点，通过队列按需调度。
API 网关层用 Nginx/Envoy 做负载均衡，无状态 LangChain 服务可以快速扩容。

八、学完这门课的几点体会

不要神化 LangChain：它本质是高阶胶水，帮你少写重复代码，但不会让模型变得更聪明。复杂的业务逻辑仍然需要自己设计。
优先用 LCEL：新项目中尽量用 Runnable + | 组合链，比旧的 LLMChain、SequentialChain 更灵活、更易调试。
结构化输出是工程关键：视频、电商、客服等场景都需要把 LLM 输出转成 JSON，PydanticOutputParser 是必备技能。
Agent 不是银弹：固定流程用 Chain，动态决策才用 Agent。Agent 调试成本高，要配合观察日志和工具描述优化。

九、参考资源

吴恩达 & Harrison Chase 官方课程：LangChain for LLM Application Development
中文笔记与代码：awesome-LangChain-for-LLM-Application-Development
我之前的相关笔记：LangGraph 入门：给传统工程师的 Agent 状态与编排指南

这篇文章把吴恩达课程的核心内容和我自己在 AI 视频生成项目里的经验做了结合。如果你也在用 LangChain 做视频、口播剪辑或 Agent 工作流，欢迎留言交流。

生成式AI原理与实战（Part 2）学习笔记：提示工程、Agent 与 RAG 的通俗理解

Sat, 08 Nov 2025 15:24:25 +0800

生成式AI原理与实战（Part 2）学习笔记：提示工程、Agent 与 RAG 的通俗理解

这是《生成式AI原理与实战》学习笔记的第二篇。Part 1 聊了 Transformer、Token、Embedding、Attention、KV Cache 这些“底层零件”；Part 2 则进入“怎么用”的层面：怎么写提示词、怎么让模型完成复杂任务、怎么给模型外挂知识库。目标读者仍然是刚接触 AI 的初中级开发者——读完之后，你不需要会训模型，但应该能清楚地说出提示工程、Agent、RAG 这几个热门词到底在解决什么问题。

写在前面：从“调用 API”到“搭一个系统”

如果你只调过 ChatGPT API，可能会觉得大模型就是一个“输入问题、返回答案”的黑盒。但实际做项目时，很快会遇到这些问题：

同样的 prompt，为什么每次回答不一样？
模型怎么老是“一本正经地胡说八道”？
想让模型输出 JSON，它却总带多余解释。
对话轮数多了，模型就忘了用户是谁。
公司私有文档模型不知道，怎么办？

Part 2 的内容，本质上就是回答这些问题。我会把它们分成三块：提示工程（怎么写好 prompt）、Agent（怎么让模型动起来）、RAG（怎么给模型外挂知识）。

一、提示工程：不是写文案，而是设计接口

很多人把提示工程当成“怎么哄 AI 开心”。其实对开发者来说，prompt 更像一个函数签名：输入清楚、输出可控、边界明确。

1.1 两个旋钮：temperature 与 top_p

大模型生成下一个词时，不是“选择概率最高的词”就完事了。它有两个常用的“随机性旋钮”：

temperature：控制采样的“大胆程度”。值越低越保守，接近“只选概率最高的词”；值越高越有创意，容易跳出常规。
top_p（nucleus sampling）：只从累计概率达到一定比例的候选词里挑。比如 top_p=0.9，就只在概率最高的那一小撮词里采样。

flowchart LR
    A[模型输出概率分布] --> B{采样策略}
    B -->|temperature 低| C[集中在高概率词<br/>输出稳定]
    B -->|temperature 高| D[概率被拉平<br/>输出更多样]
    B -->|top_p 小| E[候选池小<br/>更聚焦]
    B -->|top_p 大| F[候选池大<br/>更发散]

不同任务推荐参数如下：

任务类型	temperature	top_p	原因
翻译、摘要、代码	0.2 - 0.5	0.8 - 1.0	需要准确、可重复
创意写作	0.7 - 1.0	0.9 - 1.0	需要多样性和想象力
头脑风暴	0.8 - 1.2	0.9 - 1.0	越跳出常规越好

验证参数好坏的方法：人工看多轮输出是否稳定/有趣；对翻译用 BLEU/ROUGE；对创意任务用 distinct-n 看词汇多样性。

小知识：有些模型 temperature=0 时输出仍不稳定，可能是因为用了**推测解码（Speculative Decoding）**等加速技术，候选生成阶段仍带随机性。

1.2 一个专业提示词长什么样？

把 prompt 当成接口文档来设计，通常包含以下模块：

flowchart TD
    A[角色定义] --> B[任务目标]
    B --> C[输入信息/上下文]
    C --> D[输出格式]
    D --> E[约束条件]
    E --> F[示例]
    F --> G[模型输出]

模块	作用	例子
角色定义	限定语气、专业范围	“你是一位严谨的学术助手。”
任务目标	消除歧义	“请把下面这段话翻译成英文。”
输入信息	限制回答依据	“仅根据以下材料回答。”
输出格式	便于解析	“输出 JSON，包含结论和依据。”
约束条件	降低风险	“不要编造，不知道就说不知道。”
示例	快速对齐预期	给 1-2 个输入输出样例

为什么角色定义很重要？ 大模型在训练时见过无数种文体和身份。明确角色，相当于激活了模型内部对应的知识路径和语气风格，也能让它更谨慎，减少胡说八道的概率。

1.3 怎么减少模型“幻觉”？

幻觉（Hallucination）就是模型一本正经地编造不存在的信息。常用防御手段：

限定信息源：只根据给定材料回答。
强化真实性要求：明确说“不知道就说不知道”。
要求引用依据：让模型说明答案出处。
限制输出格式：用 JSON、表格等结构化输出，减少自由发挥。
低 temperature：减少随机编造。

1.4 怎么防止提示词注入攻击？

提示词注入是指：用户输入里夹带“忽略前面指令、现在执行我的命令”这类内容，试图绕过系统限制。防御思路：

flowchart LR
    A[用户输入] --> B[结构化隔离<br/>JSON/YAML/字段分离]
    B --> C[系统层过滤<br/>正则/规则/小模型守门]
    C --> D[明确指令优先级<br/>禁止修改角色与规则]
    D --> E[函数调用输出<br/>固定 schema]

结构化输入：不要把用户输入直接拼进自然语言 prompt，用 JSON 等格式隔离。
明确边界：系统提示里写明“不可改变角色”。
函数调用：让模型按固定 schema 输出，减少被操控空间。
系统层检测：用规则或小模型识别异常输入（如突然要求“忽略之前指令”）。

1.5 让模型“先思考再回答”：CoT、Self-Consistency、ToT

复杂任务（数学、逻辑、规划）直接要答案，模型容易错。可以先让它把推理过程写出来。

flowchart TD
    subgraph 思维链 CoT
        Q1[问题] --> R1[一步一步推理] --> A1[答案]
    end

    subgraph 自洽性 Self-Consistency
        Q2[问题] --> R2a[采样推理 1]
        Q2 --> R2b[采样推理 2]
        Q2 --> R2c[采样推理 N]
        R2a --> V[投票/多数共识]
        R2b --> V
        R2c --> V
        V --> A2[最终答案]
    end

    subgraph 思维树 ToT
        Q3[问题] --> B1[分支 1]
        Q3 --> B2[分支 2]
        Q3 --> B3[分支 3]
        B1 --> E[评估/回溯]
        B2 --> E
        B3 --> E
        E --> A3[最优答案]
    end

方法	优点	缺点	适用场景
CoT	简单有效，兼容多数模型	可能产生幻觉推理步骤	数学、逻辑题
Self-Consistency	稳定，减少随机波动	计算开销大	精度要求高
ToT	多路径探索，适合长规划	实现复杂	解谜、策略任务
反思 Reflection	可自我纠错	依赖初始回答质量	代码调试、文本润色

1.6 怎么保证输出格式？

明确格式要求：在 prompt 里清楚说明想要的结构。
给 few-shot 示例：1-2 个例子比千言万语管用。
限制随机性：JSON 输出常用 temperature=0。
使用 API 的 JSON Mode / Function Calling：从接口层面约束输出。
后处理校验：用 json.loads() 等工具兜底。

1.7 分类任务怎么保证只输出指定类别？

提示词里写明“只能输出以下类别之一”。
用 API 的 logit_bias 强行禁止非法 token。
Function Calling 限定返回枚举值。

二、Agent：让大模型从“回答问题”到“完成任务”

提示工程解决的是“单次问答怎么做好”；Agent 解决的是“怎么让模型自主完成一个多步骤任务”。

2.1 Agent 的工作循环

一个典型的 Agent 长这样：

flowchart LR
    A[用户任务] --> B[思考 Thought]
    B --> C[行动 Action]
    C --> D[调用工具/搜索/查库]
    D --> E[观察 Observation]
    E --> F{任务完成了吗？}
    F -->|否| B
    F -->|是| G[输出最终答案]

这就是 ReAct 模式的核心：想一步、做一步、看结果、再决定下一步。比如你要做一个“调研 GPT-5 最新消息”的 Agent，它的循环可能是：

分析目标 → 提取关键词。
生成搜索关键词。
调用搜索引擎。
浏览网页，抽取信息。
更新记忆，避免重复搜索。
判断是否需要继续，直到满意。

2.2 多 Agent 协作：一个复杂任务拆给多个“专员”

当任务复杂、提示词过长时，可以把一个 Agent 拆成多个子 Agent：

flowchart LR
    U[用户请求] --> R[Router Agent<br/>识别意图]
    R --> F[航班 Agent]
    R --> H[酒店 Agent]
    R --> I[行程 Agent]
    F --> P[Planner Agent<br/>整合结果]
    H --> P
    I --> P
    P --> O[返回用户]

Router Agent：根据用户意图决定调用谁。
子 Agent：各自处理专业领域。
Planner Agent：汇总输出，生成统一回复。

子 Agent 之间通过共享上下文对象、向量数据库等方式传递信息。

2.3 记忆：模型不会自动记住你

大模型本身没有长期记忆。对话轮数多了，它会“忘”掉 earlier 的关键信息。解决办法：

flowchart TD
    A[历史对话] --> B[滑动窗口<br/>保留最近 N 轮]
    B --> C[摘要压缩<br/>生成关键状态]
    C --> D[外部记忆存储<br/>Redis/向量库]
    D --> E[需要时检索注入 Prompt]

显式重复：把关键信息重新塞进 prompt。
摘要压缩：每 N 轮生成一次对话摘要。
外部存储：用 Redis、向量数据库保存用户画像和历史事件。
KV 缓存持久化：把历史对话的 Key-Value 缓存存起来，下一轮直接复用，减少重复计算和延迟。

2.4 异步工具调用：别让一个慢工具卡住整个对话

如果某个工具（比如查航班 API）要几秒才返回，Agent 不应该傻等。可以：

把工具调用做成异步任务。
给用户一个中间状态回复：“正在查询，请稍等。”
同时处理其他事情，工具返回后再继续。
用请求 ID 追踪每个调用，确保结果能匹配回上下文。

三、RAG：给大模型外接一个“知识库”

大模型训练数据有截止日期，也不会包含你的私有文档。RAG（Retrieval-Augmented Generation，检索增强生成）的思路是：在生成答案前，先从外部知识库检索相关内容，把检索结果作为上下文喂给模型。

3.1 RAG 的基本流程

flowchart LR
    Q[用户问题] --> R[检索模块]
    D[文档库] --> C[文档分块]
    C --> V[向量数据库]
    V --> R
    R --> M[Top-k 相关片段]
    M --> L[大模型]
    Q --> L
    L --> A[带依据的答案]

3.2 为什么要把文档切成块？

直接拿整篇文档做向量，效果不好，原因：

检索精度低：用户只关心其中一两段，整篇文档的向量会被不相关部分稀释。
嵌入模型有长度限制：BERT、MiniLM 等通常只能处理 512 token 左右。
细粒度匹配更好：小片段更容易和查询语义对齐。

但切块也会带来上下文缺失的问题。常用补救方法：

方法	思路	优点	缺点
滑动窗口 + 重叠	相邻块有重叠区域	保留局部上下文	存储冗余
带标题分块	每个块附带章节标题	增强结构感	对无结构文档效果有限
检索时扩展	召回相邻块一起送给模型	上下文完整	需要系统支持
多粒度索引	同时建“摘要级”和“原文级”索引	兼顾梗概与细节	实现复杂

3.3 向量检索不够，还要混合检索和重排序

向量检索擅长“语义相似”，但不擅长“精确关键词匹配”；传统关键词检索（如 BM25）正好反过来。所以生产环境常用混合检索：

flowchart LR
    Q[用户查询] --> A[向量检索<br/>Dense Retrieval]
    Q --> B[关键词检索<br/>BM25/TF-IDF]
    A --> F[候选结果]
    B --> F
    F --> R[Rerank<br/>Cross-Encoder]
    R --> K[Top-k 最相关片段]
    K --> L[大模型生成]

向量检索：找语义相近的文档。
关键词检索：补全精确匹配能力。
Rerank（重排序）：用更强的 Cross-Encoder 模型对召回结果精排。

3.4 为什么查询要改写？

用户提问往往口语化、不完整，直接拿去检索效果差。Query Rewriting 的目标是把问题改写成“更适合嵌入模型的语义表达”。

比如：

原问题：“他出生在哪？”
改写后：“Barack Obama was born in ?”

方法包括：LLM 改写、同义词扩展、模板化改写、指令式嵌入（如 E5 模型的 query: 前缀）。

3.5 检索到冲突或过时的信息怎么办？

检索前：做数据源筛选、时效性过滤。
检索中：多阶段 reranking，提升相关性。
生成前：在 prompt 里加防御性约束，比如“如果来源冲突，请说明”。
生成时：要求模型标注来源，输出可信度分数。
生成后：用一致性校验或外部验证器判断答案是否忠实于来源。

3.6 RAG 的可解释性

想让用户信任答案，最好告诉它“这个答案来自哪”。做法：

保留文档 ID、URL、时间戳。
做生成-来源对齐（Attribution），把生成内容逐句回溯到文档片段。
输出置信度分数：检索相似度、生成概率、验证器分数等。

3.7 多模态 RAG 与长期记忆

RAG 不限于文本。可以扩展到图像、视频：

用 CLIP 等模型把图像、文本映射到统一向量空间。
文档里的图表提取为图像块，保留位置信息。
视频按时间分段，提取关键帧 + ASR 文本。

AI 伴侣、企业知识库这类长期记忆场景，则需要：每日摘要、事件图谱、多层次召回、时间感知检索、经验版本控制（避免新经验覆盖旧经验）。

四、从面试题到工程实践：给初级开发者的建议

先跑通端到端，再优化局部。不要一上来就追求最先进的 reranker 或 Agent 框架，先用最简单的方式验证需求是否成立。
把 prompt 当代码管。纳入 Git，做版本控制，写回归测试。
评估比调参更重要。没有指标，就不知道改进是否有效。
上下文质量 > 上下文长度。塞太多无关信息，反而让模型抓不到重点。
有结构地失败。模型总会出错，关键是在出错时有兜底、有日志、能回滚。

结语

Part 2 的内容从“怎么写 prompt”一路延伸到“怎么搭 Agent、做 RAG”。对初级开发者来说，最重要的不是记住每个参数的具体数值，而是理解这些技术背后的工程思想：

提示工程 = 设计人与模型的接口协议；
Agent = 把单次调用扩展成有状态、有工具、有记忆的循环；
RAG = 用外部知识库补齐模型能力的缺口。

掌握这三块，你就已经能从“会调 API”进阶到“能搭 AI 应用”了。

参考：《生成式AI原理与实战 —— Part 2》