🦌 DeerFlow

오픈소스에서 시작하여, 오픈소스에 기여합니다.

DeerFlow (Deep Exploration and Efficient Research Flow)는 오픈소스 커뮤니티의 놀라운 작업을 기반으로 구축된 커뮤니티 주도의 딥 리서치 프레임워크입니다. 우리의 목표는 언어 모델을 웹 검색, 크롤링, Python 코드 실행과 같은 작업을 위한 특수 도구와 결합하면서, 이를 가능하게 한 커뮤니티에 다시 기여하는 것입니다.

자세한 내용은 공식 웹사이트를 방문해 주세요.

데모

비디오

https://github.com/user-attachments/assets/f3786598-1f2a-4d07-919e-8b99dfa1de3e

이 데모에서는 DeerFlow를 사용하여 다음을 수행하는 방법을 보여줍니다:

• MCP 서비스와 원활한 통합
• 딥 리서치 프로세스 수행 및 이미지가 포함된 종합 보고서 생성
• 생성된 보고서를 기반으로 한 팟캐스트 오디오 생성

리플레이

• 에펠탑은 가장 높은 건물과 비교했을 때 얼마나 높을까요?
• GitHub에서 가장 인기 있는 저장소는 무엇인가요?
• 난징의 전통 요리에 대한 기사 작성하기
• 임대 아파트를 어떻게 꾸밀까요?
• 더 많은 리플레이를 보려면 공식 웹사이트를 방문하세요.

---

📑 목차

• 🚀 빠른 시작
• 🌟 기능
• 🏗️ 아키텍처
• 🛠️ 개발
• 🐳 Docker
• 🗣️ 텍스트-투-스피치 통합
• 📚 예제
• ❓ FAQ
• 📜 라이선스
• 💖 감사의 말
• ⭐ 스타 히스토리

빠른 시작

DeerFlow는 Python으로 개발되었으며, Node.js로 작성된 웹 UI가 포함되어 있습니다. 원활한 설정 프로세스를 위해 다음 도구를 사용하는 것을 권장합니다:

권장 도구

• uv: Python 환경 및 의존성 관리를 단순화합니다. uv는 루트 디렉토리에 가상 환경을 자동으로 생성하고 필요한 모든 패키지를 설치합니다—Python 환경을 수동으로 설치할 필요가 없습니다.

• nvm: Node.js 런타임의 여러 버전을 쉽게 관리할 수 있습니다.

• pnpm: Node.js 프로젝트의 의존성을 설치하고 관리합니다.

환경 요구사항

시스템이 다음 최소 요구사항을 충족하는지 확인하세요:

• Python: 버전 3.12+
• Node.js: 버전 22+

설치

# 저장소 클론
git clone https://github.com/bytedance/deer-flow.git
cd deer-flow

# 의존성 설치, uv가 Python 인터프리터와 venv 생성을 처리하고 필요한 패키지를 설치합니다
uv sync

# API 키로 .env 구성
# Tavily: https://app.tavily.com/home
# Brave_SEARCH: https://brave.com/search/api/
# volcengine TTS: TTS 자격 증명이 있다면 추가하세요
cp .env.example .env

# 사용 가능한 모든 옵션은 아래의 '지원되는 검색 엔진'과 '텍스트-투-스피치 통합' 섹션을 참조하세요

# LLM 모델과 API 키로 conf.yaml 구성
# 자세한 내용은 'docs/configuration_guide.md'를 참조하세요
cp conf.yaml.example conf.yaml

# ppt 생성을 위한 marp 설치
# https://github.com/marp-team/marp-cli?tab=readme-ov-file#use-package-manager
brew install marp-cli

선택적으로, pnpm을 통해 웹 UI 의존성을 설치할 수 있습니다:

cd deer-flow/web
pnpm install

구성

자세한 내용은 구성 가이드를 참조하세요.

콘솔 UI

프로젝트를 실행하는 가장 빠른 방법은 콘솔 UI를 사용하는 것입니다.

# bash와 같은 셸에서 프로젝트 실행
uv run main.py

웹 UI

이 프로젝트는 더 역동적이고 매력적인 대화형 경험을 제공하는 웹 UI도 포함하고 있습니다.

