【LangChain】langchain_core.messages.SystemMessage 类：表示系统消息的核心类

于 2025-05-16 10:17:55 发布
阅读量685 收藏 10
点赞数 18
分类专栏： LangChain 文章标签： langchain langchain_core messages SystemMessage
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
本文链接：https://blog.csdn.net/u013172930/article/details/147994853
版权

langchain_core.messages.SystemMessage 是 LangChain 库中用于表示系统消息的核心类，隶属于 langchain_core.messages 模块。它继承自 BaseMessage，专门用于向语言模型提供初始指令或上下文，以定义模型的行为、语气或角色。SystemMessage 通常作为对话的首个消息，广泛应用于聊天机器人、代理和检索增强生成（RAG）等场景。

以下是对 SystemMessage 的详细介绍，涵盖其定义、功能、属性、方法、使用方式、应用场景、优化建议和注意事项，全部用中文回答，内容结构化且清晰，适合初学者和进阶用户。

1. 什么是 SystemMessage？

SystemMessage 是一个消息类，用于封装系统级指令或上下文，告诉语言模型如何处理后续对话。例如，它可以指定模型的角色（如“你是一个量子计算专家”）或设置回答风格（如“简洁回答”）。SystemMessage 的设计目标是：

  • 定义模型行为：通过指令或上下文引导模型的响应方式。
  • 标准化系统输入：提供结构化格式，确保模型正确理解指令。
  • 支持序列化：支持 JSON 序列化和反序列化，便于存储或传输。
  • 维持对话一致性：作为对话历史的起点，确保响应符合预期。

背景：

  • 在 LangChain 中，对话由消息列表（List[BaseMessage]）组成，传递给聊天模型（如 ChatOpenAI）。
  • SystemMessage 的 role 固定为 "system"，明确标识消息为系统指令。
  • 它在 LangChain 0.1.20 及以上版本中稳定支持，尤其在 0.2.17 版本中有详细文档。

简单比喻：
可以将 SystemMessage 想象为导演对演员的“开场指导”，在对话开始前告诉 AI 它的角色和表演方式，例如“扮演一个友好的助手”。

2. 核心功能

SystemMessage 提供了以下主要功能：

  1. 设置对话上下文：
    • 提供初始指令或背景，如“你是一个量子计算专家，回答要简洁”。
    • 示例：SystemMessage(content="你是一个旅行助手，专注于国际旅行。")。
  2. 引导模型行为：
    • 指定模型的语气、风格或角色，确保响应一致。
    • 示例：设置“正式”或“幽默”的回答风格。
  3. 支持多模态内容（有限）：
    • 虽然主要处理文本，content 理论上可包含多模态数据（如图像），但需模型支持。
    • 示例：content=[{"type": "text", "text": "分析图片"}]（需特定模型支持）。
  4. 序列化与反序列化：
    • 支持将消息转换为 JSON 格式，或从 JSON 还原，便于存储对话历史。
    • 示例：将系统指令保存到数据库。
  5. 元数据支持：
    • 通过 additional_kwargs 存储额外信息，如时间戳或会话标识。
    • 示例：additional_kwargs={"session_id": "sess_001"}。
  6. 对话初始化：
    • 通常作为消息列表的首个元素，初始化对话上下文。
    • 示例：多轮对话中，SystemMessage 定义模型的整体行为。

特点：

  • 标准化：提供统一的指令格式，兼容多种模型（如 OpenAI、Anthropic）。
  • 灵活性：支持简单和复杂指令，适应不同场景。
  • 类型安全：使用 Pydantic 模型，确保字段验证和类型一致性。
  • 模块化：与 LangChain 的聊天模型、代理、记忆等模块无缝集成。

3. 核心属性与方法

核心属性

SystemMessage 继承自 BaseMessage，包含以下主要属性：

属性类型描述示例
contentUnion[str, List[Union[str, Dict]]]消息内容，通常为指令或上下文，也可为多模态数据（需模型支持）。"你是一个量子计算专家。" 或 [{"type": "text", "text": "分析图片"}]
rolestr消息角色，固定为 "system"，标识系统指令。"system"
typestr消息类型，固定为 "system"，用于序列化。"system"
additional_kwargsDict[str, Any]附加元数据，如时间戳或会话 ID，通常为空。{"timestamp": "2025-05-15"}
examplebool是否为示例对话的一部分，默认 False，通常被忽略。False
idOptional[str]可选的消息唯一标识符，通常由模型或提供商生成。"msg_001"
nameOptional[str]可选的人类可读名称，依赖模型实现，通常不使用。"SystemInstruction"
response_metadataDict响应元数据，如头部信息或 token 计数，通常为空。{"headers": {}}

