From 722a9c4753c229c11763dc81a722d6f174a638d1 Mon Sep 17 00:00:00 2001 From: 13ernkastel Date: Wed, 8 Apr 2026 09:45:31 +0800 Subject: [PATCH] docs: clarify deployment sizing guidance (#1963) --- CONTRIBUTING.md | 12 ++++++++++++ README.md | 15 +++++++++++++++ README_zh.md | 15 +++++++++++++++ 3 files changed, 42 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c64a60d2c..d6f8d4a13 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -77,6 +77,18 @@ export UV_INDEX_URL=https://pypi.org/simple export NPM_REGISTRY=https://registry.npmjs.org ``` +#### Recommended host resources + +Use these as practical starting points for development and review environments: + +| Scenario | Starting point | Recommended | Notes | +|---------|-----------|------------|-------| +| `make dev` on one machine | 4 vCPU, 8 GB RAM | 8 vCPU, 16 GB RAM | Best when DeerFlow uses hosted model APIs. | +| `make docker-start` review environment | 4 vCPU, 8 GB RAM | 8 vCPU, 16 GB RAM | Docker image builds and sandbox containers need extra headroom. | +| Shared Linux test server | 8 vCPU, 16 GB RAM | 16 vCPU, 32 GB RAM | Prefer this for heavier multi-agent runs or multiple reviewers. | + +`2 vCPU / 4 GB` environments often fail to start reliably or become unresponsive under normal DeerFlow workloads. + #### Linux: Docker daemon permission denied If `make docker-init`, `make docker-start`, or `make docker-stop` fails on Linux with an error like below, your current user likely does not have permission to access the Docker daemon socket: diff --git a/README.md b/README.md index 0d84a0861..694f0f804 100644 --- a/README.md +++ b/README.md @@ -53,6 +53,7 @@ DeerFlow has newly integrated the intelligent search and crawling toolset indepe - [Quick Start](#quick-start) - [Configuration](#configuration) - [Running the Application](#running-the-application) + - [Deployment Sizing](#deployment-sizing) - [Option 1: Docker (Recommended)](#option-1-docker-recommended) - [Option 2: Local Development](#option-2-local-development) - [Advanced](#advanced) @@ -225,6 +226,20 @@ That prompt is intended for coding agents. It tells the agent to clone the repo ### Running the Application +#### Deployment Sizing + +Use the table below as a practical starting point when choosing how to run DeerFlow: + +| Deployment target | Starting point | Recommended | Notes | +|---------|-----------|------------|-------| +| Local evaluation / `make dev` | 4 vCPU, 8 GB RAM, 20 GB free SSD | 8 vCPU, 16 GB RAM | Good for one developer or one light session with hosted model APIs. `2 vCPU / 4 GB` is usually not enough. | +| Docker development / `make docker-start` | 4 vCPU, 8 GB RAM, 25 GB free SSD | 8 vCPU, 16 GB RAM | Image builds, bind mounts, and sandbox containers need more headroom than pure local dev. | +| Long-running server / `make up` | 8 vCPU, 16 GB RAM, 40 GB free SSD | 16 vCPU, 32 GB RAM | Preferred for shared use, multi-agent runs, report generation, or heavier sandbox workloads. | + +- These numbers cover DeerFlow itself. If you also host a local LLM, size that service separately. +- Linux plus Docker is the recommended deployment target for a persistent server. macOS and Windows are best treated as development or evaluation environments. +- If CPU or memory usage stays pinned, reduce concurrent runs first, then move to the next sizing tier. + #### Option 1: Docker (Recommended) **Development** (hot-reload, source mounts): diff --git a/README_zh.md b/README_zh.md index 9b832eb0d..f6043ff86 100644 --- a/README_zh.md +++ b/README_zh.md @@ -40,6 +40,7 @@ https://github.com/user-attachments/assets/a8bcadc4-e040-4cf2-8fda-dd768b999c18 - [快速开始](#快速开始) - [配置](#配置) - [运行应用](#运行应用) + - [部署建议与资源规划](#部署建议与资源规划) - [方式一：Docker（推荐）](#方式一docker推荐) - [方式二：本地开发](#方式二本地开发) - [进阶配置](#进阶配置) @@ -150,6 +151,20 @@ https://github.com/user-attachments/assets/a8bcadc4-e040-4cf2-8fda-dd768b999c18 ### 运行应用 +#### 部署建议与资源规划 + +可以先按下面的资源档位来选择 DeerFlow 的运行方式： + +| 部署场景 | 起步配置 | 推荐配置 | 说明 | +|---------|-----------|------------|-------| +| 本地体验 / `make dev` | 4 vCPU、8 GB 内存、20 GB SSD 可用空间 | 8 vCPU、16 GB 内存 | 适合单个开发者或单个轻量会话，且模型走外部 API。`2 核 / 4 GB` 通常跑不稳。 | +| Docker 开发 / `make docker-start` | 4 vCPU、8 GB 内存、25 GB SSD 可用空间 | 8 vCPU、16 GB 内存 | 镜像构建、源码挂载和 sandbox 容器都会比纯本地模式更吃资源。 | +| 长期运行服务 / `make up` | 8 vCPU、16 GB 内存、40 GB SSD 可用空间 | 16 vCPU、32 GB 内存 | 更适合共享环境、多 agent 任务、报告生成或更重的 sandbox 负载。 | + +- 上面的配置只覆盖 DeerFlow 本身；如果你还要本机部署本地大模型，请单独为模型服务预留资源。 +- 持续运行的服务更推荐使用 Linux + Docker。macOS 和 Windows 更适合作为开发机或体验环境。 +- 如果 CPU 或内存长期打满，先降低并发会话或重任务数量，再考虑升级到更高一档配置。 + #### 方式一：Docker（推荐） **开发模式**（支持热更新，挂载源码）：