Haystack 图像转换器Image Converters完全指南文档、图片与 PDF 到多模态 ImageContent 的转换实战【免费下载链接】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 开源 AI 编排框架中的图像转换器模块为核心系统讲解DocumentToImageContent、ImageFileToDocument、ImageFileToImageContent与PDFToImageContent四个组件的用法、参数与底层实现。读完本文你将掌握如何把磁盘上的图片与 PDF 文件转换为可供多模态大模型直接消费的ImageContentbase64 编码图像并能在 Pipeline 中正确编排这些转换器以支撑图文理解、图片检索等场景。概览Haystack 的图像转换器家族在 Haystack 中转换器Converter负责把外部数据文件、字节流等变成下游组件可消费的数据结构。图像转换器专门处理图像格式的数据统一输出ImageContent对象或承载路径元数据的空Document。它们都位于haystack/components/converters/image/目录下公开导出四个组件见 image/init.py组件输入输出典型用途DocumentToImageContent带元数据的Document列表文件路径 MIME 类型 页码ImageContent列表把索引管线中已存在的 Document源自 PDF/图片转换成图像内容ImageFileToDocument文件路径 /Path/ByteStream列表content 为None的空Document把图片路径包装成 Document供下游提取器、嵌入器消费ImageFileToImageContent文件路径 /Path/ByteStream列表ImageContent列表把图片文件直接转成 base64 图像内容PDFToImageContent文件路径 /Path/ByteStream列表ImageContent列表每页一个把 PDF 按页渲染成图像这些组件遵循 Haystack 组件的统一约定通过component装饰器注册如 document_to_image.pyrun方法返回字典键名由component.output_types声明例如image_contents、documents。核心数据结构ImageContent所有转成图像的组件最终都产出 ImageContent 数据类它是连接转换器与多模态模型的桥梁。其字段包括base64_imagestrbase64 编码的图像字符串可直接嵌入多模态 API 请求。mime_typestr | None图像 MIME 类型如image/png、image/jpeg。大多数 LLM 提供商要求必须提供若缺失初始化时会通过filetype库从字节流猜测猜测失败仅发出警告。detailLiteral[auto, high, low] | None图像细节级别目前仅 OpenAI 系列模型支持会被原样透传给下游。metadict随图像的元数据如file_path、page_number。**validationbool默认 True是否执行 base64 合法性校验与 MIME 类型校验。从源码看ImageContent在__post_init__中会做三件事校验 base64 字符串合法性、缺失时猜测 MIME 类型、校验 MIME 类型必须在IMAGE_MIME_TYPES集合内该集合来自 PIL 的FORMAT_TO_MIME映射覆盖 JPEG、PNG、GIF、WEBP、TIFF、BMP、ICO 等常见格式见 image_content.py。此外它还提供了show()在 Jupyter 或本地窗口显示图片、to_dict()/from_dict()序列化、from_file_path()与from_url()便捷构造等方法其中from_file_path底层就是复用ImageFileToImageContent组件from_url则先通过LinkContentFetcher下载再转换。DocumentToImageContent从 Document 元数据提取图像DocumentToImageContent处理的是已经存在于索引管线中的 Document——它并不接受裸文件路径而是读取每个Document元数据里的文件路径字段把对应的图片文件或 PDF 页面转成ImageContent。它的声明与使用示例如下from haystack import Document from haystack.components.converters.image.document_to_image import DocumentToImageContent converter DocumentToImageContent( file_path_meta_fieldfile_path, root_pathtest/test_files, detailhigh, size(800, 600) ) documents [ Document(contentOptional description of apple.jpg, meta{file_path: images/apple.jpg}), Document( contentOptional description of sample_pdf_1.pdf, meta{file_path: pdf/sample_pdf_1.pdf, page_number: 1} ) ] result converter.run(documents) image_contents result[image_contents] # [ImageContent( # base64_image/9j/4A..., mime_typeimage/jpeg, detailhigh, meta{file_path: images/apple.jpg} # ), # ImageContent( # base64_image/9j/4A..., mime_typeimage/jpeg, detailhigh, # meta{file_path: pdf/sample_pdf_1.pdf, page_number: 1}) # )]参数说明__init__的签名如下__init__( *, file_path_meta_field: str file_path, root_path: str | None None, detail: Literal[auto, high, low] | None None, size: tuple[int, int] | None None ) - Nonefile_path_meta_fieldstr默认file_pathDocument 元数据中存放图片/PDF 路径的键名。root_pathstr | None文档文件所在根目录。提供后元数据中的路径将相对于该目录解析并强制保证解析后的路径不越出该目录为None时路径被当作绝对路径处理、不做包含性检查。detail图像细节级别透传给ImageContent。size(width, height)元组。若提供图像将等比缩放到该尺寸之内从而降低文件体积、内存占用与处理耗时对带有分辨率限制的模型或需要向远程服务传输图像的场景尤其有用。run 方法run(documents: list[Document]) - dict[str, list[ImageContent | None]]输入documents中每个 Document 的元数据至少需包含file_path_meta_field键PDF 类文档额外必须包含page_number键以指定要抽取哪一页。返回字典含单一键image_contents其顺序与输入 Document 顺序一一对应若某个 Document 转换失败对应位置为None并会打印一条包含 Document ID 的警告日志见 document_to_image.py。异常行为若任何 Document 缺少必需元数据键、文件路径无效、MIME 类型不受支持或 PDF 文档缺少page_number都会抛出ValueError错误信息会明确指出是哪个 Document、缺失/错误的是什么。底层处理流程从 document_to_image.py 的实现可以看到其内部算法调用_extract_image_sources_info对每个 Document 做校验与路径解析检查file_path_meta_field键是否存在、解析路径、验证文件存在、通过mimetypes.guess_type或元数据中的mime_type判断类型并校验其属于IMAGE_MIME_TYPESPDF 文档额外校验page_number。图片文件走ByteStream.from_file_path_encode_image_to_base64直接编码PDF 文档则先收集页码信息。所有 PDF 页按文件路径分组批处理_batch_convert_pdf_pages_to_images保证同一个 PDF 只被打开一次再映射回各自的 Document 索引输出 MIME 类型统一为image/jpeg。安全提示路径穿越防护该组件会从宿主文件系统读取file_path_meta_field指向的文件。如果 Document 元数据可能受不可信输入影响例如由上游 LLM 或用户生成务必设置root_path指向专用数据目录。源码在 image_utils.py 中通过resolve()后再用is_relative_to()判断解析路径是否仍位于根目录内任何试图逃逸的载荷如绝对路径或../都会被拒绝并抛出ValueError。这是该组件与纯文件转换器最核心的差异点之一。ImageFileToDocument把图片路径包装成 DocumentImageFileToDocument是一个轻量包装器它不提取图片的任何内容只为每个图片源创建一个contentNone的空Document并把文件路径等元数据附加其上。这种结构非常适合那些以 Document 为单位消费图片路径的组件例如LLMDocumentContentExtractor或sentence-transformers-haystack集成中的SentenceTransformersDocumentImageEmbedder。from haystack.components.converters.image import ImageFileToDocument converter ImageFileToDocument() sources [image.jpg, another_image.png] result converter.run(sourcessources) documents result[documents] print(documents) # [Document(id..., meta: {file_path: image.jpg}), # Document(id..., meta: {file_path: another_image.png})]参数说明__init__(*, store_full_path: bool False) - Nonestore_full_pathbool默认False为True时在元数据中保存文件的完整路径为False时只保存文件名os.path.basename处理见 file_to_document.py。run 方法run( *, sources: list[str | Path | ByteStream], meta: dict[str, Any] | list[dict[str, Any]] | None None ) - dict[str, list[Document]]sources要转换的文件路径或ByteStream对象列表。meta附加到 Document 的元数据。可以是单个字典加到所有输出 Document或字典列表长度必须与sources数量一致按位置 zipByteStream自身的meta也会合并进输出。实现上通过normalize_metadata统一处理三种形态且单个字典会被深拷贝以保证每个 Document 的元数据互不共享见 converters/utils.py。返回字典含documents键值为 content 为空、元数据完整的Document列表。ImageFileToImageContent图片文件直接转 ImageContent与ImageFileToDocument不同ImageFileToImageContent会真正读取图片文件并编码为 base64 图像内容是图片 → 多模态输入最直接的路径from haystack.components.converters.image import ImageFileToImageContent converter ImageFileToImageContent() sources [image.jpg, another_image.png] image_contents converter.run(sourcessources)[image_contents] print(image_contents) # [ImageContent(base64_image..., # mime_typeimage/jpeg, # detailNone, # meta{file_path: image.jpg}), # ...]构造参数与运行期覆盖__init__( *, detail: Literal[auto, high, low] | None None, size: tuple[int, int] | None None ) - Nonerun( sources: list[str | Path | ByteStream], meta: dict[str, Any] | list[dict[str, Any]] | None None, *, detail: Literal[auto, high, low] | None None, size: tuple[int, int] | None None ) - dict[str, list[ImageContent]]构造时设置的detail与size作为默认值run时传入的同名参数优先覆盖构造值resolved_detail detail or self.detail。返回字典含image_contents键。源码级行为细节空sources直接返回空列表见 file_to_image.py。对每个源读取失败、文件为空data b、编码失败如不是合法图片都会记录警告并跳过该文件而不是整体失败见 file_to_image.py。若ByteStream没有 MIME 类型且源是Path会尝试用mimetypes.guess_type推断。size参数被设置时要求安装 Pillow懒加载检查提示pip install pillow编码逻辑见下文底层原理。最终ImageContent的元数据是{**bytestream.meta, **metadata}的合并结果detail使用运行期解析值。PDFToImageContent按页渲染 PDF 为图像PDFToImageContent把 PDF 文件按页渲染成多张ImageContent每一页对应一个输出对象其meta中会带上对应的page_numberfrom haystack.components.converters.image import PDFToImageContent converter PDFToImageContent() sources [file.pdf, another_file.pdf] image_contents converter.run(sourcessources)[image_contents] print(image_contents) # [ImageContent(base64_image..., # mime_typeapplication/pdf, # detailNone, # meta{file_path: file.pdf, page_number: 1}), # ...]参数说明__init__( *, detail: Literal[auto, high, low] | None None, size: tuple[int, int] | None None, page_range: list[str | int] | None None ) - Nonedetail/size语义与ImageFileToImageContent相同。page_rangelist[str | int] | None要转换为图像的页码与/或页码范围列表页码从 1 开始。为None时转换 PDF 全部页面超出有效范围1 到总页数的页面会被跳过并告警。支持数字与可打印范围字符串混合例如page_range[1, 3]只转第 1、3 页而[1-3, 5, 8, 10-12]会转换第 1、2、3、5、8、10、11、12 页。run 方法run( sources: list[str | Path | ByteStream], meta: dict[str, Any] | list[dict[str, Any]] | None None, *, detail: Literal[auto, high, low] | None None, size: tuple[int, int] | None None, page_range: list[str | int] | None None ) - dict[str, list[ImageContent]]run期的detail、size、page_range均会覆盖构造时的默认值。返回字典含image_contents键输出页面按文件顺序排列每个ImageContent的 MIME 类型固定为image/jpeg因为 PDF 页面已被栅格化为 JPEG。page_range 的展开机制page_range中的范围字符串由 utils/misc.py 的expand_page_range展开为整数列表整数直接保留纯数字字符串转intstart-end形式的字符串展开为闭区间。非法输入如-混在整数表达式里、非数字范围会抛出ValueError空列表同样报错。展开后的页码在 image_utils.py 中被逐个校验越界页记录警告并跳过。底层原理编码、缩放与 PDF 渲染四个组件共享 image_utils.py 中的三个核心工具函数理解它们有助于预估性能与输出行为。base64 编码与等比缩放_encode_image_to_base64不传size时直接对ByteStream.data做base64.b64encodeMIME 类型取字节流已有值缺失时打警告可能引发下游兼容问题。传size时用 Pillow 打开图片优先按字节流 MIME 类型对应的格式解析随后用image.thumbnail(sizesize, reducing_gapNone)原地等比缩小reducing_gapNone禁用多步缩小以获得更好画质最后按 MIME 类型重新编码为 base64。若无法确定 MIME 类型默认image/jpeg。编码时若目标是 JPEG 而图片带透明通道RGBA、LA或带 transparency 的调色板模式会自动先转成RGB再保存见 image_utils.py。PDF 页面渲染_convert_pdf_to_imagesPDF 渲染依赖pypdfium2懒加载提示pip install pypdfium2流程为用PdfDocument打开字节流读取失败或 PDF 为空时记录警告并返回空列表。默认以300 DPI渲染target_scale 300 / 72.0。大 PDF 保护计算目标分辨率下的像素总量若超过 PillowMAX_IMAGE_PIXELS的 90%会自动降低 scale 以适配像素上限避免 PIL 的 DecompressionBomb 报错见 image_utils.py。逐页page.render(scalescale)→ 转 PIL Image → 可选thumbnail缩放 → 编码为 JPEG base64。批处理优化_batch_convert_pdf_pages_to_images当多个 Document 指向同一 PDF 的不同页时该函数按文件路径分组defaultdict(list)每个 PDF 只打开并渲染一次再把结果映射回各 Document 索引见 image_utils.py。DocumentToImageContent正是借此实现同 PDF 多页抽取的高效处理。在 Pipeline 中的编排示例图像转换器通常作为多模态管线的入口环节。以PDF 文档 → 页面图像 → 多模态模型理解为例可先由PDFToImageContent产出图像再接多模态 Chat Generator 或经过LLMDocumentContentExtractor抽取文档内容而ImageFileToDocument产出的空 Document 则适合接入按 Document 消费路径的下游如图像嵌入器。from haystack import Pipeline from haystack.components.converters.image import PDFToImageContent from haystack.components.generators.chat.openai import OpenAIChatGenerator pipeline Pipeline() pipeline.add_component(pdf_to_images, PDFToImageContent(page_range[1-3])) # pipeline.add_component(llm, OpenAIChatGenerator(...)) # pipeline.connect(pdf_to_images.image_contents, llm.images)注意此类转换器输出是 base64 图像列表接入的模型组件必须支持图像输入例如支持 vision 的 Chat Generator具体连接方式取决于下游组件对图像内容参数的声明。依赖与安装图像转换器用到两个可选依赖均通过LazyImport懒加载并在需要时给出明确提示Pillowpip install pillow图片解码、等比缩放与 JPEG 编码涉及size参数或 PDF 页面编码时必需。pypdfium2pip install pypdfium2PDF 页面栅格化DocumentToImageContent与PDFToImageContent必需构造时即检查见 document_to_image.py 与 pdf_to_image.py。若只想把图片转成ImageContent而不涉及 PDF 与缩放ImageFileToImageContent在不设置size时可以零额外依赖运行。测试与验证仓库为每个组件都配有完整的单元测试可作为使用方式的补充参考test_document_to_image_content.py覆盖 Document 元数据校验、PDF 页码缺失报错、路径穿越防护、输出顺序与None占位等 12 个用例。test_file_to_image.py 与 test_pdf_to_image.py各 9 个用例覆盖空输入、非法源跳过、page_range展开与越界跳过等行为。test_file_to_document.py8 个用例验证store_full_path与元数据合并逻辑。测试使用的示例文件位于 test/test_files其中包含用于验证 PDF 转换的sample_pdf_1.pdf等资源。小结与选型建议四个图像转换器覆盖了多模态管线的常见入口场景选型时可依据数据形态与下游消费方式判断数据已是 Document 且元数据带路径如索引管线产物→DocumentToImageContent注意配置root_path防范路径穿越。只有图片文件路径下游按 Document 消费→ImageFileToDocument。只有图片文件直接喂给多模态模型→ImageFileToImageContent。PDF 文件需要按页转图像→PDFToImageContent善用page_range控制转换页数。无论选择哪个组件输出端统一的ImageContent数据结构都保证了与 Haystack 多模态生态的无缝衔接——这正是该转换器族设计上的一致性所在。【免费下载链接】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 图像转换器（Image Converters）完全指南：文档、图片与 PDF 到多模态 ImageContent 的转换实战
Haystack 图像转换器Image Converters完全指南文档、图片与 PDF 到多模态 ImageContent 的转换实战【免费下载链接】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 开源 AI 编排框架中的图像转换器模块为核心系统讲解DocumentToImageContent、ImageFileToDocument、ImageFileToImageContent与PDFToImageContent四个组件的用法、参数与底层实现。读完本文你将掌握如何把磁盘上的图片与 PDF 文件转换为可供多模态大模型直接消费的ImageContentbase64 编码图像并能在 Pipeline 中正确编排这些转换器以支撑图文理解、图片检索等场景。概览Haystack 的图像转换器家族在 Haystack 中转换器Converter负责把外部数据文件、字节流等变成下游组件可消费的数据结构。图像转换器专门处理图像格式的数据统一输出ImageContent对象或承载路径元数据的空Document。它们都位于haystack/components/converters/image/目录下公开导出四个组件见 image/init.py组件输入输出典型用途DocumentToImageContent带元数据的Document列表文件路径 MIME 类型 页码ImageContent列表把索引管线中已存在的 Document源自 PDF/图片转换成图像内容ImageFileToDocument文件路径 /Path/ByteStream列表content 为None的空Document把图片路径包装成 Document供下游提取器、嵌入器消费ImageFileToImageContent文件路径 /Path/ByteStream列表ImageContent列表把图片文件直接转成 base64 图像内容PDFToImageContent文件路径 /Path/ByteStream列表ImageContent列表每页一个把 PDF 按页渲染成图像这些组件遵循 Haystack 组件的统一约定通过component装饰器注册如 document_to_image.pyrun方法返回字典键名由component.output_types声明例如image_contents、documents。核心数据结构ImageContent所有转成图像的组件最终都产出 ImageContent 数据类它是连接转换器与多模态模型的桥梁。其字段包括base64_imagestrbase64 编码的图像字符串可直接嵌入多模态 API 请求。mime_typestr | None图像 MIME 类型如image/png、image/jpeg。大多数 LLM 提供商要求必须提供若缺失初始化时会通过filetype库从字节流猜测猜测失败仅发出警告。detailLiteral[auto, high, low] | None图像细节级别目前仅 OpenAI 系列模型支持会被原样透传给下游。metadict随图像的元数据如file_path、page_number。**validationbool默认 True是否执行 base64 合法性校验与 MIME 类型校验。从源码看ImageContent在__post_init__中会做三件事校验 base64 字符串合法性、缺失时猜测 MIME 类型、校验 MIME 类型必须在IMAGE_MIME_TYPES集合内该集合来自 PIL 的FORMAT_TO_MIME映射覆盖 JPEG、PNG、GIF、WEBP、TIFF、BMP、ICO 等常见格式见 image_content.py。此外它还提供了show()在 Jupyter 或本地窗口显示图片、to_dict()/from_dict()序列化、from_file_path()与from_url()便捷构造等方法其中from_file_path底层就是复用ImageFileToImageContent组件from_url则先通过LinkContentFetcher下载再转换。DocumentToImageContent从 Document 元数据提取图像DocumentToImageContent处理的是已经存在于索引管线中的 Document——它并不接受裸文件路径而是读取每个Document元数据里的文件路径字段把对应的图片文件或 PDF 页面转成ImageContent。它的声明与使用示例如下from haystack import Document from haystack.components.converters.image.document_to_image import DocumentToImageContent converter DocumentToImageContent( file_path_meta_fieldfile_path, root_pathtest/test_files, detailhigh, size(800, 600) ) documents [ Document(contentOptional description of apple.jpg, meta{file_path: images/apple.jpg}), Document( contentOptional description of sample_pdf_1.pdf, meta{file_path: pdf/sample_pdf_1.pdf, page_number: 1} ) ] result converter.run(documents) image_contents result[image_contents] # [ImageContent( # base64_image/9j/4A..., mime_typeimage/jpeg, detailhigh, meta{file_path: images/apple.jpg} # ), # ImageContent( # base64_image/9j/4A..., mime_typeimage/jpeg, detailhigh, # meta{file_path: pdf/sample_pdf_1.pdf, page_number: 1}) # )]参数说明__init__的签名如下__init__( *, file_path_meta_field: str file_path, root_path: str | None None, detail: Literal[auto, high, low] | None None, size: tuple[int, int] | None None ) - Nonefile_path_meta_fieldstr默认file_pathDocument 元数据中存放图片/PDF 路径的键名。root_pathstr | None文档文件所在根目录。提供后元数据中的路径将相对于该目录解析并强制保证解析后的路径不越出该目录为None时路径被当作绝对路径处理、不做包含性检查。detail图像细节级别透传给ImageContent。size(width, height)元组。若提供图像将等比缩放到该尺寸之内从而降低文件体积、内存占用与处理耗时对带有分辨率限制的模型或需要向远程服务传输图像的场景尤其有用。run 方法run(documents: list[Document]) - dict[str, list[ImageContent | None]]输入documents中每个 Document 的元数据至少需包含file_path_meta_field键PDF 类文档额外必须包含page_number键以指定要抽取哪一页。返回字典含单一键image_contents其顺序与输入 Document 顺序一一对应若某个 Document 转换失败对应位置为None并会打印一条包含 Document ID 的警告日志见 document_to_image.py。异常行为若任何 Document 缺少必需元数据键、文件路径无效、MIME 类型不受支持或 PDF 文档缺少page_number都会抛出ValueError错误信息会明确指出是哪个 Document、缺失/错误的是什么。底层处理流程从 document_to_image.py 的实现可以看到其内部算法调用_extract_image_sources_info对每个 Document 做校验与路径解析检查file_path_meta_field键是否存在、解析路径、验证文件存在、通过mimetypes.guess_type或元数据中的mime_type判断类型并校验其属于IMAGE_MIME_TYPESPDF 文档额外校验page_number。图片文件走ByteStream.from_file_path_encode_image_to_base64直接编码PDF 文档则先收集页码信息。所有 PDF 页按文件路径分组批处理_batch_convert_pdf_pages_to_images保证同一个 PDF 只被打开一次再映射回各自的 Document 索引输出 MIME 类型统一为image/jpeg。安全提示路径穿越防护该组件会从宿主文件系统读取file_path_meta_field指向的文件。如果 Document 元数据可能受不可信输入影响例如由上游 LLM 或用户生成务必设置root_path指向专用数据目录。源码在 image_utils.py 中通过resolve()后再用is_relative_to()判断解析路径是否仍位于根目录内任何试图逃逸的载荷如绝对路径或../都会被拒绝并抛出ValueError。这是该组件与纯文件转换器最核心的差异点之一。ImageFileToDocument把图片路径包装成 DocumentImageFileToDocument是一个轻量包装器它不提取图片的任何内容只为每个图片源创建一个contentNone的空Document并把文件路径等元数据附加其上。这种结构非常适合那些以 Document 为单位消费图片路径的组件例如LLMDocumentContentExtractor或sentence-transformers-haystack集成中的SentenceTransformersDocumentImageEmbedder。from haystack.components.converters.image import ImageFileToDocument converter ImageFileToDocument() sources [image.jpg, another_image.png] result converter.run(sourcessources) documents result[documents] print(documents) # [Document(id..., meta: {file_path: image.jpg}), # Document(id..., meta: {file_path: another_image.png})]参数说明__init__(*, store_full_path: bool False) - Nonestore_full_pathbool默认False为True时在元数据中保存文件的完整路径为False时只保存文件名os.path.basename处理见 file_to_document.py。run 方法run( *, sources: list[str | Path | ByteStream], meta: dict[str, Any] | list[dict[str, Any]] | None None ) - dict[str, list[Document]]sources要转换的文件路径或ByteStream对象列表。meta附加到 Document 的元数据。可以是单个字典加到所有输出 Document或字典列表长度必须与sources数量一致按位置 zipByteStream自身的meta也会合并进输出。实现上通过normalize_metadata统一处理三种形态且单个字典会被深拷贝以保证每个 Document 的元数据互不共享见 converters/utils.py。返回字典含documents键值为 content 为空、元数据完整的Document列表。ImageFileToImageContent图片文件直接转 ImageContent与ImageFileToDocument不同ImageFileToImageContent会真正读取图片文件并编码为 base64 图像内容是图片 → 多模态输入最直接的路径from haystack.components.converters.image import ImageFileToImageContent converter ImageFileToImageContent() sources [image.jpg, another_image.png] image_contents converter.run(sourcessources)[image_contents] print(image_contents) # [ImageContent(base64_image..., # mime_typeimage/jpeg, # detailNone, # meta{file_path: image.jpg}), # ...]构造参数与运行期覆盖__init__( *, detail: Literal[auto, high, low] | None None, size: tuple[int, int] | None None ) - Nonerun( sources: list[str | Path | ByteStream], meta: dict[str, Any] | list[dict[str, Any]] | None None, *, detail: Literal[auto, high, low] | None None, size: tuple[int, int] | None None ) - dict[str, list[ImageContent]]构造时设置的detail与size作为默认值run时传入的同名参数优先覆盖构造值resolved_detail detail or self.detail。返回字典含image_contents键。源码级行为细节空sources直接返回空列表见 file_to_image.py。对每个源读取失败、文件为空data b、编码失败如不是合法图片都会记录警告并跳过该文件而不是整体失败见 file_to_image.py。若ByteStream没有 MIME 类型且源是Path会尝试用mimetypes.guess_type推断。size参数被设置时要求安装 Pillow懒加载检查提示pip install pillow编码逻辑见下文底层原理。最终ImageContent的元数据是{**bytestream.meta, **metadata}的合并结果detail使用运行期解析值。PDFToImageContent按页渲染 PDF 为图像PDFToImageContent把 PDF 文件按页渲染成多张ImageContent每一页对应一个输出对象其meta中会带上对应的page_numberfrom haystack.components.converters.image import PDFToImageContent converter PDFToImageContent() sources [file.pdf, another_file.pdf] image_contents converter.run(sourcessources)[image_contents] print(image_contents) # [ImageContent(base64_image..., # mime_typeapplication/pdf, # detailNone, # meta{file_path: file.pdf, page_number: 1}), # ...]参数说明__init__( *, detail: Literal[auto, high, low] | None None, size: tuple[int, int] | None None, page_range: list[str | int] | None None ) - Nonedetail/size语义与ImageFileToImageContent相同。page_rangelist[str | int] | None要转换为图像的页码与/或页码范围列表页码从 1 开始。为None时转换 PDF 全部页面超出有效范围1 到总页数的页面会被跳过并告警。支持数字与可打印范围字符串混合例如page_range[1, 3]只转第 1、3 页而[1-3, 5, 8, 10-12]会转换第 1、2、3、5、8、10、11、12 页。run 方法run( sources: list[str | Path | ByteStream], meta: dict[str, Any] | list[dict[str, Any]] | None None, *, detail: Literal[auto, high, low] | None None, size: tuple[int, int] | None None, page_range: list[str | int] | None None ) - dict[str, list[ImageContent]]run期的detail、size、page_range均会覆盖构造时的默认值。返回字典含image_contents键输出页面按文件顺序排列每个ImageContent的 MIME 类型固定为image/jpeg因为 PDF 页面已被栅格化为 JPEG。page_range 的展开机制page_range中的范围字符串由 utils/misc.py 的expand_page_range展开为整数列表整数直接保留纯数字字符串转intstart-end形式的字符串展开为闭区间。非法输入如-混在整数表达式里、非数字范围会抛出ValueError空列表同样报错。展开后的页码在 image_utils.py 中被逐个校验越界页记录警告并跳过。底层原理编码、缩放与 PDF 渲染四个组件共享 image_utils.py 中的三个核心工具函数理解它们有助于预估性能与输出行为。base64 编码与等比缩放_encode_image_to_base64不传size时直接对ByteStream.data做base64.b64encodeMIME 类型取字节流已有值缺失时打警告可能引发下游兼容问题。传size时用 Pillow 打开图片优先按字节流 MIME 类型对应的格式解析随后用image.thumbnail(sizesize, reducing_gapNone)原地等比缩小reducing_gapNone禁用多步缩小以获得更好画质最后按 MIME 类型重新编码为 base64。若无法确定 MIME 类型默认image/jpeg。编码时若目标是 JPEG 而图片带透明通道RGBA、LA或带 transparency 的调色板模式会自动先转成RGB再保存见 image_utils.py。PDF 页面渲染_convert_pdf_to_imagesPDF 渲染依赖pypdfium2懒加载提示pip install pypdfium2流程为用PdfDocument打开字节流读取失败或 PDF 为空时记录警告并返回空列表。默认以300 DPI渲染target_scale 300 / 72.0。大 PDF 保护计算目标分辨率下的像素总量若超过 PillowMAX_IMAGE_PIXELS的 90%会自动降低 scale 以适配像素上限避免 PIL 的 DecompressionBomb 报错见 image_utils.py。逐页page.render(scalescale)→ 转 PIL Image → 可选thumbnail缩放 → 编码为 JPEG base64。批处理优化_batch_convert_pdf_pages_to_images当多个 Document 指向同一 PDF 的不同页时该函数按文件路径分组defaultdict(list)每个 PDF 只打开并渲染一次再把结果映射回各 Document 索引见 image_utils.py。DocumentToImageContent正是借此实现同 PDF 多页抽取的高效处理。在 Pipeline 中的编排示例图像转换器通常作为多模态管线的入口环节。以PDF 文档 → 页面图像 → 多模态模型理解为例可先由PDFToImageContent产出图像再接多模态 Chat Generator 或经过LLMDocumentContentExtractor抽取文档内容而ImageFileToDocument产出的空 Document 则适合接入按 Document 消费路径的下游如图像嵌入器。from haystack import Pipeline from haystack.components.converters.image import PDFToImageContent from haystack.components.generators.chat.openai import OpenAIChatGenerator pipeline Pipeline() pipeline.add_component(pdf_to_images, PDFToImageContent(page_range[1-3])) # pipeline.add_component(llm, OpenAIChatGenerator(...)) # pipeline.connect(pdf_to_images.image_contents, llm.images)注意此类转换器输出是 base64 图像列表接入的模型组件必须支持图像输入例如支持 vision 的 Chat Generator具体连接方式取决于下游组件对图像内容参数的声明。依赖与安装图像转换器用到两个可选依赖均通过LazyImport懒加载并在需要时给出明确提示Pillowpip install pillow图片解码、等比缩放与 JPEG 编码涉及size参数或 PDF 页面编码时必需。pypdfium2pip install pypdfium2PDF 页面栅格化DocumentToImageContent与PDFToImageContent必需构造时即检查见 document_to_image.py 与 pdf_to_image.py。若只想把图片转成ImageContent而不涉及 PDF 与缩放ImageFileToImageContent在不设置size时可以零额外依赖运行。测试与验证仓库为每个组件都配有完整的单元测试可作为使用方式的补充参考test_document_to_image_content.py覆盖 Document 元数据校验、PDF 页码缺失报错、路径穿越防护、输出顺序与None占位等 12 个用例。test_file_to_image.py 与 test_pdf_to_image.py各 9 个用例覆盖空输入、非法源跳过、page_range展开与越界跳过等行为。test_file_to_document.py8 个用例验证store_full_path与元数据合并逻辑。测试使用的示例文件位于 test/test_files其中包含用于验证 PDF 转换的sample_pdf_1.pdf等资源。小结与选型建议四个图像转换器覆盖了多模态管线的常见入口场景选型时可依据数据形态与下游消费方式判断数据已是 Document 且元数据带路径如索引管线产物→DocumentToImageContent注意配置root_path防范路径穿越。只有图片文件路径下游按 Document 消费→ImageFileToDocument。只有图片文件直接喂给多模态模型→ImageFileToImageContent。PDF 文件需要按页转图像→PDFToImageContent善用page_range控制转换页数。无论选择哪个组件输出端统一的ImageContent数据结构都保证了与 Haystack 多模态生态的无缝衔接——这正是该转换器族设计上的一致性所在。【免费下载链接】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），仅供参考