从零到一搭建企业级智能问答系统：Ch02 ·提示词工程管理

Ch02 · 提示词工程管理：从硬编码到可视化

覆盖提交：aead072(002) · 3595a3b(010) · 1aa9262(013) · c5e06c4(014) 难度：★★☆☆☆　阶段：Day 1–5 关键词：Prompt 三层次 / 模板化 / 版本管理 / 幻觉第一类 / 文本资产

本章导读

上一章，你让模型「看见」了文档——num_ctx 从默认的 2048 拉到 8192，私域手册的前半本终于进了模型的视野。

但看得见，不等于会答。模型还得知道三件事：什么时候该答、按什么规矩答、以什么口吻答。这三件事，全靠提示词。

麻烦的是，提示词一旦散在代码里，改一次要改代码、要重启、要提测，还说不清线上生效的是哪一版。所以本章只干一件事：把提示词当成资产管起来——能存、能改、能回滚、能看版本。

这笔投入第 3 天花出去，第 4 天就兑现了：第 014 次提交「解决闲聊幻觉」，改了 113 行提示词，当天上线，从改到生效不到 10 秒。没有这套管理，同样的修法至少拖一天。

还记得 ch01 第三部分里那些各司其职的节点吗——classify 判意图、grade 打分、rewrite 改写、generate 写答案，每个节点压着不同的温度。每个节点背后，都压着一份提示词。 节点越多，提示词越多，越需要管理。这就是本章的舞台。

本集学习目标

学完这一章，回到这张表逐一自查——四条，一条都不能少：

目标 1 是认知地基——先分清「写好提示词」和「管好提示词」是两回事；目标 2 是本章的工程主体，也是「第二天就兑现价值」的地方；目标 3 是全章最反直觉、最容易调错方向的一个点；目标 4 是顺手捡的便宜，ROI 极高。带着这四个目标往下读，读完回来打钩。

📐 理论基石：提示词 = 给条件分布加约束，工程化 = 把约束固化进版本

为什么「提示词工程」要单独成章、还要进数据库？（呼应 P0-02 §1/§2）：

• 提示的本质是给模型的条件分布加约束：P(回答 | 提示)。prompt_manager.py:16-17 的 prompt_templates 表，就是把「这组约束」固化成可存储、可版本化的资产，而不是散落在代码里的字符串。
• 角色设定（如 prompt_manager.py:82-93 的 classify 模板写 system 提示）是风格先验，不是知识注入——它约束「以什么口吻答」，不改变模型会不会答错事实（呼应 P0-02 §3）。所以「调角色」救不了事实性幻觉。
• few-shot / CoT（P0-02 §2）是更重的约束：把示例或推理步骤摊进上下文窗口，让分布更集中。但这些约束一旦要 A/B，就必须能回滚到上一个版本——没有版本号（本章 L2），你连「哪次提示改动让闲聊变差」都追不回。
• 采样温度是分布宽度的旋钮：llm_gateway.py:109 默认 temperature: float = 0.0，548 行的 opts{temperature,seed} 是调用入口。低温 = 收敛、可复现，正是「工程化提示词」想要的可控性。很多人以为幻觉是「措辞没调好」，其实 temperature 是更直接的开关。

本章关键洞察的理论版本：闲聊也幻觉，根因往往不在提示词措辞，而在路由（让模型在「不该检索时检索了」）。提示只能约束分布，改不了检索链路——这正是 P0-02「提示有边界」的结论。所以 ch02 把提示搬进数据库，价值不在「改措辞更方便」，而在「让路由/提示的每次改动都可版本化、可 A/B、可回滚」。

先记住这条主线，现在开始动手——第一件事，搞清楚「管起来」到底管什么。

第一部分 · 为什么要把提示词管起来

这一部分拿下目标 1。 很多人以为「提示词工程」就是钻研措辞——怎么写让模型更听话。方向一开始就偏了。本章要教你的第一件事是：「写好提示词」和「管好提示词」是两回事，前者是手艺，后者是工程。

