deer-flow

🦌 DeerFlow

English | 简体中文 | 日本語

オープンソースから始まり、オープンソースに還元します。

DeerFlow (Deep Exploration and Efficient Research Flow) は、オープンソースコミュニティの素晴らしい成果を基盤として構築された、コミュニティ主導のディープリサーチフレームワークです。私たちの目標は、言語モデルと、ウェブ検索、クローリング、Python コードの実行などのタスクに特化したツールを組み合わせるとともに、この実現を可能にしたコミュニティに還元することです。

詳しくは、公式ウェブサイトをご覧ください。

デモ

動画

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

このデモでは、DeerFlow を使用して以下を行う方法をご紹介します。

• MCP サービスとシームレスに連携する
• ディープリサーチのプロセスを実行し、画像を含む包括的なレポートを作成する
• 生成されたレポートをもとにポッドキャスト音声を作成する

リプレイ

• エッフェル塔は最も高い建物と比べてどのくらいの高さですか？
• GitHub で現在人気のリポジトリは何ですか？
• 南京の伝統料理についての記事を書く
• 賃貸アパートをどのように飾り付ければよいですか？
• 公式ウェブサイトで、ほかのリプレイもご覧ください。

---

📑 目次

• 🚀 クイックスタート
• 🌟 機能
• 🏗️ アーキテクチャ
• 🛠️ 開発
• 🗣️ テキスト読み上げの連携
• 📚 例
• ❓ FAQ
• 📜 ライセンス
• 💖 謝辞
• ⭐ スター履歴

クイックスタート

DeerFlow は Python で開発されており、Node.js で記述されたウェブ UI が付属しています。スムーズにセットアップするため、以下のツールの使用をおすすめします。

推奨ツール

• uv: Python 環境と依存関係の管理を簡素化します。uv はルートディレクトリに仮想環境を自動で作成し、必要なパッケージをすべてインストールするため、Python 環境を手動でインストールする必要はありません。

• nvm: 複数バージョンの Node.js ランタイムを手軽に管理できます。

• pnpm: Node.js プロジェクトの依存関係をインストールして管理します。

環境要件

システムが以下の最小要件を満たしていることを確認してください。

• Python: バージョン 3.12+
• Node.js: バージョン 22+

インストール

# Clone the repository
git clone https://github.com/bytedance/deer-flow.git
cd deer-flow

# Install dependencies, uv will take care of the python interpreter and venv creation, and install the required packages
uv sync

# Configure .env with your API keys
# Tavily: https://app.tavily.com/home
# Brave_SEARCH: https://brave.com/search/api/
# volcengine TTS: Add your TTS credentials if you have them
cp .env.example .env

# See the 'Supported Search Engines' and 'Text-to-Speech Integration' sections below for all available options

# Configure conf.yaml for your LLM model and API keys
# Please refer to 'docs/configuration_guide.md' for more details
cp conf.yaml.example conf.yaml

# Install marp for ppt generation
# 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 を使用します。

# Run the project in a bash-like shell
uv run main.py

ウェブ UI

このプロジェクトにはウェブ UI も含まれており、より動的で魅力的な対話型エクスペリエンスを提供します。

メモ

まずウェブ UI の依存関係をインストールする必要があります。

# Run both the backend and frontend servers in development mode
# On macOS/Linux
./bootstrap.sh -d

# On 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 変数を設定します。

# Choose one: tavily, duckduckgo, brave_search, arxiv
SEARCH_API=tavily

機能

主な機能

• 🤖 LLM との連携
  • litellm を通じて、ほとんどのモデルと連携できます。
  • Qwen などのオープンソースモデルに対応
  • OpenAI 互換の API インターフェース
  • タスクの複雑さに応じたマルチティア LLM システム

ツールと MCP 連携

• 🔍 検索と情報取得

  • Tavily、Brave Search などを利用したウェブ検索
  • Jina によるクロール
  • 高度なコンテンツ抽出

• 🔗 シームレスな MCP 連携

  • プライベートドメインへのアクセス、ナレッジグラフ、ウェブ閲覧などの機能を拡張
  • 多様なリサーチツールや手法との連携を促進

人間との協働

• 🧠 Human-in-the-loop

  • 自然言語を使ったリサーチ計画の対話的な変更に対応
  • リサーチ計画の自動承認に対応

• 📝 レポートの編集

  • Notion のようなブロック編集に対応
  • AI による仕上げ、文章の短縮、拡張などの AI 支援による調整が可能
  • tiptap を利用

コンテンツ作成

• 🎙️ ポッドキャストとプレゼンテーションの生成
  • AI によるポッドキャスト台本の生成と音声合成
  • シンプルな PowerPoint プレゼンテーションを自動作成
  • コンテンツに合わせてカスタマイズできるテンプレート

アーキテクチャ