属性说明：

  • content：核心字段，存储系统指令。字符串适用于文本指令，列表适用于多模态输入（较少使用）。
  • role 和 type：固定值，确保消息被正确识别为系统指令。
  • additional_kwargs：提供扩展性，通常用于存储元数据，但需谨慎使用以避免敏感信息泄露。
  • example：早期设计用于标记示例对话，但目前大多数模型忽略此字段。
  • id 和 name：可选字段，适合需要跟踪或命名指令的场景，但不常用于 SystemMessage。
  • response_metadata：通常为空，仅在特定场景（如模型返回元数据）中使用。
核心方法

SystemMessage 继承了 BaseMessage 的方法，以下是主要方法：

方法描述输入输出示例
to_json将消息序列化为 JSON 格式。无Dictmessage.to_json()
from_json从 JSON 还原消息对象（类方法）。DictSystemMessageSystemMessage.from_json(json_data)
__str__返回消息的字符串表示，便于调试。无strstr(message)
__eq__比较两个消息是否相等。SystemMessageboolmessage1 == message2

方法说明：

  • to_json 和 from_json：支持消息存储和传输，常用于对话历史的持久化。
  • __str__：提供人类可读的表示，适合日志记录或调试。
  • __eq__：用于比较消息内容，通常在测试或验证中应用。

4. 使用方式与代码示例

以下是通过代码示例展示 SystemMessage 的使用方式，涵盖基本创建、与聊天模型集成、多模态输入（有限）、序列化和代理工作流等场景。

示例 1：基本 SystemMessage 创建

创建一个简单的 SystemMessage 表示系统指令：

from langchain_core.messages import SystemMessage

# 创建 SystemMessage
system_message = SystemMessage(content="你是一个量子计算专家，回答要简洁。")

# 打印消息
print(system_message)

输出：

content='你是一个量子计算专家，回答要简洁。' role='system' additional_kwargs={}

说明：

  • content 存储系统指令。
  • role 固定为 "system"，标识消息为系统指令。
示例 2：与聊天模型集成

结合 SystemMessage 和 HumanMessage 调用聊天模型：

from langchain_core.messages import HumanMessage, SystemMessage
from langchain_openai import ChatOpenAI
import os
import getpass

# 配置 API 密钥
if not os.environ.get("OPENAI_API_KEY"):
    os.environ["OPENAI_API_KEY"] = getpass.getpass("请输入 OpenAI API 密钥：")

# 初始化模型
llm = ChatOpenAI(model="gpt-4o", temperature=0.7)

# 创建消息
messages = [
    SystemMessage(content="你是一个量子计算专家，回答要简洁。"),
    HumanMessage(content="量子计算的最新进展是什么？")
]

# 调用模型
response = llm.invoke(messages)
print(response.content)

输出：

量子计算的最新进展包括超导量子比特的突破和量子纠错技术的改进。

说明：

  • SystemMessage 设置模型角色和回答风格。
  • HumanMessage 表示用户提问。
  • 消息列表传递给模型生成响应。
示例 3：多模态输入（有限支持）

处理多模态指令（需支持多模态的模型，如 GPT-4o）：

from langchain_core.messages import SystemMessage
from langchain_openai import ChatOpenAI

# 初始化模型
llm = ChatOpenAI(model="gpt-4o", api_key="your-openai-key")

# 创建多模态 SystemMessage
messages = [
    SystemMessage(content=[
        {"type": "text", "text": "你是一个图像分析专家，描述图片内容。"},
        {"type": "image_url", "image_url": {"url": "https://example.com/quantum.jpg"}}
    ]),
    HumanMessage(content="这张图片是什么？")
]

# 调用模型
response = llm.invoke(messages)
print(response.content)

输出（假设图片可用）：

图片显示一台量子计算机的实验设备，周围有冷却装置和控制面板。

