【LangChain】langchain_core.messages.HumanMessage 类：人类用户输入消息的核心类

最新推荐文章于 2025-05-19 10:20:36 发布

彬彬侠

最新推荐文章于 2025-05-19 10:20:36 发布

阅读量1k

点赞数 29

分类专栏： LangChain 文章标签： langchain langchain_core messages HumanMessage

本文链接：https://blog.csdn.net/u013172930/article/details/147994727

版权

LangChain 专栏收录该内容

157 篇文章

订阅专栏

关于 `langchain_core.messages.HumanMessage`

langchain_core.messages.HumanMessage 是 LangChain 库中用于表示人类用户输入消息的核心类，隶属于 langchain_core.messages 模块。它继承自 BaseMessage，专门用于封装用户在对话中的输入，如提问或指令，以便语言模型（如聊天模型）能够正确处理。HumanMessage 是 LangChain 对话系统的基础组件，广泛应用于聊天机器人、代理和检索增强生成（RAG）等场景。

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

1. 什么是 `HumanMessage`？

HumanMessage 是一个消息类，用于表示人类用户发送的输入，例如问题、命令或评论。它在 LangChain 的对话工作流中起到关键作用，帮助模型区分用户输入、系统指令（SystemMessage）和模型响应（AIMessage）。HumanMessage 的设计目标是：

标准化用户输入：将用户输入封装为结构化消息，方便模型处理。
支持多模态：支持文本和多模态内容（如图像），具体取决于模型能力。
维持对话上下文：作为对话历史的一部分，确保多轮对话的连贯性。
序列化支持：支持 JSON 序列化和反序列化，便于存储或传输。

背景：

在 LangChain 中，对话通常由消息列表（List[BaseMessage]）组成，传递给聊天模型（如 ChatOpenAI）。
HumanMessage 的 role 固定为 "human"，明确标识消息来源为用户。
它在 LangChain 0.1.20 及以上版本中稳定支持，广泛应用于各种 AI 应用。

简单比喻：
可以将 HumanMessage 想象为用户写给 AI 的“便条”，内容是用户的提问或指令，附带一些元数据（如时间戳），便于 AI 理解和回应。

2. 核心功能

HumanMessage 提供了以下主要功能：

封装用户输入：
- 将用户输入（如“量子计算是什么？”）存储在 content 字段，供模型处理。
- 示例：用户提问存储为 HumanMessage(content="你好！今天是星期几？")。
角色标识：
- 固定 role="human"，帮助模型区分消息来源，维护对话上下文。
- 示例：模型根据 human 角色知道这是用户提问，而非系统指令。
支持多模态内容：
- content 可以是字符串或包含文本和图像的列表，适用于支持多模态的模型（如 GPT-4o）。
- 示例：content=[{"type": "text", "text": "描述这张图片"}, {"type": "image_url", "image_url": {...}}]。
序列化与反序列化：
- 支持将消息转换为 JSON 格式，或从 JSON 还原，便于存储对话历史或跨系统传输。
- 示例：将消息保存到数据库或从日志中恢复。
元数据支持：
- 通过 additional_kwargs 存储额外信息，如用户 ID、时间戳或会话标识。
- 示例：additional_kwargs={"user_id": "user_001"}。
对话历史：
- 作为消息列表的一部分，传递给模型或代理，确保对话连贯。
- 示例：多轮对话中，HumanMessage 记录用户每次输入。

特点：

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

3. 核心属性与方法

核心属性

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

属性	类型	描述	示例
`content`	`Union[str, List[Union[str, Dict]]]`	消息内容，通常为字符串，也可为多模态数据（如文本+图像）。	`"量子计算是什么？"` 或 `[{"type": "text", "text": "描述图片"}]`
`role`	`str`	消息角色，固定为 `"human"`，标识用户输入。	`"human"`
`type`	`str`	消息类型，固定为 `"human"`，用于序列化。	`"human"`
`additional_kwargs`	`Dict[str, Any]`	附加元数据，如时间戳或用户 ID，通常为空。	`{"timestamp": "2025-05-15"}`
`example`	`bool`	是否为示例对话的一部分，默认 `False`，通常被忽略。	`False`
`id`	`Optional[str]`	可选的消息唯一标识符，通常由模型或提供商生成。	`"msg_001"`

