Haystack
获取企业支持
开始使用
📘 **TELUS Agriculture & Consumer Goods** 如何通过 **Haystack Agents** 转变促销交易

Haystack 2.16.0

在 Github 上查看

⭐️ Highlights

🧠 Agent 断点

此版本引入了强大的新功能 **Agent 断点**，可在处理 Haystack Agents 时增强调试和可观察性。您可以通过在 Agent 或其工具中插入断点来暂停执行，以检查内部状态并无缝恢复执行。这为代理开发带来了细粒度的控制，并显著提高了复杂交互过程中的可追溯性。

from haystack.dataclasses.breakpoints import AgentBreakpoint, Breakpoint
from haystack.dataclasses import ChatMessage

chat_generator_breakpoint = Breakpoint(
    component_name="chat_generator", 
    visit_count=0, 
    snapshot_file_path="debug_snapshots"
)
agent_breakpoint = AgentBreakpoint(break_point=chat_generator_breakpoint, agent_name='calculator_agent')

response = agent.run(
    messages=[ChatMessage.from_user("What is 7 * (4 + 2)?")],
    break_point=agent_breakpoint
)

🖼️ 多模态管道和代理

现在，您可以在 Haystack 的生成、索引和检索中融合文本和图像功能。

  • 新的 ImageContent 数据类：一个专用结构，用于存储图像数据以及 base64_image、mime_type、detail 和 metadata。

  • 支持图像的聊天生成器：OpenAIChatGenerator 现在支持图像输入

from haystack.dataclasses import ImageContent, ChatMessage
from haystack.components.generators.chat import OpenAIChatGenerator

image_url = "https://cdn.britannica.com/79/191679-050-C7114D2B/Adult-capybara.jpg"
image_content = ImageContent.from_url(image_url)

message = ChatMessage.from_user(
    content_parts=["Describe the image in short.", image_content]
)

llm = OpenAIChatGenerator(model="gpt-4o-mini")
print(llm.run([message])["replies"][0].text)

  • 强大的多模态组件:

    • PDFToImageContent、ImageFileToImageContent、DocumentToImageContent：将 PDF、图像文件和文档转换为 ImageContent 对象。
    • LLMDocumentContentExtractor：使用支持视觉的 LLM 从图像中提取文本。
    • SentenceTransformersDocumentImageEmbedder：使用 CLIP 等模型从基于图像的文档生成嵌入。
    • DocumentLengthRouter：根据文本内容的长度路由文档——非常适合区分扫描的 PDF 和基于文本的 PDF。
    • DocumentTypeRouter：根据 MIME 类型元数据自动路由文档。

  • 支持图像的提示构建：ChatPromptBuilder 现在支持带有嵌入式图像的模板，可实现动态多模态提示创建。

通过这些新增功能，您现在可以构建多模态代理和 RAG 管道，这些管道可以同时处理文本和视觉内容，从而实现更丰富的交互和检索功能。

👉 在我们的 多模态文本生成入门指南中了解有关多模态的更多信息。

🚀 新功能

  • 向 ByteStream 添加 to_dict 和 from_dict，使其与其他数据类保持一致，具有序列化和反序列化方法。

  • 向 StreamingChunk、ToolCallResult、ToolCall、ComponentInfo 和 ToolCallDelta 类添加 to_dict 和 from_dict，使其与其他数据类保持一致，具有序列化和反序列化方法。

  • 向 Agent 添加了 tool_invoker_kwargs 参数，以便可以将其他 kwargs 传递给 ToolInvoker，例如 max_workers 和 enable_streaming_callback_passthrough。

  • ChatPromptBuilder 现在除了 ChatMessage 对象列表外，还支持特殊字符串模板。这种新格式更灵活，允许将结构化部分（如图像）包含在模板化的 ChatMessage 中。

    from haystack.components.builders import ChatPromptBuilder 
from haystack.dataclasses.chat_message import ImageContent

template = """
{% message role="user" %}
Hello! I am {{user_name}}. 
What's the difference between the following images? 
{% for image in images %}
{{ image | templatize_part }}
{% endfor %}
{% endmessage %}
""" 

images=[
    ImageContent.from_file_path("apple-fruit.jpg"),
    ImageContent.from_file_path("apple-logo.jpg")
]

