文档API 参考📓 教程🧑‍🍳 食谱🤝 集成💜 Discord🎨 Studio
API 参考

图像转换器

各种转换器，用于将图像数据从一种格式转换为另一种格式。

模块 document_to_image

DocumentToImageContent

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

此组件处理文档列表，并从支持的文件格式中提取视觉内容，将其转换为可用于多模态 AI 任务的 ImageContents。它通过提取特定页面作为图像来处理直接图像文件和 PDF 文档。

文档应包含元数据

  • 该file_path_meta_field 键，其中包含一个有效文件路径，该路径在与root_path
  • 支持的图像格式（MIME 类型必须是受支持的图像类型之一）
  • 对于 PDF 文件，一个page_number 键，指定要提取的页面

使用示例

```python
from haystack import Document
from haystack.components.converters.image.document_to_image import DocumentToImageContent

converter = DocumentToImageContent(
    file_path_meta_field="file_path",
    root_path="/data/files",
    detail="high",
    size=(800, 600)
)

documents = [
    Document(content="Optional description of image.jpg", meta={"file_path": "image.jpg"}),
    Document(content="Text content of page 1 of doc.pdf", meta={"file_path": "doc.pdf", "page_number": 1})
]

result = converter.run(documents)
image_contents = result["image_contents"]
# [ImageContent(
#    base64_image='/9j/4A...', mime_type='image/jpeg', detail='high', meta={'file_path': 'image.jpg'}
#  ),
#  ImageContent(
#    base64_image='/9j/4A...', mime_type='image/jpeg', detail='high',
#    meta={'page_number': 1, 'file_path': 'doc.pdf'}
#  )]
```

DocumentToImageContent.__init__

def __init__(*,
             file_path_meta_field: str = "file_path",
             root_path: Optional[str] = None,
             detail: Optional[Literal["auto", "high", "low"]] = None,
             size: Optional[tuple[int, int]] = None)

初始化 DocumentToImageContent 组件。

参数:

  • file_path_meta_field: Document 中包含图像或 PDF 文件路径的元数据字段。
  • root_path: 存储文档文件的根目录路径。如果提供，文档元数据中的文件路径将相对于此路径解析。如果为 None，则文件路径被视为绝对路径。
  • detail: 可选的图像详细信息级别（仅 OpenAI 支持）。可以是 "auto"、"high" 或 "low"。这将传递给创建的 ImageContent 对象。
  • size: 如果提供，则将图像调整为适合指定的尺寸（宽度，高度），同时保持纵横比。这可以减小文件大小、内存使用量和处理时间，这在处理具有分辨率限制的模型或向远程服务传输图像时非常有用。

DocumentToImageContent.run

@component.output_types(image_contents=list[Optional[ImageContent]])
def run(documents: list[Document]) -> dict[str, list[Optional[ImageContent]]]

将具有图像或 PDF 源的文档转换为 ImageContent 对象。

此方法处理输入文档，从支持的文件格式中提取图像并将其转换为 ImageContent 对象。

参数:

  • documents: 要处理的文档列表。每个文档都应包含至少一个 'file_path_meta_field' 键的元数据。PDF 文档还需要一个 'page_number' 键来指定要转换的页面。

引发:

  • ValueError: 如果任何文档缺少必需的元数据键、文件路径无效或 MIME 类型不受支持。错误消息将指明哪个文档以及缺少或不正确的信息。

返回值:

包含一个键的字典

  • "image_contents": 从处理过的文档创建的 ImageContents。这些包含 base64 编码的图像数据和元数据。顺序对应于输入文档的顺序。

模块 file_to_document

ImageFileToDocument

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

当图像文件路径需要被包装到Document 对象中以便被下游组件（如SentenceTransformersImageDocumentEmbedder.

）处理时，此组件非常有用。它**不**从图像文件中提取任何内容，而是创建Document 对象，其内容为None，并附加文件路径和任何用户提供的值的元数据。

使用示例

from haystack.components.converters.image import ImageFileToDocument