# 개발 모드에서 백엔드와 프론트엔드 서버 모두 실행
# macOS/Linux에서
./bootstrap.sh -d

# Windows에서
bootstrap.bat -d

브라우저를 열고 http://localhost:3000을 방문하여 웹 UI를 탐색하세요.

web 디렉토리에서 더 자세한 내용을 확인하세요.

지원되는 검색 엔진

DeerFlow는 .env 파일의 SEARCH_API 변수를 사용하여 구성할 수 있는 여러 검색 엔진을 지원합니다:

• Tavily (기본값): AI 애플리케이션을 위한 특수 검색 API

  • .env 파일에 TAVILY_API_KEY 필요
  • 가입: https://app.tavily.com/home

• DuckDuckGo: 개인정보 보호 중심 검색 엔진

  • API 키 불필요

• Brave Search: 고급 기능이 있는 개인정보 보호 중심 검색 엔진

  • .env 파일에 BRAVE_SEARCH_API_KEY 필요
  • 가입: https://brave.com/search/api/

• Arxiv: 학술 연구를 위한 과학 논문 검색

  • API 키 불필요
  • 과학 및 학술 논문에 특화됨

선호하는 검색 엔진을 구성하려면 .env 파일에서 SEARCH_API 변수를 설정하세요:

# 선택: tavily, duckduckgo, brave_search, arxiv
SEARCH_API=tavily

기능

핵심 기능

• 🤖 LLM 통합
  • litellm을 통해 대부분의 모델 통합을 지원합니다.
  • Qwen과 같은 오픈소스 모델 지원
  • OpenAI 호환 API 인터페이스
  • 다양한 작업 복잡성에 대한 다단계 LLM 시스템

도구 및 MCP 통합

• 🔍 검색 및 검색

  • Tavily, Brave Search 등을 통한 웹 검색
  • Jina를 사용한 크롤링
  • 고급 콘텐츠 추출

• 🔗 MCP 원활한 통합

  • 프라이빗 도메인 접근, 지식 그래프, 웹 브라우징 등을 위한 기능 확장
  • 다양한 연구 도구 및 방법론의 통합 촉진

인간 협업

• 🧠 인간-인-루프

  • 자연어를 사용한 연구 계획의 대화형 수정 지원
  • 연구 계획의 자동 수락 지원

• 📝 보고서 후편집

  • Notion과 같은 블록 편집 지원
  • AI 지원 다듬기, 문장 축소, 확장을 포함한 AI 개선 허용
  • tiptap으로 구동

콘텐츠 생성

• 🎙️ 팟캐스트 및 프레젠테이션 생성
  • AI 기반 팟캐스트 스크립트 생성 및 오디오 합성
  • 간단한 PowerPoint 프레젠테이션 자동 생성
  • 맞춤형 콘텐츠를 위한 사용자 정의 가능한 템플릿

아키텍처

DeerFlow는 자동화된 연구 및 코드 분석을 위해 설계된 모듈식 다중 에이전트 시스템 아키텍처를 구현합니다. 이 시스템은 LangGraph를 기반으로 구축되어, 구성 요소가 잘 정의된 메시지 전달 시스템을 통해 통신하는 유연한 상태 기반 워크플로우를 가능하게 합니다.

!아키텍처 다이어그램

deerflow.tech에서 실시간으로 확인하세요

이 시스템은 다음과 같은 구성 요소로 구성된 간소화된 워크플로우를 사용합니다:

1. 코디네이터: 워크플로우 수명 주기를 관리하는 진입점

   • 사용자 입력을 기반으로 연구 프로세스 시작
   • 적절한 시점에 플래너에 작업 위임
   • 사용자와 시스템 간의 주요 인터페이스 역할

2. 플래너: 작업 분해 및 계획을 위한 전략적 구성 요소

   • 연구 목표를 분석하고 구조화된 실행 계획 생성
   • 충분한 컨텍스트가 있는지 또는 더 많은 연구가 필요한지 결정
   • 연구 흐름 관리 및 최종 보고서 생성 시점 결정

3. 연구팀: 계획을 실행하는 전문 에이전트 모음:

   • 연구원: 웹 검색 엔진, 크롤링 및 MCP 서비스를 사용하여 웹 검색 및 정보 수집 수행
   • 코더: Python REPL 도구를 사용하여 코드 분석, 실행 및 기술 작업 처리 각 에이전트는 LangGraph 프레임워크 내에서 작동하며 역할에 최적화된 특정 도구에 접근할 수 있습니다