1.1 三个层次：L1 写得好 → L2 管得住 → L3 测得出

图 1　提示词工程的三个层次。L2「管得住」是 L3「测得出」的前提——提示词不进数据库、不带版本号，你连 A/B 都没法做。

大多数团队卡在 L1 —— 反复调措辞，但无法证明"变好了"。因为L2 是 L3 的前提：没有版本号，A/B 测试就要部署两套代码，成本高到不可行。

1.2 一个认知：管好提示词，是工程能力，不是玄学

「写好提示词」确实在贬值——新一代模型内置推理，很多「咒语」没用了（详见本章思考题 7）。但「管好提示词」在升值，原因就一条：

模型越强，应用场景越多，提示词数量暴增，改坏的成本越高。 本项目到后期有 13 个节点的模板要维护——不靠版本号、不靠可视化后台，谁记得住 13 份提示词各自改到第几版？

第一部分小结 · 对照自查

• ✓ 三个层次——L1 写得好（决定单次上限）、L2 管得住（决定能否持续优化）、L3 测得出（决定方向对不对）
• ✓ 关键结论——L2 是 L3 的前提：没有版本号，A/B 测试就是纸上谈兵
• ✓ 认知刷新——「写好提示词」在贬值，「管好提示词」在升值

到这里，目标 1 完成。但「管得住」三个字，第一步是让提示词存得进数据库。这就是第二部分。

第二部分 · 把提示词搬进数据库

这一部分拿下目标 2，也是本章的工程主体。 路线是：先看改造前有多痛，再看表结构怎么设计、缓存怎么失效、渲染怎么做对，最后对照改造前后的账本。

2.1 改造前：散落在业务代码里的提示词

# ❌ 散落在业务代码里
prompt = f"""你是一个助手。请根据以下上下文回答：
{context}

问题：{query}
"""

三个致命问题：

2.2 表结构设计：版本号是灵魂

-- config/init_db.sql:20
CREATE TABLE IF NOT EXISTS `prompt_templates` (
  `id`          INT AUTO_INCREMENT PRIMARY KEY,
  `name`        VARCHAR(128) NOT NULL COMMENT '模板唯一标识',
  `title`       VARCHAR(255) COMMENT '中文名，后台展示用',
  `content`     TEXT NOT NULL COMMENT '模板内容，支持 {变量} 占位符',
  `category`    VARCHAR(64) COMMENT '分类：classify/grade/rewrite/generate...',
  `version`     INT DEFAULT 1,
  `enabled`     TINYINT(1) DEFAULT 1,
  `updated_at`  TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
);

四个关键字段：

2.3 三层结构

┌─────────────────┐
│ 后台管理页面     │  编辑 / 灰度 / 回滚     ← rag_web_server.py (+924 行)
└────────┬────────┘
         ↓
┌─────────────────┐
│ prompt_templates│  MySQL 持久化 + 版本号
└────────┬────────┘
         ↓
┌─────────────────┐
│ prompt_manager  │  加载 / 渲染 / 缓存失效   ← prompt_manager.py (684 行)
└─────────────────┘

2.4 缓存与热更新

def get(self, name: str) -> str:
    """缓存 key 必须包含版本号 —— 模板一改，key 变，自动失效。"""
    version = self._current_version(name)
    key = f"prompt:{name}:v{version}"

    if key in self._cache:
        return self._cache[key]

    content = self._load_from_db(name)
    self._cache[key] = content
    return content

改提示词不用重启服务。 这在调参阶段价值巨大。

2.5 渲染：为什么不用 str.format()

def render(self, name: str, **kwargs) -> str:
    """渲染模板。

    注意：不用 str.format()，因为文档内容里可能含花括号
    （JSON 片段、代码块），format 会抛 KeyError。

    改用白名单替换：只替换模板声明过的变量。
    """
    content = self.get(name)
    for key, value in kwargs.items():
        content = content.replace("{" + key + "}", str(value))
    return content