DeerFlow は、自動リサーチとコード分析向けに設計されたモジュール型マルチエージェントシステムアーキテクチャを実装しています。システムは LangGraph 上に構築されており、明確に定義されたメッセージパッシングシステムを介してコンポーネントが通信する、柔軟な状態ベースのワークフローを実現します。

deerflow.tech で実際の動作をご覧ください

システムは、以下のコンポーネントで構成される簡素化されたワークフローを採用しています。

1. Coordinator：ワークフローのライフサイクルを管理する入口

   • ユーザー入力に基づいてリサーチを開始します
   • 適切な場合に Planner にタスクを委任します
   • ユーザーとシステムをつなぐ主要なインターフェースとして機能します

2. Planner：タスクの分解と計画を担う戦略的コンポーネント

   • リサーチの目的を分析し、構造化された実行計画を作成します
   • 十分なコンテキストがあるか、追加のリサーチが必要かを判断します
   • リサーチの流れを管理し、最終レポートを生成するタイミングを決定します

3. Research Team：計画を実行する専門エージェントの集合体

   • Researcher：ウェブ検索エンジン、クロール、MCP サービスなどのツールを使って、ウェブ検索と情報収集を行います。
   • Coder：Python REPL ツールを使って、コード分析、実行、技術的なタスクを担当します。 各エージェントは役割に最適化された特定のツールを利用でき、LangGraph フレームワーク内で動作します

4. Reporter：リサーチ成果物を処理する最終段階のプロセッサー

   • Research Team の調査結果を集約します
   • 収集した情報を処理し、構成を整えます
   • 包括的なリサーチレポートを生成します

テキスト読み上げの統合

DeerFlow にテキスト読み上げ（TTS）機能が追加されました。この機能を使うと、調査レポートを音声に変換できます。volcengine TTS API を使用して、テキストから高品質な音声を生成します。速度、音量、ピッチなどもカスタマイズできます。

TTS API の使用

/api/tts エンドポイントから TTS 機能にアクセスできます。

# Example API call using curl
curl --location 'http://localhost:8000/api/tts' \
--header 'Content-Type: application/json' \
--data '{
    "text": "This is a test of the text-to-speech functionality.",
    "speed_ratio": 1.0,
    "volume_ratio": 1.0,
    "pitch_ratio": 1.0
}' \
--output speech.mp3

開発

テスト

テストスイートを実行します。

# Run all tests
make test

# Run specific test file
pytest tests/integration/test_workflow.py

# Run with coverage
make coverage

コード品質

# Run linting
make lint

# Format code
make format

LangGraph Studio でのデバッグ

DeerFlow はワークフローアーキテクチャに LangGraph を使用しています。LangGraph Studio を使って、ワークフローをリアルタイムでデバッグし、可視化できます。

LangGraph Studio をローカルで実行する

DeerFlow には、LangGraph Studio 用のグラフ構造と依存関係を定義する langgraph.json 設定ファイルが含まれています。このファイルはプロジェクト内で定義されたワークフローグラフを参照し、.env ファイルから環境変数を自動的に読み込みます。

Mac

# Install uv package manager if you don't have it
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install dependencies and start the LangGraph server
uvx --refresh --from "langgraph-cli[inmem]" --with-editable . --python 3.12 langgraph dev --allow-blocking

Windows / Linux

# Install dependencies
pip install -e .
pip install -U "langgraph-cli[inmem]"

# Start the LangGraph server
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 で調査トピックを送信すると、次の内容を含むワークフロー全体の実行状況を確認できます。

• 調査計画を作成する計画フェーズ
• 計画を変更できるフィードバックループ
• 各セクションの調査および執筆フェーズ
• 最終レポートの生成

例

以下の例では、DeerFlow の機能を紹介します。

調査レポート

1. OpenAI Sora レポート - OpenAI の Sora AI ツールの分析

   • 機能、アクセス方法、プロンプトエンジニアリング、制限事項、倫理的な考慮事項について説明します
   • レポート全文を見る

2. Google のエージェント間プロトコルレポート - Google の Agent to Agent（A2A）プロトコルの概要

   • AI エージェントの通信における役割と、Anthropic の Model Context Protocol（MCP）との関係について説明します
   • レポート全文を見る

3. MCP とは？ - 複数の文脈における「MCP」という用語の包括的な分析

   • AI 分野の Model Context Protocol、化学分野のリン酸一カルシウム、電子工学分野のマイクロチャネルプレートについて解説します
   • レポート全文を見る

4. ビットコイン価格の変動 - 最近のビットコイン価格の動きに関する分析

   • 市場動向、規制の影響、テクニカル指標を調査します
   • 過去のデータに基づいた推奨事項を提示します
   • レポート全文を見る

5. LLM とは？ - 大規模言語モデルを詳しく解説します

   • アーキテクチャ、学習、用途、倫理的な考慮事項について説明します
   • レポート全文を見る