4. 리포터: 연구 출력을 위한 최종 단계 프로세서

   • 연구팀의 발견 사항 집계
   • 수집된 정보 처리 및 구조화
   • 종합적인 연구 보고서 생성

텍스트-투-스피치 통합

DeerFlow는 이제 연구 보고서를 음성으로 변환할 수 있는 텍스트-투-스피치(TTS) 기능을 포함하고 있습니다. 이 기능은 volcengine TTS API를 사용하여 텍스트에서 고품질 오디오를 생성합니다. 속도, 볼륨, 피치 등의 기능도 사용자 정의할 수 있습니다.

TTS API 사용

/api/tts 엔드포인트를 통해 TTS 기능에 접근할 수 있습니다:

# curl을 사용한 예제 API 호출
curl --location 'http://localhost:8000/api/tts' \
--header 'Content-Type: application/json' \
--data '{
    "text": "이것은 텍스트-투-스피치 기능 테스트입니다.",
    "speed_ratio": 1.0,
    "volume_ratio": 1.0,
    "pitch_ratio": 1.0
}' \
--output speech.mp3

개발

테스트

테스트 스위트 실행:

# 모든 테스트 실행
make test

# 특정 테스트 파일 실행
pytest tests/integration/test_workflow.py

# 커버리지와 함께 실행
make coverage

코드 품질

# 린팅 실행
make lint

# 코드 포맷팅
make format

LangGraph Studio로 디버깅

DeerFlow는 워크플로우 아키텍처에 LangGraph를 사용합니다. LangGraph Studio를 사용하여 워크플로우를 실시간으로 디버깅하고 시각화할 수 있습니다.

LangGraph Studio 로컬 실행

DeerFlow는 LangGraph Studio를 위한 langgraph.json 구성 파일을 포함하고 있으며, 이 파일은 프로젝트에 정의된 워크플로우 그래프와 의존성을 정의합니다. 이 파일은 .env 파일에서 환경 변수를 자동으로 로드합니다.

Mac

# uv 패키지 관리자가 없다면 설치
curl -LsSf https://astral.sh/uv/install.sh | sh

# 의존성 설치 및 LangGraph 서버 시작
uvx --refresh --from "langgraph-cli[inmem]" --with-editable . --python 3.12 langgraph dev --allow-blocking

Windows / Linux

# 의존성 설치
pip install -e .
pip install -U "langgraph-cli[inmem]"

# LangGraph 서버 시작
langgraph dev

LangGraph 서버를 시작한 후, 터미널에서 여러 URL이 표시됩니다:

• API: http://127.0.0.1:2024
• Studio UI: https://smith.langchain.com/studio/?baseUrl=http://127.0.0.1:2024
• API 문서: http://127.0.0.1:2024/docs

브라우저에서 Studio UI 링크를 열어 디버깅 인터페이스에 접근하세요.

LangGraph Studio 사용

Studio UI에서 다음을 수행할 수 있습니다:

1. 워크플로우 그래프를 시각화하고 구성 요소가 어떻게 연결되는지 확인
2. 실시간으로 실행을 추적하여 데이터가 시스템을 통해 어떻게 흐르는지 확인
3. 워크플로우의 각 단계에서 상태 검사
4. 각 구성 요소의 입력과 출력을 검사하여 문제 디버깅
5. 연구 계획을 개선하기 위해 계획 단계에서 피드백 제공

Studio UI에서 연구 주제를 제출하면 다음을 포함한 전체 워크플로우 실행을 볼 수 있습니다:

• 연구 계획이 생성되는 계획 단계
• 계획을 수정할 수 있는 피드백 루프
• 각 섹션의 연구 및 작성 단계
• 최종 보고서 생성

LangSmith 추적 활성화

DeerFlow는 워크플로우를 디버깅하고 모니터링하는 데 도움이 되는 LangSmith 추적을 지원합니다. LangSmith 추적을 활성화하려면:

1. .env 파일에 다음 구성이 있는지 확인하세요 (.env.example 참조):

   LANGSMITH_TRACING=true
   LANGSMITH_ENDPOINT="https://api.smith.langchain.com"
   LANGSMITH_API_KEY="xxx"
   LANGSMITH_PROJECT="xxx"
   

2. LangSmith로 추적을 시작하고 그래프를 로컬에서 시각화하려면 다음을 실행하세요:

   langgraph dev
   

이렇게 하면 LangGraph Studio에서 추적 시각화가 활성화되고 추적이 LangSmith로 전송되어 모니터링 및 분석이 가능합니다.

Docker

이 프로젝트는 Docker로도 실행할 수 있습니다.

먼저 아래의 구성을 읽어야 합니다. .env, .conf.yaml 파일이 준비되어 있는지 확인하세요.

둘째, 자체 웹 서버의 Docker 이미지를 빌드하려면:

docker build -t deer-flow-api .

마지막으로, 웹 서버를 실행하는 Docker 컨테이너를 시작합니다:

# deer-flow-api-app을 선호하는 컨테이너 이름으로 교체하세요
docker run -d -t -p 8000:8000 --env-file .env --name deer-flow-api-app deer-flow-api

# 서버 중지
docker stop deer-flow-api-app

Docker Compose (백엔드와 프론트엔드 모두 포함)

DeerFlow는 백엔드와 프론트엔드를 함께 쉽게 실행할 수 있는 docker-compose 설정을 제공합니다:

# Docker 이미지 빌드
docker compose build

# 서버 시작
docker compose up

예제

다음 예제는 DeerFlow의 기능을 보여줍니다:

연구 보고서

1. OpenAI Sora 보고서 - OpenAI의 Sora AI 도구 분석

   • 기능, 접근성, 프롬프트 엔지니어링, 제한 사항 및 윤리적 고려사항 논의
   • 전체 보고서 보기

2. Google의 Agent to Agent 프로토콜 보고서 - Google의 Agent to Agent (A2A) 프로토콜 개요

   • AI 에이전트 통신에서의 역할과 Anthropic의 Model Context Protocol (MCP)과의 관계 논의
   • 전체 보고서 보기

3. MCP란 무엇인가? - 여러 맥락에서 "MCP"라는 용어에 대한 종합적인 분석

   • AI의 Model Context Protocol, 화학의 Monocalcium Phosphate, 전자공학의 Micro-channel Plate 탐구
   • 전체 보고서 보기

4. 비트코인 가격 변동 - 최근 비트코인 가격 움직임 분석

   • 시장 동향, 규제 영향 및 기술적 지표 검토
   • 과거 데이터를 기반으로 한 권장사항 제공
   • 전체 보고서 보기

5. LLM이란 무엇인가? - 대규모 언어 모델에 대한 심층 탐구

   • 아키텍처, 훈련, 응용 및 윤리적 고려사항 논의
   • 전체 보고서 보기

6. Claude를 딥 리서치에 어떻게 사용할까? - Claude를 딥 리서치에 사용하기 위한 모범 사례 및 워크플로우

   • 프롬프트 엔지니어링, 데이터 분석 및 다른 도구와의 통합 다룸
   • 전체 보고서 보기

7. 의료 분야의 AI 채택: 영향 요인 - 의료 분야에서 AI 채택을 주도하는 요인 분석

   • AI 기술, 데이터 품질, 윤리적 고려사항, 경제적 평가, 조직 준비도 및 디지털 인프라 논의
   • 전체 보고서 보기

8. 양자 컴퓨팅이 암호화에 미치는 영향 - 양자 컴퓨팅이 암호화에 미치는 영향 분석

   • 고전 암호화의 취약성, 포스트-양자 암호화 및 양자 저항 암호화 솔루션 논의
   • 전체 보고서 보기

9. 크리스티아누 호날두의 성과 하이라이트 - 크리스티아누 호날두의 성과 하이라이트 분석

   • 그의 경력 성취, 국제 골, 다양한 경기에서의 성과 논의
   • 전체 보고서 보기

이러한 예제를 실행하거나 자신의 연구 보고서를 작성하려면 다음 명령을 사용할 수 있습니다:

# 특정 쿼리로 실행
uv run main.py "의료 분야에서 AI 채택에 영향을 미치는 요인은 무엇인가요?"

