Perplexity API 연동해서 실시간 AI 검색 앱 만들기

들어가며: Perplexity API로 실시간 AI 검색 앱 만드는 이유

ChatGPT, Claude, Gemini 같은 생성형 AI 모델들은 학습 데이터 기한으로 인해 최신 정보를 놓치는 문제가 있습니다. 반면 Perplexity는 실시간 웹 검색을 통합한 AI로, 최신 뉴스, 주가, 날씨, 이벤트 정보 등을 즉시 제공합니다.

Perplexity API를 활용하면 단순한 검색 엔진을 넘어 AI가 자동으로 정보를 종합하고 요약해주는 앱을 만들 수 있습니다. 예를 들어:

• 기업 투자자를 위한 실시간 시장 분석 대시보드
• 저널리스트의 뉴스 리서치 자동화 도구
• 학생 및 연구원을 위한 학술 정보 수집 봇
• 트렌드 모니터링 및 경쟁사 분석 플랫폼

이 튜토리얼에서는 Perplexity API 가입부터 실제 검색 앱 구현까지 단계별로알아보겠습니다.

1단계: Perplexity API 키 발급받기

1-1. Perplexity 계정 생성 및 로그인

Perplexity API를 사용하려면 먼저 Perplexity 개발자 콘솔에 접근해야 합니다. 공식 웹사이트 https://www.perplexity.ai에 접속한 후 회원가입하거나 로그인합니다. Google, GitHub 계정으로도 가입 가능합니다.

1-2. API 키 생성

로그인 후 프로필 아이콘을 클릭하고 "Settings" 또는 "API Keys" 항목을 찾아 새로운 API 키를 생성합니다. 생성된 키는 한 번만 표시되므로 즉시 복사하여 안전한 곳에 저장하세요. 노출되지 않도록 주의해야 합니다.

API 키 형식:

pplx-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

1-3. 요금제 확인

Perplexity는 무료 티어(월 100회 제한) 및 유료 플랜(Pro, Business)을 제공합니다. API 이용 시 요청 수에 따라 금액이 청구되므로, 빌링 설정에서 월별 한도를 설정할 것을 권장합니다. 초기 테스트 단계에서는 무료 티어로 충분합니다.

2단계: Python 환경 설정 및 라이브러리 설치

2-1. Python 및 pip 설치 확인

Perplexity API를 활용한 앱 개발은 Python이 가장 간편합니다. Python 3.8 이상이 설치되어 있는지 확인하세요:

python --version
# 또는
python3 --version

2-2. 필요한 라이브러리 설치

다음 명령어로 필요한 패키지들을 설치합니다:

pip install requests python-dotenv flask

• requests: HTTP API 호출
• python-dotenv: 환경 변수 관리 (API 키 보안)
• flask: 웹 서버 구축 (선택사항, 추후 예제에서 사용)

또는 공식 Python SDK를 설치할 수도 있습니다:

pip install perplexity-sdk

2-3. 환경 변수 설정

API 키를 직접 코드에 작성하지 않도록 .env 파일을 생성합니다:

# .env
PERPLEXITY_API_KEY=pplx-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

프로젝트 루트 디렉토리에 파일을 저장하고, Python 코드에서 로드합니다:

from dotenv import load_dotenv
import os

load_dotenv()
api_key = os.getenv('PERPLEXITY_API_KEY')

3단계: Perplexity API 기본 요청 구현하기

3-1. 첫 번째 API 호출

Perplexity API는 REST 기반이며, 엔드포인트는 https://api.perplexity.ai/chat/completions입니다. 기본 구조는 OpenAI의 Chat Completions API와 유사합니다.

import requests
from dotenv import load_dotenv
import os

load_dotenv()
api_key = os.getenv('PERPLEXITY_API_KEY')

def search_with_perplexity(query: str) -> str:
    """
    Perplexity API를 이용해 실시간 검색 수행
    """
    url = "https://api.perplexity.ai/chat/completions"

    headers = {
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    }

    payload = {
        "model": "sonar",
        "messages": [
            {
                "role": "user",
                "content": query
            }
        ],
        "temperature": 0.7,
        "top_p": 0.9,
        "max_tokens": 1024
    }

    response = requests.post(url, json=payload, headers=headers)

    if response.status_code == 200:
        result = response.json()
        return result['choices'][0]['message']['content']
    else:
        return f"Error: {response.status_code} - {response.text}"

# 사용 예
query = "2026년 4월 한국 경제 뉴스"
result = search_with_perplexity(query)
print(result)

3-2. API 응답 구조 이해하기