属性说明：

content：核心字段，存储用户输入。字符串适用于文本输入，列表适用于多模态输入。
role 和 type：固定值，确保消息被正确识别为用户输入。
additional_kwargs：提供扩展性，通常用于存储元数据，但需谨慎使用以避免敏感信息泄露。
example：早期设计用于标记示例对话，但目前大多数模型忽略此字段。
id：可选字段，适合需要跟踪消息的场景，但不常用于 HumanMessage。

核心方法

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

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

方法说明：

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

4. 使用方式与代码示例

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

示例 1：基本 `HumanMessage` 创建

创建一个简单的 HumanMessage 表示用户提问：

from langchain_core.messages import HumanMessage

# 创建 HumanMessage
user_message = HumanMessage(content="你好！量子计算是什么？")

# 打印消息
print(user_message)

输出：

content='你好！量子计算是什么？' role='human' additional_kwargs={}

说明：

content 存储用户输入。
role 固定为 "human"，标识消息来源。

示例 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 HumanMessage
from langchain_openai import ChatOpenAI

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

# 创建多模态消息
messages = [
    HumanMessage(content=[
        {"type": "text", "text": "描述这张图片的内容。"},
        {"type": "image_url", "image_url": {"url": "https://example.com/quantum.jpg"}}
    ])
]

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

输出（假设图片可用）：

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

说明：

content 为列表，包含文本和图像 URL。
仅支持多模态模型（如 GPT-4o）。

示例 4：序列化与反序列化

将 HumanMessage 序列化为 JSON 并还原：

from langchain_core.messages import HumanMessage

# 创建 HumanMessage
message = HumanMessage(
    content="量子计算是什么？",
    additional_kwargs={"user_id": "user_001"}
)

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

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

输出：

{'type': 'human', 'content': '量子计算是什么？', 'additional_kwargs': {'user_id': 'user_001'}}
量子计算是什么？ {'user_id': 'user_001'}

说明：

to_json 生成 JSON 表示，适合存储。
from_json 还原为 HumanMessage 实例。

示例 5：结合代理

在代理工作流中使用 HumanMessage：