converter = ImageFileToDocument()

sources = ["image.jpg", "another_image.png"]

result = converter.run(sources=sources)
documents = result["documents"]

print(documents)

# [Document(id=..., meta: {'file_path': 'image.jpg'}),
# Document(id=..., meta: {'file_path': 'another_image.png'})]

ImageFileToDocument.__init__

def __init__(*, store_full_path: bool = False)

初始化 ImageFileToDocument 组件。

参数:

  • store_full_path: 如果为 True，则文件的完整路径将存储在文档的元数据中。如果为 False，则仅存储文件名。

ImageFileToDocument.run

@component.output_types(documents=list[Document])
def run(
    *,
    sources: list[Union[str, Path, ByteStream]],
    meta: Optional[Union[dict[str, Any], list[dict[str, Any]]]] = None
) -> dict[str, list[Document]]

将图像文件转换为带有元数据的空 Document 对象。

此方法接受图像文件引用（作为文件路径或 ByteStreams）并创建Document 对象，但没有内容。这些文档会通过从输入源派生的元数据和可选的用户提供的元数据进行丰富。

参数:

  • sources: 要转换的 PDF 文件路径或 ByteStream 对象列表。
  • meta: 可选的要附加到文档的元数据。此值可以是字典列表或单个字典。如果为单个字典，则其内容将添加到所有生成的文档的元数据中。如果为列表，其长度必须与源的数量匹配，因为它们会被一起打包。对于 ByteStream 对象，它们的meta 将被添加到输出文档中。

返回值:

一个包含

  • documents: Document 对象列表。Document 对象，内容为空，并附有相关元数据。

模块 file_to_image

ImageFileToImageContent

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

使用示例

from haystack.components.converters.image import ImageFileToImageContent

converter = ImageFileToImageContent()

sources = ["image.jpg", "another_image.png"]

image_contents = converter.run(sources=sources)["image_contents"]
print(image_contents)

# [ImageContent(base64_image='...',
#               mime_type='image/jpeg',
#               detail=None,
#               meta={'file_path': 'image.jpg'}),
#  ...]

ImageFileToImageContent.__init__

def __init__(*,
             detail: Optional[Literal["auto", "high", "low"]] = None,
             size: Optional[tuple[int, int]] = None)

创建 ImageFileToImageContent 组件。

参数:

  • detail: 可选的图像详细信息级别（仅 OpenAI 支持）。可以是 "auto"、"high" 或 "low"。这将传递给创建的 ImageContent 对象。
  • size: 如果提供，则将图像调整为适合指定的尺寸（宽度，高度），同时保持纵横比。这可以减小文件大小、内存使用量和处理时间，这在处理具有分辨率限制的模型或向远程服务传输图像时非常有用。

ImageFileToImageContent.run

@component.output_types(image_contents=list[ImageContent])
def run(sources: list[Union[str, Path, ByteStream]],
        meta: Optional[Union[dict[str, Any], list[dict[str, Any]]]] = None,
        *,
        detail: Optional[Literal["auto", "high", "low"]] = None,
        size: Optional[tuple[int,
                             int]] = None) -> dict[str, list[ImageContent]]

将文件转换为 ImageContent 对象。

参数:

  • sources: 要转换的 PDF 文件路径或 ByteStream 对象列表。
  • meta: 可选的要附加到 ImageContent 对象的元数据。此值可以是字典列表或单个字典。如果为单个字典，则其内容将添加到所有生成的 ImageContent 对象的元数据中。如果为列表，其长度必须与源的数量匹配，因为它们会被一起打包。对于 ByteStream 对象，它们的meta 会被添加到输出的 ImageContent 对象中。
  • detail: 可选的图像详细信息级别（仅 OpenAI 支持）。可以是 "auto"、"high" 或 "low"。这将传递给创建的 ImageContent 对象。如果未提供，详细信息级别将是构造函数中设置的级别。
  • size: 如果提供，则将图像调整到指定尺寸（宽度、高度）以内的尺寸，同时保持纵横比。这可以减小文件大小、内存使用和处理时间，这在处理具有分辨率限制的模型或将图像传输到远程服务时非常有用。如果未提供，则 size 值将是构造函数中设置的值。