Perplexity API의 응답은 다음과 같은 구조입니다:

{
    "id": "xxxxx",
    "object": "chat.completion",
    "created": 1234567890,
    "model": "sonar",
    "choices": [
        {
            "index": 0,
            "message": {
                "role": "assistant",
                "content": "검색 결과 및 AI 분석 내용..."
            },
            "finish_reason": "stop"
        }
    ],
    "usage": {
        "prompt_tokens": 15,
        "completion_tokens": 152,
        "total_tokens": 167
    }
}

choices[0]['message']['content']에 최종 답변이 들어있으며, usage 필드에서 토큰 사용량을 확인할 수 있습니다.

3-3. 사용 가능한 모델 확인

Perplexity API에서 제공하는 주요 모델들:

• sonar: 기본 모델 (가장 저렴, 빠름)
• sonar-pro: 고급 모델 (더 정확한 분석)
• sonar-reasoning: 복잡한 추론 작업용

코드의 "model": "sonar" 부분을 변경해서 다른 모델을 사용할 수 있습니다.

4단계: 검색 쿼리 최적화 및 심화 예제

4-1. 다양한 검색 쿼리 패턴

Perplexity API는 단순 검색뿐 아니라 복잡한 질문도 처리합니다:

# 최신 뉴스 검색
query1 = "최신 AI 기술 트렌드 2026년"

# 비교 분석
query2 = "ChatGPT, Claude, Gemini 성능 비교"

# 특정 도메인 검색
query3 = "Python asyncio의 event loop 동작 원리"

# 시계열 분석
query4 = "비트코인 가격 추이 지난 3개월"

# 종합 보고서
query5 = "스타트업 펀딩 시 고려해야 할 법적 이슈와 최신 동향"

4-2. 고급 파라미터 튜닝

응답의 품질을 조절하려면 다음 파라미터들을 조정합니다:

payload = {
    "model": "sonar",
    "messages": [{"role": "user", "content": query}],
    "temperature": 0.2,      # 0~1: 낮을수록 결정적, 높을수록 창의적
    "top_p": 0.7,            # 0~1: 낮을수록 집중된 응답
    "max_tokens": 2000,      # 응답 길이 제한 (최대 4096)
    "return_citations": True  # 출처 정보 포함 여부
}

response = requests.post(url, json=payload, headers=headers)

4-3. 에러 처리 강화

실제 앱에서는 다양한 예외 상황을 처리해야 합니다:

import requests
import time

def search_with_retry(query: str, max_retries: int = 3) -> str:
    """
    재시도 로직이 포함된 API 호출
    """
    url = "https://api.perplexity.ai/chat/completions"
    headers = {
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    }

    payload = {
        "model": "sonar",
        "messages": [{"role": "user", "content": query}],
        "temperature": 0.7,
        "max_tokens": 1024
    }

    for attempt in range(max_retries):
        try:
            response = requests.post(url, json=payload, headers=headers, timeout=30)

            if response.status_code == 200:
                return response.json()['choices'][0]['message']['content']
            elif response.status_code == 429:  # Rate limit
                wait_time = 2 ** attempt  # 지수 백오프
                print(f"Rate limited. Waiting {wait_time} seconds...")
                time.sleep(wait_time)
            elif response.status_code == 401:  # Unauthorized
                return "Error: API 키가 유효하지 않습니다."
            elif response.status_code >= 500:  # Server error
                print(f"Server error {response.status_code}. Retrying...")
                time.sleep(2 ** attempt)
            else:
                return f"Error: {response.status_code}"

        except requests.exceptions.Timeout:
            print("Request timeout. Retrying...")
            time.sleep(2)
        except requests.exceptions.RequestException as e:
            return f"Network error: {str(e)}"

    return "Max retries exceeded."

5단계: 실전 앱 구현 — Flask 웹 앱

5-1. 프로젝트 구조 설계

간단한 웹 기반 검색 앱을 만들어봅시다:

perplexity-search-app/
├── app.py              # Flask 메인 앱
├── search_api.py       # API 로직
├── .env                # 환경 변수
├── requirements.txt    # 패키지 목록
└── templates/
    └── index.html      # 프론트엔드

5-2. 백엔드 구현 (app.py)

from flask import Flask, render_template, request, jsonify
from dotenv import load_dotenv
import os
from search_api import search_with_perplexity

load_dotenv()
app = Flask(__name__)

@app.route('/')
def index():
    return render_template('index.html')

