MetadataReplacementPostProcessor crashes with ValidationError when target metadata key is present but None

快速结论：该报错发生在 LlamaIndex 的 MetadataReplacementPostProcessor 节点后处理器中，当节点 metadata 里目标 key 存在但值为 None 时触发。优先排查你的 metadata 中是否有字段被显式设置为 None（例如从 JSON 往返加载、向量存储读取或可选字段空值），而不是简单地将默认值逻辑寄托在 dict.get() 上。

适用环境：LlamaIndex（llama-index-core），已确认受影响版本为 0.14.24，且当前 main 分支仍存在该问题。不涉及特定操作系统、Python、CUDA 或显卡，为纯 Python 逻辑问题。

最快修复方案：暂无确认的一步修复方案（截至 Issue 关闭时，修复尚未合入正式版本）。可优先尝试在调用 MetadataReplacementPostProcessor 之前，对节点的 metadata 进行清洗，将值为 None 的目标 key 移除，或将其替换为回退内容。

注意事项：社区提出的代码级修复方案（使用 is not None 判断而非 or）仅在讨论中被认可为正确方向，但未在 Issue 中标注为已合并或已发布，升级依赖前请确认你使用的版本是否已包含修复。

问题场景

在 LlamaIndex 中使用 MetadataReplacementPostProcessor 对节点内容进行替换时触发。该后处理器设计上允许通过 target_metadata_key 指定任意 metadata 字段来替换节点原始文本。当你的数据中（例如经 SentenceWindowNodeParser 处理的首尾边界节点，或从 JSON/向量库读取回传的 metadata）存在该字段且值为 None 时，查询会因 Pydantic 校验失败而中断。

报错原文

pydantic_core._pydantic_core.ValidationError: 1 validation error for TextNode
text
  Input should be a valid string [type=string_type, input_value=None, input_type=NoneType]
    For further information visit https://errors.pydantic.dev/2.13/v/string_type

原因分析

根本原因是 Python dict.get(key, default) 的行为：只有当 key 完全不存在时才返回默认值。当 metadata 中目标 key 存在但值为 None 时，.get() 会返回 None，随后 set_content(None) 被调用。由于 TextNode.text 是严格的 str 类型字段，Pydantic 直接拒绝赋值并抛出 ValidationError，而不是静默回退到原始内容。

可能原因还包括：SentenceWindowNodeParser 在切分边界节点（首块/末块没有邻居）时可能留下 window 字段为空或 None，这并非刻意构造的异常输入，而是正常数据处理流程中可能出现的情况。

环境排查

确认 llama-index-core 具体版本（受影响版本：0.14.24，且 issue 提出时 main 分支未修复）。
检查传入 MetadataReplacementPostProcessor(target_metadata_key="...") 的节点 metadata，确认目标 key 是否存在且值为 None（可用 print(node.metadata) 直接观察）。
如果使用 SentenceWindowNodeParser，请检查首尾节点的 "window" 字段是否被填充为 None。
若 metadata 经 JSON 序列化/反序列化，注意 null 值会被保留为 None。
确认升级依赖时的最新版本是否已包含修复 commit（需查看上游 release note）。

解决步骤

数据层规避（可优先尝试）：在构造节点时，确保目标 metadata key 不存在，或将其值设为合法的非空字符串。例如：
if node.metadata.get("window") is None: node.metadata.pop("window", None)
代码层修复（社区建议，未验证已合入）：参考 Issue 讨论，修改 _postprocess_nodes 的取值逻辑，避免使用 .get(key, default) 和 or 回退，改用显式 is None 判断：
value = n.node.metadata.get(self.target_metadata_key)
n.node.set_content(value if value is not None else n.node.get_content(metadata_mode=MetadataMode.NONE))
不要使用 metadata.get(key) or fallback 写法：这会把合法的空字符串 "" 或数字 0 也误判为缺失，社区已确认这是不安全的替代方案。
升级/等待修复：关注 LlamaIndex 后续版本的 release notes，确认该修复是否随版本发布。

验证方法

使用 Issue 中的复现脚本测试 Case 2（metadata 为 {"window": None}）。修复后，脚本应输出 Result content: 'original content' 而不是抛出 ValidationError。此外，建议补充测试 {"window": ""} 和 {"window": 0} 的场景，确保回退逻辑不会误伤合法的空值替换内容。