第 2 章：环境搭建与依赖管理

1. 问题背景与设计动机

Deep Research 是一个涉及 Python 后端、Vue 3 前端、向量数据库（Milvus）、关系数据库（PostgreSQL）和缓存（Redis）的多组件系统。搭建开发环境时需要解决以下核心问题：

多运行时版本管理：Python 3.10+（TypedDict、| 语法）和 Node.js 18+（ESM、Vite 7）缺一不可
外部依赖服务：Milvus 2.6+ 需要 Docker 环境，PostgreSQL 14+ 和 Redis 7+ 需要正确配置
配置优先级：环境变量 > config.json > 代码默认值，需要理解 AppConfig 的三层解析机制
API 密钥安全：DASHSCOPE_API_KEY 和 BOCHA_API_KEY 的管理方式

2. 环境要求总览

2.1 版本要求对照表

组件	最低版本	推荐版本	用途	检查命令
Python	3.10	3.12	后端运行时	`python --version`
Node.js	18.x	22.x	前端构建	`node --version`
PostgreSQL	14	16	结构化记忆存储	`psql --version`
Redis	7.0	7.4	短期记忆 + 缓存	`redis-server --version`
Milvus	2.6	2.6	向量检索引擎	Docker 镜像
pip	22.0+	最新	Python 包管理	`pip --version`
npm	9.0+	最新	前端包管理	`npm --version`

2.2 Python 3.10+ 的必要性

项目代码中大量使用了 Python 3.10 引入的类型注解语法：

python

# 源码: app/mult_agents/config.py:61
@staticmethod
def _resolve_int(data: dict, field: str, env_key: str, default: int) -> int:
    ...

# 源码: app/backend/service/workflow_service.py:42
def _build_runtime_config(
    self,
    user_id: str,
    thread_id: str,
    tenant_id: str,
    max_iterations: int | None,     # Python 3.10+ 语法
    enable_memory: bool | None,     # Python 3.10+ 语法
) -> AppConfig:

int | None 语法在 Python 3.9 及以下会抛出 TypeError，因此必须使用 3.10+。

3. Python 环境搭建

3.1 安装 Python

bash

# Windows（推荐使用 pyenv-win 或官方安装器）
# https://www.python.org/downloads/
py install 3.12

# macOS
brew install python@3.12

# Ubuntu/Debian
sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt install python3.12 python3.12-venv python3.12-dev

3.2 创建虚拟环境

bash

cd deep_research
python -m venv .venv

# Windows PowerShell
.venv\Scripts\Activate.ps1

# macOS/Linux
source .venv/bin/activate

3.3 安装 Python 依赖

项目使用 pyproject.toml 定义依赖（deep_research/pyproject.toml）：

toml

[project]
name = "mult_agents"
version = "0.1.0"
requires-python = ">=3.10"
dependencies = [
  "langgraph",                    # 工作流编排引擎
  "langgraph-checkpoint-redis",   # Redis 检查点后端
  "langgraph-checkpoint-postgres",# PostgreSQL 检查点后端
  "fastapi",                      # Web 框架
  "uvicorn[standard]",            # ASGI 服务器
  "langchain",                    # LangChain 核心
  "langchain-community",          # 社区集成
  "langchain-core",               # 核心抽象
  "langchain-milvus",             # Milvus 向量存储
  "dashscope",                    # 阿里通义 API
  "pymilvus",                     # Milvus Python SDK
  "psycopg[binary,pool]",         # PostgreSQL 驱动（v3）
  "redis",                        # Redis 客户端
  "python-dotenv",                # .env 文件加载
  "pydantic-settings",            # 配置管理
  "typing-extensions"             # 类型扩展
]

执行安装：

bash

# 开发模式安装（可编辑）
pip install -e .

# 或直接安装依赖
pip install -r requirements.txt  # 如果有
# 或手动
pip install langgraph langchain fastapi uvicorn dashscope pymilvus "psycopg[binary,pool]" redis python-dotenv pydantic-settings

3.4 依赖关系图

4. Node.js 前端环境

4.1 安装 Node.js

bash

# 推荐使用 nvm 管理版本
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash
nvm install 22
nvm use 22

4.2 安装前端依赖

bash

cd deep_research/front/agent_front
npm install

前端依赖（package.json）：

json

{
  "dependencies": {
    "vue": "^3.5.30"
  },
  "devDependencies": {
    "@vitejs/plugin-vue": "^6.0.4",
    "typescript": "~5.9.3",
    "vite": "^7.3.1",
    "vite-plugin-vue-devtools": "^8.0.7",
    "vue-tsc": "^3.2.5"
  },
  "engines": {
    "node": "^20.19.0 || >=22.12.0"
  }
}

关键点：engines 字段要求 Node.js 20.19.0+ 或 22.12.0+，这是 Vite 7 的要求。

