tavily-ai/tavily-python

The Tavily Python SDK allows for easy interaction with the Tavily API, offering the full range of our search, extract, crawl, map, and research functionalities directly from your Python programs. Easily integrate smart search, content extraction, and research capabilities into your applications, harnessing Tavily's powerful features.

Tavily‑Python이란?

Tavily‑Python은 Tavily API의 공식 Python SDK입니다. 이 API는 단순 검색, 질문 응답, 콘텐츠 추출, 사이트 크롤링, 사이트 매핑, 자동 연구 보고서 생성과 같은 웹 검색 관련 서비스를 제공하며, Python 코드에서 호출할 수 있습니다.

주요 기능

기능	기능 설명	일반적인 사용 사례
search	쿼리에 해당하는 웹 검색 결과 목록을 반환합니다.	LLM에 피드백하거나 사용자에게 표시합니다.
qna_search	질문에 간결한 답변을 제공합니다 (RAG에 적합).	프롬프트 엔지니어링 또는 챗봇 백엔드에 사용합니다.
get_search_context	상위 결과들로부터 구성된 단일 컨텍스트 문자열을 반환합니다.	직접 Retrieval‑Augmented Generation 파이프라인에 삽입합니다.
extract	최대 20개의 URL에서 원시 텍스트(옵션으로 이미지 포함)를 추출합니다.	임베딩이나 요약 전 문서 전처리에 사용합니다.
crawl (초대 제한)	시작 URL에서 사이트를 깊이/제한 및 사용자 지정 지시사항에 따라 탐색합니다.	도메인에서 집중적인 데이터셋을 구축합니다.
map (초대 제한)	사이트의 계층적 구조를 반환합니다.	사이트 아키텍처를 시각화하거나 크롤링할 대상을 결정합니다.
research	인용 정보를 포함한 다중 소스 연구 보고서를 생성하며, 스트리밍 및 사용 추적을 지원합니다.	에이전트나 분석가를 위한 자동 보고서 생성에 사용합니다.
feedback	각 결과에 대한 점수와 의견을 Tavily로 전송합니다.	자신의 에이전트의 순위를 개선하거나 사용자 피드백을 수집합니다.

시작하기

pip install tavily-python

from tavily import TavilyClient

# API 키 사용 (모든 기능을 사용하려면 권장)
client = TavilyClient(api_key="tvly‑YOUR_KEY")

# 간단한 웹 검색
results = client.search("리오나르도 메시는 누구인가요?")
print(results)

또한 키 없이 사용 (API 키 없이) 모드도 가능하며, 이 경우 search와 extract만 사용 가능하고, 레이트 제한이 적용됩니다:

client = TavilyClient()  # 키 없음
try:
    print(client.search("양자 컴퓨팅이란 무엇인가요?"))
except TavilyKeylessLimitError as e:
    print(e.retry_after_seconds, "초 후 다음 할당량이 가능")

고급 사용법

사용자 정의 HTTP 세션 – 미리 구성된 requests.Session 또는 httpx.AsyncClient를 삽입할 수 있습니다 (기업 게이트웨이 뒤에서 유용).
메타데이터 헤더 – 선택적 project_id, session_id, human_id, client_name는 HTTP 헤더로 전송되어 추적에 사용됩니다.
스트리밍 연구 – stream=True로 설정하면 생성되는 청크를 실시간으로 수신할 수 있습니다.
사용량/크레딧 – get_research(..., include_usage=True)를 호출하면 작업에 소비된 크레딧 수를 확인할 수 있습니다 (무료 계정: 월 1,000 크레딧).

누가 사용할 수 있나요?

LLM 개발자 – 신속하고 신뢰할 수 있는 웹 검색 소스가 필요한 Retrieval‑Augmented Generation 파이프라인을 구축하는 사람.
데이터 엔지니어 – 자체 크롤러를 작성하지 않고도 콘텐츠를 스크래핑하고 추출하고 싶은 사람.
제품 팀 – SaaS 앱에 "웹에 질문하기" 기능을 추가하고 싶은 사람.
연구 보조원 – 인용 정보를 포함한 보고서를 자동화하는 사람.

라이선스 및 지원

MIT 라이선스 – 자유롭게 사용, 수정, 재배포 가능.
도움이 필요하면 support@tavily.com으로 이메일을 보내거나 Tavily Developer Community에 가입하세요.

모든 정보는 리포지토리의 README에서 직접 가져왔습니다.