为什么 str.format() 会出问题？

# 情况 1：文档内容含花括号 → 抛异常
context = '配置：{"timeout": 30}'
"上下文：{context}".format(context=context)   # 若还有其他占位符会 KeyError

# 情况 2：更危险 —— 内容里的占位符被意外替换
context = '用户问：{query} 是什么意思'
# 文档内容里的 {query} 可能被替换，造成内容错乱

2.6 兜底与校验：别让一次手滑打翻全站

兜底——渲染后检查是否还有未替换的占位符：

import re

def render(template, **kwargs):
    result = template
    for key, value in kwargs.items():
        result = result.replace("{" + key + "}", str(value))

    # 渲染后检查是否还有未替换的占位符
    leftover = set(re.findall(r"\{(\w+)\}", result))
    if leftover:
        logger.warning(f"模板存在未替换变量: {leftover}")
        # 生产环境降级（填空），开发环境应报错

    return result

校验——防止后台改错变量名：

ALLOWED_VARS = {"query", "context", "history", "role", "tenant"}

def validate_template(content: str) -> tuple[bool, str]:
    """校验模板中的占位符是否合法（后台保存前调用）。"""
    found = set(re.findall(r"\{(\w+)\}", content))
    invalid = found - ALLOWED_VARS
    if invalid:
        return False, f"未知变量: {invalid}，可用: {ALLOWED_VARS}"
    return True, "OK"

2.7 改造前后的账本

第二部分小结 · 对照自查

• ✓ 表结构——name（唯一）+ version（可回滚可 A/B）+ enabled（开关）+ category（分类），四个字段缺一不可
• ✓ 缓存失效——key 带版本号 prompt:{name}:v{version}，一改自动失效，不用重启
• ✓ 渲染——白名单替换，不用 str.format()（内容里的花括号会炸）
• ✓ 兜底 + 校验——渲染后查漏、保存前查错，两道防线挡手滑

到这里，目标 2 完成——提示词已经「存得进、改得动、回得了」。但搬进数据库的价值，不只在「改起来方便」，而在它让你第二天就修掉了一个顽固的 bug。这个 bug 就是第三部分的主角。

第三部分 · 第一类幻觉：不该检索时检索

这一部分拿下目标 3，也是全章最反直觉的一个点。 一句话剧透：这个幻觉，调提示词没用。

3.1 现象：闲聊也编出「知识库腔」

用户问"你好"、"你是谁"，系统也去检索知识库，然后编造一段"知识库风格的回答"：

用户：你好
系统：根据文档第 2.1 节，您好！本设备支持多种通讯协议...   ← 荒谬

3.2 根因：不是提示词的问题，是路由的问题

这是本章最关键的一点。

错误的诊断："提示词不够强，要加更严格的约束。"

正确的诊断：系统在该走"直接回答"的时候走了"检索回答"。

用户问"你好" → classify 判为 simple → 走检索 → 编造基于文档的回答
                    ↑ 根因在这里

如果只在提示词里加约束（"如果是闲聊就直接回答"），效果有限，因为：

• 模型已经拿到了一堆文档，它会倾向于"用上"这些文档
• 约束越强，模型越容易在两个指令间摇摆

正确的修法：在意图识别阶段就分流，闲聊根本不进检索分支。

对照 ch01：上一章你排掉的是第 2 类幻觉（检索到了、但 num_ctx 截断没读进去），这一章排的是第 1 类（压根不该去检索）。两类一个在「看得见」、一个在「该不该看」，都是工程层的错，不是模型的锅。

3.3 修法：chitchat 分支

# langgraph_rag_agent.py:882 —— 三条分支
graph.add_conditional_edges(
    "classify",
    self.route_after_classify,
    {
        "simple":   "query_rewrite",   # 简单查询 → 多轮检索
        "complex":  "planner",         # 复杂查询 → 多智能体拆解
        "chitchat": "direct_llm",      # 闲聊 → 直接回答（不检索！）
    },
)