说明：

  • content 为列表，包含文本和图像 URL（较少使用）。
  • 仅支持多模态模型，且 SystemMessage 的多模态支持有限。
示例 4：序列化与反序列化

将 SystemMessage 序列化为 JSON 并还原：

from langchain_core.messages import SystemMessage

# 创建 SystemMessage
message = SystemMessage(
    content="你是一个旅行助手，专注于国际旅行。",
    additional_kwargs={"session_id": "sess_001"}
)

# 序列化为 JSON
json_data = message.to_json()
print(json_data)

# 从 JSON 还原
restored_message = SystemMessage.from_json(json_data)
print(restored_message.content, restored_message.additional_kwargs)

输出：

{'type': 'system', 'content': '你是一个旅行助手，专注于国际旅行。', 'additional_kwargs': {'session_id': 'sess_001'}}
你是一个旅行助手，专注于国际旅行。 {'session_id': 'sess_001'}

说明：

  • to_json 生成 JSON 表示，适合存储。
  • from_json 还原为 SystemMessage 实例。
示例 5：结合代理

在代理工作流中使用 SystemMessage：

from langchain_openai import ChatOpenAI
from langchain_core.messages import HumanMessage, SystemMessage
from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder
from langchain.agents import create_openai_tools_agent, AgentExecutor
from langchain_core.tools import Tool
from langchain_core.callbacks import StdOutCallbackHandler
from langchain_core.runnables import RunnableConfig
import os
import getpass

# 配置 API 密钥
if not os.environ.get("OPENAI_API_KEY"):
    os.environ["OPENAI_API_KEY"] = getpass.getpass("请输入 OpenAI API 密钥：")

# 定义工具
def search_web(query: str) -> str:
    return f"搜索结果：{query} 的最新信息..."

search_tool = Tool(name="SearchWeb", func=search_web, description="搜索网络信息")

# 初始化模型
llm = ChatOpenAI(model="gpt-4o", temperature=0)

# 设置提示模板
prompt = ChatPromptTemplate.from_messages([
    SystemMessage(content="你是一个研究助手，擅长搜索信息，回答要简洁。"),
    MessagesPlaceholder(variable_name="messages"),
    MessagesPlaceholder(variable_name="agent_scratchpad")
])

# 创建代理
agent = create_openai_tools_agent(llm, [search_tool], prompt)
agent_executor = AgentExecutor(agent=agent, tools=[search_tool], verbose=True)

# 配置 RunnableConfig
config = RunnableConfig(callbacks=[StdOutCallbackHandler()], max_iterations=3)

# 创建消息
messages = [HumanMessage(content="量子计算的最新进展是什么？")]

# 执行任务
response = agent_executor.invoke({"messages": messages}, config=config)
print(response["output"])

输出：

[AgentExecutor] 正在执行...
[Tool: SearchWeb] 输入：量子计算的最新进展
[Tool Output] 搜索结果：量子计算的最新信息...
[Final Answer] 量子计算的最新进展包括超导量子比特的突破...

说明：

  • SystemMessage 在提示模板中设置代理行为。
  • 代理根据 HumanMessage 调用搜索工具并生成响应。

5. 应用场景

SystemMessage 在以下场景中广泛应用：

  1. 聊天机器人：
    • 设置聊天机器人的角色或语气，如“友好”或“专业”。
    • 示例：SystemMessage(content="你是一个友好的助手，名叫小明。")。
  2. 代理工作流：
    • 为代理提供指令，如“使用工具搜索信息”。
    • 示例：代理根据 SystemMessage 调用搜索工具。
  3. 检索增强生成（RAG）：
    • 设置 RAG 系统的上下文，如“根据检索文档回答”。
    • 示例：SystemMessage(content="仅使用提供的文档回答问题。")。
  4. 多模态交互（有限）：
    • 为多模态模型提供指令，如“分析图片内容”。
    • 示例：SystemMessage 设置图像分析任务（需模型支持）。
  5. 对话记忆：
    • 结合 ConversationBufferMemory 存储系统指令。
    • 示例：维护多轮对话的上下文。
  6. 自定义角色：
    • 定义特定角色，如“旅行助手”或“技术专家”。
    • 示例：SystemMessage(content="你是一个国际旅行专家。")。

6. 优化建议