5. 外部服务搭建

5.1 Docker Compose 一键部署

创建 docker-compose.yml：

yaml

version: "3.9"

services:
  # ====== PostgreSQL 16 ======
  postgres:
    image: postgres:16-alpine
    container_name: dr-postgres
    environment:
      POSTGRES_USER: deepresearch
      POSTGRES_PASSWORD: dr_password_2024
      POSTGRES_DB: deepresearch
    ports:
      - "5432:5432"
    volumes:
      - pg_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U deepresearch"]
      interval: 5s
      timeout: 5s
      retries: 5

  # ====== Redis 7 ======
  redis:
    image: redis:7-alpine
    container_name: dr-redis
    ports:
      - "6379:6379"
    volumes:
      - redis_data:/data
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      timeout: 5s
      retries: 5

  # ====== Milvus 2.6 依赖 ======
  etcd:
    image: quay.io/coreos/etcd:v3.5.18
    container_name: dr-etcd
    environment:
      ETCD_AUTO_COMPACTION_MODE: revision
      ETCD_AUTO_COMPACTION_RETENTION: "1000"
      ETCD_QUOTA_BACKEND_BYTES: "4294967296"
      ETCD_SNAPSHOT_COUNT: "50000"
    volumes:
      - etcd_data:/etcd
    command: >
      etcd
      --advertise-client-urls=http://127.0.0.1:2379
      --listen-client-urls=http://0.0.0.0:2379
      --data-dir=/etcd

  minio:
    image: minio/minio:RELEASE.2023-03-20T20-16-18Z
    container_name: dr-minio
    environment:
      MINIO_ACCESS_KEY: minioadmin
      MINIO_SECRET_KEY: minioadmin
    ports:
      - "9001:9001"
      - "9000:9000"
    volumes:
      - minio_data:/minio_data
    command: minio server /minio_data --console-address ":9001"

  # ====== Milvus 2.6 ======
  milvus:
    image: milvusdb/milvus:v2.6.0
    container_name: dr-milvus
    environment:
      ETCD_ENDPOINTS: etcd:2379
      MINIO_ADDRESS: minio:9000
    ports:
      - "19530:19530"
      - "9091:9091"
    volumes:
      - milvus_data:/var/lib/milvus
    command: ["milvus", "run", "standalone"]
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:9091/healthz"]
      interval: 30s
      timeout: 20s
      retries: 3
    depends_on:
      - etcd
      - minio

volumes:
  pg_data:
  redis_data:
  etcd_data:
  minio_data:
  milvus_data:

启动所有服务：

bash

docker compose up -d
# 验证服务状态
docker compose ps

5.2 服务连接验证

bash

# 验证 PostgreSQL
psql -h 127.0.0.1 -U deepresearch -d deepresearch -c "SELECT 1;"

# 验证 Redis
redis-cli ping

# 验证 Milvus
curl http://127.0.0.1:9091/healthz

6. 配置文件详解

6.1 .env 环境变量

复制示例文件并填写（deep_research/.env.example）：

bash

cp .env.example .env

关键配置项说明：

变量名	必填	说明	示例值
`DASHSCOPE_API_KEY`	是	阿里通义 API 密钥	`sk-xxx`
`BOCHA_API_KEY`	否	博查搜索 API（网页检索）	`sk-xxx`
`MODEL`	否	LLM 模型名	`qwen-plus`
`POSTGRES_DSN`	否	PostgreSQL 连接串	`postgresql://user:pass@127.0.0.1:5432/deepresearch`
`REDIS_URL`	否	Redis 连接串	`redis://127.0.0.1:6379`
`MILVUS_HOST`	否	Milvus 地址	`127.0.0.1`
`MILVUS_PORT`	否	Milvus 端口	`19530`

6.2 config.json 运行时配置

json

{
  "api_key": "",
  "model": "qwen-turbo",
  "tenant_id": "default_tenant",
  "user_id": "default_user",
  "thread_id": "default",
  "max_iterations": 3,
  "enable_memory": true,
  "short_term_ttl_seconds": 604800,
  "short_term_max_messages": 30,
  "short_term_summary_threshold": 20,
  "short_term_backend": "postgres",
  "long_term_backend": "postgres",
  "long_term_scope": "user",
  "save_conversation_task": false,
  "checkpointer_backend": "postgres",
  "enable_milvus": true,
  "memory_top_k": 6,
  "redis_url": "",
  "postgres_dsn": "",
  "milvus_host": "",
  "milvus_port": 19530,
  "milvus_collection": "mult_agent_memory"
}

6.3 配置解析优先级

源码实现（app/mult_agents/config.py:51-58）：

python