builder = ChatPromptBuilder(template=template) builder.run(user_name="John", images=images)

  • 向 ImageContent 数据类添加了方便的类方法，用于从文件路径和 URL 创建 ImageContent 对象。

  • 添加了多个转换器，以帮助在不同格式之间转换图像数据

  • DocumentToImageContent：将源自 PDF 和图像文件的文档转换为 ImageContents。

  • ImageFileToImageContent：将图像文件转换为 ImageContent 对象。

  • ImageFileToDocument：将图像文件引用转换为带有相关元数据的空 Document 对象。

  • PDFToImageContent：将 PDF 文件转换为 ImageContent 对象。

  • 用户角色的聊天消息现在可以使用新的 ImageContent 数据类包含图像。我们已将图像支持添加到 OpenAIChatGenerator，并计划随着时间的推移支持更多模型提供商。

  • 当管道因**所有**剩余组件均被阻止运行**且**未生成任何预期的管道输出而无法继续运行时，发出警告。这种情况可能是合法发生的。例如，在具有互斥分支的管道中，其中一些组件被故意阻止。为了帮助避免误报，检查确保在当前运行期间未生成任何预期的输出（由 Pipeline().outputs() 定义）。

  • 为 SentenceWindowRetriever 添加了 source_id_meta_field 和 split_id_meta_field 以实现可自定义的元数据字段名称。添加了 raise_on_missing_meta_fields 以控制在运行时文档缺少所需元字段时是否引发 ValueError（默认为 True）。如果为 False，则缺少元字段的文档将在检索其窗口时被跳过，但原始文档仍将包含在结果中。

  • 向 haystack.dataclasses 模块添加了一个 ComponentInfo 数据类。此数据类用于存储组件信息。我们将其传递给 StreamingChunk，以便我们可以知道流来自哪个组件。

  • 将 component_info 传递给 OpenAIChatGenerator、AzureOpenAIChatGenerator、HuggingFaceAPIChatGenerator 和 HuggingFaceLocalChatGenerator 中的 StreamingChunk。

  • 将 enable_streaming_callback_passthrough 添加到 ToolInvoker 的 init、run 和 run_async 方法。如果设置为 True，则 ToolInvoker 仅在工具的 invoke 方法在其签名中包含 streaming_callback 时，才会尝试将 streaming_callback 函数传递给工具的 invoke 方法。

  • 向 StreamingChunk 类添加了专用的 finish_reason 字段，以提高类型安全性并实现复杂的流式 UI 逻辑。该字段使用 FinishReason 类型别名，具有标准值：“stop”、“length”、“tool_calls”、“content_filter”，以及 Haystack 特有值“tool_call_results”（由 ToolInvoker 用于指示工具执行完成）。

  • 更新了 ToolInvoker 组件以在流式传输工具结果时使用新的 finish_reason 字段。该组件现在会在最后一个流式块中设置 finish_reason="tool_call_results" 以指示工具执行已完成，同时通过在 meta["finish_reason"] 中设置值来保持向后兼容性。

  • 添加了新的 HuggingFaceTEIRanker 组件，以使用 Text Embeddings Inference (TEI) API 进行重新排序。此组件支持自托管的 Text Embeddings Inference 服务和 Hugging Face Inference Endpoints。

  • 向 OpenAIDocumentEmbedder 和 AzureOpenAIDocumentEmbedder 添加了 raise_on_failure 布尔参数。如果设置为 True，则在 API 请求出现错误时，组件将引发异常。默认值为 False，以便将日志记录异常并继续执行的先前行为仍为默认值。

  • ToolInvoker 现在支持同步和异步模式下的并行执行 tool_calls。

  • 为 HuggingFaceLocalChatGenerator 添加 AsyncHFTokenStreamingHandler 以支持异步流式传输

  • 对于 HuggingFaceAPIGenerator 和 HuggingFaceAPIChatGenerator，现在会将 api_params 中传递的所有其他键值对传递给底层推理客户端的初始化。这允许将其他参数传递给客户端，例如 timeout、headers、provider 等。这意味着我们现在可以通过在 api_params 中传递 provider 键来轻松指定不同的推理提供商。

  • 更新了 StreamingChunk 以添加 tool_calls、tool_call_result、index 和 start 字段，以便在流式回调中更轻松地格式化流。

