Haystack 数据类Data Classes完整指南理解承载数据与消息的七大核心类型【免费下载链接】haystackOpen-source AI orchestration framework for building context-engineered, production-ready LLM applications. Design modular pipelines and agent workflows with explicit control over retrieval, routing, memory, and generation. Built for scalable agents, RAG, multimodal applications, semantic search, and conversational systems.项目地址: https://gitcode.com/GitHub_Trending/ha/haystack本文是 Haystack 2.18 数据类体系的技术指南围绕 data_classes_api.md 展开深入剖析Answer、ByteStream、ChatMessage及其内容部件、Document、ImageContent、SparseEmbedding与StreamingChunk这七大核心类型的设计理念、字段语义、序列化机制与实际用法。这些数据类构成了 Haystack 管道Pipeline中组件间传递数据的通用货币掌握它们是在 Haystack 中构建 RAG、Agent、多模态应用的基础。数据类在 Haystack 中的地位Haystack 是一个开源的 AI 编排框架用于构建上下文工程化的生产级 LLM 应用支持模块化管道与 Agent 工作流对检索、路由、记忆和生成提供显式控制。而在这一切背后数据在组件之间的流动依赖一套统一的数据类Data Classes体系。从 pydoc/data_classes_api.yml 可以看出该模块由haystack/dataclasses包导出官方将其定位为承载系统数据的核心类Core classes that carry data through the system。所有组件输入、输出和序列化均围绕这些类型展开检索与 RAG 场景Document文档、SparseEmbedding稀疏向量、ExtractedAnswer/GeneratedAnswer答案对话与 Agent 场景ChatMessage消息、ChatRole角色、ToolCall工具调用、ReasoningContent推理内容、StreamingChunk流式块多模态场景ByteStream二进制流、ImageContent图像内容所有数据类统一实现to_dict()/from_dict()序列化协议这是它们能被管道、Pipeline序列化YAML/JSON和调试快照使用的前提。数据类源码位于 haystack/dataclasses 目录顶层__init__.py通过 lazy_imports.py 实现延迟导入用户可直接从haystack.dataclasses导入所需类型。Answer 模块抽取式与生成式答案answer.py定义了三个核心类型Answer协议、ExtractedAnswer抽取式答案和GeneratedAnswer生成式答案。Answer 协议Answer是一个用runtime_checkable标记的Protocol见 answer.py定义了任何答案类型必须满足的最小接口data、query、meta三个字段以及to_dict/from_dict方法。任何实现了该协议的数据类都可以作为管道输出与回答相关的组件对接。ExtractedAnswer抽取式 Reader 的产物ExtractedAnswer持有由抽取式 Reader如ExtractiveReader从文档中抽取的答案字段包括query用户查询score答案置信度得分data抽取出的答案文本document答案来源文档Document对象context答案所在上下文片段document_offset/context_offset答案在文档/上下文中的起止位置由嵌套的Span数据类start、end表示meta附加元数据在 answer.py 中to_dict()会调用self.document.to_dict(flattenFalse)序列化来源文档from_dict()则处理了向后兼容——旧格式将字段包裹在init_parameters信封中新格式直接平铺两种都能正确反序列化同时把document_offset、context_offset还原为Span对象。GeneratedAnswer生成式 Generator 的产物GeneratedAnswer持有生成式 Generator如 LLM 生成组件产生的答案字段包括data生成的答案文本query用户查询documents生成答案所引用的文档列表meta元数据其meta中常携带all_messages生成过程中的完整对话消息列表。从源码可见 answer.py 的一个细节to_dict()时若all_messages中的元素是ChatMessage对象会逐个转换为字典from_dict()反向操作时则把字典还原为ChatMessage列表——这正是ChatMessage与GeneratedAnswer联动关系的体现。ByteStream二进制数据的基础载体ByteStream是 Haystack 中表示任意二进制对象的统一数据类字段为data二进制数据bytesmeta附加元数据字典mime_type二进制数据的 MIME 类型如application/pdf、image/png它在文档转换Converters、文件读取等场景中承担原始字节的传递职责。完整实现见 byte_stream.py。构造与转换方法方法功能from_file_path(filepath, mime_typeNone, metaNone, guess_mime_typeFalse)从文件读取字节构造ByteStream当guess_mime_typeTrue时会用内部工具_guess_mime_type猜测 MIME 类型from_string(text, encodingutf-8, mime_typeNone, metaNone)将字符串编码为字节构造ByteStreamto_string(encodingutf-8)将字节解码为字符串解码失败会抛出UnicodeDecodeErrorto_file(destination_path)将二进制数据写回文件注意元数据不会写入文件序列化与追踪细节to_dict()返回键为data、meta、mime_type的字典其中data被转换为整数列表——源码注释明确说明JSON 无法直接表示bytes因此转为整数列表以便序列化byte_stream.py。from_dict()用bytes(data[data])还原。值得关注的是_to_trace_dict()方法当把ByteStream发送到 tracing 后端时真实二进制数据被替换为Binary data (N bytes)占位符避免超大 payload 拖垮追踪系统byte_stream.py。另外__repr__会将 data 截断到 100 字节展示防止控制台刷屏。ChatMessage 与内容部件对话与 Agent 的核心消息模型ChatMessage是 Haystack 对话、Chat Generator 和 Agent 工作流中最核心的消息类型位于 chat_message.py。它采用角色 内容部件列表content parts的复合结构一条消息由若干内容部件组成每种部件都有专门的类型。ChatRole四种角色ChatRole继承自str, Enum定义四种角色枚举值字符串值语义ChatRole.USERuser用户消息只含文本ChatRole.SYSTEMsystem系统消息只含文本ChatRole.ASSISTANTassistant助手消息可含文本、工具调用与元数据ChatRole.TOOLtool工具消息包含一次工具调用的结果ChatRole.from_str(string)静态方法将字符串转为枚举若字符串不在支持范围内会抛出包含全部支持角色的ValueErrorchat_message.py。内容部件类型每条ChatMessage的_content是ChatMessageContentT的序列支持六种部件TextContent纯文本内容唯一字段textToolCall模型准备发起的工具调用字段为id工具调用 ID、tool_name工具名、arguments参数字典、extra厂商私有附加信息须 JSON 可序列化ToolCallResult工具调用的结果字段为result字符串或TextContent/ImageContent/FileContent列表、origin产生该结果的ToolCall、error调用是否出错ImageContent消息中的图像内容ReasoningContent模型输出的可选推理内容字段为reasoning_text与extra厂商私有附加信息须 JSON 可序列化FileContent消息中携带的文件内容。这些内容部件的序列化映射定义在_CONTENT_PART_CLASSES_TO_SERIALIZATION_KEYS字典中text、tool_call、tool_call_result、image、reasoning、filechat_message.py。序列化时每个部件被包裹为对应键的字典例如{tool_call: {tool_name: search, arguments: {}, id: call_123}}。构造消息四个工厂类方法文档明确建议使用四个类方法创建ChatMessage而非直接实例化from haystack.dataclasses import ChatMessage, ToolCall # 用户消息 user_msg ChatMessage.from_user(textWhat is the capital of France?) # 系统消息 system_msg ChatMessage.from_system( textYou are a helpful assistant., meta{model: gpt-4o}, # 可选元数据 ) # 助手消息可携带文本、工具调用与推理内容 tool_call ToolCall(idcall_1, tool_namesearch_documents, arguments{query: Paris}) assistant_msg ChatMessage.from_assistant( textIll search for that., tool_calls[tool_call], reasoningI need to look up the answer., ) # 工具消息回应一次工具调用 tool_msg ChatMessage.from_tool( tool_resultParis is the capital of France., origintool_call, errorFalse, )各工厂方法的要点from_user(textNone, metaNone, nameNone, *, content_partsNone)text与content_parts二选一源码会校验两者都传或都不传均抛ValueError。content_parts支持str、TextContent、ImageContent、FileContent混合列表用于构造多模态用户消息name字段仅 OpenAI 支持。from_system(text, metaNone, nameNone)系统消息只能包含文本。from_assistant(textNone, metaNone, nameNone, tool_callsNone, *, reasoningNone)reasoning可传字符串自动包装为ReasoningContent或ReasoningContent对象其他类型抛TypeError。from_tool(tool_result, origin, errorFalse, metaNone)origin必须是触发该结果的ToolCall对象。属性访问器ChatMessage提供了丰富的只读属性方便对内容做结构化访问属性返回说明roleChatRole消息发送方角色metadict[str, Any]消息元数据namestr \| None参与者名称仅 OpenAI 支持texts/textlist[str]/str \| None全部文本 / 第一个文本tool_calls/tool_calllist[ToolCall]/ToolCall \| None全部工具调用 / 第一个tool_call_results/tool_call_result对应列表或单个全部工具结果 / 第一个images/imagelist[ImageContent]/ 单个全部图像 / 第一个files/filelist[FileContent]/ 单个全部文件 / 第一个reasonings/reasoning对应列表或单个全部推理内容 / 第一个is_from(role)bool判断消息是否来自某角色接受枚举或字符串注意texts只统计TextContent部件to_openai_dict_format中使用的has_content判断则同时考虑文本、工具调用、工具结果、图像与文件。序列化to_dict / from_dictto_dict()输出的结构为{role: ..., meta: ..., name: ..., content: [部件字典列表]}。from_dict()兼容三种历史格式源码 chat_message.py当前格式content为字典列表2.9.0 及以后2.9.0 之前格式content为普通字符串2.9.0 至 2.12.0 之间格式使用_content、_role、_meta键。此外_deserialize_content_part还兼容 Pydanticmodel_dump()产生的平铺字典如直接含tool_namearguments、base64_image等键的字典。反序列化出错时会抛出含格式示例的详细ValueError源码注释说明这是为了给 Agent 运行中的 LLM 提供创建合法消息的引导。与 OpenAI Chat API 互操作ChatMessage提供了两个双向转换方法to_openai_dict_format(require_tool_call_idsTrue)转为 OpenAI Chat Completions API 格式。require_tool_call_idsTrue默认要求每个ToolCall必须有非空id设为False可兼容浅层OpenAI 兼容 API。转换遵循的规则包括用户消息若只含单个TextContentcontent直接是字符串多模态时转为{type: text, text: ...}与{type: image_url, image_url: {url: data:mime;base64,data}}列表未提供 MIME 时默认image/jpeg工具结果消息若结果为字符串或纯文本部件列表则放入content否则抛ValueError并提示多模态工具结果请改用 OpenAI Responses API助手消息中的ReasoningContent会被忽略OpenAI Chat API 不支持推理内容工具调用转为{type: function, function: {name: ..., arguments: json.dumps(...)}, id: ...}且json.dumps关闭ensure_ascii以保留 emoji 等特殊字符只有助手消息允许空内容API 要求 assistant 必须有 content 或 tool_calls 时发送空字符串。from_openai_dict_format(message)将 OpenAI 格式字典还原为ChatMessage。该方法对角色做了严格校验assistant/user/system/developer/tool处理零参数工具调用时容忍arguments为空字符串、null或缺失统一按{}处理文档特别提示OpenAI API 要求 tool 消息带tool_call_id但此方法允许缺失以便兼容浅层 API若要与 OpenAI 联用必须补齐tool_call_id否则会触发校验错误。Document检索系统的核心数据单元Document是 Haystack 中可被检索的最小数据单元完整实现见 document.py。字段语义字段类型说明idstr唯一标识。未显式设置时基于各字段值自动生成contentstr \| None文档文本内容blobByteStream \| None与文档关联的二进制数据metadict[str, Any]自定义元数据必须 JSON 可序列化scorefloat \| None文档得分用于排序通常由检索器Retriever赋值embeddinglist[float] \| None稠密向量表示sparse_embeddingSparseEmbedding \| None稀疏向量表示ID 自动生成与向后兼容Document使用元类_RemoveLegacyFields和__post_init__完成两件事document.py清理遗留字段_LEGACY_FIELDS [content_type, id_hash_keys, dataframe]在__init__前被移除避免 1.x 代码迁移时崩溃1.x 嵌入转换1.x 中embedding以 NumPy 数组存储这里自动转为list[float]ID 生成id为空时调用_create_id()用 SHA-256 对content blob mime_type meta embedding sparse_embedding的拼接串取哈希。meta用sort_keysTrue排序后再 JSON 序列化保证元数据键顺序不影响 ID 稳定性。__eq__比较两个Document的to_dict(flattenFalse)结果是否完全一致。content_type属性保留 1.x 兼容性有文本时返回text否则抛ValueError。序列化与 meta 展开flattento_dict(flattenTrue)的flatten参数值得特别注意当flattenTrue默认为兼容 1.x时meta字典的键会被展开到文档字典顶层若某个 meta 键与文档字段名冲突如id、content则该键会保留在嵌套的meta字典中避免覆盖字段当flattenFalse时meta保持嵌套结构。from_dict()是反向操作顶层非字段键自动收拢回metablob通过ByteStream.from_dict还原sparse_embedding通过SparseEmbedding.from_dict还原。这种设计让 1.x 与 2.x 的文档序列化可以互读。ImageContent多模态消息的图像载体ImageContent表示聊天消息中的图像内容字段包括base64_image图像的 base64 字符串mime_type图像 MIME 类型如image/png、image/jpeg文档建议显式提供因为多数 LLM 厂商要求它不提供时会从 base64 字符串猜测速度慢且不一定可靠detail图像细节级别仅 OpenAI 支持取auto、high、low之一meta附加元数据validation默认True开启时会校验 base64 合法性、猜测缺失的 MIME 类型、检查是否为合法图像 MIME设为False可跳过校验、加快初始化构造方式ImageContent提供三种创建路径from_file_path(file_path, *, sizeNone, detailNone, metaNone)从本地图片文件构造。size参数宽、高元组会在保持宽高比的前提下把图像缩放到指定尺寸内降低文件体积、内存与处理耗时——对带分辨率限制的模型或需要传输到远程服务的场景尤其有用。注意 PDF 文件不受支持PDF 转图像请用PDFToImageContent组件源码明确交叉引用。from_url(url, *, retry_attempts2, timeout10, sizeNone, detailNone, metaNone)从 URL 下载图像并转为 base64。retry_attempts控制重试次数timeout为请求超时秒数若 URL 指向非图像或 PDF 文件会抛ValueError。直接传base64_image等字段实例化。ImageContent.show()可直接展示图像__repr__会把 base64 截断到 100 字节便于调试。SparseEmbedding稀疏向量表示SparseEmbedding以双列表形式表示稀疏向量sparse_embedding.pyindices非零元素的下标列表values非零元素的值列表__post_init__校验两个列表长度必须一致否则抛ValueError。to_dict()输出{indices: [...], values: [...]}from_dict()反向还原。它常与Document.sparse_embedding字段配合用于 BM25 等稀疏检索或混合检索Hybrid Retrieval场景。StreamingChunk流式输出的分段载体StreamingChunk封装一段流式内容及其元数据是 LLM 流式生成streaming时逐块回调的数据类型。其字段包括content块内容字符串meta块相关元数据字典component_infoComponentInfo对象携带产生该块的组件信息类型与名称index该块所属内容块的序号可选tool_callsToolCallDelta列表表示与消息块关联的工具调用增量tool_call_result工具调用结果可选start布尔值标记该块是否为某个内容块的起始finish_reason生成结束原因标准值遵循 OpenAI 约定stop、length、tool_calls、content_filter外加 Haystack 特有值tool_call_resultsFinishReason类型别名定义于 streaming_chunk.pyreasoning可选的ReasoningContent对象表示与该块关联的推理内容ToolCallDelta 与 ComponentInfo流式过程中工具调用也是增量到达的因此引入ToolCallDelta字段为index工具调用在列表中的序号、tool_name、arguments完整 JSON 或增量片段、id、extra。ComponentInfo则通过from_component(component)从组件实例提取信息type为模块名.类名全限定名name取自__component_name__属性组件加入管道时被赋予的名称。select_streaming_callback该模块还导出一个工具函数select_streaming_callback(init_callback, runtime_callback, requires_async)当初始化时与运行时各传入一个回调时运行时回调优先于初始化回调requires_async用于判断所选回调是否需要异步兼容。其设计意图是既允许用户在构建组件时预设回调也允许在Pipeline.run()时按调用临时覆盖。序列化统一模式与实战建议纵观所有数据类可以提炼出 Haystack 数据类设计的几条规律统一to_dict/from_dict协议这是管道序列化YAML/JSON、调试快照、Agent 状态持久化的基础。无论是Document、ChatMessage还是StreamingChunk都能无损地转成 JSON 兼容结构再还原。向后兼容优先Document的遗留字段清理与 meta flatten、ExtractedAnswer/GeneratedAnswer的init_parameters信封兼容、ChatMessage的三种序列化格式兼容都体现了对 1.x 迁移用户的重视。二进制与图像数据的占位处理ByteStream的_to_trace_dict和ChatMessage._to_trace_dict都会用占位符替换大 payload避免追踪系统被撑爆。内容部件模式ChatMessage的多态内容部件文本、工具调用、图像、文件、推理内容让一条消息可以承载完整的多模态对话历史这正是 Agent 编排的基础。实际编码时建议优先用工厂方法from_user等创建ChatMessage不要直接传_role/_content私有字段把Document的meta保持 JSON 可序列化避免序列化时踩坑构造ImageContent时尽量显式传mime_type并利用size参数控制发送给模型的数据量涉及 OpenAI 互操作时保持ToolCall.id非空或显式将require_tool_call_idsFalse以兼容浅层 API。深入阅读数据类源码haystack/dataclassesanswer.py、byte_stream.py、chat_message.py、document.py、image_content.py、sparse_embedding.py、streaming_chunk.pyAPI 文档生成配置pydoc/data_classes_api.yml本文依据的 API 参考文档data_classes_api.md对应版本的其他参考文档version-2.18haystack-api目录含管道、组件等配套 API 参考掌握这些数据类你就掌握了 Haystack 中数据如何流动的底层语言无论是组装检索管道、调试对话 Agent还是接入流式输出都能游刃有余。【免费下载链接】haystackOpen-source AI orchestration framework for building context-engineered, production-ready LLM applications. Design modular pipelines and agent workflows with explicit control over retrieval, routing, memory, and generation. Built for scalable agents, RAG, multimodal applications, semantic search, and conversational systems.项目地址: https://gitcode.com/GitHub_Trending/ha/haystack创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Haystack 数据类（Data Classes）完整指南：理解承载数据与消息的七大核心类型
Haystack 数据类Data Classes完整指南理解承载数据与消息的七大核心类型【免费下载链接】haystackOpen-source AI orchestration framework for building context-engineered, production-ready LLM applications. Design modular pipelines and agent workflows with explicit control over retrieval, routing, memory, and generation. Built for scalable agents, RAG, multimodal applications, semantic search, and conversational systems.项目地址: https://gitcode.com/GitHub_Trending/ha/haystack本文是 Haystack 2.18 数据类体系的技术指南围绕 data_classes_api.md 展开深入剖析Answer、ByteStream、ChatMessage及其内容部件、Document、ImageContent、SparseEmbedding与StreamingChunk这七大核心类型的设计理念、字段语义、序列化机制与实际用法。这些数据类构成了 Haystack 管道Pipeline中组件间传递数据的通用货币掌握它们是在 Haystack 中构建 RAG、Agent、多模态应用的基础。数据类在 Haystack 中的地位Haystack 是一个开源的 AI 编排框架用于构建上下文工程化的生产级 LLM 应用支持模块化管道与 Agent 工作流对检索、路由、记忆和生成提供显式控制。而在这一切背后数据在组件之间的流动依赖一套统一的数据类Data Classes体系。从 pydoc/data_classes_api.yml 可以看出该模块由haystack/dataclasses包导出官方将其定位为承载系统数据的核心类Core classes that carry data through the system。所有组件输入、输出和序列化均围绕这些类型展开检索与 RAG 场景Document文档、SparseEmbedding稀疏向量、ExtractedAnswer/GeneratedAnswer答案对话与 Agent 场景ChatMessage消息、ChatRole角色、ToolCall工具调用、ReasoningContent推理内容、StreamingChunk流式块多模态场景ByteStream二进制流、ImageContent图像内容所有数据类统一实现to_dict()/from_dict()序列化协议这是它们能被管道、Pipeline序列化YAML/JSON和调试快照使用的前提。数据类源码位于 haystack/dataclasses 目录顶层__init__.py通过 lazy_imports.py 实现延迟导入用户可直接从haystack.dataclasses导入所需类型。Answer 模块抽取式与生成式答案answer.py定义了三个核心类型Answer协议、ExtractedAnswer抽取式答案和GeneratedAnswer生成式答案。Answer 协议Answer是一个用runtime_checkable标记的Protocol见 answer.py定义了任何答案类型必须满足的最小接口data、query、meta三个字段以及to_dict/from_dict方法。任何实现了该协议的数据类都可以作为管道输出与回答相关的组件对接。ExtractedAnswer抽取式 Reader 的产物ExtractedAnswer持有由抽取式 Reader如ExtractiveReader从文档中抽取的答案字段包括query用户查询score答案置信度得分data抽取出的答案文本document答案来源文档Document对象context答案所在上下文片段document_offset/context_offset答案在文档/上下文中的起止位置由嵌套的Span数据类start、end表示meta附加元数据在 answer.py 中to_dict()会调用self.document.to_dict(flattenFalse)序列化来源文档from_dict()则处理了向后兼容——旧格式将字段包裹在init_parameters信封中新格式直接平铺两种都能正确反序列化同时把document_offset、context_offset还原为Span对象。GeneratedAnswer生成式 Generator 的产物GeneratedAnswer持有生成式 Generator如 LLM 生成组件产生的答案字段包括data生成的答案文本query用户查询documents生成答案所引用的文档列表meta元数据其meta中常携带all_messages生成过程中的完整对话消息列表。从源码可见 answer.py 的一个细节to_dict()时若all_messages中的元素是ChatMessage对象会逐个转换为字典from_dict()反向操作时则把字典还原为ChatMessage列表——这正是ChatMessage与GeneratedAnswer联动关系的体现。ByteStream二进制数据的基础载体ByteStream是 Haystack 中表示任意二进制对象的统一数据类字段为data二进制数据bytesmeta附加元数据字典mime_type二进制数据的 MIME 类型如application/pdf、image/png它在文档转换Converters、文件读取等场景中承担原始字节的传递职责。完整实现见 byte_stream.py。构造与转换方法方法功能from_file_path(filepath, mime_typeNone, metaNone, guess_mime_typeFalse)从文件读取字节构造ByteStream当guess_mime_typeTrue时会用内部工具_guess_mime_type猜测 MIME 类型from_string(text, encodingutf-8, mime_typeNone, metaNone)将字符串编码为字节构造ByteStreamto_string(encodingutf-8)将字节解码为字符串解码失败会抛出UnicodeDecodeErrorto_file(destination_path)将二进制数据写回文件注意元数据不会写入文件序列化与追踪细节to_dict()返回键为data、meta、mime_type的字典其中data被转换为整数列表——源码注释明确说明JSON 无法直接表示bytes因此转为整数列表以便序列化byte_stream.py。from_dict()用bytes(data[data])还原。值得关注的是_to_trace_dict()方法当把ByteStream发送到 tracing 后端时真实二进制数据被替换为Binary data (N bytes)占位符避免超大 payload 拖垮追踪系统byte_stream.py。另外__repr__会将 data 截断到 100 字节展示防止控制台刷屏。ChatMessage 与内容部件对话与 Agent 的核心消息模型ChatMessage是 Haystack 对话、Chat Generator 和 Agent 工作流中最核心的消息类型位于 chat_message.py。它采用角色 内容部件列表content parts的复合结构一条消息由若干内容部件组成每种部件都有专门的类型。ChatRole四种角色ChatRole继承自str, Enum定义四种角色枚举值字符串值语义ChatRole.USERuser用户消息只含文本ChatRole.SYSTEMsystem系统消息只含文本ChatRole.ASSISTANTassistant助手消息可含文本、工具调用与元数据ChatRole.TOOLtool工具消息包含一次工具调用的结果ChatRole.from_str(string)静态方法将字符串转为枚举若字符串不在支持范围内会抛出包含全部支持角色的ValueErrorchat_message.py。内容部件类型每条ChatMessage的_content是ChatMessageContentT的序列支持六种部件TextContent纯文本内容唯一字段textToolCall模型准备发起的工具调用字段为id工具调用 ID、tool_name工具名、arguments参数字典、extra厂商私有附加信息须 JSON 可序列化ToolCallResult工具调用的结果字段为result字符串或TextContent/ImageContent/FileContent列表、origin产生该结果的ToolCall、error调用是否出错ImageContent消息中的图像内容ReasoningContent模型输出的可选推理内容字段为reasoning_text与extra厂商私有附加信息须 JSON 可序列化FileContent消息中携带的文件内容。这些内容部件的序列化映射定义在_CONTENT_PART_CLASSES_TO_SERIALIZATION_KEYS字典中text、tool_call、tool_call_result、image、reasoning、filechat_message.py。序列化时每个部件被包裹为对应键的字典例如{tool_call: {tool_name: search, arguments: {}, id: call_123}}。构造消息四个工厂类方法文档明确建议使用四个类方法创建ChatMessage而非直接实例化from haystack.dataclasses import ChatMessage, ToolCall # 用户消息 user_msg ChatMessage.from_user(textWhat is the capital of France?) # 系统消息 system_msg ChatMessage.from_system( textYou are a helpful assistant., meta{model: gpt-4o}, # 可选元数据 ) # 助手消息可携带文本、工具调用与推理内容 tool_call ToolCall(idcall_1, tool_namesearch_documents, arguments{query: Paris}) assistant_msg ChatMessage.from_assistant( textIll search for that., tool_calls[tool_call], reasoningI need to look up the answer., ) # 工具消息回应一次工具调用 tool_msg ChatMessage.from_tool( tool_resultParis is the capital of France., origintool_call, errorFalse, )各工厂方法的要点from_user(textNone, metaNone, nameNone, *, content_partsNone)text与content_parts二选一源码会校验两者都传或都不传均抛ValueError。content_parts支持str、TextContent、ImageContent、FileContent混合列表用于构造多模态用户消息name字段仅 OpenAI 支持。from_system(text, metaNone, nameNone)系统消息只能包含文本。from_assistant(textNone, metaNone, nameNone, tool_callsNone, *, reasoningNone)reasoning可传字符串自动包装为ReasoningContent或ReasoningContent对象其他类型抛TypeError。from_tool(tool_result, origin, errorFalse, metaNone)origin必须是触发该结果的ToolCall对象。属性访问器ChatMessage提供了丰富的只读属性方便对内容做结构化访问属性返回说明roleChatRole消息发送方角色metadict[str, Any]消息元数据namestr \| None参与者名称仅 OpenAI 支持texts/textlist[str]/str \| None全部文本 / 第一个文本tool_calls/tool_calllist[ToolCall]/ToolCall \| None全部工具调用 / 第一个tool_call_results/tool_call_result对应列表或单个全部工具结果 / 第一个images/imagelist[ImageContent]/ 单个全部图像 / 第一个files/filelist[FileContent]/ 单个全部文件 / 第一个reasonings/reasoning对应列表或单个全部推理内容 / 第一个is_from(role)bool判断消息是否来自某角色接受枚举或字符串注意texts只统计TextContent部件to_openai_dict_format中使用的has_content判断则同时考虑文本、工具调用、工具结果、图像与文件。序列化to_dict / from_dictto_dict()输出的结构为{role: ..., meta: ..., name: ..., content: [部件字典列表]}。from_dict()兼容三种历史格式源码 chat_message.py当前格式content为字典列表2.9.0 及以后2.9.0 之前格式content为普通字符串2.9.0 至 2.12.0 之间格式使用_content、_role、_meta键。此外_deserialize_content_part还兼容 Pydanticmodel_dump()产生的平铺字典如直接含tool_namearguments、base64_image等键的字典。反序列化出错时会抛出含格式示例的详细ValueError源码注释说明这是为了给 Agent 运行中的 LLM 提供创建合法消息的引导。与 OpenAI Chat API 互操作ChatMessage提供了两个双向转换方法to_openai_dict_format(require_tool_call_idsTrue)转为 OpenAI Chat Completions API 格式。require_tool_call_idsTrue默认要求每个ToolCall必须有非空id设为False可兼容浅层OpenAI 兼容 API。转换遵循的规则包括用户消息若只含单个TextContentcontent直接是字符串多模态时转为{type: text, text: ...}与{type: image_url, image_url: {url: data:mime;base64,data}}列表未提供 MIME 时默认image/jpeg工具结果消息若结果为字符串或纯文本部件列表则放入content否则抛ValueError并提示多模态工具结果请改用 OpenAI Responses API助手消息中的ReasoningContent会被忽略OpenAI Chat API 不支持推理内容工具调用转为{type: function, function: {name: ..., arguments: json.dumps(...)}, id: ...}且json.dumps关闭ensure_ascii以保留 emoji 等特殊字符只有助手消息允许空内容API 要求 assistant 必须有 content 或 tool_calls 时发送空字符串。from_openai_dict_format(message)将 OpenAI 格式字典还原为ChatMessage。该方法对角色做了严格校验assistant/user/system/developer/tool处理零参数工具调用时容忍arguments为空字符串、null或缺失统一按{}处理文档特别提示OpenAI API 要求 tool 消息带tool_call_id但此方法允许缺失以便兼容浅层 API若要与 OpenAI 联用必须补齐tool_call_id否则会触发校验错误。Document检索系统的核心数据单元Document是 Haystack 中可被检索的最小数据单元完整实现见 document.py。字段语义字段类型说明idstr唯一标识。未显式设置时基于各字段值自动生成contentstr \| None文档文本内容blobByteStream \| None与文档关联的二进制数据metadict[str, Any]自定义元数据必须 JSON 可序列化scorefloat \| None文档得分用于排序通常由检索器Retriever赋值embeddinglist[float] \| None稠密向量表示sparse_embeddingSparseEmbedding \| None稀疏向量表示ID 自动生成与向后兼容Document使用元类_RemoveLegacyFields和__post_init__完成两件事document.py清理遗留字段_LEGACY_FIELDS [content_type, id_hash_keys, dataframe]在__init__前被移除避免 1.x 代码迁移时崩溃1.x 嵌入转换1.x 中embedding以 NumPy 数组存储这里自动转为list[float]ID 生成id为空时调用_create_id()用 SHA-256 对content blob mime_type meta embedding sparse_embedding的拼接串取哈希。meta用sort_keysTrue排序后再 JSON 序列化保证元数据键顺序不影响 ID 稳定性。__eq__比较两个Document的to_dict(flattenFalse)结果是否完全一致。content_type属性保留 1.x 兼容性有文本时返回text否则抛ValueError。序列化与 meta 展开flattento_dict(flattenTrue)的flatten参数值得特别注意当flattenTrue默认为兼容 1.x时meta字典的键会被展开到文档字典顶层若某个 meta 键与文档字段名冲突如id、content则该键会保留在嵌套的meta字典中避免覆盖字段当flattenFalse时meta保持嵌套结构。from_dict()是反向操作顶层非字段键自动收拢回metablob通过ByteStream.from_dict还原sparse_embedding通过SparseEmbedding.from_dict还原。这种设计让 1.x 与 2.x 的文档序列化可以互读。ImageContent多模态消息的图像载体ImageContent表示聊天消息中的图像内容字段包括base64_image图像的 base64 字符串mime_type图像 MIME 类型如image/png、image/jpeg文档建议显式提供因为多数 LLM 厂商要求它不提供时会从 base64 字符串猜测速度慢且不一定可靠detail图像细节级别仅 OpenAI 支持取auto、high、low之一meta附加元数据validation默认True开启时会校验 base64 合法性、猜测缺失的 MIME 类型、检查是否为合法图像 MIME设为False可跳过校验、加快初始化构造方式ImageContent提供三种创建路径from_file_path(file_path, *, sizeNone, detailNone, metaNone)从本地图片文件构造。size参数宽、高元组会在保持宽高比的前提下把图像缩放到指定尺寸内降低文件体积、内存与处理耗时——对带分辨率限制的模型或需要传输到远程服务的场景尤其有用。注意 PDF 文件不受支持PDF 转图像请用PDFToImageContent组件源码明确交叉引用。from_url(url, *, retry_attempts2, timeout10, sizeNone, detailNone, metaNone)从 URL 下载图像并转为 base64。retry_attempts控制重试次数timeout为请求超时秒数若 URL 指向非图像或 PDF 文件会抛ValueError。直接传base64_image等字段实例化。ImageContent.show()可直接展示图像__repr__会把 base64 截断到 100 字节便于调试。SparseEmbedding稀疏向量表示SparseEmbedding以双列表形式表示稀疏向量sparse_embedding.pyindices非零元素的下标列表values非零元素的值列表__post_init__校验两个列表长度必须一致否则抛ValueError。to_dict()输出{indices: [...], values: [...]}from_dict()反向还原。它常与Document.sparse_embedding字段配合用于 BM25 等稀疏检索或混合检索Hybrid Retrieval场景。StreamingChunk流式输出的分段载体StreamingChunk封装一段流式内容及其元数据是 LLM 流式生成streaming时逐块回调的数据类型。其字段包括content块内容字符串meta块相关元数据字典component_infoComponentInfo对象携带产生该块的组件信息类型与名称index该块所属内容块的序号可选tool_callsToolCallDelta列表表示与消息块关联的工具调用增量tool_call_result工具调用结果可选start布尔值标记该块是否为某个内容块的起始finish_reason生成结束原因标准值遵循 OpenAI 约定stop、length、tool_calls、content_filter外加 Haystack 特有值tool_call_resultsFinishReason类型别名定义于 streaming_chunk.pyreasoning可选的ReasoningContent对象表示与该块关联的推理内容ToolCallDelta 与 ComponentInfo流式过程中工具调用也是增量到达的因此引入ToolCallDelta字段为index工具调用在列表中的序号、tool_name、arguments完整 JSON 或增量片段、id、extra。ComponentInfo则通过from_component(component)从组件实例提取信息type为模块名.类名全限定名name取自__component_name__属性组件加入管道时被赋予的名称。select_streaming_callback该模块还导出一个工具函数select_streaming_callback(init_callback, runtime_callback, requires_async)当初始化时与运行时各传入一个回调时运行时回调优先于初始化回调requires_async用于判断所选回调是否需要异步兼容。其设计意图是既允许用户在构建组件时预设回调也允许在Pipeline.run()时按调用临时覆盖。序列化统一模式与实战建议纵观所有数据类可以提炼出 Haystack 数据类设计的几条规律统一to_dict/from_dict协议这是管道序列化YAML/JSON、调试快照、Agent 状态持久化的基础。无论是Document、ChatMessage还是StreamingChunk都能无损地转成 JSON 兼容结构再还原。向后兼容优先Document的遗留字段清理与 meta flatten、ExtractedAnswer/GeneratedAnswer的init_parameters信封兼容、ChatMessage的三种序列化格式兼容都体现了对 1.x 迁移用户的重视。二进制与图像数据的占位处理ByteStream的_to_trace_dict和ChatMessage._to_trace_dict都会用占位符替换大 payload避免追踪系统被撑爆。内容部件模式ChatMessage的多态内容部件文本、工具调用、图像、文件、推理内容让一条消息可以承载完整的多模态对话历史这正是 Agent 编排的基础。实际编码时建议优先用工厂方法from_user等创建ChatMessage不要直接传_role/_content私有字段把Document的meta保持 JSON 可序列化避免序列化时踩坑构造ImageContent时尽量显式传mime_type并利用size参数控制发送给模型的数据量涉及 OpenAI 互操作时保持ToolCall.id非空或显式将require_tool_call_idsFalse以兼容浅层 API。深入阅读数据类源码haystack/dataclassesanswer.py、byte_stream.py、chat_message.py、document.py、image_content.py、sparse_embedding.py、streaming_chunk.pyAPI 文档生成配置pydoc/data_classes_api.yml本文依据的 API 参考文档data_classes_api.md对应版本的其他参考文档version-2.18haystack-api目录含管道、组件等配套 API 参考掌握这些数据类你就掌握了 Haystack 中数据如何流动的底层语言无论是组装检索管道、调试对话 Agent还是接入流式输出都能游刃有余。【免费下载链接】haystackOpen-source AI orchestration framework for building context-engineered, production-ready LLM applications. Design modular pipelines and agent workflows with explicit control over retrieval, routing, memory, and generation. Built for scalable agents, RAG, multimodal applications, semantic search, and conversational systems.项目地址: https://gitcode.com/GitHub_Trending/ha/haystack创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