# langgraph_rag_agent.py:925
graph.add_edge("direct_llm", "respond")     # 闲聊直答后直接出口

direct_llm 节点完全没有检索环节，从结构上杜绝了"闲聊编造文档内容"。

3.4 意图识别的实现（三代技术的第一代）

第 014 次提交时用的是快速分类（词表）：

# langgraph_rag_agent.py:2438
def _quick_classify(self, query: str) -> str:
    """快速分类：基于词表的规则判定。

    这是三代意图识别技术里的第一代（详见 Ch11）：
      第一代 关键词/词表   ← 本章
      第二代 LLM 分类
      第三代 向量语义路由  ← 最终形态
    """

# langgraph_rag_agent.py:979
def node_classify(self, state: AgentState) -> dict:
    """意图识别节点 —— 系统的分叉口。"""

# langgraph_rag_agent.py:1158
def route_after_classify(self, state: AgentState) -> str:
    """根据意图返回下一个节点名（必须命中 mapping 的键）。"""

这次提交的 119 行改动里，113 行在 prompt_manager.py —— 说明"提示词管理"这次改造直接加速了幻觉修复。这正是 L2 能力的价值兑现：没有版本号后台，这 113 行提示词还得走「改代码 + 重启」的老路。

3.5 幻觉的四种类型：先分类，再下药

很多人一遇到幻觉就调提示词，但实际上只有第 ③ 类适合用提示词解决。 先分类，再下药。

第三部分小结 · 对照自查

• ✓ 现象——闲聊也编「知识库腔」的回答
• ✓ 根因——在路由，不在提示词：该直答时走了检索
• ✓ 修法——{"chitchat": "direct_llm"}，从结构上分流，不从措辞上约束
• ✓ 认知——四类幻觉里，只有 1/4 适合用提示词解决

到这里，目标 3 完成——模型知道「什么时候不该去查」了。但本章还有一笔顺手的账要收：提示词是文本资产，注释也是。这就到了第四部分。

第四部分 · 另一类文本资产：注释

这一部分拿下目标 4。 提示词需要被管理，注释也一样——它们都是「写出来给人和机器看」的文本资产。区别只在于：提示词写给模型看，注释写给人看。

4.1 四个等级：什么样的注释才有价值

第 002 次提交只改了 13 行，但确立了注释的标准：

4.2 一个模板：六要素注释

第 010 次提交给 958 行 LangGraph 代码补了 1295 行注释（注释/代码比 135%）。以 MMR 算法为例，最终形成的注释模板：

# langgraph_rag_agent.py:2590
def _mmr_rerank(self, query: str, results: List, k: int = 5) -> List:
    """
    【辅助：MMR (Maximal Marginal Relevance) 重排序】

    作用：在相关性和多样性之间做平衡的文档排序算法。   ← ① 一句话职责

    原理：                                              ← ② 为什么需要
    向量检索容易返回内容相似的多个文档（来自同一段落的不同切片）。
    如果全部塞给 LLM，既浪费 token 空间，又让答案偏向重复内容。

    MMR 同时优化两个目标：                              ← ③ 核心机制
    - 相关性（Relevance）：选与查询最相关的文档
    - 多样性（Diversity）：选与已选中文档不重复的新文档

    算法（贪心）：                                      ← ④ 实现步骤
    1. 按距离排序，选最相关的作为第一个选中项
    2. 循环选择剩余项：
       a. 计算它和已选中集合的最大相似度（Jaccard）
       b. MMR 分数 = λ × 相关性 - (1-λ) × 冗余度
       c. 选 MMR 分数最高的加入选中集合

    λ（lambda_param=0.7）的含义：                       ← ⑤ 参数含义
    - 越接近 1 越看重相关性，越接近 0 越看重多样性
    - 0.7 是经验值，7:3 的权衡

    参数：query / results / k                           ← ⑥ 签名说明
    返回：MMR 排序后的文档列表
    """