6. Claude を使って深掘り調査を行う方法 - 深掘り調査で Claude を活用するためのベストプラクティスとワークフロー

   • プロンプトエンジニアリング、データ分析、他のツールとの連携について説明します
   • レポート全文を見る

7. 医療分野における AI 導入：影響要因 - 医療分野で AI の導入を促進する要因の分析

   • AI 技術、データ品質、倫理的な考慮事項、経済評価、組織の準備状況、デジタルインフラについて説明します
   • レポート全文を見る

8. 量子コンピューティングが暗号技術に与える影響 - 量子コンピューティングが暗号技術に及ぼす影響の分析

   • 従来の暗号技術の脆弱性、耐量子暗号、量子耐性のある暗号ソリューションについて説明します
   • レポート全文を見る

9. クリスティアーノ・ロナウドの主な活躍 - クリスティアーノ・ロナウドの主な活躍の分析

   • キャリアでの功績、代表チームでの得点、さまざまな試合でのパフォーマンスについて説明します
   • レポート全文を見る

これらの例を実行したり、独自の調査レポートを作成したりするには、次のコマンドを使用できます。

# Run with a specific query
uv run main.py "What factors are influencing AI adoption in healthcare?"

# Run with custom planning parameters
uv run main.py --max_plan_iterations 3 "How does quantum computing impact cryptography?"

# Run in interactive mode with built-in questions
uv run main.py --interactive

# Or run with basic interactive prompt
uv run main.py

# View all available options
uv run main.py --help

インタラクティブモード

このアプリケーションは、英語と中国語の両方で組み込みの質問を利用できるインタラクティブモードに対応しました。

1. インタラクティブモードを起動します。

   uv run main.py --interactive
   

2. 希望する言語（English または 中文）を選択します。

3. 組み込みの質問一覧から選択するか、独自の質問をするオプションを選択します。

4. システムが質問を処理し、包括的な調査レポートを生成します。

人間参加型プロセス

DeerFlow には、人間参加型の仕組みが組み込まれており、調査計画の実行前に内容を確認、編集、承認できます。

1. 計画の確認：人間参加型プロセスが有効な場合、実行前に生成された調査計画が提示され、確認できます。

2. フィードバックの提供：次の操作ができます。

   • [ACCEPTED] と返信して計画を承認します
   • フィードバックを提示して計画を編集します（例：[EDIT PLAN] Add more steps about technical implementation）
   • システムがフィードバックを反映し、修正版の計画を生成します

3. 自動承認：自動承認を有効にすると、確認プロセスを省略できます。

   • API 経由：リクエストで auto_accepted_plan: true を設定します

4. API 連携：API の使用時には、feedback パラメーターを通じてフィードバックを提供できます。

   {
     "messages": [{"role": "user", "content": "What is quantum computing?"}],
     "thread_id": "my_thread_id",
     "auto_accepted_plan": false,
     "feedback": "[EDIT PLAN] Include more about quantum algorithms"
   }
   

コマンドライン引数

このアプリケーションでは、動作をカスタマイズするために次のコマンドライン引数を使用できます。

• query：処理する調査クエリ（複数の単語を指定できます）
• --interactive：組み込みの質問を使ってインタラクティブモードで実行します
• --max_plan_iterations：計画サイクルの最大数（デフォルト：1）
• --max_step_num：調査計画に含めるステップの最大数（デフォルト：3）
• --debug：詳細なデバッグログを有効にします

FAQ

詳細については、FAQ.md を参照してください。

ライセンス

このプロジェクトはオープンソースで、MIT License の下で公開されています。

謝辞

DeerFlow は、オープンソースコミュニティの素晴らしい成果の上に成り立っています。DeerFlow を実現してくださった、すべてのプロジェクトと貢献者の皆さまに深く感謝します。私たちはまさに、先人たちの築いた基盤の上に立っています。

貴重な貢献をいただいた次のプロジェクトに、心より感謝申し上げます。

• LangChain：優れたフレームワークによって LLM とのやり取りやチェーンを支え、シームレスな統合と機能を実現しています。
• LangGraph：マルチエージェントオーケストレーションへの革新的なアプローチは、DeerFlow の高度なワークフローを実現するうえで大きな役割を果たしています。

これらのプロジェクトは、オープンソースでの協業がもたらす変革の力を示しています。私たちは、その基盤の上に構築できることを誇りに思います。

主な貢献者

DeerFlow の中心的な作者の皆さまに、心から感謝します。皆さまのビジョン、情熱、献身によって、このプロジェクトが実現しました。

• Daniel Walnut
• Henry Li

揺るぎない取り組みと専門知識は、DeerFlow の成功を支える原動力となっています。この歩みを率いてくださることを光栄に思います。

スターの履歴