⬆️ 升级说明

  • HuggingFaceAPIGenerator 可能不再与 Hugging Face Inference API 兼容。截至 2025 年 7 月，Hugging Face Inference API 不再提供支持 text_generation 端点的生成模型。生成模型现在仅通过支持 chat_completion 端点的提供商可用。因此，HuggingFaceAPIGenerator 组件可能无法与 Hugging Face Inference API 配合使用。它仍然与 Hugging Face Inference Endpoints 和自托管的 TGI 实例兼容。要通过 Hugging Face Inference API 使用生成模型，请使用 HuggingFaceAPIChatGenerator 组件，它支持 chat_completion 端点。

  • Pipeline.draw() 和 Pipeline.show() 方法的所有参数现在必须指定为关键字参数。示例

pipeline.draw(
    path="output.png",
    server_url="https://custom-server.com",
    params=None,
    timeout=30,
    super_component_expansion=False
)

  • ToolInvoker 类中已删除已弃用的 async_executor 参数。请改用 max_workers 参数，将自动为此创建 ThreadPoolExecutor 以实现并行工具调用。

  • 已从 haystack.dataclasses 模块中删除已弃用的 State 类。State 类现在是 haystack.components.agents 模块的一部分。

  • 从 base_serialization 模块中删除 deserialize_component_inplace 函数。此函数用于反序列化使用 Haystack 2.14.0 或更早版本创建的 State 对象。Haystack 2.16.0 中已移除对旧序列化格式的支持。