六要素：职责 → 动机 → 机制 → 步骤 → 参数 → 返回值。

4.3 判断准则：意外程度决定注释量

判据：代码的"意外程度"越高，注释越要多。

记忆口诀：函数名能说清的，别写；函数名为止的，必须写。 注释只写「为什么」，不写「怎么做」——「怎么做」会变，「为什么」很少变。

4.4 这笔投资的回报

半天投入，回报持续整个项目周期。 这是本项目 ROI 最高的一次"非功能"提交。

第四部分小结 · 对照自查

• ✓ 四个等级——L0 有害 / L1 无用 / L2 有用 / L3 珍贵，只写 L2/L3
• ✓ 六要素——职责、动机、机制、步骤、参数、返回值
• ✓ 判断准则——意外程度决定注释量，算法核心可以到 100%+

踩坑总表

到这里，四个目标全部拿下。把这一章的坑摆到一张表上——每一个都是真实踩过的：

这张表值得截图存好。愿意把这些坑一个个提前填平——这就是工程化 AI 和玩具 demo 的分水岭。

学习目标回顾

回到开头的四个目标，逐一自查：

• ✓ 目标 1 · 管什么——L1 写得好 / L2 管得住 / L3 测得出，L2 是 L3 的前提，你分清了
• ✓ 目标 2 · 搬进数据库——表结构带版本号、缓存 key 带版本号、白名单渲染，你会设计了
• ✓ 目标 3 · 第一类幻觉——根在路由不在措辞，chitchat 分流，你拿下了
• ✓ 目标 4 · 注释——意外程度原则、六要素模板，你立住了

四个全过，这一章就没白读。最后送一句话带走：

「写好提示词」是手艺，「管好提示词」是工程。 手艺会过时，工程不会——提示词越多、部署越大、改坏越贵，管理越值钱。

而管好提示词的第一步，永远是先承认：提示词只约束「怎么答」，不决定「答不答」——该不该答，是路由的事。

知识点卡片

【知识点】提示词工程的三个层次

L3 测得出  ← 离线评测集 / A/B（证明"变好了"）
   ↑ 依赖
L2 管得住  ← 版本 / 灰度 / 回滚 / 可视化
   ↑ 依赖
L1 写得好  ← 措辞 / few-shot / 思维链

为什么 L2 是 L3 的前提？ A/B 测试要求两组用不同版本提示词。硬编码的话要部署两个实例才能对比——成本极高。进数据库后，A/B 只是"按流量比例取不同 version"。

【知识点】幻觉的第一类：不该检索时检索

特征：用户问闲聊/OOS 问题，系统也去检索，然后编造"知识库风格"的回答。

为什么调提示词没用？ 因为模型已经拿到了文档，它会倾向于"用上"这些文档。你加约束说"闲聊就直接回答"，模型反而要在两个指令间摇摆。

正确修法：在路由层分流 —— 闲聊根本不进检索分支：

{"chitchat": "direct_llm"}     # direct_llm 节点没有检索环节

从结构上杜绝，而不是从措辞上约束。

【知识点】注释的"意外程度"原则

代码越意外，注释越要多。

判断方法：想象一个和你水平相当的同事读这段代码，他会在哪里卡住？在每个卡住的地方写注释。

反例（浪费）：

def get_user_by_id(user_id):
    """根据 ID 获取用户。"""      # 函数名已经说清楚了

正例（必要）：

# BM25 取负：系统内统一约定"距离越小越相似"，
# 而 BM25 原始分数是"越大越相似"。漏掉负号会导致排序完全反向。
dist = -raw_score

记忆口诀：函数名能说清的，别写；函数名为止的，必须写。

练习题

基础题

1. 用户问"你好"，系统回答"根据文档第 2.1 节，您好！本设备支持多种通讯协议"。有人说这是提示词不够强。请评价这个诊断。

用户问"你好" → classify 判为 simple → 走检索 → 编造基于文档的回答
                    ↑ 根因在这里

