Haystack Pipeline 组件连接类型不匹配怎么办

Haystack Pipeline 报组件连接类型不匹配时，先不要改模型或重写自定义组件。大多数问题发生在 Pipeline.connect()：发送端的输出 socket、接收端的输入 socket 或两边的类型契约没有对上。把连接拆成“名称、方向、类型、占用状态”四项检查，通常能在真正运行前定位。

官方地址：https://docs.haystack.deepset.ai/

最稳妥的修复方式是先确认两端 socket，再判断 Haystack 是否支持这组类型的隐式适配；如果语义一致但类型不同，就加一个只负责转换数据形状的适配组件。

先把错误缩小到 socket 名称和类型

连接报错先记录四个值：发送组件名、发送输出名、接收组件名、接收输入名。Haystack 的连接写法是 sender.output 到 receiver.input。如果组件只有一个输入和一个输出，可以省略名称；一旦存在多个候选，就必须写全，否则即使类型正确也可能连错端口。

例如，一个组件输出 str，下游却声明接收 list[Document]，这不是“名字写错”，而是数据形状不一致。下面的伪场景只演示连接契约，不代表真实运行日志：

from haystack import Document, Pipeline, component

@component
class TextProducer:
    @component.output_types(text=str)
    def run(self):
        # 输出单个字符串，不能直接冒充文档列表。
        return {"text": "一段待检索文本"}

@component
class DocumentConsumer:
    @component.output_types(answer=str)
    def run(self, documents: list[Document]):
        # 消费者明确要求文档列表，输入契约与字符串不同。
        return {"answer": documents[0].content}

pipe = Pipeline()
pipe.add_component("producer", TextProducer())
pipe.add_component("consumer", DocumentConsumer())
# 这里会暴露 socket 类型不兼容，问题发生在 connect() 阶段。
pipe.connect("producer.text", "consumer.documents")

排查时可按下面的表快速归类：

连接校验通过后，再检查运行输入

Haystack 文档把连接校验放在组件执行之前，所以 connect() 报错与模型推理、向量库查询、提示词内容无关。修复名称后，如果类型仍不兼容，再看是否属于有限的隐式适配范围，例如单个值包装为同类型列表；不要把任意字符串自动当成 Document。

语义确实一致时，适配器要小而明确：输入是什么、输出是什么、是否丢失元数据，都写在组件契约里。把转换逻辑塞进检索器或生成器，会让下次排错又回到“连接看似成功、运行结果难懂”的状态。

@component
class TextToDocumentList:
    @component.output_types(documents=list[Document])
    def run(self, text: str):
        # 只做数据形状转换，并把原文本放进 Document.content。
        return {"documents": [Document(content=text)]}

pipe.add_component("adapter", TextToDocumentList())
# 修复后的两条连接分别表达输入和输出契约。
pipe.connect("producer.text", "adapter.text")
pipe.connect("adapter.documents", "consumer.documents")

如果不确定还有哪些必填输入，使用 pipeline.inputs() 查看组件输入及其类型；它适合确认“连接已通过，但运行时还缺什么”。

一份可复用的反向确认清单

• 先读两端组件的输入输出声明，再写连接字符串。
• 多输入、多输出场景始终显式写 socket 名称。
• 区分“类型不兼容”和“输入已被另一条连接占用”。
• 只在语义一致时加适配器，并保留必要的元数据。
• 连接通过后用 pipeline.inputs() 补齐必填运行参数，再进入 run()。

常见问题

只改 socket 名称就能解决类型错误吗？

不能。名称错误和类型错误是两层问题；名称正确后仍要比较输出和输入的实际类型。

Haystack 会自动把所有类型转换好吗？

不会。官方只支持有限的隐式适配，未知类型或语义不同的容器仍应显式转换。

为什么 connect() 成功，run() 仍然失败？

连接校验只说明结构契约成立；必填输入缺失、运行数据格式错误或组件内部逻辑异常，仍要在 pipeline.inputs() 和运行参数层继续排查。