FirecrawlWebSearch

Firecrawl API를 사용해 웹을 검색하고 콘텐츠를 추출해요.

출처: 문서

본문

FirecrawlWebSearch에 쿼리를 주면 Firecrawl Search API로 웹을 검색하고, 결과 페이지를 크롤링하며, 구조화된 텍스트를 Haystack Document 객체 리스트로 반환해요. 기본 URL 리스트도 함께 반환해요.

Firecrawl이 찾은 페이지의 콘텐츠를 LLM 친화적인 형식으로 능동적으로 스크래핑·구조화하기 때문에, 일반적으로 웹 페이지를 읽기 위한 LinkContentFetcher 같은 추가 구성 요소가 필요 없어요. FirecrawlWebSearch가 검색과 스크래핑을 한 단계로 처리하죠.

FirecrawlWebSearch는 작동하려면 Firecrawl API 키가 필요해요. 기본적으로 FIRECRAWL_API_KEY 환경 변수를 찾으며, 대신 초기화 시점에 api_key를 직접 전달할 수도 있어요.

대표적인 파이프라인 위치: ChatPromptBuilder 앞, 또는 인덱싱 파이프라인의 맨 시작
필수 init 변수: api_key — Firecrawl API 키. FIRECRAWL_API_KEY env var로 설정 가능.
필수 run 변수: query — 검색 쿼리 문자열.
출력 변수: documents — 스크래핑된 콘텐츠와 메타데이터를 담은 Haystack Document 리스트. links — 결과 URL 문자열 리스트.
API reference: Firecrawl Search API
패키지명: firecrawl-haystack

Usage

On its own

쿼리 기준으로 웹을 검색하고, 결과 웹 페이지를 스크래핑하며, 페이지 콘텐츠를 담은 Document 리스트를 반환하는 간단한 예시예요.

from haystack_integrations.components.websearch.firecrawl import FirecrawlWebSearch
from haystack.utils import Secret

web_search = FirecrawlWebSearch(
    api_key=Secret.from_env_var("FIRECRAWL_API_KEY"),
    top_k=5,
    search_params={"scrape_options": {"formats": ["markdown"]}},
)

query = "What is Haystack by deepset?"
response = web_search.run(query=query)
for doc in response["documents"]:
    print(doc.content)

In a pipeline

FirecrawlWebSearch로 답을 찾는 RAG(Retrieval-Augmented Generation) 파이프라인 예시예요. Firecrawl이 스크래핑된 페이지의 실제 텍스트를 반환하므로, 그 documents 출력을 ChatPromptBuilder에 바로 전달해 LLM에 필요한 컨텍스트를 줄 수 있어요.

from haystack import Pipeline
from haystack.utils import Secret
from haystack.components.builders.chat_prompt_builder import ChatPromptBuilder
from haystack.components.generators.chat import OpenAIChatGenerator
from haystack_integrations.components.websearch.firecrawl import FirecrawlWebSearch
from haystack.dataclasses import ChatMessage

web_search = FirecrawlWebSearch(
    api_key=Secret.from_env_var("FIRECRAWL_API_KEY"),
    top_k=2,
    search_params={"scrape_options": {"formats": ["markdown"]}},
)

prompt_template = [
    ChatMessage.from_system("You are a helpful assistant."),
    ChatMessage.from_user(
        "Given the information below:\n"
        "{% for document in documents %}{{ document.content }}\n{% endfor %}\n"
        "Answer the following question: {{ query }}.\nAnswer:"
    ),
]
prompt_builder = ChatPromptBuilder(
    template=prompt_template,
    required_variables={"query", "documents"},
)
llm = OpenAIChatGenerator(
    api_key=Secret.from_env_var("OPENAI_API_KEY"),
    model="gpt-5-nano",
)
pipe = Pipeline()
pipe.add_component("search", web_search)
pipe.add_component("prompt_builder", prompt_builder)
pipe.add_component("llm", llm)
pipe.connect("search.documents", "prompt_builder.documents")
pipe.connect("prompt_builder.prompt", "llm.messages")
query = "What is Haystack by deepset?"
result = pipe.run(data={"search": {"query": query}, "prompt_builder": {"query": query}})
print(result["llm"]["replies"][0].text)

더 알아보기 (Learn more)

Firecrawl Search API reference를 확인하세요.

FirecrawlWebSearch