⚡️ 增强说明

  • 向 Bytestream.from_file_path() 添加 guess_mime_type 参数

  • 向 DocumentSplitter 组件添加 init 参数 skip_empty_documents。默认值为 True。将其设置为 False 在下游组件（如 LLMDocumentContentExtractor）可以从非文本文档中提取文本时可能有用。

  • 测试我们的类型验证和连接验证与 3.9 中引入的内置 Python 类型一起工作。我们发现这些类型已经得到支持，我们现在只为它们添加显式测试。

  • 我们放宽了 ToolCallDelta（在 Haystack 2.15 中引入）中对 parameters 参数或 name 必须已填充才能创建 ToolCallDelta 数据类的要求。我们取消了此要求，以更符合 OpenAI 的 SDK，并且因为这导致某些遵循 OpenAI SDK 规范的托管版本开源模型出现错误。

  • 在 InMemoryDocumentStore::init 方法中添加了 return_embedding 参数。

  • 更新了 bm25_retrieval 和 filter_documents 方法，以使用 self.return_embedding 来确定是否返回嵌入。

  • 更新了测试（test_in_memory & test_in_memory_embedding_retriever）以反映 InMemoryDocumentStore 中的更改。

  • 添加了一个新的 deserialize_component_inplace 函数来处理通用的组件反序列化，该函数可与任何组件类型配合使用。

  • 将 doc-parser 设为核心依赖项，因为使用它的 ComponentTool 是核心 Tool 组件之一。

  • 使 PipelineBase().validate_input 方法公开，以便用户可以放心地使用它，并且在没有警告的情况下不会收到破坏性更改。此方法对于检查管道中的所有必需连接是否已连接很有用，并且会在 Pipeline 的 run 方法中自动调用。它被公开，以便用户可以在运行时之前调用此方法来验证管道。

  • 对于组件 run Datadog 跟踪，将 span 资源名称设置为组件名称而不是操作名称。

  • 向 SentenceTransformersSimilarityRanker 组件添加了一个 trust_remote_code 参数。设置为 True 时，这将启用 Hugging Face Hub 上托管的自定义模型和脚本的执行。

  • 向 ChatMessage.to_openai_dict_format 添加了一个新的参数 require_tool_call_ids。默认值为 True，以与 OpenAI 的 Chat API 兼容：如果缺少 Tool Call 中的 id 字段，则会引发错误。使用 False 对于不需要 id 字段的浅层 OpenAI 兼容 API 非常有用。

  • Haystack 的核心模块现在是 [ “类型完整”]( https://typing.python.org/en/latest/guides/libraries.html#how-much-of-my-library-needs-types)，这意味着所有函数参数和返回类型都已显式注释。这增加了新添加的 py.typed 标记的有用性，并避免了各种类型检查器实现之间的类型推断差异。

  • 重构了 HuggingFaceAPIChatGenerator 以使用 util 方法 _convert_streaming_chunks_to_chat_message。这有助于保持我们将 StreamingChunks 转换为最终 ChatMessage 的一致性。

  • 我们还向 HuggingFaceGenerator 和 HugginFaceLocalGenerator 中生成的 StreamingChunks 添加了 ComponentInfo，以便我们可以知道流来自哪个组件。

  • 如果仅提供系统消息作为输入，则会向用户记录一条警告，表明这可能不是预期的，并且他们可能还应该提供用户消息。

🐛 Bug 修复

  • 修复了用于将 Haystack StreamingChunks 转换为 Haystack ChatMessage 的 _convert_streaming_chunks_to_chat_message。这修复了一个 StreamingChunk 在 StreamingChunk.tool_calls 中包含两个 ToolCallDeltas 的场景。有了这个修复，它正确地保存了两个 ToolCallDeltas，而之前它们会相互覆盖。这仅发生在某些 LLM 提供商（如 Mistral，而不是 OpenAI）上，因为提供商返回工具调用的方式。

  • 修复了 print_streaming_chunk 实用函数中的一个错误，该错误阻止了工具调用名称的打印。

  • 修复了 ToolInvoker 的 to_dict 和 from_dict 方法，以正确序列化 streaming_callback init 参数。

  • 修复了当 raise_on_failure=False 且批处理过程中发生错误时，后续嵌入会与错误文档配对的错误。

  • 修复了 ComponentTool 使用的 component_invoker，以便在将 ChatMessage 等数据类直接传递给 component_tool.invoke(...) 时能够工作。以前这会导致错误或默默地跳过您的输入。

  • 修复了 LLMMetadataExtractor 在处理 Document 对象且内容为 None 或空字符串时发生的错误。该组件现在可以优雅地处理这些情况，将这些文档标记为失败并在其元数据中提供相应的错误消息，而无需尝试 LLM 调用。

  • RecursiveDocumentSplitter 现在为每个块生成唯一的 Document.id。元字段（split_id、parent_id 等）在 Document 创建[ 之前]() 被填充，因此用于 id 生成的哈希始终是唯一的。

  • 在 ConditionalRouter 中，修复了 to_dict 和 from_dict 方法，以正确处理 output_type 是类型列表或字符串列表的情况。当用户在 ConditionalRouter 中为某个路由指定多个输出时，就会发生这种情况。

  • 修复了 GeneratedAnswer 中 ChatMessage 对象嵌套在 meta 中的序列化。

  • 修复了 ComponentTool 和 Tool 在指定 outputs_to_string 时的序列化。以前，在序列化后紧接着反序列化时会发生错误，如果 outputs_to_string 不为 None。

  • 调用 set_output_types 时，我们现在还会检查 @component.output_types 装饰器是否未出现在 Component 的 run_async 方法上。以前我们只检查 Component.run 方法是否没有该装饰器。

  • 通过将类型 List[ChatMessage] 的检查中的 is not 替换为 != 来修复 schema 验证中的类型比较。这可以防止由于 Python 的 is 运算符比较对象标识而不是相等性而导致的错误不匹配。

  • 在 __init__.py 文件中重新导出符号。这确保了像 from haystack.components.builders import ChatPromptBuilder 这样的短导入与 from haystack.components.builders.chat_prompt_builder import ChatPromptBuilder 等效工作，而不会在 mypy/Pylance 中导致错误或警告。

  • SuperComponent 类现在可以根据异步管道正确序列化和反序列化 SuperComponent。以前，SuperComponent 类始终假定底层管道是同步的。

⚠️ 弃用说明

  • ToolInvoker 中的 async_executor 参数已弃用，改用 max_workers 参数，并将在 Haystack 2.16.0 中删除。您可以使用 max_workers 参数来控制并行工具调用使用的线程数。

💙 非常感谢所有为本次发布做出贡献的人！

@Amnah199 @RafaelJohn9 @anakin87 @bilgeyucel @davidsbatista @julian-risch @kanenorman @kr1shnasomani @mathislucka @mpangrazzi @sjr @srishti-git1110