本地调试步骤

1. 环境准备

• 安装Python 3.9+（小于3.12）
• 安装Poetry 1.6.1：pip install poetry==1.6.1
• 获取火山方舟API KEY：访问 火山方舟控制台
• 开通DeepSeek-R1模型：在 开通管理页 完成

2. 选择搜索引擎

选择一：使用火山方舟零代码联网应用

• 创建零代码联网应用，获取bot id

• 推荐配置：

  • 推理接入点：Doubao-pro-32k / Doubao-pro-1.5-32k
  • 联网内容插件：开启
  • 智能改写：关闭
  • 调用方式：强制开启
  • 参考资料回复：自定义回复 选择二：使用Tavily搜索引擎

• 获取 Tavily API KEY

3. 下载代码

shell
git clone https://github.com/volcengine/ai-app-lab.git
cd demohouse/deep_research

4. 设置环境变量

如果使用火山方舟零代码联网应用：

shell
export ARK_API_KEY=xxx-xxxx-xxx-xxx
export REASONING_MODEL=deepseek-r1-250120
export SEARCH_ENGINE=volc_bot
export SEARCH_BOT_ID=bot-xxxxxx-xx

如果使用Tavily搜索引擎：

shell
export ARK_API_KEY=xxx-xxxx-xxx-xxx
export REASONING_MODEL=deepseek-r1-250120
export SEARCH_ENGINE=tavily
export TAVILY_API_KEY=xxx-xxx-xxx-xxx

5. 安装依赖并启动服务

shell
python -m venv .venv
source .venv/bin/activate
poetry install
poetry run python -m server

服务将在localhost:8888提供符合OpenAI规范的Chat API服务。

6. 启动WebUI

在新的终端窗口中：

shell
# 设置连接本地服务器
export API_ADDR=http://localhost:8888/api/v3/bots

python -m venv .venv
source .venv/bin/activate
poetry install

# 启动WebUI
poetry run python -m webui

sh
./start.sh

7. 访问应用

使用浏览器访问http://localhost:7860/ 即可使用Deep Research应用。

通过以上步骤，你可以在本地成功部署和调试Deep Research项目，体验其强大的深度推理和联网搜索能力。

8. docker打包部署

如何使用：

1. 构建镜像（无需敏感配置）

sh
# 使用构建模式构建镜像（不检查API密钥）
./deploy-all.sh --build

# 或者只构建不启动
./deploy-all.sh --build-only

2. 发布镜像 构建后可以安全地将镜像发布到 Docker Hub 或其他镜像仓库，不会包含您的敏感信息。
3. 部署使用（需要配置）

sh
# 正常部署模式，会严格检查配置
./deploy-all.sh

4. 单独使用配置检查工具

sh
# 严格检查模式（用于部署前）
./check-config.sh

# 宽松构建模式（用于构建时）
./check-config.sh --build-mode

5. 仓库镜像推送

sh
# 登录docker hub
docker login -u golovin0623
# 输入密码或访问令牌（建议用访问令牌）

# 确认本地镜像
docker images | grep golovin/deep-research
## 输出应包含：
## golovin0623/deep-research   amd64    abcdef123456   1 hour ago   1.2GB
## golovin0623/deep-research   latest   abcdef123456   1 hour ago   1.2GB


# 推送所有标签
docker push golovin0623/deep-research --all-tags

# 为 AMD64 架构打标签
docker tag golovin0623/deep-research:amd64 golovin0623/deep-research:amd64

# 为 latest 标签打标签
docker tag golovin0623/deep-research:latest golovin0623/deep-research:latest


# 或单独推送指定标签
docker push golovin0623/deep-research:amd64
docker push golovin0623/deep-research:latest

9. 镜像使用

1. 系统概述

深度研究助手由两个主要组件组成：

• Server服务：处理API请求，连接搜索引擎
• WebUI服务：提供用户界面，调用Server服务的API

这两个组件封装在同一个Docker镜像中，但需要作为两个独立的容器运行。

2. 配置准备

2.1 创建配置文件