@app.route('/search', methods=['POST'])
def search():
    """
    클라이언트 요청 처리 엔드포인트
    """
    data = request.get_json()
    query = data.get('query')

    if not query:
        return jsonify({'error': 'Query is required'}), 400

    if len(query) > 500:
        return jsonify({'error': 'Query is too long (max 500 characters)'}), 400

    try:
        result = search_with_perplexity(query)
        return jsonify({'result': result, 'status': 'success'})
    except Exception as e:
        return jsonify({'error': str(e)}), 500

@app.route('/health', methods=['GET'])
def health():
    """
    서버 헬스 체크
    """
    return jsonify({'status': 'ok'})

if __name__ == '__main__':
    app.run(debug=True, port=5000)

5-3. API 로직 모듈 (search_api.py)

import requests
import os
from dotenv import load_dotenv

load_dotenv()
api_key = os.getenv('PERPLEXITY_API_KEY')

def search_with_perplexity(query: str) -> str:
    """
    Perplexity API를 이용한 실시간 검색
    """
    url = "https://api.perplexity.ai/chat/completions"

    headers = {
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    }

    payload = {
        "model": "sonar",
        "messages": [
            {
                "role": "system",
                "content": "You are a helpful assistant that provides accurate, concise, and well-organized information based on real-time web search."
            },
            {
                "role": "user",
                "content": query
            }
        ],
        "temperature": 0.7,
        "top_p": 0.9,
        "max_tokens": 1500,
        "return_citations": True
    }

    try:
        response = requests.post(url, json=payload, headers=headers, timeout=30)
        response.raise_for_status()

        result = response.json()
        return result['choices'][0]['message']['content']

    except requests.exceptions.HTTPError as e:
        if response.status_code == 401:
            raise Exception("인증 실패: API 키를 확인하세요.")
        elif response.status_code == 429:
            raise Exception("요청이 너무 많습니다. 잠시 후 다시 시도하세요.")
        else:
            raise Exception(f"API 에러: {response.status_code}")
    except requests.exceptions.Timeout:
        raise Exception("요청 시간 초과. 잠시 후 다시 시도하세요.")
    except Exception as e:
        raise Exception(f"오류 발생: {str(e)}")

5-4. 프론트엔드 (templates/index.html)

간단한 HTML 인터페이스를 만들어봅시다. 이 부분은 Flask 템플릿으로 작동합니다:

