TavilyFetcher

TavilyFetcher

TavilyFetcher 는 Tavily Extract를 사용해 URL에서 콘텐츠를 가져와 파싱한 뒤 Haystack Document 로 만드는 컴포넌트예요. 웹 검색과 달리, 질의로 URL을 발견하는 게 아니라 여러분이 제공한 URL에서 콘텐츠를 검색해요.

출처: 문서

본문

개요 (Overview)

TavilyFetcher 는 Tavily Extract API를 감싸서, 지정한 하나 이상의 URL에서 웹 페이지 콘텐츠를 가져와 파싱해요. PDF URL도 지원해요. 성공한 각 URL은 페이지 콘텐츠를 content로, url(그리고 선택적으로 images) 같은 메타데이터를 meta로 갖는 Haystack Document 가 돼요.

이 컴포넌트는 TavilyWebSearch와 상호 보완적이에요. 검색은 질의에서 URL을 발견하고, TavilyFetcher 는 이미 확보한 URL에서 전체 콘텐츠를 추출해요.

추출 파라미터 (Extract parameters)

초기화 시 추출 동작을 제어할 수 있어요:

  • extract_depth: "basic"(빠르고 비용 저렴) 또는 "advanced"(테이블 포함 더 많은 데이터, 지연·비용 높음). 기본값은 "basic".
  • include_images: True 로 설정하면 이미지 URL이 각 Document의 meta["images"] 아래에 저장돼요. 기본값은 False.
  • extract_params: Tavily Extract API에 전달되는 추가 kwargs(예: format, include_favicon, query, chunks_per_source). Tavily Extract API 참조를 참고하세요.

이 중 extract_params 만 run() 에도 전달해 단일 호출에 대해 오버라이드할 수 있어요. 단, run() 에 전달한 extract_params 딕셔너리는 초기화 시 설정한 것과 병합되지 않고 완전히 대체해요.

인증 (Authorization)

TavilyFetcher 는 기본적으로 TAVILY_API_KEY 환경 변수를 사용해요. 키를 명시적으로 전달할 수도 있어요:

from haystack.utils import Secret
from haystack_integrations.components.fetchers.tavily import TavilyFetcher

fetcher = TavilyFetcher(api_key=Secret.from_token(""))

API 키를 얻으려면 tavily.com에서 가입하세요.

설치 (Installation)

Tavily 통합을 설치하세요:

pip install tavily-haystack

사용법 (Usage)

단독으로 쓰기

from haystack_integrations.components.fetchers.tavily import TavilyFetcher

fetcher = TavilyFetcher(extract_depth="basic")
result = fetcher.run(urls=["https://docs.haystack.deepset.ai/docs/intro"])
documents = result["documents"]
meta = result["meta"]
for doc in documents:
    print(f"{doc.meta.get('url')}: {len(doc.content or '')} chars")
print("failed:", meta.get("failed_results"))

파이프라인에서 쓰기

다음은 TavilyFetcher 로 문서 페이지를 추출해 InMemoryDocumentStore 에 저장하는 인덱싱 파이프라인 예시예요.

from haystack import Pipeline
from haystack.document_stores.in_memory import InMemoryDocumentStore
from haystack.components.preprocessors import DocumentSplitter
from haystack.components.writers import DocumentWriter
from haystack_integrations.components.fetchers.tavily import TavilyFetcher

document_store = InMemoryDocumentStore()
fetcher = TavilyFetcher(extract_depth="basic")
splitter = DocumentSplitter(split_by="sentence", split_length=5)
writer = DocumentWriter(document_store=document_store)

indexing_pipeline = Pipeline()
indexing_pipeline.add_component("fetcher", fetcher)
indexing_pipeline.add_component("splitter", splitter)
indexing_pipeline.add_component("writer", writer)
indexing_pipeline.connect("fetcher.documents", "splitter.documents")
indexing_pipeline.connect("splitter.documents", "writer.documents")
indexing_pipeline.run(
    data={
        "fetcher": {
            "urls": ["https://docs.haystack.deepset.ai/docs/intro"],
        },
    },
)

비동기 실행 (Asynchronous execution)

TavilyFetcher 는 run_async() 를 통한 비동기 실행도 지원해요:

import asyncio
from haystack_integrations.components.fetchers.tavily import TavilyFetcher

fetcher = TavilyFetcher()

async def fetch():
    result = await fetcher.run_async(
        urls=["https://docs.haystack.deepset.ai/docs/intro"],
    )
    return result["documents"]

documents = asyncio.run(fetch())

내부 클라이언트는 첫 호출 시 지연 생성돼요. 첫 호출의 콜드 스타트 지연을 피하려면 warm_up() 을 명시적으로 호출하면 돼요.

더 알아보기 (Learn more)