SmartWriter v0.2：结构化写作 — Prompt 模板与输出解析器深度实战

SmartWriter v0.2：结构化写作 — Prompt 模板与输出解析器深度实战

前言

• 核心痛点：LLM 的输出是"非结构化自然语言"，而写作产品的核心需求是"可控的结构化输出"——大纲必须按 JSON Schema 生成、正文必须遵循 Markdown 规范、元数据必须可解析。本文深入解决 Prompt 模板工程与输出解析两大核心问题，让你从"祈祷模型输出正确格式"升级为"工程化约束模型输出"。
• 前置知识：需要掌握 Python 基础、了解 LLM 基本概念，建议先完成 SmartWriter v0.1：第一个写作 Chain — LangChain 模型调用与 Chain 基础实战 的学习。
• 系列阶段：入门篇 第 2/4 篇
• 收获能力：读完可掌握 ChatPromptTemplate 完整模板体系 + Few-shot 动态示例选择 + 三大 OutputParser 的原理与实战 + 结构化输出容错与自修复机制

依赖版本：本文基于以下版本撰写，所有代码示例均已验证可运行：

目录

• 1. 技术背景与演进逻辑
• 2. 核心原理深度解析
  • 2.1 Prompt 模板体系：消息角色与语义分层
  • 2.2 ChatPromptTemplate：消息列表模板的完整形态
  • 2.3 Few-shot Prompting：示例驱动输出格式控制
  • 2.4 OutputParser 体系：从原始文本到结构化对象
• 3. 核心模块/流程/机制详解
  • 3.1 消息角色体系深度拆解
  • 3.2 ChatPromptTemplate 高级用法
  • 3.3 Few-shot 示例选择策略
  • 3.4 三大 OutputParser 原理与选型
  • 3.5 解析失败重试与格式自修复
• 4. 技术优缺点 & 适用场景
• 5. 实战落地
• 6. 全文总结
• 7. 本期专栏更新说明
• 8. 参考资料

1. 技术背景与演进逻辑

1.1 从"自由文本"到"结构化写作"的范式转变

在 SmartWriter v0.1 中，我们完成了第一个写作 Chain：prompt | model | output_parser，实现了"输入一个主题，输出一篇文章"的基本能力。但当我们开始构建真正的写作产品时，v0.1 的设计暴露出一个根本性缺陷：模型输出完全不可控。

具体表现为三个层面的失控：

第一层：格式失控。你要求模型"用 JSON 格式返回文章大纲"，模型有时返回纯文本，有时返回 Markdown 包裹的 JSON，有时 JSON 中包含非法尾逗号——每一次返回格式的不同，意味着下游代码必须为每一种可能写一个 if-else 分支。这不是工程，这是祈祷。

第二层：角色失控。你用一条长长的字符串把所有指令塞进去：“你是一个专业作家，请写一篇关于 XX 的文章，风格要专业，字数要 3000 字…”——模型确实会执行，但指令之间缺乏层次感。系统指令（“你是谁”）和用户指令（“你要做什么”）混在一起，模型无法准确区分哪些是持久的角色约束、哪些是当前请求的可变参数。

第三层：示例失控。当你需要模型模仿某种特定风格时，你在 Prompt 里手写了几个示例，然后每次请求都带着这些示例。示例越多，Token 消耗越大；示例越少，格式越不稳定。而且固定的示例无法根据用户输入的写作主题动态选择最匹配的参考案例。

这三个问题，对应着 LLM 应用工程化的三条核心原则：

Prompt 工程的核心不是"写一条好 Prompt"，而是建立一套工程化体系： 角色分层 --> 系统指令（不变的） + 用户输入（可变的） + 历史对话（累积的） | v 示例管理 --> 示例不是写死在 Prompt 里的，而是根据输入动态选择并注入的 | v 输出约束 --> 模型输出不是"希望它长这样"，而是"它的 Schema 已经被定义好了，解析器会验证"

1.2 传统方案 vs LangChain 方案

1.3 SmartWriter v0.2 的设计目标

基于以上分析，SmartWriter v0.2 的核心升级路径如下：

SmartWriter v0.1 SmartWriter v0.2 ================ ================ prompt = ChatPromptTemplate prompt = ChatPromptTemplate .from_template("写一篇文章...") .from_messages([ ("system", system_template), model = ChatOpenAI(...) ("placeholder", "{chat_history}"), ("human", human_template), output_parser = StrOutputParser() ]) chain = prompt | model | parser model = ChatOpenAI(...) --> 加入 Few-shot 动态示例 || || 升级 output_parser = PydanticOutputParser( || pydantic_object=ArticleOutline) / chain = prompt | model | parser SmartWriter v0.2 --> 带 Schema 约束的自动解析 chain.with_retry() --> 解析失败自动重试

