[오픈소스] dzhng/deep-research 완벽 가이드: 초고품질 리서치를 위한 Anthropic Claude 5.0 Opus & 셀프호스팅 Firecrawl 연동

OpenAI의 Deep Research 서비스는 강력하지만 높은 구독 비용과 사용량 제한이 존재합니다. 이를 대체하면서도 복잡한 논문, 시장 분석, 기술 조사에서 극상의 보고서 퀄리티를 얻기 위해 오픈소스 dzhng/deep-research를 활용하는 방법이 각광받고 있습니다.

본 포스팅에서는 API 비용은 다소 높지만 현존 최고 수준의 추론력과 합성 능력을 자랑하는 Anthropic Claude 5.0 Opus 모델과 셀프호스팅 Firecrawl(Docker)을 연동하여 전문가급 심층 분석 보고서를 자동 생성하는 구체적인 구축 및 활용법을 정리합니다.

---

1. dzhng/deep-research 란?

사용자가 연구 목표를 입력하면 AI가 스스로 명확한 질문을 던지고, 웹을 반복적으로 탐색·크롤링하며, 수집된 데이터를 바탕으로 출처(각주)가 포함된 종합 마크다운 보고서를 작성해 주는 자동화 AI 에이전트입니다.

주요 특징

• 재귀적 심층 검색 (Iterative Deep Search): 수집된 지식을 분석하여 스스로 부족한 공백을 파악하고 추가 추적 검색을 실행합니다.
• 스마트 크롤링 (Firecrawl 연동): 웹페이지 HTML을 LLM이 읽기 쉬운 Clean Markdown 형태로 변환해 수집합니다.
• 압도적인 Opus 추론 조합: Vercel AI SDK 기반으로 동작하여 최고 등급 모델인 Claude 5.0 Opus의 다단계 합성 능력을 온전히 활용합니다.

---

2. 기본 설치 및 환경 설정

단계 1: 리포지토리 클론 및 패키지 설치

터미널을 열고 리포지토리를 복사한 뒤 의존성 패키지를 설치합니다.

git clone https://github.com/dzhng/deep-research.git
cd deep-research
npm install

단계 2: 기본 .env.local 생성

프로젝트 루트 경로에 .env.local 파일을 생성합니다.

---

3. Anthropic Claude 5.0 Opus 연동 설정 (고성능/고품질)

Claude 5.0 Opus는 복잡한 다단계 논리 추론과 종합 보고서 작성에서 가장 뛰어난 성능을 발휘합니다. OpenRouter 또는 로컬 프록시 엔드포인트를 연결하여 설정할 수 있습니다.

방법 A: OpenRouter를 통한 Claude 5.0 Opus 연동 (추천)

OpenRouter 엔드포인트를 통해 dzhng/deep-research 환경에 Claude 5.0 Opus 모델을 연결합니다.

# OpenRouter 엔드포인트 설정
OPENAI_ENDPOINT="https://openrouter.ai/api/v1"
OPENAI_KEY="your_openrouter_api_key_here"

# 최고 성능의 Claude 5.0 Opus 모델 지정
CUSTOM_MODEL="anthropic/claude-5.0-opus"

# 대용량 토큰 컨텍스트 지원
CONTEXT_SIZE="200000"

# Web Scraping 엔진 API 키
FIRECRAWL_KEY="your_firecrawl_key"

방법 B: LiteLLM / Proxy를 통한 Anthropic API 직접 연동

Anthropic 공식 API 키(sk-ant-...)를 사용하는 경우 LiteLLM 등의 로컬 프록시를 거쳐 연결합니다.

# 로컬 LiteLLM 프록시 포트
OPENAI_ENDPOINT="http://localhost:4000/v1"
OPENAI_KEY="sk-ant-your_anthropic_key"
CUSTOM_MODEL="claude-5.0-opus"
CONTEXT_SIZE="200000"

💡 Claude 5.0 Opus 활용 및 비용 최적화 팁:
Sonnet이나 Flash 모델 대비 토큰 당 API 비용은 높지만, 수집된 수십 개의 문서를 유기적으로 합성하고 모순점을 찾아내는 능력은 독보적입니다. 최고 품질의 종합 분석서가 필요한 전문 리서치 작업에 매우 적합합니다.

---

4. 셀프호스팅 Firecrawl 구축 (Docker)

Opus 모델 사용 시 LLM 비용에 집중하기 위해, 웹 크롤링 영역은 Docker 기반 셀프호스팅 Firecrawl을 구동하여 무료로 전환합니다.

1단계: Docker로 Firecrawl 실행

git clone https://github.com/mendableai/firecrawl.git
cd firecrawl
docker compose up -d

2단계: 동작 검증

curl -X POST http://localhost:3002/v1/scrape \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'

3단계: deep-research 환경변수 연결

dzhng/deep-research 프로젝트의 .env.local에 셀프호스팅 경로를 추가합니다.

# 로컬 Firecrawl 엔드포인트
FIRECRAWL_BASE_URL="http://localhost:3002"
FIRECRAWL_KEY="local_key"

# 처리 속도 향상을 위한 동시성 확장
FIRECRAWL_CONCURRENCY="5"
CONCURRENCY_LIMIT="5"

---

5. 실전 실행 및 활용

모든 설정을 마친 뒤 터미널에서 리서치 에이전트를 실행합니다.

npm start

조사할 주제를 입력하면 Claude 5.0 Opus가 심도 있는 추가 질문을 구성하고, 로컬 Firecrawl이 수집한 자료를 바탕으로 압도적인 깊이의 output.md 보고서를 생성합니다.