以下是使用 SystemMessage 时的优化建议，帮助提高效率和可靠性：

(1) 内容管理
  • 保持指令简洁：避免过长的 content，以减少 token 消耗。
if len(message.content) > 500:
    raise ValueError("系统指令过长")
  • 清晰明确：使用直接的语言，如“简洁回答”而非“尽量简短”。
system_message = SystemMessage(content="回答问题时保持简洁，每句不超过 20 字。")
(2) 元数据优化
  • 谨慎使用 additional_kwargs：仅存储必要元数据，避免敏感信息。
message = SystemMessage(content="你是一个助手", additional_kwargs={"session_id": "sess_001"})
  • 验证输入：防止注入攻击，检查指令内容。
if "<script>" in message.content:
    raise ValueError("指令包含不安全内容")
(3) 性能优化
  • 异步调用：结合异步模型调用处理高并发。
response = await llm.ainvoke(messages)
  • 批量序列化：减少 I/O 开销。
json_data = [msg.to_json() for msg in messages]
(4) 监控与调试
  • 使用回调：记录 SystemMessage 的处理过程。
from langchain_core.callbacks import BaseCallbackHandler
class MessageCallback(BaseCallbackHandler):
    def on_chat_model_start(self, serialized, messages, **kwargs):
        print(f"系统消息：{messages[0].content}")
config = {"callbacks": [MessageCallback()]}
  • 结合 LangSmith：分析消息流和性能。
from langsmith import Client
config = {"callbacks": [Client(api_key="your-langsmith-key")]}
(5) 上下文优化
  • 动态指令：根据任务调整 content，添加上下文。
from datetime import datetime
system_message = SystemMessage(content=f"今天是 {datetime.now().strftime('%Y-%m-%d')}，回答旅行问题。")
  • 多模态谨慎使用：仅在必要时使用多模态指令，检查模型支持。
if not model_supports_multimodal:
    message.content = message.content[0]["text"]  # 仅保留文本

7. 注意事项

以下是使用 SystemMessage 时需要注意的关键点：

  • 模型兼容性：
    • 不同模型对系统消息的处理方式可能不同（如通过消息列表或单独 API 参数）。
    • 示例：检查 OpenAI 或 Anthropic 的文档确认支持方式。
  • Token 限制：
    • 过长的 content 或过多消息可能超过模型的 token 限制。
    • 示例：使用截断或简化指令。
if len(message.content) > 1000:
    message.content = message.content[:1000]
  • 序列化安全：
    • 确保 JSON 数据格式正确，避免反序列化错误。
try:
    msg = SystemMessage.from_json(json_data)
except ValueError as e:
    print(f"反序列化失败：{e}")
  • 安全性：
    • 避免在 content 或 additional_kwargs 中包含敏感信息。
    • 验证指令内容，防止意外行为。
if any(char in message.content for char in ["<", ">", "&"]):
    raise ValueError("指令包含潜在危险字符")
  • 版本兼容性：
    • 确保 LangChain 版本 >= 0.1.20，以获得完整的 SystemMessage 支持。
    • 检查 0.2.17 文档确认最新功能。
  • Example 字段：
    • example 字段通常被忽略，避免使用以免混淆。
    • 示例：始终设置 example=False 或忽略。
  • 多模态支持：
    • 多模态指令（如图像）支持有限，仅适用于特定模型（如 GPT-4o）。

8. 与 LangChain 生态的结合

SystemMessage 与 LangChain 生态中的其他组件紧密集成，以下是主要结合点：

  • 聊天模型（Chat Models）：
    • SystemMessage 作为对话历史的一部分，传递给 BaseChatModel 实例（如 ChatOpenAI）。
    llm.invoke(messages)
  • 代理（Agents）：
    • SystemMessage 为代理提供指令，引导工具调用或推理。
    agent.invoke({"messages": [SystemMessage(content="使用工具搜索"), HumanMessage(content="搜索新闻")]})
  • 提示模板（Prompt Templates）：
    • 使用 ChatPromptTemplate 管理包含 SystemMessage 的对话。
    from langchain_core.prompts import ChatPromptTemplate
prompt = ChatPromptTemplate.from_messages([("system", "{instruction}"), ("human", "{input}")])
  • 记忆（Memory）：
    • 结合 ConversationBufferMemory 存储 SystemMessage。
    from langchain.memory import ConversationBufferMemory
