快速上手

相关源文件

本页面内容基于以下源文件生成：

• README.md
• setup.py
• requirements.txt
• config/config2.example.yaml
• metagpt/config2.py
• metagpt/logs.py
• metagpt/const.py
• metagpt/utils/common.py
• metagpt/configs/llm_config.py
• metagpt/utils/yaml_model.py

MetaGPT 是一个多智能体框架，通过为 GPT 分配不同角色（产品经理、架构师、项目经理、工程师等）形成协作实体，以处理复杂任务。该框架的核心理念是 Code = SOP(Team)，将标准操作流程（SOP）应用于由大语言模型组成的团队。

安装与环境准备

系统要求

MetaGPT 对 Python 版本有明确要求：需要 Python 3.9 或更高版本，但必须低于 3.12。可以通过以下命令检查当前 Python 版本：

bash
1python --version

推荐使用 conda 创建独立的虚拟环境，以避免依赖冲突：

bash
1conda create -n metagpt python=3.9 && conda activate metagpt

(README.md:50-66)

安装方式

MetaGPT 提供多种安装方式，最简单的方式是通过 pip 安装稳定版本：

bash
1pip install --upgrade metagpt

也可以直接从 GitHub 仓库安装最新版本：

bash
1pip install --upgrade git+https://github.com/geekan/MetaGPT.git

或者克隆仓库后以开发模式安装：

bash
1git clone https://github.com/geekan/MetaGPT && cd MetaGPT && pip install --upgrade -e .

(README.md:50-66)

可选依赖

在实际使用前，需要安装 node 和 pnpm，这些工具用于 Mermaid 图表渲染等功能。

(README.md:50-66)

根据 setup.py 的定义，MetaGPT 的包名为 metagpt，版本号为 1.0.0，并明确指定了 Python 版本依赖为 >=3.9, <3.12。

(setup.py:98-111)

配置初始化

配置文件生成

MetaGPT 首次使用前需要进行配置初始化。可以通过以下命令自动生成配置文件：

bash
1metagpt --init-config

该命令会在用户主目录下创建 ~/.metagpt/config2.yaml 文件，开发者可以根据实际需求修改此文件。

(README.md:68-84)

LLM API 配置

配置文件的核心是 LLM（大语言模型）API 设置。以下是一个基础配置示例：

yaml
1llm:
2  api_type: "openai"  # 或 azure / ollama / groq 等
3  model: "gpt-4-turbo"  # 或 gpt-3.5-turbo
4  base_url: "https://api.openai.com/v1"  # 或转发 URL / 其他 LLM URL
5  api_key: "YOUR_API_KEY"

(README.md:68-84)

根据示例配置文件，完整的 LLM 配置项还包括：

(config/config2.example.yaml:1-9)

角色级别配置

MetaGPT 支持为不同角色配置独立的 LLM 设置。例如，可以为产品经理、架构师、项目经理和工程师分别指定不同的模型：

yaml
1roles:
2  - role: "ProductManager"
3    llm:
4      api_type: "openai"
5      model: "gpt-4-turbo-1106"
6  - role: "Architect"
7    llm:
8      api_type: "openai"
9      model: "gpt-35-turbo"

(config/config2.example.yaml:1-9)

命令行快速使用

基本用法

安装完成后，可以直接通过命令行使用 MetaGPT。最简单的使用方式是传入一行需求描述：

bash
1metagpt "Create a 2048 game"

该命令会在当前目录的 ./workspace 文件夹中创建一个完整的项目仓库，包含用户故事、竞争分析、需求文档、数据结构、API 定义等。

(README.md:86-92)

入口点定义

根据 setup.py 的配置，metagpt 命令行工具的入口点指向 metagpt.software_company:app，这是框架的主入口函数。

(setup.py:116-120)

作为库使用

软件公司模式

MetaGPT 可以作为 Python 库集成到其他项目中。以下是生成项目仓库的示例代码：

python
1from metagpt.software_company import generate_repo
2from metagpt.utils.project_repo import ProjectRepo
3
4repo: ProjectRepo = generate_repo("Create a 2048 game")
5print(repo)  # 打印仓库结构和文件列表

generate_repo 函数接收需求描述，返回一个 ProjectRepo 对象，该对象包含生成的项目结构和文件内容。

(README.md:94-102)

数据解释器模式