bash
# 创建配置文件
cat > config.json << EOF
{
    "ARK_API_KEY": "您的API密钥",
    "REASONING_MODEL": "deepseek-r1-250120",
    "SEARCH_ENGINE": "volc_bot",
    "SEARCH_BOT_ID": "您的搜索Bot ID",
    "API_BOT_ID": "您的API Bot ID"
}
EOF

2.2 关键配置项说明

3. 部署方法

3.1 使用Docker Compose（推荐）

1. 创建docker-compose.yml文件：

bash
services:
  server:
    image: golovin/deep-research:latest
    command: python -m server
    volumes:
      - ./config.json:/app/config.json
    ports:
      - "8889:8888"
    networks:
      - deep-research-network
    restart: unless-stopped
    environment:
      - ARK_API_KEY=您的API密钥
      - SEARCH_BOT_ID=您的搜索Bot ID
      - REASONING_MODEL=deepseek-r1-250120
      - SEARCH_ENGINE=volc_bot

  webui:
    image: golovin/deep-research:latest
    command: python -m webui
    volumes:
      - ./config.json:/app/config.json
    ports:
      - "7860:7860"
    depends_on:
      - server
    networks:
      - deep-research-network
    restart: unless-stopped
    environment:
      - API_ADDR=http://server:8888/api/v3/bots
      - ARK_API_KEY=您的API密钥
      - API_BOT_ID=您的API Bot ID

networks:
  deep-research-network:
    driver: bridge

2. 启动服务：

bash
docker-compose up -d

3.2 手动启动方法

如果不使用Docker Compose，可以手动创建网络并启动容器：

bash
# 创建网络
docker network create deep-research-network

# 启动Server容器
docker run -d --name deep_research_server \
  --network deep-research-network \
  -p 8889:8888 \
  -v $(pwd)/config.json:/app/config.json \
  -e ARK_API_KEY="您的API密钥" \
  -e SEARCH_BOT_ID="您的搜索Bot ID" \
  -e REASONING_MODEL="deepseek-r1-250120" \
  -e SEARCH_ENGINE="volc_bot" \
  golovin/deep-research:latest \
  python -m server

# 启动WebUI容器
docker run -d --name deep_research_webui \
  --network deep-research-network \
  -p 7860:7860 \
  -v $(pwd)/config.json:/app/config.json \
  -e ARK_API_KEY="您的API密钥" \
  -e API_BOT_ID="您的API Bot ID" \
  -e API_ADDR="http://deep_research_server:8888/api/v3/bots" \
  golovin/deep-research:latest \
  python -m webui

4. 配置方法说明

4.1 配置优先级

1. 环境变量（优先级最高）
2. config.json配置文件
3. 应用默认值（优先级最低）

4.2 环境变量与配置文件的选择

• 仅使用环境变量：适合CI/CD环境或不方便挂载文件的情况
• 仅使用配置文件：适合本地开发，但API_ADDR仍需要环境变量设置
• 混合使用：最灵活的方式，敏感信息用环境变量，其他用配置文件

4.3 关于API_ADDR的特殊说明

无论使用何种配置方式，都建议将API_ADDR设置为环境变量：

• 在Docker Compose中：API_ADDR=http://server:8888/api/v3/bots
• 在手动方式中：API_ADDR=http://容器名:8888/api/v3/bots

5. 验证和故障排除

5.1 验证服务是否正常运行

bash
# 检查容器状态
docker ps

# 查看WebUI日志
docker logs deep_research_webui

# 查看Server日志
docker logs deep_research_server

5.2 常见问题和解决方法

5.3 测试API连接

bash
# 进入WebUI容器测试与Server的连接
docker exec -it deep_research_webui curl http://server:8888/v1/ping

# 或者在手动部署的情况下
docker exec -it deep_research_webui curl http://deep_research_server:8888/v1/ping

6. 最佳实践

1. 使用Docker Compose：更简单、更易于管理
2. 配置文件与环境变量结合：敏感信息使用环境变量
3. 挂载配置文件：便于修改配置而不需要重建容器
4. 检查网络连接：确保两个服务可以互相通信
5. 资源配置：对于生产环境，考虑添加内存限制
6. 持久化日志：考虑配置日志卷以便排查问题

7. 访问服务

成功部署后，可通过以下地址访问服务：

• Web界面：http://localhost:7860
• API服务：http://localhost:8889