memory = ConversationBufferMemory(return_messages=True)
memory.save_context({"system": "你是一个助手"}, {"output": response})
  • 回调（Callbacks）：
    • 使用 RunnableConfig 配置回调，监控 SystemMessage 处理。
    from langchain_core.callbacks import StdOutCallbackHandler
config = {"callbacks": [StdOutCallbackHandler()]}

9. 综合示例：代理与系统指令

以下是一个结合 SystemMessage、代理和工具调用的完整示例：

from langchain_openai import ChatOpenAI
from langchain_core.messages import HumanMessage, SystemMessage
from langchain_core.prompts import ChatPromptTemplate, MessagesPlaceholder
from langchain.agents import create_openai_tools_agent, AgentExecutor
from langchain_core.tools import Tool
from langchain_core.callbacks import StdOutCallbackHandler
from langchain_core.runnables import RunnableConfig
import os
import getpass

# 配置 API 密钥
if not os.environ.get("OPENAI_API_KEY"):
    os.environ["OPENAI_API_KEY"] = getpass.getpass("请输入 OpenAI API 密钥：")

# 定义工具
def search_web(query: str) -> str:
    return f"搜索结果：{query} 的最新信息..."

search_tool = Tool(name="SearchWeb", func=search_web, description="搜索网络信息")

# 初始化模型
llm = ChatOpenAI(model="gpt-4o", temperature=0)

# 设置提示模板
prompt = ChatPromptTemplate.from_messages([
    SystemMessage(content="你是一个研究助手，擅长搜索信息，回答要简洁且准确。"),
    MessagesPlaceholder(variable_name="messages"),
    MessagesPlaceholder(variable_name="agent_scratchpad")
])

# 创建代理
agent = create_openai_tools_agent(llm, [search_tool], prompt)
agent_executor = AgentExecutor(agent=agent, tools=[search_tool], verbose=True)

# 配置 RunnableConfig
config = RunnableConfig(callbacks=[StdOutCallbackHandler()], max_iterations=3)

# 创建消息
messages = [HumanMessage(content="量子计算的最新进展是什么？")]

# 执行任务
response = agent_executor.invoke({"messages": messages}, config=config)
print(response["output"])

输出：

[AgentExecutor] 正在执行...
[Tool: SearchWeb] 输入：量子计算的最新进展
[Tool Output] 搜索结果：量子计算的最新信息...
[Final Answer] 量子计算的最新进展包括超导量子比特的突破和量子纠错技术的改进。

说明：

  • SystemMessage 设置代理的行为和回答风格。
  • 代理根据 HumanMessage 调用搜索工具并生成响应。

10. 学习资源

11. 总结

  • 定义：SystemMessage 是 LangChain 中用于封装系统指令或上下文的消息类，继承自 BaseMessage。
  • 核心属性：
    • content：指令内容（字符串或多模态）。
    • role 和 type：固定为 "system"。
    • additional_kwargs、example、id、name、response_metadata：可选字段。
  • 核心方法：
    • to_json、from_json：序列化/反序列化。
    • __str__、__eq__：字符串表示和比较。
  • 功能：设置对话上下文、引导模型行为、支持序列化、初始化对话。
  • 应用场景：聊天机器人、代理工作流、RAG、多模态交互、对话记忆、自定义角色。
  • 优化建议：内容管理、元数据优化、性能优化、监控与调试、上下文优化。
  • 注意事项：模型兼容性、token 限制、序列化安全、安全性、版本兼容性、example 字段、多模态支持。
评论
添加红包

请填写红包祝福语或标题

个

红包个数最小为10个

元

红包金额最低5元

当前余额3.43元 前往充值 >
需支付：10.00元
成就一亿技术人!
领取后你会自动成为博主和红包主的粉丝 规则
hope_wisdom
发出的红包

打赏作者

彬彬侠

你的鼓励将是我创作的最大动力

¥1 ¥2 ¥4 ¥6 ¥10 ¥20
扫码支付：¥1
获取中
扫码支付

您的余额不足，请更换扫码支付或充值

打赏作者

实付元
使用余额支付
点击重新获取
扫码支付
钱包余额 0

抵扣说明：

1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

余额充值