<!DOCTYPE html>
<html lang="ko">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Perplexity 실시간 AI 검색</title>
    <style>
        * { margin: 0; padding: 0; box-sizing: border-box; }
        body { font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif; background: linear-gradient(135deg, #667eea 0%, #764ba2 100%); min-height: 100vh; display: flex; align-items: center; justify-content: center; }
        .container { background: white; padding: 40px; border-radius: 10px; box-shadow: 0 10px 40px rgba(0,0,0,0.2); max-width: 800px; width: 100%; }
        h1 { color: #333; margin-bottom: 30px; }
        .search-box { display: flex; gap: 10px; margin-bottom: 20px; }
        input { flex: 1; padding: 12px 15px; border: 2px solid #ddd; border-radius: 5px; font-size: 16px; }
        button { padding: 12px 30px; background: #667eea; color: white; border: none; border-radius: 5px; cursor: pointer; font-size: 16px; font-weight: bold; }
        button:hover { background: #5568d3; }
        .result { margin-top: 30px; padding: 20px; background: #f5f5f5; border-left: 4px solid #667eea; border-radius: 5px; display: none; }
        .result.show { display: block; }
        .loading { text-align: center; color: #667eea; display: none; }
        .error { color: #e74c3c; background: #fadbd8; padding: 15px; border-radius: 5px; margin-top: 20px; display: none; }
    </style>
</head>
<body>
    <div class="container">
        <h1>🔍 Perplexity 실시간 AI 검색</h1>
        <div class="search-box">
            <input type="text" id="query" placeholder="검색어를 입력하세요..." />
            <button onclick="search()">검색</button>
        </div>
        <div class="loading" id="loading">검색 중입니다...</div>
        <div class="error" id="error"></div>
        <div class="result" id="result"></div>
    </div>
    <script>
        async function search() {
            const query = document.getElementById('query').value.trim();
            if (!query) { alert('검색어를 입력하세요.'); return; }

            document.getElementById('loading').style.display = 'block';
            document.getElementById('result').style.display = 'none';
            document.getElementById('error').style.display = 'none';

            try {
                const response = await fetch('/search', {
                    method: 'POST',
                    headers: { 'Content-Type': 'application/json' },
                    body: JSON.stringify({ query: query })
                });
                const data = await response.json();
                document.getElementById('loading').style.display = 'none';

                if (response.ok) {
                    document.getElementById('result').textContent = data.result;
                    document.getElementById('result').classList.add('show');
                } else {
                    document.getElementById('error').textContent = '오류: ' + data.error;
                    document.getElementById('error').style.display = 'block';
                }
            } catch (err) {
                document.getElementById('loading').style.display = 'none';
                document.getElementById('error').textContent = '네트워크 오류: ' + err.message;
                document.getElementById('error').style.display = 'block';
            }
        }

        document.getElementById('query').addEventListener('keypress', function(e) {
            if (e.key === 'Enter') search();
        });
    </script>
</body>
</html>

5-5. 앱 실행

터미널에서 다음 명령어로 Flask 앱을 시작합니다:

python app.py

브라우저에서 http://localhost:5000에 접속하면 검색 인터페이스를 사용할 수 있습니다.

6단계: 심화 기능 및 트러블슈팅

6-1. 응답 캐싱으로 비용 절감하기

동일한 쿼리에 대해 반복 요청하는 것을 피하기 위해 캐시를 구현할 수 있습니다:

from functools import lru_cache
import hashlib

@lru_cache(maxsize=100)
def search_with_cache(query: str) -> str:
    """
    LRU 캐시를 이용한 검색 결과 저장
    """
    return search_with_perplexity(query)

# 또는 Redis를 사용한 분산 캐시
import redis

cache = redis.Redis(host='localhost', port=6379, db=0)

def search_with_redis_cache(query: str, ttl: int = 3600) -> str:
    """
    Redis 캐시 (TTL: 1시간)
    """
    cache_key = f"search:{hashlib.md5(query.encode()).hexdigest()}"
    cached = cache.get(cache_key)

    if cached:
        return cached.decode('utf-8')

    result = search_with_perplexity(query)
    cache.setex(cache_key, ttl, result)
    return result

6-2. 토큰 사용량 추적 및 예산 관리

def track_usage(response_json: dict) -> None:
    """
    API 토큰 사용량 로깅
    """
    usage = response_json.get('usage', {})
    total_tokens = usage.get('total_tokens', 0)

    # 데이터베이스 또는 파일에 기록
    with open('api_usage.log', 'a') as f:
        f.write(f"{total_tokens} tokens used\n")

    print(f"✓ Used {total_tokens} tokens (Prompt: {usage.get('prompt_tokens')}, Completion: {usage.get('completion_tokens')})")

6-3. 일반적인 에러 해결

에러	원인	해결 방법
401 Unauthorized	API 키가 잘못됨	API 키 재발급 및 .env 파일 재확인
429 Too Many Requests	요청 제한 초과	지수 백오프 재시도 로직 적용
500 Internal Server Error	Perplexity 서버 이슈	몇 초 후 재시도
Timeout	네트워크 지연	timeout 파라미터 증가 (기본 30초)
Invalid model	지원하지 않는 모델명	sonar, sonar-pro 등 유효한 모델 확인

6-4. 프로덕션 배포 체크리스트

# 배포 전 확인사항
□ API 키는 환경 변수에 저장 (.env 파일 .gitignore 추가)
□ HTTPS 적용 (API 키 암호화 전송)
□ 에러 핸들링 및 재시도 로직 완성
□ Rate limiting 구현
□ 토큰 사용량 모니터링 및 예산 설정
□ 로깅 및 분석 시스템 구축
□ CORS 설정 (필요시)
□ 사용자 입력 검증 (SQL Injection, XSS 방지)
□ 응답 캐싱 (선택사항)
□ 로드 밸런싱 (높은 트래픽의 경우)

마치며: Perplexity API 활용 팁

Perplexity API를 효과적으로 활용하려면 다음을 기억하세요:

• 명확한 쿼리: 구체적일수록 정확한 답변을 얻습니다.
• 비용 최적화: 불필요한 반복 요청을 캐싱으로 줄이세요.
• 모델 선택: sonar는 빠르지만, sonar-pro는 더 정확합니다.
• 보안: API 키를 절대 코드에 직접 작성하지 말고 환경 변수로 관리하세요.
• 모니터링: 사용량을 주기적으로 확인하고 예산을 설정하세요.

이 튜토리얼에서 다룬 코드들은 GitHub에 공개하거나, 추가 기능(사용자 인증, 검색 히스토리, 고급 필터링 등)을 구현해 더욱 완성도 높은 앱으로 발전시킬 수 있습니다.

---

면책 조항: 이 글에 소개된 서비스와 도구는 작성 시점 기준이며, 업데이트에 따라 변경될 수 있습니다.