03 · ChatPromptTemplate：从手写消息列表到模板的必然性

本片目标：回答”为什么要模板”——当消息列表需要动态拼装、插入历史、复用系统提示时，手写列表会变得脆弱；模板把”消息结构”与”每次的数据”分离。 新增规定性：3（拼消息用 ChatPromptTemplate，历史用 MessagesPlaceholder） 数据字典：ChatPromptTemplate / MessagesPlaceholder / PromptTemplate / PromptValue。 进程线程模型：无变化（同步阻塞，模板 invoke 是纯内存操作，毫秒级）。 网络模型：模板本身不联网；它把消息拼好后，交给模型 invoke 才发 HTTP。

1. 上集回顾

第 02 篇我们学会了构造 SystemMessage + HumanMessage 列表传给模型。但现在遇到两个场景，手写列表开始难受： 1要插入历史消息：多轮对话时，消息列表是 [system, 历史user, 历史ai, 当前user]——历史是动态的、可长可短。 2要动态填变量："你是{company}的助手，请回答关于{product}的问题"——每次拼字符串吗？f-string 拼多了就乱。 本质问题：消息列表的结构（哪些是 system、哪里插历史、哪里放当前问题）是固定的，变的是数据（问题内容、公司名、历史消息）。把”固定结构”和”变化数据”混在一起写，必然导致重复代码和拼错。 模板 = 把结构写一次，数据每次填进去。

2. 数据字典：模板类

2.1 `ChatPromptTemplate`（聊天模板，本系列主力）

from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder

prompt = ChatPromptTemplate.from_messages([
    ("system", "你是{company}公司的智能助手，说话简洁。"),  # ① 元组写法: (角色, 模板文本)
    MessagesPlaceholder("history"),                         # ② 历史槽位
    ("human", "{question}"),                                # ③ 当前问题
])

构造方式	签名	说明
`from_messages`	`from_messages(messages: list[MessageLikeRepresentation], template_format="f-string") -> ChatPromptTemplate`	主力入口
`invoke`	`invoke(input: dict, config=None) -> PromptValue`	传入变量 dict，得到 PromptValue
`.to_messages()`	`prompt_value.to_messages() -> list[BaseMessage]`	PromptValue → 消息列表（真正给模型的）

MessageLikeRepresentation（模板里每个元素，三种写法）：

写法	例子	说明
元组	`("system", "你是{company}的助手")`	角色 + 文本模板（`{变量}` 插值）
消息对象	`SystemMessage(content="...")`	静态消息（不插值）
插槽	`MessagesPlaceholder("history")`	运行时塞进一组消息

2.2 `MessagesPlaceholder`（历史槽位——关键）

MessagesPlaceholder(variable_name="history", optional=False, n_messages=None)

参数	类型	说明
`variable_name`	`str`	对应 invoke 时 dict 里的键
`optional`	`bool`	该键缺省时是否报错
`n_messages`	`int	None`	只取最近 N 条（None=全取）

为什么需要它（规定性 3 的核心）：普通 {question} 只能塞一个字符串。而历史是一组消息对象。如果不用占位符而是 ("human", "{history}")，传列表进去会变成字符串字面量 "['AIMessage(...)', 'AIMessage(...)']"——模型看到的是 Python 列表的 repr，不是消息！

prompt_value = prompt.invoke({
    "company": "Z.ai",
    "history": [HumanMessage(content="我是小林"), AIMessage(content="你好小林！")],
    "question": "我叫什么名字？",
})
messages = prompt_value.to_messages()
# → [SystemMessage("你是Z.ai公司的..."), HumanMessage("我是小林"), AIMessage("你好小林！"), HumanMessage("我叫什么名字？")]

2.3 `PromptValue`（invoke 的返回）

属性/方法	类型	说明
`.to_messages()`	`list[BaseMessage]`	转消息列表（给模型用这个）
`.to_string()`	`str`	转纯文本（给非聊天模型用）
`.to_prompt()`	`Prompt`	转 OpenAI prompt 结构（少用）

2.4 `PromptTemplate`（单条字符串模板，偶尔用）

from langchain_core.prompts import PromptTemplate
t = PromptTemplate.from_template("你是{company}的助手", template_format="f-string")

3. 关键方法

方法	签名	说明
`ChatPromptTemplate.from_messages`	`(messages, template_format="f-string")`	建模板
`prompt.invoke(dict)`	`invoke(input: dict, config=None) -> PromptValue`	填变量
`prompt_value.to_messages()`	`-> list[BaseMessage]`	取消息列表
`prompt.format(...)`	`format(**kwargs) -> str`	直接得文本（调试用）
`prompt.partial(...)`	`partial(**kwargs)`	预填部分变量（少用）

4. 进程线程模型