graph.add_conditional_edges("classify", route_after_classify, {
    "chitchat": "direct_llm",      # direct_llm 节点没有检索环节
})

2. 为什么渲染提示词模板时不能用 str.format()？

context = '配置示例：{"timeout": 30, "retry": 3}'
prompt = "上下文：{context}"

# format 会把 {"timeout"...} 当成占位符
prompt.format(context=context)   # KeyError: 'timeout'

context = '用户问：{query} 是什么意思'     # 文档内容恰好含 {query}
prompt = "上下文：{context}\n问题：{query}"

result = prompt.format(context=context, query="心跳间隔")
# 某些渲染顺序下，context 里的 {query} 可能被替换 → 内容错乱

def render(template, **kwargs):
    result = template
    for key, value in kwargs.items():
        result = result.replace("{" + key + "}", str(value))
    return result

3. 提示词工程的 L1/L2/L3 分别是什么？为什么 L2 是 L3 的前提？

进阶题

4. 服务部署了 4 个 worker，后台改了提示词后有的实例生效有的没生效。给出三种解决方案及取舍。

CACHE_TTL = 10
def get(name):
    if name in cache and time.time() - cache[name]["ts"] < CACHE_TTL:
        return cache[name]["content"]
    # 重新加载

def get(name):
    content = redis.get(f"prompt:{name}")
    if content is None:
        content = load_from_db(name)
        redis.set(f"prompt:{name}", content)
    return content

def update_template(name, content):
    db.update(...)
    redis.delete(f"prompt:{name}")      # ← 关键：主动失效

def get(name):
    version = db.query_one("SELECT version FROM prompt_templates WHERE name=?", name)
    if cache.get(name, {}).get("version") != version:
        cache[name] = {"version": version, "content": load_content(name)}
    return cache[name]["content"]

5. 后台改提示词时打错变量名，导致线上所有问答报错。设计四道防线。

ALLOWED_VARS = {"query", "context", "history", "role", "tenant"}

def validate_template(content: str) -> tuple[bool, str]:
    found = set(re.findall(r"\{(\w+)\}", content))
    invalid = found - ALLOWED_VARS
    if invalid:
        return False, f"未知变量: {invalid}，可用: {ALLOWED_VARS}"
    return True, "OK"

leftover = set(re.findall(r"\{(\w+)\}", result))
if leftover:
    logger.warning(f"模板存在未替换变量: {leftover}")
    for var in leftover:
        result = result.replace("{" + var + "}", "")

def reset_to_default(name):
    default = BUILTIN_TEMPLATES[name]      # 默认模板硬编码在代码里
    db.update(name, content=default, version=version+1)
    cache.invalidate(name)

新模板 → 10% 流量 → 观察 5 分钟错误率 → 正常则放大到 100% → 异常自动回滚

思考题

6. 本项目给 958 行代码写了 1295 行注释（注释/代码比 135%）。这是过度注释吗？请给出判断依据。

1295 行注释的分布：
  L0 复述代码     ~0%     ← 没有浪费
  L1 重复函数名   ~10%    ← 少量冗余
  L2 解释为什么   ~60%    ← 有价值
  L3 决策与陷阱   ~30%    ← 高价值

# 与其写注释
# 注意：distance 应在 [0,2] 区间

# 不如让代码自己校验
assert 0 <= best_distance <= 2, f"COSINE 距离越界: {best_distance}"

7. 有人说「提示词工程已经过时了，现在模型足够聪明，不需要精心写提示词」。请评价。

请以 JSON 格式输出：{"intent": "...", "confidence": 0.0-1.0}

只依据提供的文档回答。文档未提及的，明确说"文档未提及"，不要推测。

本章小结

下一章：Ch03 · 工程卫生 —— 提示词管住了，但它跑在什么环境上？密钥怎么不泄露、依赖怎么选、文档怎么留痕（覆盖提交 003、004、005、009、017、018）。

导航：返回总目录 · 上一篇：大模型接入 · 下一篇：工程卫生 →