一句话总结 v0.2 的升级本质：从"请求模型输出"进化为"约束模型输出"。

2. 核心原理深度解析

2.1 Prompt 模板体系：消息角色与语义分层

LangChain 的 Prompt 模板体系建立在一个核心认知之上：现代 Chat LLM 的输入不是一段文本，而是一组消息（Messages）的有序列表，每条消息携带不同的语义角色。

一条 Chat Prompt 由多个 Message 组成，每个 Message 有明确的角色语义： +-----------------------------------------------------------+ | ChatPromptTemplate | | | | +-----------------------------------------------------+ | | | SystemMessage | | | | "你是一个专业的 AI 写作助手，名叫 SmartWriter。 | | | | 你的写作风格：简洁、准确、结构化。" | | | +-----------------------------------------------------+ | | | | | v | | +-----------------------------------------------------+ | | | MessagesPlaceholder | | | | 占位符：插入历史对话记录 | | | | [{HumanMessage: "..."}, {AIMessage: "..."}, ...] | | | +-----------------------------------------------------+ | | | | | v | | +-----------------------------------------------------+ | | | HumanMessage | | | | "请写一篇关于 {topic} 的技术文章，大纲要求 {format}" | | | +-----------------------------------------------------+ | | | +-----------------------------------------------------------+

三种核心消息角色的语义分工：

设计原则——角色分离的价值：

许多开发者习惯将系统指令和用户输入拼接成一条长字符串，这在简单场景下能工作，但在以下场景会出问题：

1. 多轮对话场景：系统指令在每轮都被重复发送，但它不应该被"对话历史"稀释——模型可能在第 5 轮对话时"忘记"自己是一个写作助手
2. Prompt 注入防御：当系统指令和用户输入在同一个字符串中时，用户可以通过精心构造的输入覆盖系统指令
3. Token 优化：系统指令通常是不变的，可以被缓存（Prompt Caching），而用户输入需要每次重新编码

2.2 ChatPromptTemplate：消息列表模板的完整形态

ChatPromptTemplate是 LangChain 中构建 Chat Prompt 的核心类。它的本质是一个消息模板列表，每条消息模板可以包含变量占位符（{variable_name}），在运行时被实际值替换。

构造方式的灵活设计：

ChatPromptTemplate 支持四种消息表示格式，这种设计体现了 LangChain 的"渐进式复杂度"哲学——简单场景用字符串，复杂场景用类型化对象：

fromlangchain_core.promptsimportChatPromptTemplate,MessagesPlaceholder# 方式一：2-tuple 格式（推荐日常使用）# (消息类型字符串, 模板字符串)template=ChatPromptTemplate([("system","你是 SmartWriter，专业的 AI 写作助手。"),("human","请写一篇关于 {topic} 的文章，大纲以 {format} 格式输出。"),])# 方式二：MessagesPlaceholder（插入历史对话）template=ChatPromptTemplate([("system","你是 SmartWriter，专业的 AI 写作助手。"),MessagesPlaceholder(variable_name="history"),# 运行时传入消息列表("human","{user_input}"),])# 方式三：纯字符串简写# 单条消息时，可以简化为一行template=ChatPromptTemplate.from_template("请写一篇关于 {topic} 的文章。")# 等价于 ChatPromptTemplate([("human", "请写一篇关于 {topic} 的文章。")])

2.3 Few-shot Prompting：示例驱动输出格式控制

Few-shot Prompting 的核心思想简单而强大：与其用文字描述"你输出的格式应该长这样"，不如直接给模型几个正确的输入-输出示例，让模型从示例中学习格式规则。

LangChain 将 Few-shot 机制工程化为两个核心组件：

Few-shot Prompting 的工程化架构： +-----------------------------------+ | FewShotChatMessagePromptTemplate | | | | +-----------------------------+ | | | ExampleSelector | | | | 根据输入动态选择最相关的示例 | | | +-----------------------------+ | | | | | v | | +-----------------------------+ | | | examples = [ | | | | {"input": "...", | | | | "output": "..."}, | | | | ... | | | | ] | | | +-----------------------------+ | | | | | v | | +-----------------------------+ | | | example_prompt | | | | 每个示例如何格式化为消息 | | | +-----------------------------+ | | | | | v | | 最终注入到 ChatPromptTemplate | | 中作为前缀消息 | +-----------------------------------+