prompt.invoke({...})   ← 纯内存操作：模板字符串插值 + 消息对象组装
  ↓ 毫秒级返回
model.invoke(messages) ← 这里才开始联网，阻塞 1~3 秒

模板这一步不联网、不阻塞。它是纯 Python 字符串/对象操作。所以放心在任意线程调用。

5. 网络模型

prompt.invoke → to_messages() → [SystemMessage, HumanMessage, AIMessage, HumanMessage]
                                          │
                                          ▼
model.invoke(messages)
  └─ 序列化为 Anthropic Messages JSON:
     {"model": "glm-4.7", "max_tokens": 512,
      "messages": [
        {"role":"system","content":"你是Z.ai公司的智能助手，说话简洁。"},
        {"role":"user","content":"我是小林"},
        {"role":"assistant","content":"你好小林！"},
        {"role":"user","content":"我叫什么名字？"}
      ]}

注意：消息的 type 字段（"system"/"human"/"ai"）在序列化时被映射成协议的 role（system/user/assistant）。

6. 验证：跑起来

配套代码 code/03_prompt.py：

建一个带 system 变量 + history 槽位 + question 的模板；
第一轮（空历史）invoke，打印拼出的消息列表；
第二轮（有历史）invoke，打印历史如何被展开插入；
演示 {history} 普通变量 vs MessagesPlaceholder 的差异（传列表会变成字面量字符串）。

cd enterprise-rag-course\code
python 03_prompt.py

预期输出（节选）：

===== 第 1 轮（history 为空） =====
拼出的消息列表:
  [SystemMessage] 你是Z.ai公司的智能助手，说话简洁。
  [HumanMessage]  我叫小林，是后端工程师

===== 第 2 轮（history 有 2 条） =====
拼出的消息列表:
  [SystemMessage] 你是Z.ai公司的智能助手，说话简洁。
  [HumanMessage]  我叫小林，是后端工程师
  [AIMessage]     收到，小林。
  [HumanMessage]  我主要做什么工作？

7. 边界

模板不是唯一方式——create_agent 内部就不用模板（直接列表拼接）。但本系列目标是 RAG，模板是拼 prompt 的正道。
{变量} 只塞字符串——塞列表会变成 repr 字符串。塞消息组必须用 MessagesPlaceholder。
f-string 语法限制——模板里别写裸 { }（如 JSON 示例），要么转义 {{，要么用 template_format="jinja2"。
system 提示也可以插值——("system", "你是{company}的助手") 完全合法，变量在 invoke 时填。

8. 未完待续

现在”输入”这块齐了：模型 + 消息 + 模板。但输出还有问题：

invoke 返回的是 AIMessage，我想要纯文本——每次手动 .content？
模型回答慢，用户等 2 秒才看到整段文字——能不能流式输出，像 ChatGPT 那样一个字一个字蹦？

这就是第 04 篇：输出解析与流式。 → 04 · 输出解析与流式

RAG 教程

小林学 LangChain

03 · ChatPromptTemplate：从手写消息列表到模板的必然性

03 · ChatPromptTemplate：从手写消息列表到模板的必然性

1. 上集回顾

2. 数据字典：模板类

2.1 `ChatPromptTemplate`（聊天模板，本系列主力）

2.2 `MessagesPlaceholder`（历史槽位——关键）

2.3 `PromptValue`（invoke 的返回）

2.4 `PromptTemplate`（单条字符串模板，偶尔用）

3. 关键方法

4. 进程线程模型

5. 网络模型

6. 验证：跑起来

7. 边界

推荐资料（延伸阅读）

8. 未完待续

​03 · ChatPromptTemplate：从手写消息列表到模板的必然性

​1. 上集回顾

​2. 数据字典：模板类

​2.1 ChatPromptTemplate（聊天模板，本系列主力）

​2.2 MessagesPlaceholder（历史槽位——关键）

​2.3 PromptValue（invoke 的返回）

​2.4 PromptTemplate（单条字符串模板，偶尔用）

​3. 关键方法

​4. 进程线程模型

​5. 网络模型

​6. 验证：跑起来

​7. 边界

​推荐资料（延伸阅读）

​8. 未完待续

03 · ChatPromptTemplate：从手写消息列表到模板的必然性

1. 上集回顾

2. 数据字典：模板类

2.1 `ChatPromptTemplate`（聊天模板，本系列主力）

2.2 `MessagesPlaceholder`（历史槽位——关键）

2.3 `PromptValue`（invoke 的返回）

2.4 `PromptTemplate`（单条字符串模板，偶尔用）

3. 关键方法

4. 进程线程模型

5. 网络模型

6. 验证：跑起来

7. 边界

推荐资料（延伸阅读）

8. 未完待续