LangChain 报 Message dict must contain role and content，消息可能在入库后变了形

数据库读出的历史消息看着有内容，交给聊天模型时却抛出：

Message dict must contain 'role' and 'content' keys

先截住模型调用前的那份数据。这个错误发生在消息转换阶段，改模型名、增加重试通常不会改变结果。常见输入是 {"role": "user", "text": "查订单"}：业务表叫 text，聊天接口期待 content，中间缺了一层明确的转换。

另一个常见变化来自序列化。原本是一条消息对象，经过队列或缓存之后成了 JSON 字符串。LangChain 的部分入口会把普通字符串当作用户文本接收；这时甚至不会报同一个错，却把整段 JSON 当成用户说的话。只检查“调用没有异常”会漏掉这种情况。

不接模型也能定位

先运行 python -m pip show langchain-core 记录实际版本。下面使用 langchain-core 的公开消息转换接口，离线验收版本为 1.6.9，不需要供应商集成包或 API key：

from langchain_core.messages import HumanMessage
from langchain_core.messages.utils import convert_to_messages

stored_rows = [
    {"speaker": "customer", "text": "订单还能查吗？"},
    {"speaker": "agent", "text": "请提供订单号"},
]
role_map = {"customer": "user", "agent": "assistant"}

def restore_message(row: dict) -> dict:
    role = role_map[row["speaker"]]  # 未知角色直接失败，避免悄悄改变身份
    content = row["text"]
    if not isinstance(content, str):
        raise TypeError("history text must be a string")
    return {"role": role, "content": content}

messages = convert_to_messages([restore_message(row) for row in stored_rows])
assert [message.type for message in messages] == ["human", "ai"]
assert messages[0].content == "订单还能查吗？"
assert isinstance(convert_to_messages([{"role": "user", "content": "hello"}])[0], HumanMessage)

try:
    convert_to_messages([{"role": "user", "text": "missing content"}])
except ValueError:
    print("invalid history rejected")
else:
    raise AssertionError("invalid message unexpectedly accepted")

这是针对这张业务表写的适配器，不要直接用来迁移所有供应商消息。工具调用消息还涉及 tool_call_id 等字段，多模态 content 也可能是内容块列表；强制转成字符串会丢掉含义。

日志打在最后一次转换之后

调用前只记录每条消息的序号、Python 类型和键名，通常足够定位，不必把完整对话、token 或个人信息写进日志。例如打印 type(item).__name__ 与字典的 sorted(item.keys())。如果入参带了一层 {"messages": [...]}，确认当前调用入口要的是完整输入字典还是其中的消息列表，再决定取哪层。

还要把“缺字段”和“角色值不被接受”分开。补上 content 后，role="HumanMessage" 仍可能是错误写法；类名不等于协议角色值。使用 HumanMessage(content="...")，或者标准的 user/content 字典，选一种贯穿边界即可。

验收先检查转换后的消息数量、角色顺序和内容，再恢复模型调用。供应商对图片、工具结果以及消息顺序另有要求，离线转换通过不能替代那一层验收。

官方依据：消息转换失败排查。