FileContent

FileContent

FileContent는 ChatMessage에 첨부할 수 있는 파일 페이로드를 나타내는 Haystack 데이터 클래스예요. PDF나 다른 문서 같은 파일 입력을 사용자의 텍스트 프롬프트와 함께 받아들이는 채팅 모델을 다룰 때 사용해요.

출처: 문서

본문

FileContent는 ChatMessage에 첨부할 수 있는 파일 페이로드를 표현해요. 챗 모델이 사용자 텍스트 프롬프트와 함께 PDF 같은 파일 입력을 받아들일 때 쓰죠. 파라미터와 메서드 전체 목록이 필요하면 FileContent API reference를 확인하세요.

Attributes ​

@dataclass
class FileContent:
    base64_data: str
    mime_type: str | None = None
    filename: str | None = None
    extra: dict[str, Any] = field(default_factory=dict)
    validation: bool = True
  • base64_data는 파일 콘텐츠를 base64로 인코딩한 문자열로 저장해요.
  • mime_type은 파일 유형을 식별해요(예: application/pdf). 많은 모델 제공자가 요구하기 때문에 명시적으로 주는 것을 권장해요.
  • filename은 선택 사항이지만 일부 제공자는 업로드된 파일을 처리할 때 이것을 사용해요.
  • extra는 제공자별 메타데이터를 저장할 수 있어요. 값은 JSON 직렬화 가능해야 해요.
  • validation은 base64_data가 유효한지 검사하고, MIME 타입이 주어지지 않았을 때 추론을 시도해요.

Create from a file path ​

from_file_path를 사용하면 로컬 파일을 읽고, base64로 인코딩하고, 경로에서 MIME 타입을 추론하며, filename을 채워줘요.

from haystack.dataclasses import ChatMessage, FileContent

file_content = FileContent.from_file_path("data/attention-is-all-you-need.pdf")
message = ChatMessage.from_user(
    content_parts=[
        file_content,
        "Summarize the key ideas in this paper.",
    ]
)

제공자가 특정 파일명이나 제공자별 옵션을 기대할 때는 filename이나 extra를 전달해요:

file_content = FileContent.from_file_path(
    "data/report.pdf",
    filename="quarterly-report.pdf",
    extra={"source": "finance"},
)

Create from a URL ​

from_url을 사용하면 파일을 다운로드해 FileContent 인스턴스로 변환해요.

from haystack.dataclasses import FileContent

file_content = FileContent.from_url(
    "https://example.com/reports/quarterly-report.pdf",
    timeout=30,
)

filename을 제공하지 않으면 Haystack은 URL의 마지막 경로 세그먼트를 사용해요.

Create from base64 data ​

이미 파일 바이트가 있다면 인코딩하고 MIME 타입을 명시적으로 전달해요.

import base64
from pathlib import Path

from haystack.dataclasses import FileContent

data = Path("data/manual.pdf").read_bytes()
file_content = FileContent(
    base64_data=base64.b64encode(data).decode("utf-8"),
    mime_type="application/pdf",
    filename="manual.pdf",
)

base64 데이터와 MIME 타입을 이미 신뢰하고 검증을 건너뛰고 싶을 때만 validation=False로 설정하세요.

Inspect files in a ChatMessage ​

FileContent를 ChatMessage에 추가한 뒤 file과 files 속성으로 파일 페이로드에 접근할 수 있어요.

from haystack.dataclasses import ChatMessage, FileContent

file_content = FileContent.from_file_path("data/invoice.pdf")
message = ChatMessage.from_user(
    content_parts=[file_content, "Extract the invoice total."]
)
print(message.file)
print(message.files)

message.file은 첫 번째 파일 페이로드를 반환하고, 파일이 없으면 None을 반환해요. message.files는 모든 파일 페이로드를 반환해요.

Serialization ​

to_dict와 from_dict로 파일 콘텐츠를 직렬화하고 복원해요.

payload = file_content.to_dict()
restored = FileContent.from_dict(payload)

트레이싱을 위해 Haystack은 큰 파일이 트레이싱 백엔드로 전송되지 않도록 전체 base64 페이로드를 플레이스홀더로 대체해요.

더 알아보기 (Learn more)

  • FileContent API reference 문서를 함께 보세요.