프레임워크

Haystack 첫걸음: 30줄 RAG로 파헤치는 LLM 오케스트레이션 프레임워크

LangChain보다 3년 먼저 Pipeline-as-Graph를 제시한 26k 스타의 베테랑 프레임워크. 30줄 코드 Demo부터 컴포넌트, 아키텍처, 프로덕션 적용까지 한 번에 정리한다.

글자 크기

GitHub에서 26,259 스타를 기록하고 있으며, Apache 2.0 라이선스, 메인 저장소 첫 커밋은 2019년——LangChain보다 3년 먼저 Pipeline-as-Graph 개념을 내놓은 프레임워크다. Haystack라는 이름은 한국에서 접해본 사람이 많지는 않지만, 프로덕션 환경에서의 접해본 빈도는 결코 낮지 않다. 오늘은 30줄짜리 RAG 데모를切入点으로 삼아, 그 설계와 아키텍처, 그리고 실제 써보면 부딪히는 문제들을 살펴본다.

이 프레임워크가 해결하는 문제

2023년 이전에 RAG를 만들려면 전부 직접 조립해야 했다. Loader로 문서를 자르고, Embedding으로 벡터를 계산하고, Vector DB에 데이터를 저장하고, Retriever로 TopK를 가져오고, Prompt 템플릿으로 문자열을拼하고, LLM API를 호출——각 단계를 개별적으로 선택하고 그 사이에 끼우는 글루 코드(glue code)를 작성하느라 회의가 들었다.

Haystack는 2019년부터 이 문제를 다뤄왔다(초기에는 BERT QA 프레임워크였음). 현재는 v2.x까지迭代됐다. 그 포지셔닝은 "체인 호출 라이브러리"가 아니라 "오케스트레이션 프레임워크"다. 한마디로 요약하면: 검색-증강-생성 파이프라인을 표준화하고, 시각화하고, 프로덕션 수준으로 끌어올리는 일을 한다.

사용법

30줄이면 최소한의 RAG가 완성된다. haystack-ai를 설치하고, OpenAI 키를 설정한 뒤, 문서 몇 개를 준비해서 InMemoryDocumentStore + OpenAITextEmbedder + OpenAIGenerator를 Pipeline으로串은 다음 pipeline.run()을 호출해 답을 받는다. 모든 노드는 Pipeline.add_component(name, instance)로 등록하고 connect()로 연결한다.

from haystack import Pipeline
from haystack.components.embedders import OpenAITextEmbedder
from haystack.components.generators import OpenAIGenerator
from haystack.components.retrievers import InMemoryEmbeddingRetriever
from haystack.document_stores.in_memory import InMemoryDocumentStore
from haystack.dataclasses import Document

# 1. 문서 준비 (실제 프로젝트에서는 converter로 PDF/MD 로드)
docs = [Document(content="Haystack은 deepset이 오픈소스로 공개한 LLM 오케스트레이션 프레임워크다"),
        Document(content="Component + Pipeline 추상화로 RAG를 구성한다"),
        Document(content="Elasticsearch, Weaviate, Pinecone 등 다양한 벡터 DB를 지원한다")]
doc_store = InMemoryDocumentStore()
doc_store.write_documents(docs)

# 2. Pipeline 구성
pipe = Pipeline()
pipe.add_component("embedder", OpenAITextEmbedder(model="text-embedding-3-small"))
pipe.add_component("retriever", InMemoryEmbeddingRetriever(document_store=doc_store))
pipe.add_component("generator", OpenAIGenerator(model="gpt-4o-mini"))

# 3. 연결 (프롬프트 템플릿 단계는 단순화)
pipe.connect("embedder.embedding", "retriever.query_embedding")
pipe.connect("retriever.documents", "generator.prompt")  # 실제로는 프롬프트를拼해야 함

# 4. 실행
result = pipe.run({"embedder": {"text": "Haystack이란 무엇인가"}})
print(result["generator"]["replies"][0])

# Bonus: 시각화 그래프 내보내기
pipe.draw("./rag_pipeline.mermaid")

Python 3.9+ 환경이면 바로 실행된다. 전체 버전은 GitHub examples에서 확인할 수 있다.

동작 원리 (아키텍처)

세 가지 핵심 추상화가 전부다.

  1. Component: 모든 노드의 베이스 클래스. @component 데코레이터로 입출력을 선언하고, dataclass 스타일의 dataclasses로 정의하며, run() 메서드를 내장한다.
  2. Pipeline: DAG 컨테이너. 순차 흐름과 조건 분기(add_branch)를 지원하고, v2에서는 루프(Agent loop)도 추가됐다. draw()를 호출하면 바로 Mermaid 다이어그램이 출력되므로 Obsidian이나 Notion에 그대로 붙여 넣을 수 있다.
  3. DocumentStore: Elasticsearch, OpenSearch, Weaviate, Pinecone, Qdrant, Milvus, pgvector, Chroma를 모두 통일된 인터페이스로 추상화한다. 공식 지원 백엔드가 10종 이상이라, 백엔드 교체는 설정 한 줄만 바꾸면 된다.