from langchain_openai import ChatOpenAI
from langchain_core.messages import HumanMessage
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([
    ("system", "你是一个研究助手，擅长搜索信息。"),
    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] 量子计算的最新进展包括超导量子比特的突破...

说明：

HumanMessage 发起代理任务，触发工具调用。
代理根据 HumanMessage 的内容调用搜索工具并生成响应。

5. 应用场景

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

聊天机器人：
- 构建交互式聊天机器人，处理用户提问。
- 示例：用户通过 HumanMessage 询问天气或技术问题。
代理工作流：
- 发起代理任务，如搜索、计算或数据查询。
- 示例：用户通过 HumanMessage 要求代理获取最新新闻。
检索增强生成（RAG）：
- 提供用户查询，结合检索器获取相关文档。
- 示例：用户询问“量子计算的应用”，HumanMessage 触发文档检索。
多模态交互：
- 处理文本和图像输入（如描述图片内容）。
- 示例：用户上传量子计算机图片并提问。
对话记忆：
- 结合 ConversationBufferMemory 存储对话历史。
- 示例：维护多轮对话的上下文。
用户意图分析：
- 分析用户输入的意图，驱动复杂工作流。
- 示例：根据 HumanMessage 内容决定调用哪个工具。

6. 优化建议

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

(1) 内容管理

保持内容简洁：避免过长的 content，以减少 token 消耗。

if len(message.content) > 1000:
    message.content = message.content[:1000]  # 截断超长内容

压缩对话历史：使用 ConversationSummaryMemory 总结长对话。

from langchain.memory import ConversationSummaryMemory
memory = ConversationSummaryMemory(llm=llm)

(2) 元数据优化

谨慎使用 additional_kwargs：仅存储必要元数据，避免敏感信息。

message = HumanMessage(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) 监控与调试

使用回调：记录 HumanMessage 的处理过程。

from langchain_core.callbacks import BaseCallbackHandler
class MessageCallback(BaseCallbackHandler):
    def on_chat_model_start(self, serialized, messages, **kwargs):
        print(f"输入消息：{messages}")
config = {"callbacks": [MessageCallback()]}

结合 LangSmith：分析消息流和性能。

from langsmith import Client
config = {"callbacks": [Client(api_key="your-langsmith-key")]}

(5) 上下文优化

动态内容：根据任务调整 content，添加上下文。

user_message = HumanMessage(content=f"用户：{user_name}，查询：{query}")

多模态处理：仅在必要时使用多模态输入，检查模型支持。

if not model_supports_multimodal:
    message.content = message.content[0]["text"]  # 仅保留文本

7. 注意事项

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

模型兼容性：
- 多模态输入（如图像）需要模型支持（如 GPT-4o），否则可能报错。
- 示例：检查模型文档确认支持的输入类型。
Token 限制：
- 过长的 content 或过多消息可能超过模型的 token 限制。
- 示例：使用截断或总结策略。

messages = messages[-10:]  # 保留最后 10 条消息

序列化安全：
- 确保 JSON 数据格式正确，避免反序列化错误。

try:
    msg = HumanMessage.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，以获得完整的 HumanMessage 支持。
- 检查文档确认最新功能。
Example 字段：
- example 字段通常被忽略，避免使用以免混淆。
- 示例：始终设置 example=False 或忽略。

8. 与 LangChain 生态的结合

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

聊天模型（Chat Models）：
- HumanMessage 作为对话历史的一部分，传递给 BaseChatModel 实例（如 ChatOpenAI）。
```
llm.invoke(messages)
```
代理（Agents）：
- HumanMessage 发起代理任务，触发工具调用或推理。
```
agent.invoke({"messages": [HumanMessage(content="搜索最新新闻")]})
```

提示模板（Prompt Templates）：

使用 ChatPromptTemplate 管理包含 HumanMessage 的对话。

from langchain_core.prompts import ChatPromptTemplate
prompt = ChatPromptTemplate.from_messages([("human", "{input}")])

记忆（Memory）：

结合 ConversationBufferMemory 存储 HumanMessage。

from langchain.memory import ConversationBufferMemory
memory = ConversationBufferMemory(return_messages=True)
memory.save_context({"input": "查询"}, {"output": response})

回调（Callbacks）：

使用 RunnableConfig 配置回调，监控 HumanMessage 处理。

from langchain_core.callbacks import StdOutCallbackHandler
config = {"callbacks": [StdOutCallbackHandler()]}

9. 综合示例：多模态代理

以下是一个结合 HumanMessage、多模态输入和代理的完整示例：

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=[
        {"type": "text", "text": "搜索量子计算的最新进展，并描述这张图片的内容。"},
        {"type": "image_url", "image_url": {"url": "https://example.com/quantum.jpg"}}
    ])
]

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

输出（假设图片可用）：

[AgentExecutor] 正在执行...
[Tool: SearchWeb] 输入：量子计算的最新进展
[Tool Output] 搜索结果：量子计算的最新信息...
[Final Answer] 量子计算的最新进展包括超导量子比特的突破。图片显示一台量子计算机的实验设备。

说明：

HumanMessage 包含多模态输入（文本和图像）。
代理根据 HumanMessage 调用搜索工具并生成综合回答。

10. 学习资源

官方文档：https://python.langchain.com/api_reference/core/messages/langchain_core.messages.human.HumanMessage.html
消息概述：https://python.langchain.com/docs/concepts/messages/
GitHub 源码：https://github.com/langchain-ai/langchain/tree/master/libs/core/langchain_core/messages
LangSmith：用于调试消息流（https://smith.langchain.com）
社区教程：LangChain 官方博客、YouTube 视频

11. 总结

定义：HumanMessage 是 LangChain 中用于封装人类用户输入的消息类，继承自 BaseMessage。
核心属性：
- content：消息内容（字符串或多模态）。
- role 和 type：固定为 "human"。
- additional_kwargs：元数据。
- example 和 id：可选字段。
核心方法：
- to_json、from_json：序列化/反序列化。
- __str__、__eq__：字符串表示和比较。
功能：封装用户输入、标识角色、支持多模态、序列化、维持对话上下文。
应用场景：聊天机器人、代理工作流、RAG、多模态交互、对话记忆、意图分析。
优化建议：内容管理、元数据优化、性能优化、监控与调试、上下文优化。
注意事项：模型兼容性、token 限制、序列化安全、安全性、版本兼容性、example 字段。