MetaGPT 还提供了 Data Interpreter（数据解释器）模式，用于数据分析和代码生成任务：

python
1import asyncio
2from metagpt.roles.di.data_interpreter import DataInterpreter
3
4async def main():
5    di = DataInterpreter()
6    await di.run("Run data analysis on sklearn Iris dataset, include a plot")
7
8asyncio.run(main())  # 或在 Jupyter Notebook 中使用 await main()

(README.md:104-115)

运行验证

验证安装成功

安装完成后，可以通过以下方式验证 MetaGPT 是否正确安装：

1. 检查命令行工具：运行 metagpt --help 查看帮助信息（需要确认：此命令的具体输出未在源文件中明确记录）。

2. 检查 Python 模块：在 Python 环境中尝试导入模块：

   python
   1import metagpt
   2print(metagpt.__version__)

3. 运行简单任务：使用命令行执行一个简单的需求，如 metagpt "Create a simple calculator"，检查是否在 ./workspace 目录下生成了项目文件。

预期输出

成功运行后，MetaGPT 会在 ./workspace 目录下创建项目仓库，包含完整的软件开发生命周期文档和代码文件。

(README.md:86-92)

常见问题与排错

问题 1：Python 版本不兼容

症状：安装时报错，提示 Python 版本不满足要求。

原因：MetaGPT 要求 Python 版本在 3.9 到 3.12 之间（不含 3.12）。

解决方案：

bash
1# 创建符合要求的 conda 环境
2conda create -n metagpt python=3.9
3conda activate metagpt

(README.md:50-66)

问题 2：配置文件未找到或 API 密钥无效

症状：运行时报错，提示无法连接到 LLM API 或认证失败。

原因：配置文件未正确初始化或 API 密钥未设置。

解决方案：

1. 运行 metagpt --init-config 生成配置文件
2. 编辑 ~/.metagpt/config2.yaml，填入有效的 api_key
3. 确保 base_url 正确（如使用 OpenAI API，应为 https://api.openai.com/v1）

(README.md:68-84)

问题 3：Mermaid 图表渲染失败

症状：生成的文档中 Mermaid 图表无法正常显示。

原因：缺少 node 和 pnpm 依赖，或 mermaid-cli 未正确安装。

解决方案：

1. 安装 node
2. 安装 pnpm
3. 运行 npm install -g @mermaid-js/mermaid-cli（需要确认：此命令的具体执行方式参考 setup.py 中的 InstallMermaidCLI 类）

(README.md:50-66, setup.py:8-19)

问题 4：依赖冲突

症状：安装过程中出现依赖版本冲突错误。

原因：系统环境中存在与 MetaGPT 不兼容的包版本。

解决方案：

• 使用独立的虚拟环境（conda 或 venv）
• 尝试使用 pip install --upgrade metagpt 获取最新版本
• 检查 requirements.txt 中的依赖版本要求

(requirements.txt:1-90)

在线体验与教程资源

在线演示平台

如果希望在本地安装前先体验 MetaGPT 的功能，可以访问以下在线平台：

• Huggingface Space：MetaGPT Huggingface Space 提供在线交互式体验

(README.md:118-123)

视频教程

以下视频教程可以帮助快速上手：

• Matthew Berman 教程：How To Install MetaGPT - Build A Startup With One Prompt!!
• 官方演示视频：展示 MetaGPT 的核心功能和工作流程

(README.md:118-123)

官方文档

MetaGPT 提供了完整的官方文档，涵盖从入门到高级用法的各个方面：

(README.md:125-141)

用例文档

官方文档还提供了多个具体用例的详细说明：

• Data Interpreter：数据分析与代码生成
• Debate：多智能体辩论场景
• Researcher：研究助手功能
• Receipt Assistant：收据处理助手

(README.md:125-141)

下一步建议

完成快速上手后，建议按以下路径深入学习：

1. 阅读官方文档：访问 使用指南 了解更多配置选项和高级用法。

2. 探索用例：查看 用例文档 了解 MetaGPT 在不同场景下的应用。

3. 自定义 Agent 开发：参考 Agent 101 和 MultiAgent 101 教程，构建符合特定需求的智能体。

4. 参与社区：加入 Discord 频道 与其他开发者交流，或在 GitHub Issues 提交问题和反馈。

(README.md:125-141)