LangChain LCEL과 가장 크게 다른 설계 차이는 다음과 같다. Haystack은 명시적 그래프 구성 방식——그래프를 먼저 다 만든 뒤 실행한다. 반면 LangChain은 암묵적 체인 방식——런타임에 조립한다. 전자는 더 엔지니어링 친화적이어서(에러 발생 시 어느 노드에서 문제가 생겼는지 한눈에 보인다), 후자는 노트북에서 빠르게 실험하기에 더 유연하다.

강점과 약점

강점:

  • OpenTelemetry tracing 내장. pipeline.run()을 한 번 호출하면 모든 span이 Jaeger / Datadog / Arize Phoenix로 들어간다. 별도 계측 코드를 작성할 필요가 없다.
  • hayhooks로 한 줄 명령이면 Pipeline을 REST/gRPC 서비스로 배포할 수 있다.
  • DocumentStore 추상화가 폭넓다. 국내에서 흔히 쓰는 Milvus, Alibaba Cloud Elasticsearch도 공식集成을 제공한다.
  • 2.0 이후 dataclass로 전환하면서 YAML 설정을 대체했고, IDE 자동 완성이 다시 살아났다.

약점:

  • 한국어와 중국어 튜토리얼, 커뮤니티 글이 LangChain / LlamaIndex보다 훨씬 적다. 문제에 부딪히면 대부분 GitHub Issues를 뒤져야 한다.
  • 컴포넌트 생태계가 LangChain만큼 풍부하지 않다. 새로 등장한 도구(예: 일부 MCP Server)는 통합이 한 박자 느린 편이다.
  • 기본 API 스타일이 다소 구식이다. 처음 접하는 개발자는 component.run(input_data) 같은 파라미터 전달 방식에서 먼저 벽에 부딪힌다.
  • Agent 기능은 v2에서야 완비됐고, AutoGen / CrewAI보다는 늦게 출발했다. 복잡한 multi-agent 시나리오는 여전히 약하다.

직접 써봤다

어제 메인 브랜치를 clone해서(2026년 1월 기준 커밋) examples/rag/basic_rag_pipeline.py를 실행해 봤다. 로컬 InMemoryDocumentStore + OpenAI Embedding으로 기술 문서 100건을 처리했을 때, 엔드 투 엔드 query는 약 1.2초가 걸렸다——OpenAI Embedding 0.4초, GPT-4o-mini 0.7초, 검색 0.1초.

pipeline.draw()를 한 번 돌려 �는데, 생성된 Mermaid 그래프가 Obsidian에서 바로 렌더링됐다. 로그를 뒤지는 것보다 훨씬 직관적이다.

한 가지 주의점은 순수 로컬 모드로는 동작하지 않는다는 점이다. Embedding과 LLM 모두 OpenAI API를 거치므로, 국내에서는 프록시를 직접 준비하거나国产 모델로 교체해야 한다. Haystack에 HuggingFace 로컬 컴포넌트와 SiliconFlow 같은 어댑터가 있긴 하지만, 기본 문서가 전부 OpenAI 기준이라 설정하려면 몇 개 이슈를 뒤져야 한다.

이런 사용자에게 맞다

적합한 경우:

  • 팀에 LLM 애플리케이션 배포를 전담하는 사람이 있고, tracing / 배포 / 모니터링을 한 번에 처리해야 할 때
  • 백엔드가 Java/Go 팀이라 LLM을 써야 하는데, Python 노트북이 아니라 안정적인 REST API가 필요할 때
  • 프로젝트에서 Vector DB나 Embedding 모델을 자주 바꿔야 할 때
  • 이미 Elasticsearch로 검색을 돌리고 있고, 그 위에 LLM 레이어만 얹고 싶을 때

맞지 않는 경우:

  • 개인 개발자가 일회성 데모를 만들 때. LangChain의 노트북 경험이 훨씬 가볍다
  • 복잡한 multi-agent / tool-use 시나리오. AutoGen / CrewAI가 더 손에 익다
  • 그냥 단순한 chat wrapper만 필요할 때. 프레임워크 없이 얇게 래핑하는 것으로 충분하다

Haystack은 독일 베를린의 deepset이维护하고 있으며, 주 개발 언어는 Python이고 라이선스는 Apache 2.0이다. 더 깊이 들여다보고 싶다면 저장소 README를 직접 보면 된다.

참고:

출처: https://github.com/deepset-ai/haystack