# MetaGPT 软件公司

## 概览

[MetaGPT](https://github.com/geekan/MetaGPT) 是一个多代理人工智能框架，模拟一个 **软件公司** —— 配备产品经理、架构师、工程师和 QA 工程师代理 —— 共同协作将一句话的想法变成一个功能完整的软件项目。MetaGPT 在 GitHub 上拥有 45K+ 星，是推动 AI 驱动软件开发的最具创新性的方法之一。

与单一编码代理不同，MetaGPT 模仿真实的团队工作流程。当你给它像“用 Python 构建一个贪吃蛇游戏”这样的任务时，它会：

1. **产品经理** —— 撰写产品需求文档（PRD）
2. **架构师** —— 设计系统架构和技术栈
3. **项目经理** —— 拆解任务并进行分配
4. **工程师** —— 为各个组件编写实际可运行的代码
5. **QA 工程师** —— 编写单元测试并验证实现

结果是一个包含代码、文档和测试的完整项目目录——由系统自主生成。

**主要功能：**

* **完整的软件生命周期** —— 从需求到可运行代码，一条命令搞定
* **基于角色的代理** —— 具有明确职责的专业化代理
* **文档生成** —— 自动生成 PRD、系统设计、API 规范
* **多语言支持** —— 支持 Python、Node.js、Go 等
* **数据解释器** —— 自主进行数据分析和可视化的代理
* **增量开发** —— 向现有项目添加功能
* **人工交互模式** —— 在关键阶段暂停以供人工审查

**为什么为 MetaGPT 选择 Clore.ai？**

MetaGPT 本身基于 CPU，但 Clore.ai 提供了关键优势：

* **长时间运行任务** —— MetaGPT 生成可能需要 10–60 分钟；专用服务器可以处理这些任务而不会超时
* **本地 LLM 后端** —— 使用 Ollama 或 vLLM 可消除大型项目的按令牌 API 成本
* **成本控制** —— 以 $0.20–0.35/小时 的费用运行，大规模 MetaGPT 会话比调用 GPT-4o API 更便宜
* **隔离环境** —— 生成的代码在受控的服务器环境中运行
* **团队协作** —— 在开发团队之间共享一个 MetaGPT 服务器端点

***

## 要求

MetaGPT 协调 LLM 的 API 调用 —— 只有在运行本地 LLM 后端时才需要 GPU。

| 配置                                 | GPU     | 显存    | 内存    | 存储     | 预计价格            |
| ---------------------------------- | ------- | ----- | ----- | ------ | --------------- |
| **MetaGPT + OpenAI/Anthropic API** | 无       | —     | 4 GB  | 20 GB  | \~$0.03–0.08/小时 |
| **+ Ollama（Qwen2.5-Coder 7B）**     | 速度      | 24 GB | 16 GB | 40 GB  | \~$0.20/小时      |
| **+ Ollama（DeepSeek Coder 33B）**   | 512x512 | 24 GB | 32 GB | 60 GB  | \~$0.35/小时      |
| **+ vLLM（Qwen2.5-Coder 32B）**      | 512x512 | 24 GB | 32 GB | 80 GB  | \~$0.35/小时      |
| **+ vLLM（Llama 3.1 70B）**          | 4 小时会话  | 80 GB | 64 GB | 100 GB | \~$1.10/小时      |

> **建议：** MetaGPT 在连贯的多步骤推理上高度依赖模型质量。对于复杂项目，请使用 GPT-4o 或 Claude Sonnet 3.5 的 API，或在本地使用 Qwen2.5-Coder-32B / DeepSeek-Coder-V2。请参阅 [GPU 比较指南](https://docs.clore.ai/guides/guides_v2-zh/kuai-su-ru-men/gpu-comparison).

**Clore.ai 服务器上的软件要求：**

* Docker 引擎（所有 Clore.ai 镜像预装）
* NVIDIA 容器工具包（仅针对本地 LLM 选项）
* 20+ GB 可用磁盘空间（MetaGPT 镜像 + 生成的项目文件）
* 出站互联网访问（用于拉取 Docker 镜像和访问 LLM API）

***

## 快速开始

### 第 1 步：连接到你的 Clore.ai 服务器

在上预订服务器 [Clore.ai 市场](https://clore.ai):

* 仅 API 模式：任意 ≥4 GB 内存的服务器
* 本地 LLM 模式：≥24 GB 显存的 GPU

```bash
ssh root@<server-ip> -p <ssh-port>
```

### 第 2 步：拉取 MetaGPT Docker 镜像

```bash
docker pull metagpt/metagpt:latest
```

> MetaGPT 镜像约为 \~3 GB。首次拉取可能需要 2–5 分钟。

### 第 3 步：设置配置

MetaGPT 需要一个包含您 LLM API 凭证的 YAML 配置文件：

```bash
# 创建目录
mkdir -p /opt/metagpt/{config,workspace}

# 从镜像中提取默认配置模板
docker run --rm metagpt/metagpt:latest \
  cat /app/metagpt/config/config2.yaml \
  > /opt/metagpt/config/config2.yaml

# 查看配置
cat /opt/metagpt/config/config2.yaml
```

### 第 4 步：配置您的 LLM 提供商

编辑配置文件：

```bash
nano /opt/metagpt/config/config2.yaml
```

**对于 OpenAI（GPT-4o）：**

```yaml
llm:
  api_type: "openai"
  model: "gpt-4o"
  base_url: "https://api.openai.com/v1"
  api_key: "sk-your-openai-key-here"

repair_llm_output: true
max_auto_summarize_code: 1
```

**对于 Anthropic（Claude）：**

```yaml
llm:
  api_type: "anthropic"
  model: "claude-3-5-sonnet-20241022"
  api_key: "sk-ant-your-key-here"

repair_llm_output: true
```

**对于本地 Ollama（参见 GPU 部分）：**

```yaml
llm:
  api_type: "ollama"
  model: "ollama/qwen2.5-coder:32b"
  base_url: "http://host.docker.internal:11434"
  api_key: "ollama"

repair_llm_output: true
```

### 第 5 步：运行您的第一个 MetaGPT 项目

```bash
# 生成一个贪吃蛇游戏（经典演示）
docker run --rm --privileged \
  -v /opt/metagpt/config/config2.yaml:/app/metagpt/config/config2.yaml \
  -v /opt/metagpt/workspace:/app/metagpt/workspace \
  metagpt/metagpt:latest \
  metagpt "Create a snake game with Python"
```

观察代理的工作：您将依次看到 PRD 生成、系统设计、代码编写和测试。根据您使用的 LLM，预计需时 5–15 分钟。

### 第 6 步：查看输出

```bash
ls -la /opt/metagpt/workspace/
# 您将看到以项目命名的目录

find /opt/metagpt/workspace -type f | head -30
# 列出所有生成的文件：.py、.md、requirements.txt、tests/ 等
```

***

## 配置

### 完整配置参考

```yaml
# /opt/metagpt/config/config2.yaml

# 主要 LLM 配置
llm:
  api_type: "openai"          # openai | anthropic | ollama | azure | gemini
  model: "gpt-4o"
  base_url: "https://api.openai.com/v1"
  api_key: "your-api-key"
  temperature: 0.0            # 值越低，代码生成越确定性
  max_token: 4096

# MetaGPT 行为设置
repair_llm_output: true       # 自动修复格式错误的 LLM 响应
max_auto_summarize_code: 1    # 代码摘要迭代次数（0 = 禁用）
max_project_auto_run: 5       # 最大自动执行周期数

# 项目设置
project_name: ""              # 可选：覆盖生成的项目名称
inc: false                    # 增量模式（添加到现有项目）
reqa_file: ""                 # 在特定文件上运行 QA

# 成本跟踪
max_budget: 10.0              # 最大支出（仅限 API 调用）
```

### 以交互模式运行

如需更多控制，可在 MetaGPT 中启用人工审查检查点：

```bash
docker run --rm -it --privileged \
  -v /opt/metagpt/config/config2.yaml:/app/metagpt/config/config2.yaml \
  -v /opt/metagpt/workspace:/app/metagpt/workspace \
  metagpt/metagpt:latest \
  metagpt "Build a REST API for a todo list app with FastAPI" \
  --human-review
```

使用 `--human-review`，MetaGPT 会在 PRD 和系统设计阶段之后暂停，允许您在工程开始前提供反馈。

### 增量开发（向现有项目添加功能）

```bash
# 在现有项目上继续开发
docker run --rm -it --privileged \
  -v /opt/metagpt/config/config2.yaml:/app/metagpt/config/config2.yaml \
  -v /opt/metagpt/workspace:/app/metagpt/workspace \
  -v /opt/metagpt/workspace/my-project:/app/metagpt/workspace/my-project \
  metagpt/metagpt:latest \
  metagpt "Add user authentication to the existing todo API" \
  --project-path /app/metagpt/workspace/my-project \
  --inc
```

### 运行数据解释器

MetaGPT 包含一个用于数据分析的专用数据解释器代理：

```bash
# 交互式 Python 数据分析
docker run --rm -it --privileged \
  -v /opt/metagpt/config/config2.yaml:/app/metagpt/config/config2.yaml \
  -v /opt/metagpt/workspace:/app/metagpt/workspace \
  -v /path/to/your/data:/data:ro \
  metagpt/metagpt:latest \
  python -m metagpt.roles.di.data_interpreter \
    "Analyze /data/sales.csv and find top-performing products, create visualization"
```

### 用于持久化部署的 Docker Compose

```yaml
# /opt/metagpt/docker-compose.yml
version: "3.9"

services:
  metagpt:
    image: metagpt/metagpt:latest
    privileged: true
    volumes:
      - /opt/metagpt/config/config2.yaml:/app/metagpt/config/config2.yaml:ro
      - /opt/metagpt/workspace:/app/metagpt/workspace
      - /opt/metagpt/logs:/app/metagpt/logs
    environment:
      - PYTHONUNBUFFERED=1
    stdin_open: true
    tty: true
    # 注意：MetaGPT 是基于任务的，而不是一个常驻服务。
    # 使用 'docker compose run metagpt metagpt "your task"' 来执行任务
    entrypoint: ["bash"]
```

```bash
# 通过 docker-compose 运行任务
docker compose -f /opt/metagpt/docker-compose.yml \
  run --rm metagpt \
  metagpt "Create a Flask web app with user registration"
```

***

## GPU 加速（本地 LLM 集成）

### MetaGPT + Ollama

使用本地编码模型可完全免费运行 MetaGPT（无需 API 成本）：

```bash
# 第 1 步：使用 GPU 启动 Ollama
docker run -d \
  --name ollama \
  --gpus all \
  --restart unless-stopped \
  -p 11434:11434 \
  -v ollama-models:/root/.ollama \
  ollama/ollama:latest

# 第 2 步：拉取高质量的编码模型
# 适用于 RTX 3090/4090（24 GB 显存）：
docker exec ollama ollama pull qwen2.5-coder:32b      # 最适合代码
docker exec ollama ollama pull deepseek-coder-v2:16b  # 替代选项
# 适用于较小 GPU（8–16 GB 显存）：
docker exec ollama ollama pull qwen2.5-coder:7b
docker exec ollama ollama pull codellama:13b

# 第 3 步：为 Ollama 配置 MetaGPT
cat > /opt/metagpt/config/config2.yaml << 'EOF'
llm:
  api_type: "ollama"
  model: "ollama/qwen2.5-coder:32b"
  base_url: "http://host.docker.internal:11434"
  api_key: "ollama"
  temperature: 0.0
  max_token: 4096

repair_llm_output: true
max_auto_summarize_code: 0
EOF

# 第 4 步：以 host 网络运行 MetaGPT 以便访问 Ollama
docker run --rm --privileged \
  --add-host host.docker.internal:host-gateway \
  -v /opt/metagpt/config/config2.yaml:/app/metagpt/config/config2.yaml \
  -v /opt/metagpt/workspace:/app/metagpt/workspace \
  metagpt/metagpt:latest \
  metagpt "Create a Python CLI tool for file organization"
```

> 参见完整的 [Ollama 指南](https://docs.clore.ai/guides/guides_v2-zh/yu-yan-mo-xing/ollama) 以获取模型设置和 GPU 优化说明。

### MetaGPT + vLLM（高吞吐）

针对大型复杂项目以获得最大令牌吞吐量：

```bash
# 第 1 步：使用编码模型启动 vLLM
docker run -d \
  --name vllm \
  --gpus all \
  --restart unless-stopped \
  -p 8000:8000 \
  --ipc=host \
  vllm/vllm-openai:latest \
  --model Qwen/Qwen2.5-Coder-32B-Instruct \
  --max-model-len 32768 \
  --gpu-memory-utilization 0.90

# 等待模型加载
until curl -s http://localhost:8000/health | grep -q ok; do
  echo "Waiting for vLLM..."; sleep 10
done

# 第 2 步：为 vLLM 配置 MetaGPT
cat > /opt/metagpt/config/config2.yaml << 'EOF'
llm:
  api_type: "openai"
  model: "Qwen/Qwen2.5-Coder-32B-Instruct"
  base_url: "http://host.docker.internal:8000/v1"
  api_key: "none"
  temperature: 0.0
  max_token: 8192

repair_llm_output: true
EOF

# 第 3 步：运行 MetaGPT
docker run --rm --privileged \
  --add-host host.docker.internal:host-gateway \
  -v /opt/metagpt/config/config2.yaml:/app/metagpt/config/config2.yaml \
  -v /opt/metagpt/workspace:/app/metagpt/workspace \
  metagpt/metagpt:latest \
  metagpt "Build a complete e-commerce backend with FastAPI and PostgreSQL"
```

> 参见 [vLLM 指南](https://docs.clore.ai/guides/guides_v2-zh/yu-yan-mo-xing/vllm) 有关量化选项和多 GPU 设置的说明。

### 按任务推荐的模型

| 任务类型  | A100                           | 最小显存  | 注意事项         |
| ----- | ------------------------------ | ----- | ------------ |
| 简单脚本  | `qwen2.5-coder:7b`             | 8 GB  | 快速，适合 CLI 工具 |
| 中型项目  | `qwen2.5-coder:14b`            | 12 GB | 良好平衡         |
| 复杂系统  | `qwen2.5-coder:32b`            | 24 GB | 最佳本地选项       |
| 大型代码库 | `gpt-4o` / `claude-3-5-sonnet` | API   | 在复杂 PRD 上最可靠 |

> **提示：** 本地模型在代码生成方面表现良好，但有时在复杂的架构推理上会遇到困难。对于生产级的 PRD 和系统设计，建议在规划阶段使用 GPT-4o 或 Claude，而使用本地模型来生成代码。

***

## 提示与最佳实践

### 1. 编写有效的任务提示

MetaGPT 的性能在很大程度上取决于您初始提示的质量：

```
✅ 良好的提示：
"使用 FastAPI 创建一个 Python REST API 来管理图书馆目录。
功能：添加/搜索/删除书籍，使用 JWT 的用户认证， 
SQLite 数据库，OpenAPI 文档。目标：具备测试的生产就绪状态。"

"用 Python 构建一个 CLI 数据管道工具，读取 CSV 文件，
执行统计分析，并使用 matplotlib 输出图表。"

❌ 含糊的提示：
"制作一个网页应用"
"用 Python 做点什么"
```

### 2. 在运行前估算 API 成本

```bash
# MetaGPT 每个项目会处理大量令牌：
# - 简单脚本：~50K 令牌（使用 GPT-4o 约 $0.25）
# - 中型 Web 应用：~200K 令牌（使用 GPT-4o 约 $1.00）
# - 复杂系统：~500K+ 令牌（使用 GPT-4o 约 $2.50+）

# 在配置中设置预算限制：
# max_budget: 2.0  # 花费 $2 后停止
```

### 3. 首先审查生成的 PRD

使用 `--human-review` 对于重要项目尤其如此。PRD 阶段是锁定需求的环节——在此处发现问题相比在代码生成后修改可以节省大量令牌成本。

### 4. 测试生成的代码

MetaGPT 会生成单元测试，但请务必验证：

```bash
# 进入生成的项目
cd /opt/metagpt/workspace/<your-project>

# 安装依赖
pip install -r requirements.txt

# 运行生成的测试
pytest tests/ -v

# 尝试运行主应用
python main.py
```

### 5. 使用版本控制

```bash
# 在工作区初始化 git
cd /opt/metagpt/workspace
git init
git add .
git commit -m "Initial MetaGPT generation"

# 每次迭代后
git add .
git commit -m "MetaGPT: Added authentication feature"
```

### 6. 批量运行多个项目

在 Clore.ai 上一夜之间运行多个项目以获得最大价值：

```bash
#!/bin/bash
# /opt/metagpt/batch-run.sh
PROJECTS=(
  "Create a URL shortener service with Python and Redis"
  "Build a Markdown to PDF converter CLI tool"
  "Create a REST API for a blog with comments and tags"
)

for project in "${PROJECTS[@]}"; do
  echo "Starting: $project"
  docker run --rm --privileged \
    -v /opt/metagpt/config/config2.yaml:/app/metagpt/config/config2.yaml \
    -v /opt/metagpt/workspace:/app/metagpt/workspace \
    metagpt/metagpt:latest \
    metagpt "$project"
  echo "Completed: $project"
done
```

***

## # 使用固定种子以获得一致结果

### 镜像拉取失败

```bash
# 如果触及 Docker Hub 速率限制
docker login  # 使用您的 Docker Hub 帐户登录
docker pull metagpt/metagpt:latest

# 检查可用磁盘空间
df -h
# MetaGPT 镜像约为 ~3 GB；工作区可能增长到数 GB
```

### 配置文件未找到

```bash
# 验证路径映射是否正确
docker run --rm \
  -v /opt/metagpt/config/config2.yaml:/app/metagpt/config/config2.yaml \
  metagpt/metagpt:latest \
  ls -la /app/metagpt/config/

# 还要验证您的 YAML 是否有效
python3 -c "import yaml; yaml.safe_load(open('/opt/metagpt/config/config2.yaml'))"
```

### LLM API 认证错误

```bash
# 单独测试您的 API 密钥
curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer sk-your-key"

# 对于 Anthropic：
curl https://api.anthropic.com/v1/models \
  -H "x-api-key: sk-ant-your-key" \
  -H "anthropic-version: 2023-06-01"

# 常见问题：
# - 密钥复制时带有额外空白字符
# - 密钥已过期或配额已用尽
# - 配置中的 api_type 错误（例如 "openai" 与 "anthropic"）
```

### 容器中 Ollama 连接被拒绝

```bash
# 验证 Ollama 是否正在运行
docker ps | grep ollama
curl http://localhost:11434/api/tags

# 从 MetaGPT 容器角度进行测试
docker run --rm \
  --add-host host.docker.internal:host-gateway \
  metagpt/metagpt:latest \
  curl http://host.docker.internal:11434/api/tags

# 如果仍然失败，请检查 Ollama 日志
docker logs ollama --tail 20
```

### 生成挂起或超时

```bash
# 检查 LLM 是否确实在响应
# 添加调试日志以查看哪个代理卡住
docker run --rm --privileged \
  -e PYTHONUNBUFFERED=1 \
  -v /opt/metagpt/config/config2.yaml:/app/metagpt/config/config2.yaml \
  -v /opt/metagpt/workspace:/app/metagpt/workspace \
  metagpt/metagpt:latest \
  metagpt "Simple task" 2>&1 | tee /opt/metagpt/logs/debug.log

# 常见原因：
# - 本地模型太慢（尝试更小的量化模型）
# - API 限流（添加延迟或切换等级）
# - 模型上下文窗口超限（减少 max_auto_summarize_code）
```

### 磁盘空间不足

```bash
# 生成的项目可能很大；清理旧项目
du -sh /opt/metagpt/workspace/*
rm -rf /opt/metagpt/workspace/old-project/

# 还要清理 Docker 构建缓存
docker system prune -f

# 检查总体使用情况
df -h /opt/metagpt/
```

### “修复 LLM 输出” 循环

```bash
# 如果 MetaGPT 因格式错误的 LLM 输出而不断重试：
# 1. 试用更强的模型（GPT-4o、Claude Sonnet）
# 2. 降低 temperature（设置为 0.0 以获得确定性）
# 3. 禁用修复（如果使用的是强大的模型）：
#    repair_llm_output: false
```

***

## 延伸阅读

* [MetaGPT GitHub 仓库](https://github.com/geekan/MetaGPT) —— 源代码、示例、路线图
* [MetaGPT 文档](https://docs.deepwisdom.ai/main/en/) —— 官方文档、配置参考、教程
* [MetaGPT Discord](https://discord.gg/DYn29wFk9z) —— 社区支持、用例、模型技巧
* [Docker Hub: metagpt/metagpt](https://hub.docker.com/r/metagpt/metagpt) —— 可用的镜像标签
* [Clore.ai 上的 Ollama](https://docs.clore.ai/guides/guides_v2-zh/yu-yan-mo-xing/ollama) —— 运行本地 LLM 以免费为 MetaGPT 提供算力
* [Clore.ai 上的 vLLM](https://docs.clore.ai/guides/guides_v2-zh/yu-yan-mo-xing/vllm) —— 用于大规模 MetaGPT 的高吞吐本地 LLM
* [GPU 比较指南](https://docs.clore.ai/guides/guides_v2-zh/kuai-su-ru-men/gpu-comparison) — 为你的工作负载选择合适的 Clore.ai GPU
* [SWE-bench 排行榜](https://www.swebench.com) —— 基准测试多代理编码框架
* [MetaGPT 论文](https://arxiv.org/abs/2308.00352) —— 原始研究：“MetaGPT: Meta Programming for a Multi-Agent Collaborative Framework”