返回值:

包含以下键的字典

  • image_contents: ImageContent 对象列表。

模块 pdf_to_image

PDFToImageContent

将 PDF 文件转换为 ImageContent 对象。

使用示例

from haystack.components.converters.image import PDFToImageContent

converter = PDFToImageContent()

sources = ["file.pdf", "another_file.pdf"]

image_contents = converter.run(sources=sources)["image_contents"]
print(image_contents)

# [ImageContent(base64_image='...',
#               mime_type='application/pdf',
#               detail=None,
#               meta={'file_path': 'file.pdf', 'page_number': 1}),
#  ...]

PDFToImageContent.__init__

def __init__(*,
             detail: Optional[Literal["auto", "high", "low"]] = None,
             size: Optional[tuple[int, int]] = None,
             page_range: Optional[list[Union[str, int]]] = None)

创建 PDFToImageContent 组件。

参数:

  • detail: 可选的图像详细信息级别（仅 OpenAI 支持）。可以是 "auto"、"high" 或 "low"。这将传递给创建的 ImageContent 对象。
  • size: 如果提供，则将图像调整为适合指定的尺寸（宽度，高度），同时保持纵横比。这可以减小文件大小、内存使用量和处理时间，这在处理具有分辨率限制的模型或向远程服务传输图像时非常有用。
  • page_range: 要转换为图像的页码和/或页码范围列表。页码从 1 开始。如果为 None，将转换 PDF 中的所有页面。超出有效范围（1 到页数）的页面将被跳过并发出警告。例如，page_range=[1, 3] 将仅转换文档的第一页和第三页。它还接受可打印的范围字符串，例如：['1-3', '5', '8', '10-12'] 将转换第 1、2、3、5、8、10、11、12 页。

PDFToImageContent.run

@component.output_types(image_contents=list[ImageContent])
def run(
    sources: list[Union[str, Path, ByteStream]],
    meta: Optional[Union[dict[str, Any], list[dict[str, Any]]]] = None,
    *,
    detail: Optional[Literal["auto", "high", "low"]] = None,
    size: Optional[tuple[int, int]] = None,
    page_range: Optional[list[Union[str, int]]] = None
) -> dict[str, list[ImageContent]]

将文件转换为 ImageContent 对象。

参数:

  • sources: 要转换的 PDF 文件路径或 ByteStream 对象列表。
  • meta: 可选的要附加到 ImageContent 对象的元数据。此值可以是字典列表或单个字典。如果为单个字典，则其内容将添加到所有生成的 ImageContent 对象的元数据中。如果为列表，其长度必须与源的数量匹配，因为它们会被一起打包。对于 ByteStream 对象，它们的meta 会被添加到输出的 ImageContent 对象中。
  • detail: 可选的图像详细信息级别（仅 OpenAI 支持）。可以是 "auto"、"high" 或 "low"。这将传递给创建的 ImageContent 对象。如果未提供，详细信息级别将是构造函数中设置的级别。
  • size: 如果提供，则将图像调整到指定尺寸（宽度、高度）以内的尺寸，同时保持纵横比。这可以减小文件大小、内存使用和处理时间，这在处理具有分辨率限制的模型或将图像传输到远程服务时非常有用。如果未提供，则 size 值将是构造函数中设置的值。
  • page_range: 要转换为图像的页码和/或页码范围列表。页码从 1 开始。如果为 None，将转换 PDF 中的所有页面。超出有效范围（1 到页数）的页面将被跳过并发出警告。例如，page_range=[1, 3] 将仅转换文档的第一页和第三页。它还接受可打印的范围字符串，例如：['1-3', '5', '8', '10-12'] 将转换第 1、2、3、5、8、10、11、12 页。如果未提供，page_range 的值将是构造函数中设置的值。

返回值:

包含以下键的字典

  • image_contents: ImageContent 对象列表。