# 사용자 정의 계획 매개변수로 실행
uv run main.py --max_plan_iterations 3 "양자 컴퓨팅이 암호화에 어떤 영향을 미치나요?"

# 내장된 질문이 있는 대화형 모드로 실행
uv run main.py --interactive

# 또는 기본 대화형 프롬프트로 실행
uv run main.py

# 사용 가능한 모든 옵션 보기
uv run main.py --help

대화형 모드

이제 애플리케이션은 영어와 중국어로 내장된 질문이 있는 대화형 모드를 지원합니다:

1. 대화형 모드 시작:

   uv run main.py --interactive
   

2. 선호하는 언어 선택 (영어 또는 中文)

3. 내장된 질문 목록에서 선택하거나 자신의 질문을 묻는 옵션 선택

4. 시스템이 질문을 처리하고 종합적인 연구 보고서 생성

인간-인-루프

DeerFlow는 연구 계획이 실행되기 전에 검토, 편집 및 승인할 수 있는 인간-인-루프 메커니즘을 포함하고 있습니다:

1. 계획 검토: 인간-인-루프가 활성화되면 시스템은 실행 전에 생성된 연구 계획을 검토할 수 있도록 제시합니다

2. 피드백 제공: 다음을 수행할 수 있습니다:

   • [ACCEPTED]로 응답하여 계획 수락
   • 피드백을 제공하여 계획 편집 (예: [EDIT PLAN] 기술 구현에 대한 단계 추가)
   • 시스템이 피드백을 통합하고 수정된 계획 생성

3. 자동 수락: 검토 프로세스를 건너뛰기 위해 자동 수락을 활성화할 수 있습니다:

   • API를 통해: 요청에서 auto_accepted_plan: true 설정

4. API 통합: API를 사용할 때 feedback 매개변수를 통해 피드백을 제공할 수 있습니다:

   {
     "messages": [{ "role": "user", "content": "양자 컴퓨팅이란 무엇인가요?" }],
     "thread_id": "my_thread_id",
     "auto_accepted_plan": false,
     "feedback": "[EDIT PLAN] 양자 알고리즘에 대한 내용 추가"
   }
   

명령줄 인수

애플리케이션은 동작을 사용자 정의하기 위한 여러 명령줄 인수를 지원합니다:

• query: 처리할 연구 쿼리 (여러 단어 가능)
• --interactive: 내장된 질문이 있는 대화형 모드로 실행
• --max_plan_iterations: 최대 계획 주기 수 (기본값: 1)
• --max_step_num: 연구 계획의 최대 단계 수 (기본값: 3)
• --debug: 상세한 디버그 로깅 활성화

FAQ

자세한 내용은 FAQ.md를 참조하세요.

라이선스

이 프로젝트는 MIT 라이선스에 따라 오픈소스로 제공됩니다.

감사의 말

DeerFlow는 오픈소스 커뮤니티의 놀라운 작업을 기반으로 구축되었습니다. DeerFlow를 가능하게 한 모든 프로젝트와 기여자들에게 깊은 감사를 표합니다. 진정으로, 우리는 거인의 어깨 위에 서 있습니다.

다음 프로젝트들의 귀중한 기여에 진심으로 감사드립니다:

• LangChain: 그들의 탁월한 프레임워크가 우리의 LLM 상호작용과 체인을 구동하여 원활한 통합과 기능을 가능하게 합니다.
• LangGraph: 그들의 혁신적인 다중 에이전트 오케스트레이션 접근 방식이 DeerFlow의 정교한 워크플로우를 가능하게 하는 데 중요한 역할을 했습니다.

이러한 프로젝트들은 오픈소스 협업의 변혁적인 힘을 보여주며, 우리는 그들의 기반 위에 구축하게 되어 자랑스럽습니다.

주요 기여자

DeerFlow의 핵심 저자들에게 진심으로 감사드립니다. 그들의 비전, 열정, 헌신이 이 프로젝트를 실현시켰습니다:

• Daniel Walnut
• Henry Li

여러분의 변함없는 헌신과 전문성이 DeerFlow의 성공을 이끌어낸 원동력이었습니다. 이 여정의 선두에 여러분이 계셔서 영광입니다.

스타 히스토리