데이터 클래스

데이터 클래스 (Data Classes)

Haystack에는 여러 곳에서 자주 쓰이는 핵심 클래스 몇 가지가 있어요. 이 클래스들은 시스템 안에서 데이터를 실어 나르는 역할을 하며, 파이프라인의 입력이나 출력으로 여러분이 직접 마주치기 쉬운 것들이죠.

Haystack은 데이터 클래스를 사용해 컴포넌트들이 간단하고 모듈적으로 서로 소통하게 만듭니다. 덕분에 데이터가 Haystack 파이프라인을 타고 매끄럽게 흐르죠. 이 페이지에서는 Haystack이 제공하는 데이터 클래스들 — ByteStream, Answer(그리고 그 변형인 ExtractedAnswer, GeneratedAnswer), ChatMessage, FileContent, ImageContent, Document, StreamingChunk — 을 하나씩 살펴보며 각각이 Haystack 생태계에 어떻게 기여하는지 설명할게요.

상세 파라미터는 Data Classes API 레퍼런스에서 확인할 수 있어요.

출처: 공식문서

Answer

Answer 클래스는 Haystack 안에서 생성되는 응답의 기본(base) 역할을 해요. 답변의 데이터, 출처가 된 쿼리, 그리고 추가 메타데이터를 담고 있죠.

• 어떤 데이터 타입이든 유연하게 처리합니다 (data).
• 문맥 관련성을 추적할 수 있게 쿼리를 담습니다 (query).
• 답변을 상세히 설명할 수 있는 풍부한 메타데이터를 지원합니다.

@dataclass
class Answer:
    data: Any
    query: str
    meta: Dict[str, Any]

ExtractedAnswer

ExtractedAnswer는 Answer의 서브클래스로, Document에서 추출한 답변을 다룹니다. 더 세부적인 속성을 제공해요.

• 출처가 된 Document에 대한 참조를 포함합니다.
• 답변의 신뢰도를 정량화하는 score 속성이 있어요.
• 소스 안에서 답변이 위치한 지점을 정확히 짚어주는 시작·끝 인덱스(선택)를 제공합니다.

@dataclass
class ExtractedAnswer:
    query: str
    score: float
    data: Optional[str] = None
    document: Optional[Document] = None
    context: Optional[str] = None
    document_offset: Optional["Span"] = None
    context_offset: Optional["Span"] = None
    meta: Dict[str, Any] = field(default_factory=dict)

GeneratedAnswer

GeneratedAnswer는 Answer 클래스를 확장해서 여러 Document로부터 생성된 답변을 담아요.

• 문자열 타입의 데이터를 처리합니다.
• 답변의 추적성을 높여주는 Document 객체 리스트를 연결합니다.

@dataclass
class GeneratedAnswer:
    data: str
    query: str
    documents: List[Document]
    meta: Dict[str, Any] = field(default_factory=dict)

ByteStream

ByteStream은 Haystack 프레임워크에서 이진 객체(binary object)를 추상화한 클래스예요. 다양한 바이너리 데이터 형식을 다룰 때 핵심적인 역할을 합니다.

• 바이너리 데이터와 관련 메타데이터를 담습니다.
• 유연성을 위해 선택적으로 MIME 타입을 지정할 수 있어요.
• 파일 상호작용 메서드(to_file, from_file_path, from_string)로 데이터를 쉽게 다뤄요.

@dataclass(repr=False)
class ByteStream:
    data: bytes
    meta: Dict[str, Any] = field(default_factory=dict, hash=False)
    mime_type: Optional[str] = field(default=None)

from haystack.dataclasses.byte_stream import ByteStream

image = ByteStream.from_file_path("dog.jpg")

ChatMessage

ChatMessage는 LLM에 보내는 메시지를 나타내는 핵심 추상화예요. 역할(role), 메타데이터, 그리고 텍스트·툴 호출·툴 호출 결과 같은 여러 유형의 콘텐츠를 담고 있죠.

ChatMessage 데이터 클래스에 대한 자세한 문서는 전용 ChatMessage 페이지를 참고하세요.

FileContent

FileContent는 ChatMessage에 첨부할 수 있는 파일 페이로드를 나타내요. base64 데이터, MIME 타입, 파일명, 그리고 공급자별 메타데이터를 포함합니다.

FileContent 데이터 클래스에 대한 자세한 문서는 전용 FileContent 페이지를 참고하세요.

ImageContent

ImageContent는 멀티모달 채팅 메시지와 비전-언어 파이프라인에서 쓰이는 이미지 기반 콘텐츠를 나타내요.

ImageContent 데이터 클래스에 대한 자세한 문서는 전용 ImageContent 페이지를 참고하세요.

Document

Document는 Haystack의 중심 데이터 추상화이자, 텍스트·표·바이너리 데이터를 모두 담을 수 있는 클래스예요.

• 문서마다 고유한 ID를 가집니다.
• 텍스트, 바이너리(blob) 등 여러 콘텐츠 타입을 지원합니다.
• 고급 문서 관리를 위한 커스텀 메타데이터와 점수(scoring)를 지원합니다.
• AI 기반 애플리케이션을 위한 임베딩(선택)을 담을 수 있어요.

