关于作者
- 深耕领域:大语言模型开发 / RAG 知识库 / AI Agent 落地 / 模型微调
- 技术栈:Python | RAG (LangChain / Dify + Milvus) | FastAPI + Docker
- 工程能力:专注模型工程化部署、知识库构建与优化,擅长全流程解决方案
「让 AI 交互更智能,让技术落地更高效」
欢迎技术探讨与项目合作,解锁大模型与智能交互的无限可能!
LangChain Message 与 Prompt 模板系统
摘要
消息(Message)和提示词模板(Prompt Template)是 LangChain 中最基础也是最重要的概念。本文将深入解析 LangChain 的消息类型系统、提示词模板机制,以及如何通过外部文件(YAML、JSON、Markdown)管理提示词,帮助开发者构建可维护、可扩展的 AI 应用。
一、消息系统详解
1.1 消息类型概览
LangChain 定义了一套完整的消息类型系统,对应不同的对话角色:
1.2 核心消息类型
from langchain_core.messages import (
BaseMessage,
SystemMessage,
HumanMessage,
AIMessage,
ToolMessage,
FunctionMessage,
)
# 系统消息 - 设定 AI 的角色和行为
system_msg = SystemMessage(content="你是一个专业的 Python 开发助手。")
# 用户消息 - 用户的输入
user_msg = HumanMessage(content="如何实现一个单例模式?")
# AI 消息 - AI 的响应
ai_msg = AIMessage(content="单例模式可以通过以下方式实现...")
# 工具消息 - 工具调用的结果
tool_msg = ToolMessage(
content="文件已成功读取",
tool_call_id="call_abc123"
)
1.3 消息结构详解
from langchain_core.messages import BaseMessage, HumanMessage, AIMessage
from typing import Optional, Any
class BaseMessage:
"""
消息基类。
属性:
content: 消息内容(字符串或内容块列表)
additional_kwargs: 额外的元数据
response_metadata: 响应元数据(仅 AI 消息)
id: 消息唯一标识符
"""
content: str | list[dict]
additional_kwargs: dict = {}
response_metadata: dict = {}
id: Optional[str] = None
class HumanMessage(BaseMessage):
"""
用户消息。
支持多模态内容(文本 + 图片)。
"""
type: str = "human"
class AIMessage(BaseMessage):
"""
AI 响应消息。
额外属性:
tool_calls: 工具调用列表
invalid_tool_calls: 无效的工具调用
"""
type: str = "ai"
tool_calls: list[ToolCall] = []
1.4 多模态消息
from langchain_core.messages import HumanMessage
# 纯文本消息
text_msg = HumanMessage(content="描述这张图片")
# 多模态消息(文本 + 图片)
multimodal_msg = HumanMessage(content=[
{"type": "text", "text": "描述这张图片"},
{
"type": "image_url",
"image_url": {
"url": "https://example.com/image.jpg"
}
}
])
# 本地图片(Base64)
import base64
from pathlib import Path
def create_image_message(image_path: str, text: str) -> HumanMessage:
"""创建包含本地图片的消息。"""
image_data = base64.b64encode(Path(image_path).read_bytes()).decode()
return HumanMessage(content=[
{"type": "text", "text": text},
{
"type": "image_url",
"image_url": {
"url": f"data:image/jpeg;base64,{image_data}"
}
}
])
1.5 消息转换工具
from langchain_core.messages import convert_to_messages, get_buffer_string
# 从字典列表转换
messages_dict = [
{"role": "system", "content": "你是助手"},
{"role": "user", "content": "你好"},
{"role": "assistant", "content": "你好!"},
]
messages = convert_to_messages(messages_dict)
# [SystemMessage(...), HumanMessage(...), AIMessage(...)]
# 转换为字符串(用于调试)
message_str = get_buffer_string(messages)
# System: 你是助手
# Human: 你好
# AI: 你好!
二、提示词模板系统
2.1 模板类型概览
2.2 PromptTemplate - 字符串模板
from langchain_core.prompts import PromptTemplate
# 基础模板
template = PromptTemplate.from_template("给我讲一个关于{topic}的笑话")
# 填充变量
prompt = template.invoke({"topic": "程序员"})
print(prompt.text) # 给我讲一个关于程序员的笑话
# 带格式验证的模板
template = PromptTemplate(
template="你是一个{role},请帮我{task}",
input_variables=["role", "task"],
)
# 部分填充
partial_template = template.partial(role="Python 专家")
prompt = partial_template.invoke({"task": "优化这段代码"})
2.3 ChatPromptTemplate - 对话模板
from langchain_core.prompts import ChatPromptTemplate
# 方式一:从模板字符串创建
prompt = ChatPromptTemplate.from_messages([
("system", "你是一个{role},擅长{skill}"),
("human", "{question}"),
])
# 填充变量
messages = prompt.invoke({
"role": "Python 专家",
"skill": "代码优化",
"question": "如何优化列表推导式?"
})
# 方式二:使用消息模板类
from langchain_core.prompts import (
SystemMessagePromptTemplate,
HumanMessagePromptTemplate,
AIMessagePromptTemplate,
)
prompt = ChatPromptTemplate.from_messages([
SystemMessagePromptTemplate.from_template(
"你是一个{role},请用{style}风格回答"
),
HumanMessagePromptTemplate.from_template("{question}"),
AIMessagePromptTemplate.from_template("好的,让我想想..."),
HumanMessagePromptTemplate.from_template("{follow_up}"),
])
2.4 模板组合
from langchain_core.prompts import ChatPromptTemplate, PromptTemplate
# 组合多个模板
system_template = PromptTemplate.from_template(
"你是{company}的{role}"
)
task_template = PromptTemplate.from_template(
"请帮我完成以下任务: {task}"
)
# 组合成对话模板
full_prompt = ChatPromptTemplate.from_messages([
("system", system_template.template),
("human", task_template.template),
])
# 也可以使用管道操作符组合
from langchain_core.prompts import PipelinePromptTemplate
pipeline_prompt = PipelinePromptTemplate(
final_prompt=ChatPromptTemplate.from_messages([
("system", "{system_prompt}"),
("human", "{user_prompt}"),
]),
pipeline_prompts=[
("system_prompt", system_template),
("user_prompt", task_template),
]
)
2.5 高级模板特性
from langchain_core.prompts import ChatPromptTemplate
# 条件模板
prompt = ChatPromptTemplate.from_messages([
("system", "你是{role}。"),
("placeholder", "{history}"), # 可选的历史消息占位符
("human", "{question}"),
])
# 使用 MessagesPlaceholder 插入消息列表
from langchain_core.prompts import MessagesPlaceholder
prompt = ChatPromptTemplate.from_messages([
("system", "你是一个助手"),
MessagesPlaceholder("history"), # 插入对话历史
("human", "{question}"),
])
# 填充
messages = prompt.invoke({
"history": [
HumanMessage(content="你好"),
AIMessage(content="你好!"),
],
"question": "今天天气怎么样?"
})
三、外部文件管理提示词
3.1 为什么需要外部文件管理
| 优势 | 说明 |
|---|---|
| 可维护性 | 提示词与代码分离,便于修改 |
| 版本控制 | 提示词变更可追踪 |
| 多语言支持 | 不同语言的提示词文件 |
| A/B 测试 | 轻松切换不同提示词版本 |
| 团队协作 | 非技术人员也能修改提示词 |
3.2 YAML 格式提示词
提示词文件 prompts/assistant.yaml:
# AI 助手提示词配置
system_prompt:
template: |
你是一个{role},具有以下特点:
- 专业领域: {domain}
- 回答风格: {style}
- 语言: {language}
请根据用户的问题提供专业、准确的回答。
human_prompt:
template: |
{question}
# 默认变量值
default_values:
role: "AI 助手"
domain: "通用知识"
style: "简洁专业"
language: "中文"
# 示例对话
examples:
- question: "什么是机器学习?"
answer: "机器学习是人工智能的一个分支..."
- question: "Python 有什么优势?"
answer: "Python 具有语法简洁、生态丰富..."
加载器实现:
"""
YAML 提示词加载器。
支持从 YAML 文件加载提示词模板,包括:
- 系统提示词
- 用户提示词
- 默认变量值
- 示例对话
作者: LangChain 学习者
日期: 2026-02
"""
import yaml
from pathlib import Path
from typing import Any
from langchain_core.prompts import ChatPromptTemplate, PromptTemplate
from langchain_core.messages import HumanMessage, AIMessage
class YAMLPromptLoader:
"""
YAML 提示词加载器。
从 YAML 文件加载提示词配置,支持:
- 模板定义
- 默认变量值
- 示例对话
- 多语言支持
示例:
>>> loader = YAMLPromptLoader("prompts/assistant.yaml")
>>> prompt = loader.get_chat_prompt()
>>> messages = prompt.invoke({"question": "你好"})
"""
def __init__(self, file_path: str | Path):
"""
初始化加载器。
Args:
file_path: YAML 文件路径
"""
self.file_path = Path(file_path)
self._config: dict[str, Any] = {}
self._load()
def _load(self) -> None:
"""加载 YAML 配置。"""
with open(self.file_path, "r", encoding="utf-8") as f:
self._config = yaml.safe_load(f) or {}
@property
def system_template(self) -> str:
"""获取系统提示词模板。"""
return self._config.get("system_prompt", {}).get("template", "")
@property
def human_template(self) -> str:
"""获取用户提示词模板。"""
return self._config.get("human_prompt", {}).get("template", "{question}")
@property
def default_values(self) -> dict[str, Any]:
"""获取默认变量值。"""
return self._config.get("default_values", {})
@property
def examples(self) -> list[dict[str, str]]:
"""获取示例对话。"""
return self._config.get("examples", [])
def get_system_prompt(self) -> PromptTemplate:
"""获取系统提示词模板。"""
return PromptTemplate.from_template(self.system_template)
def get_human_prompt(self) -> PromptTemplate:
"""获取用户提示词模板。"""
return PromptTemplate.from_template(self.human_template)
def get_chat_prompt(self) -> ChatPromptTemplate:
"""
获取完整的对话提示词模板。
Returns:
ChatPromptTemplate 实例
"""
messages = []
# 系统提示词
if self.system_template:
messages.append(("system", self.system_template))
# 示例对话(可选)
if self.examples:
for example in self.examples:
messages.append(("human", example["question"]))
messages.append(("ai", example["answer"]))
# 用户提示词
messages.append(("human", self.human_template))
return ChatPromptTemplate.from_messages(messages)
def invoke(
self,
variables: dict[str, Any] | None = None,
**kwargs: Any
) -> list:
"""
填充模板并返回消息列表。
Args:
variables: 模板变量
**kwargs: 额外的模板变量
Returns:
消息列表
"""
# 合并默认值和传入的变量
all_vars = {**self.default_values, **(variables or {}), **kwargs}
prompt = self.get_chat_prompt()
return prompt.invoke(all_vars)
def get_few_shot_examples(self) -> list:
"""
获取少样本学习示例。
Returns:
消息列表
"""
examples = []
for example in self.examples:
examples.append(HumanMessage(content=example["question"]))
examples.append(AIMessage(content=example["answer"]))
return examples
3.3 JSON 格式提示词
提示词文件 prompts/assistant.json:
{
"name": "code_assistant",
"description": "代码助手提示词配置",
"version": "1.0.0",
"messages": [
{
"role": "system",
"template": "你是一个{language}编程专家,擅长{skill}。请用{style}风格回答问题。"
},
{
"role": "human",
"template": "{question}"
}
],
"variables": {
"language": {
"type": "string",
"default": "Python",
"description": "编程语言"
},
"skill": {
"type": "string",
"default": "代码优化和重构",
"description": "专业技能"
},
"style": {
"type": "string",
"default": "简洁专业",
"enum": ["简洁专业", "详细解释", "幽默风趣"],
"description": "回答风格"
}
},
"examples": [
{
"input": "如何优化这段代码?",
"output": "让我分析一下代码的性能瓶颈..."
}
]
}
加载器实现:
"""
JSON 提示词加载器。
支持从 JSON 文件加载提示词配置,包括:
- 消息模板列表
- 变量定义和默认值
- 示例对话
作者: LangChain 学习者
日期: 2026-02
"""
import json
from pathlib import Path
from typing import Any
from langchain_core.prompts import ChatPromptTemplate
class JSONPromptLoader:
"""
JSON 提示词加载器。
示例:
>>> loader = JSONPromptLoader("prompts/assistant.json")
>>> prompt = loader.get_chat_prompt()
>>> messages = prompt.invoke({"question": "你好"})
"""
def __init__(self, file_path: str | Path):
self.file_path = Path(file_path)
self._config: dict[str, Any] = {}
self._load()
def _load(self) -> None:
"""加载 JSON 配置。"""
with open(self.file_path, "r", encoding="utf-8") as f:
self._config = json.load(f)
@property
def name(self) -> str:
"""获取提示词名称。"""
return self._config.get("name", "unnamed")
@property
def description(self) -> str:
"""获取提示词描述。"""
return self._config.get("description", "")
@property
def variables(self) -> dict[str, Any]:
"""获取变量定义。"""
return self._config.get("variables", {})
def get_default_values(self) -> dict[str, Any]:
"""获取所有变量的默认值。"""
defaults = {}
for var_name, var_config in self.variables.items():
if "default" in var_config:
defaults[var_name] = var_config["default"]
return defaults
def get_chat_prompt(self) -> ChatPromptTemplate:
"""
获取对话提示词模板。
Returns:
ChatPromptTemplate 实例
"""
messages = []
for msg_config in self._config.get("messages", []):
role = msg_config["role"]
template = msg_config["template"]
messages.append((role, template))
return ChatPromptTemplate.from_messages(messages)
def invoke(
self,
variables: dict[str, Any] | None = None,
**kwargs: Any
) -> list:
"""
填充模板并返回消息列表。
Args:
variables: 模板变量
**kwargs: 额外的模板变量
Returns:
消息列表
"""
defaults = self.get_default_values()
all_vars = {**defaults, **(variables or {}), **kwargs}
prompt = self.get_chat_prompt()
return prompt.invoke(all_vars)
def validate_variables(self, variables: dict[str, Any]) -> list[str]:
"""
验证变量是否符合定义。
Args:
variables: 要验证的变量
Returns:
错误消息列表
"""
errors = []
for var_name, var_config in self.variables.items():
# 检查必需变量
if var_name not in variables and "default" not in var_config:
errors.append(f"缺少必需变量: {var_name}")
continue
value = variables.get(var_name, var_config.get("default"))
# 检查枚举值
if "enum" in var_config and value not in var_config["enum"]:
errors.append(
f"变量 {var_name} 的值 '{value}' 不在允许的枚举值中: {var_config['enum']}"
)
# 检查类型
if "type" in var_config:
expected_type = var_config["type"]
if expected_type == "string" and not isinstance(value, str):
errors.append(f"变量 {var_name} 应该是字符串类型")
elif expected_type == "integer" and not isinstance(value, int):
errors.append(f"变量 {var_name} 应该是整数类型")
return errors
3.4 Markdown 格式提示词
提示词文件 prompts/assistant.md:
# Python 代码助手
## 系统提示词
你是一个 {language} 编程专家,具有以下能力:
- {skill_1}
- {skill_2}
请用 {style} 风格回答问题。
## 用户提示词
{question}
## 示例
### 示例 1
**用户**: 如何实现一个装饰器?
**助手**: 装饰器是 Python 的高级特性,可以用来修改函数行为...
### 示例 2
**用户**: 什么是列表推导式?
**助手**: 列表推导式是 Python 中创建列表的简洁方式...
加载器实现:
"""
Markdown 提示词加载器。
支持从 Markdown 文件加载提示词,通过章节解析:
- 系统提示词
- 用户提示词
- 示例对话
作者: LangChain 学习者
日期: 2026-02
"""
import re
from pathlib import Path
from typing import Any
from langchain_core.prompts import ChatPromptTemplate
from langchain_core.messages import HumanMessage, AIMessage
class MarkdownPromptLoader:
"""
Markdown 提示词加载器。
通过解析 Markdown 章节来提取提示词模板。
示例:
>>> loader = MarkdownPromptLoader("prompts/assistant.md")
>>> prompt = loader.get_chat_prompt()
"""
def __init__(self, file_path: str | Path):
self.file_path = Path(file_path)
self._content = ""
self._load()
def _load(self) -> None:
"""加载 Markdown 文件。"""
self._content = self.file_path.read_text(encoding="utf-8")
def _extract_section(self, heading: str) -> str:
"""
提取指定章节的内容。
Args:
heading: 章节标题
Returns:
章节内容
"""
pattern = rf"## {heading}\s*\n(.*?)(?=\n## |\Z)"
match = re.search(pattern, self._content, re.DOTALL)
return match.group(1).strip() if match else ""
@property
def system_template(self) -> str:
"""获取系统提示词模板。"""
return self._extract_section("系统提示词")
@property
def human_template(self) -> str:
"""获取用户提示词模板。"""
content = self._extract_section("用户提示词")
return content if content else "{question}"
def get_examples(self) -> list[dict[str, str]]:
"""
提取示例对话。
Returns:
示例列表
"""
examples = []
# 匹配示例章节
example_pattern = r"### 示例 \d+\s*\n(.*?)(?=\n### 示例 |\n## |\Z)"
example_sections = re.findall(example_pattern, self._content, re.DOTALL)
for section in example_sections:
# 提取用户问题
user_match = re.search(r"\*\*用户\*\*:\s*(.*?)\n", section)
# 提取助手回答
assistant_match = re.search(r"\*\*助手\*\*:\s*(.*?)\Z", section, re.DOTALL)
if user_match and assistant_match:
examples.append({
"question": user_match.group(1).strip(),
"answer": assistant_match.group(1).strip()
})
return examples
def get_chat_prompt(self) -> ChatPromptTemplate:
"""
获取对话提示词模板。
Returns:
ChatPromptTemplate 实例
"""
messages = []
# 系统提示词
if self.system_template:
messages.append(("system", self.system_template))
# 示例对话
for example in self.get_examples():
messages.append(("human", example["question"]))
messages.append(("ai", example["answer"]))
# 用户提示词
messages.append(("human", self.human_template))
return ChatPromptTemplate.from_messages(messages)
def invoke(
self,
variables: dict[str, Any] | None = None,
**kwargs: Any
) -> list:
"""填充模板并返回消息列表。"""
all_vars = {**(variables or {}), **kwargs}
prompt = self.get_chat_prompt()
return prompt.invoke(all_vars)
四、统一提示词管理器
4.1 多格式支持
"""
统一提示词管理器。
支持多种格式的提示词文件:
- YAML (.yaml, .yml)
- JSON (.json)
- Markdown (.md)
作者: LangChain 学习者
日期: 2026-02
"""
from pathlib import Path
from typing import Any
from langchain_core.prompts import ChatPromptTemplate
class PromptManager:
"""
统一提示词管理器。
自动识别文件格式并加载提示词。
示例:
>>> manager = PromptManager("prompts/")
>>> prompt = manager.load("assistant")
>>> messages = prompt.invoke({"question": "你好"})
"""
LOADERS = {
".yaml": "YAMLPromptLoader",
".yml": "YAMLPromptLoader",
".json": "JSONPromptLoader",
".md": "MarkdownPromptLoader",
}
def __init__(self, prompts_dir: str | Path):
"""
初始化提示词管理器。
Args:
prompts_dir: 提示词文件目录
"""
self.prompts_dir = Path(prompts_dir)
self._cache: dict[str, Any] = {}
def _get_loader(self, file_path: Path):
"""获取对应的加载器。"""
suffix = file_path.suffix.lower()
loader_name = self.LOADERS.get(suffix)
if loader_name == "YAMLPromptLoader":
from langchain_prompts.yaml_loader import YAMLPromptLoader
return YAMLPromptLoader(file_path)
elif loader_name == "JSONPromptLoader":
from langchain_prompts.json_loader import JSONPromptLoader
return JSONPromptLoader(file_path)
elif loader_name == "MarkdownPromptLoader":
from langchain_prompts.markdown_loader import MarkdownPromptLoader
return MarkdownPromptLoader(file_path)
raise ValueError(f"不支持的文件格式: {suffix}")
def load(self, name: str) -> ChatPromptTemplate:
"""
加载提示词模板。
Args:
name: 提示词名称(不含扩展名)
Returns:
ChatPromptTemplate 实例
"""
if name in self._cache:
return self._cache[name].get_chat_prompt()
# 查找文件
for ext in self.LOADERS.keys():
file_path = self.prompts_dir / f"{name}{ext}"
if file_path.exists():
loader = self._get_loader(file_path)
self._cache[name] = loader
return loader.get_chat_prompt()
raise FileNotFoundError(f"未找到提示词文件: {name}")
def invoke(
self,
name: str,
variables: dict[str, Any] | None = None,
**kwargs: Any
) -> list:
"""
加载并填充提示词。
Args:
name: 提示词名称
variables: 模板变量
**kwargs: 额外的模板变量
Returns:
消息列表
"""
if name not in self._cache:
self.load(name)
return self._cache[name].invoke(variables, **kwargs)
def list_prompts(self) -> list[str]:
"""
列出所有可用的提示词。
Returns:
提示词名称列表
"""
prompts = set()
for file_path in self.prompts_dir.iterdir():
if file_path.suffix.lower() in self.LOADERS:
prompts.add(file_path.stem)
return sorted(prompts)
4.2 使用示例
import asyncio
from pathlib import Path
from langchain_openai import ChatOpenAI
async def main():
# 初始化提示词管理器
manager = PromptManager(Path("./prompts"))
# 列出所有提示词
print("可用提示词:", manager.list_prompts())
# 加载并使用提示词
messages = manager.invoke(
"assistant",
language="Python",
skill_1="代码优化",
skill_2="调试排错",
style="简洁专业",
question="如何实现一个单例模式?"
)
# 调用 LLM
llm = ChatOpenAI(model="gpt-4o")
response = await llm.ainvoke(messages)
print(response.content)
if __name__ == "__main__":
asyncio.run(main())
五、项目目录结构
project/
├── prompts/ # 提示词目录
│ ├── assistant.yaml # YAML 格式
│ ├── code_review.json # JSON 格式
│ └── translator.md # Markdown 格式
├── src/
│ └── langchain_prompts/
│ ├── __init__.py
│ ├── manager.py # 提示词管理器
│ ├── yaml_loader.py # YAML 加载器
│ ├── json_loader.py # JSON 加载器
│ └── markdown_loader.py # Markdown 加载器
└── main.py
六、最佳实践
6.1 提示词版本管理
# prompts/assistant_v2.yaml
version: "2.0.0"
changes:
- 添加了多语言支持
- 优化了系统提示词结构
system_prompt:
template: |
你是一个{role}...
6.2 多语言支持
prompts/
├── en/
│ └── assistant.yaml
├── zh/
│ └── assistant.yaml
└── ja/
└── assistant.yaml
manager = PromptManager(f"prompts/{language}/")
6.3 提示词测试
def test_prompt_template():
"""测试提示词模板。"""
loader = YAMLPromptLoader("prompts/assistant.yaml")
# 测试变量提取
prompt = loader.get_chat_prompt()
input_variables = prompt.input_variables
# 测试填充
messages = loader.invoke({"question": "测试问题"})
assert len(messages) > 0
七、总结
| 格式 | 优势 | 适用场景 |
|---|---|---|
| YAML | 可读性好、支持多行字符串 | 复杂提示词、带默认值 |
| JSON | 结构化、易于验证 | API 集成、变量校验 |
| Markdown | 直观、易于编写文档 | 简单提示词、示例展示 |
通过外部文件管理提示词,可以实现:
| 目标 | 实现方式 |
|---|---|
| 可维护性 | 提示词与代码分离 |
| 版本控制 | Git 追踪变更 |
| 团队协作 | 非技术人员可编辑 |
| A/B 测试 | 多版本提示词文件 |
| 国际化 | 多语言目录结构 |
358



被折叠的 条评论
为什么被折叠?