Few-shot 的两种使用模式：

2.4 OutputParser 体系：从原始文本到结构化对象

OutputParser 是连接"模型的非结构化输出"和"应用的结构化数据"之间的桥梁。它的设计哲学是：不要让下游代码承担格式解析的职责——将格式定义、验证和修复封装在 Parser 层。

OutputParser 的工作流程： 模型输出（AIMessage） | v +------------------+ | OutputParser | | | | 1. 提取文本 | --> get_text(message) | 2. 格式验证 | --> validate_format(text) | 3. 结构化转换 | --> parse(text) -> StructuredObject | 4. 失败重试 | --> if fail: retry_with_feedback(error) +------------------+ | v 结构化对象（Pydantic Model / dict / str）

LangChain 提供三类核心 OutputParser，形成从简单到复杂的渐进体系：

OutputParser 选型决策树： 需要结构化输出吗？ | +-- 不需要 --> StrOutputParser | 返回纯文本字符串 | +-- 需要 --> 需要强类型验证吗？ | +-- 不需要 --> JsonOutputParser | 返回 dict，宽松验证 | +-- 需要 --> PydanticOutputParser 返回 Pydantic Model 实例 字段级类型验证 + 描述注入 Prompt

3. 核心模块/流程/机制详解

3.1 消息角色体系深度拆解

3.1.1 SystemMessage 的设计艺术

SystemMessage 是最容易被滥用的消息类型。许多开发者在这里塞入大量指令：“你是一个 XX 角色，你的风格是 XX，你要注意 XX，你不能 XX，当用户 XX 时你应该 XX…”——结果是一条 2000 字的系统消息，模型在前 500 Token 后就"注意力衰减"了。

优秀的 SystemMessage 应该遵循"三段式"结构：

# SmartWriter v0.2 的系统消息设计SMARTWRITER_SYSTEM_PROMPT="""\n【角色定义】 你是 SmartWriter，一个专业的 AI 写作助手。你的核心能力是： - 根据用户主题生成结构化的技术文章大纲 - 按规定格式输出内容（JSON 大纲 + Markdown 正文） - 保持技术准确性和逻辑连贯性 【行为约束】 - 大纲必须包含 title、sections（每个含 heading 和 key_points）字段 - 正文必须使用标准 Markdown 格式 - 不确定的技术细节标注 [需要验证]，不要编造 【输出规范】 - 先输出 JSON 大纲，再根据大纲逐节生成正文 - JSON 中不要包含注释或多余文本 """

三段式设计背后的认知心理学原理：

• 角色定义（Who）：建立模型的"身份锚点"，约占总篇幅的 30%
• 行为约束（How）：定义模型的"操作边界"，约占总篇幅的 30%
• 输出规范（What）：明确模型的"交付标准"，约占总篇幅的 40%

3.1.2 HumanMessage 的变量注入模式

HumanMessage 模板的核心是变量注入。LangChain 使用{variable_name}占位符语法，支持三种注入方式：

fromlangchain_core.promptsimportChatPromptTemplate template=ChatPromptTemplate.from_messages([("system",SMARTWRITER_SYSTEM_PROMPT),("human","请写一篇关于 {topic} 的技术文章，目标读者是 {audience}，""字数要求约 {word_count} 字，重点关注以下方面：{focus_points}"),])# invoke 时传入变量值prompt_value=template.invoke({"topic":"LangChain Output Parser 深度解析","audience":"有 Python 基础的后端开发者","word_count":"3000","focus_points":"PydanticOutputParser 的原理、常见坑和最佳实践",})

3.1.3 AIMessage 与 MessagesPlaceholder 的会话管理

在多轮写作对话中，AIMessage 和历史消息管理至关重要。MessagesPlaceholder 提供了灵活的历史消息注入机制：

fromlangchain_core.promptsimportChatPromptTemplate,MessagesPlaceholder# 带历史记录管理的写作 Promptwriting_prompt=ChatPromptTemplate.from_messages([("system",SMARTWRITER_SYSTEM_PROMPT),MessagesPlaceholder(variable_name="chat_history",optional=True),("human","{user_input}"),])# 模拟多轮写作对话chat_history=[HumanMessage(content="我想写一篇关于 Python 协程的文章"),AIMessage(content="好的！我建议从以下角度展开：1. 协程 vs 线程..."),HumanMessage(content="大纲可以，但我希望更侧重于 async/await 的实际用法"),AIMessage(content="明白了，我会调整大纲，增加更多的代码示例..."),]# 新一轮请求，带着完整的历史上下文result=writing_prompt.invoke({"chat_history"