@staticmethod
def _resolve_str(data: dict, field: str, env_key: str, default: str = "") -> str:
    # 第一优先级：环境变量
    env_value = os.getenv(env_key)
    if env_value is not None and str(env_value).strip() != "":
        return str(env_value).strip()
    # 第二优先级：config.json 文件值
    file_value = data.get(field)
    if file_value is not None and str(file_value).strip() != "":
        return str(file_value).strip()
    # 第三优先级：代码默认值
    return default

关键设计：DASHSCOPE_API_KEY 是唯一必填项，缺少时会抛出 ValueError（config.py:79-82）。

7. 启动验证

7.1 CLI 模式启动

bash

cd deep_research
python main.py

main.py 的启动流程（main.py:5-16）：

python

def _bootstrap() -> None:
    root = Path(__file__).resolve().parent
    src = root / "app"
    if str(src) not in sys.path:
        sys.path.insert(0, str(src))       # 将 app/ 加入 sys.path
    from dotenv import load_dotenv
    env_path = root / ".env"
    if env_path.exists():
        load_dotenv(env_path)              # 加载 .env

7.2 Web 服务启动

bash

cd deep_research/app
python app_main.py

默认监听 127.0.0.1:8000，开发模式自动启用热重载。

7.3 前端启动

bash

cd deep_research/front/agent_front
npm run dev

Vite 开发服务器启动在 http://localhost:5173，通过代理转发 /api 请求到后端。

8. 最佳实践

8.1 开发环境检查清单

bash

# 1. 检查 Python 版本
python --version  # >= 3.10

# 2. 检查 Node 版本
node --version  # >= 20.19.0

# 3. 检查 Docker 服务
docker compose ps  # postgres, redis, milvus 全部 healthy

# 4. 检查 API 密钥
python -c "from dotenv import load_dotenv; import os; load_dotenv(); print('KEY' if os.getenv('DASHSCOPE_API_KEY') else 'MISSING')"

# 5. 验证 Milvus 连接
curl http://127.0.0.1:9091/healthz

8.2 常见问题排查

问题	原因	解决方案
`ModuleNotFoundError: langgraph`	依赖未安装	`pip install -e .`
`TypeError: unsupported operand type(s) for	`	Python < 3.10
`Connection refused: Milvus`	Milvus 未启动	`docker compose up -d milvus`
`DASHSCOPE_API_KEY not set`	缺少 API 密钥	在 `.env` 中填写
`ECONNREFUSED 127.0.0.1:8000`	后端未启动	`python app_main.py`
`Redis 初始化失败`	Redis 未启动或密码错误	检查 `REDIS_URL` 配置

8.3 生产环境建议

使用 config.json 集中管理配置，通过环境变量覆盖敏感值（API Key、数据库密码）
PostgreSQL 必须部署：短期记忆、长期记忆、Checkpointer 均依赖它
Milvus 建议部署：启用向量语义检索，否则只能使用关键词匹配
Redis 可选：作为短期记忆的高性能后端，生产环境推荐启用

第 2 章：环境搭建与依赖管理 ​

1. 问题背景与设计动机 ​

2. 环境要求总览 ​

2.1 版本要求对照表 ​

2.2 Python 3.10+ 的必要性 ​

3. Python 环境搭建 ​

3.1 安装 Python ​

3.2 创建虚拟环境 ​

3.3 安装 Python 依赖 ​

3.4 依赖关系图 ​

4. Node.js 前端环境 ​

4.1 安装 Node.js ​

4.2 安装前端依赖 ​

5. 外部服务搭建 ​

5.1 Docker Compose 一键部署 ​

5.2 服务连接验证 ​

6. 配置文件详解 ​

6.1 .env 环境变量 ​

6.2 config.json 运行时配置 ​

6.3 配置解析优先级 ​

7. 启动验证 ​

7.1 CLI 模式启动 ​

7.2 Web 服务启动 ​

7.3 前端启动 ​

8. 最佳实践 ​

8.1 开发环境检查清单 ​

8.2 常见问题排查 ​

8.3 生产环境建议 ​

第 2 章：环境搭建与依赖管理

1. 问题背景与设计动机

2. 环境要求总览

2.1 版本要求对照表

2.2 Python 3.10+ 的必要性

3. Python 环境搭建

3.1 安装 Python

3.2 创建虚拟环境

3.3 安装 Python 依赖

3.4 依赖关系图

4. Node.js 前端环境

4.1 安装 Node.js

4.2 安装前端依赖

5. 外部服务搭建

5.1 Docker Compose 一键部署

5.2 服务连接验证

6. 配置文件详解

6.1 .env 环境变量

6.2 config.json 运行时配置

6.3 配置解析优先级

7. 启动验证

7.1 CLI 模式启动

7.2 Web 服务启动

7.3 前端启动

8. 最佳实践

8.1 开发环境检查清单

8.2 常见问题排查

8.3 生产环境建议