@dataclass
class Document(metaclass=_BackwardCompatible):
    id: str = field(default="")
    content: Optional[str] = field(default=None)
    blob: Optional[ByteStream] = field(default=None)
    meta: Dict[str, Any] = field(default_factory=dict)
    score: Optional[float] = field(default=None)
    embedding: Optional[List[float]] = field(default=None)
    sparse_embedding: Optional[SparseEmbedding] = field(default=None)

from haystack import Document

documents = Document(
    content="Here are the contents of your document",
    embedding=[0.1] * 768,
)

StreamingChunk

StreamingChunk는 부분적으로 스트리밍된 LLM 응답을 나타내요. LLM 응답의 실시간 처리를 가능하게 해주죠. 스트리밍된 콘텐츠의 한 조각과 관련 메타데이터를 담고, 스트리밍 상태에 대한 종합적인 정보를 제공합니다.

• 텍스트 청크를 위한 문자열 기반 콘텐츠 표현
• 툴 호출과 툴 호출 결과 지원
• 컴포넌트 추적과 메타데이터 관리
• 스트리밍 상태 표시(start, finish reason)
• 멀티파트 응답을 위한 콘텐츠 블록 인덱싱

@dataclass
class StreamingChunk:
    content: str
    meta: dict[str, Any] = field(default_factory=dict, hash=False)
    component_info: Optional[ComponentInfo] = field(default=None)
    index: Optional[int] = field(default=None)
    tool_calls: Optional[list[ToolCallDelta]] = field(default=None)
    tool_call_result: Optional[ToolCallResult] = field(default=None)
    start: bool = field(default=False)
    finish_reason: Optional[FinishReason] = field(default=None)
    reasoning: Optional[ReasoningContent] = field(default=None)

from haystack.dataclasses import StreamingChunk, ToolCallDelta, ReasoningContent

# Basic text chunk
chunk = StreamingChunk(
    content="Hello world",
    start=True,
    meta={"model": "gpt-5-mini"},
)

# Tool call chunk
tool_chunk = StreamingChunk(
    content="",
    tool_calls=[
        ToolCallDelta(
            index=0,
            tool_name="calculator",
            arguments='{"operation": "add", "a": 2, "b": 3}',
        ),
    ],
    index=0,
    start=False,
    finish_reason="tool_calls",
)

# Reasoning chunk
reasoning_chunk = StreamingChunk(
    content="",
    reasoning=ReasoningContent(
        reasoning_text="Thinking step by step about the answer.",
    ),
    index=0,
    start=True,
    meta={"model": "gpt-4.1-mini"},
)

ToolCallDelta

ToolCallDelta는 모델이 준비한 툴 호출을 나타내요. 보통 스트리밍 중에 어시스턴트 메시지에 담겨 있죠.

@dataclass
class ToolCallDelta:
    index: int
    tool_name: Optional[str] = field(default=None)
    arguments: Optional[str] = field(default=None)
    id: Optional[str] = field(default=None)
    extra: Optional[Dict[str, Any]] = field(default=None)

ComponentInfo

ComponentInfo 클래스는 Haystack 파이프라인 안의 컴포넌트에 대한 정보를 나타내요. 데이터를 생성하거나 처리하는 컴포넌트의 타입과 이름을 추적하는 데 쓰이며, 파이프라인 전반의 디버깅·추적·메타데이터 관리에 도움을 줍니다.

• 컴포넌트의 타입(모듈과 클래스 이름 포함)을 저장합니다.
• 파이프라인에서 컴포넌트에 부여된 이름을 선택적으로 저장합니다.
• Component 객체에서 ComponentInfo 인스턴스를 만드는 편리한 클래스 메서드를 제공합니다.

@dataclass
class ComponentInfo:
    type: str
    name: Optional[str] = field(default=None)

    @classmethod
    def from_component(cls, component: Component) -> "ComponentInfo": ...

from haystack.dataclasses.streaming_chunk import ComponentInfo
from haystack.core.component import Component


class MyComponent(Component): ...


component = MyComponent()
info = ComponentInfo.from_component(component)
print(info.type)  # e.g., 'my_module.MyComponent'
print(info.name)  # Name assigned in the pipeline, if any

SparseEmbedding

SparseEmbedding 클래스는 희소 임베딩(sparse embedding), 즉 대부분의 값이 0인 벡터를 나타내요.

• indices: 임베딩에서 0이 아닌 요소들의 인덱스 리스트.
• values: 임베딩에서 0이 아닌 요소들의 값 리스트.

Tool은 언어 모델이 호출을 준비할 수 있는 도구를 나타내는 데이터 클래스입니다. Tool 데이터 클래스에 대한 자세한 문서는 전용 Tool 페이지를 참고하세요.

더 알아보기 (Learn more)

• 데이터 클래스 (Data Classes) — 원문 문서.
• Data Classes API 레퍼런스 — 각 클래스의 상세 파라미터.