helallao/perplexity-ai

Perplexity‑AI (공식이 아닌 Python 래퍼)

무엇인가요 – 공식 API 키 없이 공개된 Perplexity.ai 웹 UI와 통신하는 Python 라이브러리입니다. 웹사이트에서 제공하는 검색/추론 쿼리를 동기 또는 비동기로 실행할 수 있으며, Chrome 브라우저를 자동화하는 드라이버도 포함되어 있어 Emailnator를 통해 일시적인 Gmail 계정을 생성하여 무료 레벨의 "5개의 프로 쿼리" 제한을 다시 획득할 수 있습니다.

주요 기능

검색 및 추론 – client.search()를 호출하고 쿼리를 입력하며 mode (auto, pro, reasoning, deep research)를 선택합니다. 응답에는 answer 필드(일반 텍스트)가 포함됩니다.
스트리밍 – stream=True로 설정하면 부분적인 응답 청크를 생성되는 대로 수신할 수 있습니다.
파일 업로드 – {filename: data} 형식의 사전을 첨부하여 Perplexity가 문서를 분석할 수 있습니다.
동기 및 비동기 API – perplexity.Client (블로킹) 및 perplexity_async.Client (awaitable).
MCP 서버 – perplexity-mcp라는 Model Context Protocol 서버로, Claude Code 또는 어떤 MCP 호환 클라이언트에서도 도구로 사용할 수 있으며, 원격 공유를 위한 선택적 HTTP 전송도 지원합니다.
계정 생성 – client.create_account(emailnator_cookies)를 사용해 Emailnator의 일시 메일 서비스를 통해 새 Gmail 계정을 등록하여 무료 프로 쿼리 한 세트를 다시 얻을 수 있습니다.
레트 제한 처리, 재시도, 타입 지정 인터페이스, 구조화된 로깅, 사용자 정의 예외 계층으로 강력한 통합이 가능합니다.

설치 (Python 3.10+ 및 uv 패키지 매니저 필요, pip도 대체 가능):

# 핵심 라이브러리
uv sync               # 또는: pip install -e .

# 선택적 MCP 서버
uv sync --extra mcp   # 또는: pip install .[mcp]

# 선택적 웹 드라이버 (계정 생성용)
uv sync --extra driver
uv run patchright install chromium   # 드라이버용 헤드리스 Chromium 설치

빠른 사용 예제 (동기)

import perplexity

client = perplexity.Client()                     # 익명, 무료 레벨 전용
resp = client.search("What is artificial intelligence?")
print(resp["answer"])                           # → 일반 텍스트 응답

자신의 Perplexity 계정 사용 (브라우저에서 얻은 쿠키 제공):

cookies = {
    "next-auth.session-token": "…",
    "next-auth.csrf-token": "…",
}
client = perplexity.Client(cookies)
resp = client.search(
    "Explain quantum computing",
    mode="reasoning",
    model="gpt-5.2-thinking",
    sources=["web", "scholar"],
    stream=True,
)
for chunk in resp:
    if "answer" in chunk:
        print(chunk["answer"], end="", flush=True)

비동기 버전 – perplexity를 perplexity_async로 바꾸고 호출에 await를 사용합니다.

MCP 서버 – perplexity-mcp를 실행(기본 stdio 전송)하거나 MCP_TRANSPORT=http perplexity-mcp로 HTTP 엔드포인트를 사용합니다. Claude Code는 claude mcp add perplexity -- perplexity-mcp로 도구로 추가할 수 있습니다. 서버는 쿼리를 래퍼로 전달하며, 익명 모드 또는 PERPLEXITY_COOKIES 환경 변수로 제공된 쿠키를 사용합니다.

제한 사항 (문서에 기재됨)

다중 메시지 messages 배열 없음 – 각 호출당 단일 쿼리 문자열만 가능.
고급 검색 필터(최근성, 도메인, 컨텍스트 크기, 추론 노력 등) 없음.
일반 텍스트 응답만 반환; 구조화된 인용, 이미지, 풍부한 결과 객체 없음.
계정 생성을 위해 신선한 Emailnator 쿠키가 필요함 (즉시 만료됨).

더 많은 정보 찾기 – examples/에 예제, README에 전체 API 참조, docs/에 변경 기록 및 로드맵, tests/에 테스트 세트.

법적 주의사항 – 이는 비공식 래퍼입니다. 책임감 있게 사용하고 Perplexity.ai의 이용 약관을 존중해 주세요.

helallao/perplexity-ai

Perplexity‑AI (공식이 아닌 Python 래퍼)

관련