# CrewAI 多代理框架

## 概览

[CrewAI](https://github.com/crewAIInc/crewAI) 是一个用于编排 **角色扮演自治 AI 代理**的前沿框架，具有 **44K+ GitHub 星**。与单代理系统不同，CrewAI 允许你定义专业化的代理（研究员、作者、开发者、分析师……）作为一个“团队”协作完成复杂任务——每个代理都有自己的角色、目标、背景故事和工具包。

在 **Clore.ai**，CrewAI 可以部署在容器化环境中，成本低至 **每小时 $0.05–0.20**。虽然 CrewAI 本身受限于 CPU（它负责协调 API 调用），但将其与运行在同一 GPU 节点上的本地 Ollama 或 vLLM 服务器结合使用，可实现完全私有、支持离线的多代理系统。

**主要功能：**

* 👥 **多代理团队** — 使用角色、目标和背景故事定义代理设定
* 🎯 **任务委派** — 管理代理会自动将任务分配给合适的专家
* 🛠️ **工具生态** — 网页搜索、文件 I/O、代码执行、数据库访问、自定义工具
* 🔁 **顺序与并行** — 按顺序执行任务或同时运行相互独立的任务
* 🧠 **代理记忆** — 短期、长期、实体与上下文记忆类型
* 🔌 **与 LLM 无关** — 可与 OpenAI、Anthropic、Google、Ollama、Groq、Azure 等配合使用
* 📊 **CrewAI Studio** — 用于无代码构建团队的可视化界面（企业版）
* 🚀 **流水线** — 将多个团队串联以实现复杂的多阶段工作流

***

## 要求

CrewAI 是一个 Python 库。它在 CPU 上运行，仅需系统 Python 3.10+ 环境或 Docker。GPU 为可选，但可解锁强大的本地模型推理能力。

| 配置               | GPU             | 显存    | 系统内存  | 磁盘     | Clore.ai 价格     |
| ---------------- | --------------- | ----- | ----- | ------ | --------------- |
| **最小** （云端 API）  | 无 / 仅 CPU       | —     | 2 GB  | 10 GB  | 约 $0.03/小时（CPU） |
| **标准**           | 无 / 仅 CPU       | —     | 4 GB  | 20 GB  | 约 $0.05/小时      |
| **+ 本地 LLM（小型）** | RTX 3080        | 10 GB | 8 GB  | 40 GB  | 约 $0.15/小时      |
| **+ 本地 LLM（大型）** | RTX 3090 / 4090 | 24 GB | 16 GB | 60 GB  | $0.20–0.35/小时   |
| **+ 高质量本地 LLM**  | A100 40 GB      | 40 GB | 32 GB | 100 GB | 约 $0.80/小时      |

### API 密钥

CrewAI 可与大多数主流 LLM 提供商配合使用。你至少需要一个：

* **OpenAI** — GPT-4o（在复杂任务上具有最佳推理能力）
* **Anthropic** — Claude 3.5 Sonnet（非常适合以写作为主的团队）
* **Groq** — 免费额度，推理快速（Llama 3 70B）
* **Ollama** — 完全本地，不需要 API 密钥（参见 [GPU 加速](#gpu-acceleration))

***

## 快速开始

### 1. 租用 Clore.ai 服务器

登录到 [clore.ai](https://clore.ai):

* **仅 CPU** 如果使用云端 LLM API
* **RTX 3090/4090** 用于本地 Ollama 推理
* 已启用 SSH 访问
* CLI 使用不需要特殊端口（仅在使用 Web UI 时暴露端口）

### 2. 连接与准备

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

# 更新系统
apt-get update && apt-get upgrade -y

# 安装 Python 3.11（如果尚未安装）
apt-get install -y python3.11 python3.11-venv python3-pip
python3 --version   # 应为 3.10+

# 验证 Docker
docker --version
```

### 3. 选项 A — 直接 pip 安装（最快）

```bash
# 创建虚拟环境
python3 -m venv crewai-env
source crewai-env/bin/activate

# 安装包含所有工具的 CrewAI
pip install crewai crewai-tools

# 验证安装
python -c "import crewai; print(crewai.__version__)"
crewai --version
```

### 4. 选项 B — Docker 容器（推荐用于可重现性）

```bash
# 创建项目目录
mkdir my-crew && cd my-crew

# 编写 Dockerfile
cat > Dockerfile << 'EOF'
FROM python:3.11-slim

# 安装系统依赖项
RUN apt-get update && apt-get install -y \
    curl \
    git \
    && rm -rf /var/lib/apt/lists/*

# 设置工作目录
WORKDIR /app

# 安装 CrewAI 和常用工具
RUN pip install --no-cache-dir \
    crewai \
    crewai-tools \
    langchain-openai \
    langchain-anthropic \
    python-dotenv

# 复制应用代码
COPY . .

# 默认命令
CMD ["python", "main.py"]
EOF

# 构建镜像
docker build -t my-crewai-app .
```

### 5. 创建你的第一个团队

```bash
# 使用 CLI 初始化一个新的 CrewAI 项目
source crewai-env/bin/activate
crewai create crew my-research-crew
cd my-research-crew

# 配置 API 密钥
cat > .env << 'EOF'
OPENAI_API_KEY=sk-...
# 或对于 Anthropic：
# ANTHROPIC_API_KEY=sk-ant-...
# 或对于 Ollama（无需密钥）：
# OPENAI_API_BASE=http://localhost:11434/v1
# OPENAI_API_KEY=ollama
EOF

# 安装项目依赖
crewai install

# 运行团队
crewai run
```

***

## 配置

### 项目结构（来自 `crewai create`)

```
my-research-crew/
├── .env                    # API 密钥与设置
├── pyproject.toml          # 依赖项
├── src/
│   └── my_research_crew/
│       ├── config/
│       │   ├── agents.yaml   # 代理定义
│       │   └── tasks.yaml    # 任务定义
│       ├── tools/
│       │   └── custom_tool.py  # 你的自定义工具
│       ├── crew.py           # 团队组装
│       └── main.py           # 入口点
```

### agents.yaml — 定义你的代理

```yaml
researcher:
  role: >
    高级研究分析师
  goal: >
    发现 {topic} 领域的前沿进展并综合可执行洞见
  backstory: >
    你是一名擅长从多样化来源发现并连接信息的专家研究员
    。你对可信度和相关性有敏锐的判断力。
  tools:
    - SerperDevTool
    - ScrapeWebsiteTool
  llm: gpt-4o                # 可按代理单独设置
  verbose: true
  max_iter: 15               # 最大推理迭代次数
  memory: true               # 启用代理记忆

writer:
  role: >
    专家级技术写作者
  goal: >
    将复杂研究转化为清晰、有吸引力且准确的内容
  backstory: >
    你撰写的解释能在不牺牲深度的前提下让复杂主题易于理解。
    你引用来源并以最大可读性来组织内容。
  llm: claude-3-5-sonnet-20241022
  verbose: true
```

### tasks.yaml — 定义任务

```yaml
research_task:
  description: >
    研究过去 6 个月内关于 {topic} 的最新进展。
    识别关键趋势、突破和其影响。
    汇编至少 10 个可信来源。
  expected_output: >
    一份按主题组织的详细研究报告，
    包括来源 URL 和出版日期。
  agent: researcher

writing_task:
  description: >
    使用研究报告，撰写一篇关于 {topic} 的综合博客文章。
    目标长度：1500–2000 字。包含标题、引言、主要章节，
    以及带有未来展望的结论。
  expected_output: >
    以 Markdown 格式输出一篇可发布的博客文章。
  agent: writer
  context:
    - research_task    # 写作任务接收研究者的输出
  output_file: output/blog_post.md
```

### crew\.py — 组装团队

```python
from crewai import Agent, Crew, Process, Task
from crewai.project import CrewBase, agent, crew, task
from crewai_tools import SerperDevTool, ScrapeWebsiteTool

@CrewBase
class MyResearchCrew():
    """研究与写作团队"""
    agents_config = 'config/agents.yaml'
    tasks_config = 'config/tasks.yaml'

    @agent
    def researcher(self) -> Agent:
        return Agent(
            config=self.agents_config['researcher'],
            tools=[SerperDevTool(), ScrapeWebsiteTool()],
            verbose=True
        )

    @agent
    def writer(self) -> Agent:
        return Agent(
            config=self.agents_config['writer'],
            verbose=True
        )

    @task
    def research_task(self) -> Task:
        return Task(config=self.tasks_config['research_task'])

    @task
    def writing_task(self) -> Task:
        return Task(
            config=self.tasks_config['writing_task'],
            output_file='output/blog_post.md'
        )

    @crew
    def crew(self) -> Crew:
        return Crew(
            agents=self.agents,
            tasks=self.tasks,
            process=Process.sequential,  # 或 Process.hierarchical
            verbose=True,
            memory=True,
            max_rpm=10   # 限制 API 调用速率
        )
```

### 使用 Docker Compose 运行（含 Ollama）

```yaml
# docker-compose.yml
version: "3.8"

services:
  crewai:
    build: .
    volumes:
      - ./src:/app/src
      - ./output:/app/output
    environment:
      - OPENAI_API_BASE=http://ollama:11434/v1
      - OPENAI_API_KEY=ollama
      - OPENAI_MODEL_NAME=llama3.1:70b
      - SERPER_API_KEY=${SERPER_API_KEY}
    depends_on:
      - ollama

  ollama:
    image: ollama/ollama:latest
    volumes:
      - ollama_data:/root/.ollama
    ports:
      - "11434:11434"
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]

volumes:
  ollama_data:
```

```bash
# 启动服务栈
docker compose up -d ollama

# 拉取你的模型
docker compose exec ollama ollama pull llama3.1:70b

# 运行你的团队
docker compose run --rm crewai python src/my_research_crew/main.py
```

***

## GPU 加速

CrewAI 本身不使用 GPU —— 但它调用的 LLM 会使用。将 Ollama 或 vLLM 在同一 Clore 服务器上运行可以实现 GPU 加速的本地推理。

### Ollama 安装（为方便起见推荐）

```bash
# 在主机上安装 Ollama
curl -fsSL https://ollama.com/install.sh | sh

# 验证 GPU 检测
nvidia-smi
ollama run llama3:8b "Test"   # 应使用 GPU

# 为不同代理需求拉取模型
ollama pull llama3.1:8b          # 快速、轻量的推理
ollama pull llama3.1:70b         # 复杂推理（需要 A100+）
ollama pull codestral:latest     # 为代码代理专门优化
ollama pull nomic-embed-text     # 用于记忆 / RAG 嵌入

# 配置 CrewAI 使用 Ollama
export OPENAI_API_BASE=http://localhost:11434/v1
export OPENAI_API_KEY=ollama
export OPENAI_MODEL_NAME=llama3.1:8b
```

### 为每个代理配置 CrewAI 的 LLM

```python
from crewai import Agent, LLM

# 为特定代理使用 Ollama
local_llm = LLM(
    model="ollama/llama3.1:8b",
    base_url="http://localhost:11434"
)

# 为另一个代理使用云端 API（例如复杂推理）
cloud_llm = LLM(
    model="gpt-4o",
    api_key="sk-..."
)

researcher = Agent(
    role="Researcher",
    goal="Find information",
    backstory="Expert researcher",
    llm=local_llm    # 使用本地 GPU
)

strategist = Agent(
    role="Strategist",
    goal="Plan actions",
    backstory="Strategic thinker",
    llm=cloud_llm    # 使用云端 API
)
```

### 代理任务的模型推荐

| 任务类型      | 推荐模型             | 显存     | 注意事项    |
| --------- | ---------------- | ------ | ------- |
| 研究 + 网页搜索 | Llama 3.1 70B    | 40 GB  | 最佳本地推理  |
| 代码生成      | Codestral 22B    | 13 GB  | 代码专用    |
| 写作        | Llama 3.1 8B     | 6 GB   | 快速、质量良好 |
| 复杂编排      | GPT-4o（API）      | —      | 总体最佳    |
| 嵌入 / 记忆   | nomic-embed-text | < 1 GB | 记忆所需    |

> 参见 [Clore.ai 上的 Ollama](https://docs.clore.ai/guides/guides_v2-zh/yu-yan-mo-xing/ollama) 和 [Clore.ai 上的 vLLM](https://docs.clore.ai/guides/guides_v2-zh/yu-yan-mo-xing/vllm) 以获取完整的推理设置指南。

***

## 提示与最佳实践

### 成本优化

```bash
# 使用 CrewAI 内置使用情况跟踪来跟踪 LLM API 成本
# 将其添加到你的团队：
result = crew.kickoff(inputs={"topic": "AI agents"})
print(f"使用的总令牌数: {result.token_usage}")

# 对于简单任务使用更便宜的模型，对于复杂任务使用高端模型
# Ollama 上的 Llama 3.1 8B = $0 API 成本
# GPT-4o = 约 $0.005/1K 输入令牌

# 设置 max_iter 以防止代理失控
Agent(max_iter=10, max_execution_time=120)  # 2 分钟超时

# 在开发过程中缓存 LLM 响应
os.environ["CREWAI_DISABLE_CACHE"] = "false"
```

### 将团队作为持久服务运行

```bash
# 通过 FastAPI 端点提供团队服务
pip install fastapi uvicorn

cat > server.py << 'EOF'
from fastapi import FastAPI, BackgroundTasks
from my_research_crew.crew import MyResearchCrew
import asyncio

app = FastAPI()
results = {}

@app.post("/run/{topic}")
async def run_crew(topic: str, background_tasks: BackgroundTasks):
    job_id = f"job-{topic}-{len(results)}"
    background_tasks.add_task(execute_crew, job_id, topic)
    return {"job_id": job_id, "status": "started"}

async def execute_crew(job_id: str, topic: str):
    crew = MyResearchCrew().crew()
    result = crew.kickoff(inputs={"topic": topic})
    results[job_id] = str(result)

@app.get("/result/{job_id}")
async def get_result(job_id: str):
    return {"result": results.get(job_id, "pending")}

EOF

# 运行服务器
uvicorn server:app --host 0.0.0.0 --port 8080 &

# 触发一次团队运行
curl -X POST http://<clore-ip>:8080/run/quantum-computing
```

### 内置的有用 CrewAI 工具

```python
from crewai_tools import (
    SerperDevTool,        # 通过 Serper API 的 Google 搜索
    ScrapeWebsiteTool,    # 网页抓取
    FileReadTool,         # 读取本地文件
    FileWriterTool,       # 写入文件
    DirectoryReadTool,    # 列出目录内容
    CodeInterpreterTool,  # 执行 Python 代码
    GithubSearchTool,     # 搜索 GitHub 仓库
    YoutubeVideoSearchTool, # 搜索 YouTube
    PGSearchTool,         # 查询 PostgreSQL
)
```

### 实现人类在环（human-in-the-loop）

```python
# 在特定任务处请求人工输入
task = Task(
    description="Research {topic}",
    expected_output="Research report",
    agent=researcher,
    human_input=True    # 暂停并提示用户反馈
)
```

***

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

### "openai.AuthenticationError" 即使密钥有效

```bash
# 检查你的 API 密钥是否已加载
python3 -c "import os; from dotenv import load_dotenv; load_dotenv(); print(os.getenv('OPENAI_API_KEY')[:10])"

# 如果使用 Ollama，请确保设置了以下项：
export OPENAI_API_BASE=http://localhost:11434/v1
export OPENAI_API_KEY=ollama
export OPENAI_MODEL_NAME=llama3.1:8b

# 验证 Ollama 是否可访问
curl http://localhost:11434/v1/models
```

### 代理卡在推理循环中

```bash
# 设置迭代的硬性上限
Agent(
    max_iter=10,            # 最大推理步数
    max_execution_time=300  # 5 分钟硬性超时
)

# 启用 verbose 以查看循环位置
Agent(verbose=True)

# 检查模型是否支持工具调用
# 一些较小的模型不支持；使用 llama3.1 或 mistral-nemo
```

### CrewAI 工具失败（SerperDevTool 403）

```bash
# SerperDevTool 需要从 serper.dev 获取免费的 API 密钥
export SERPER_API_KEY=your-serper-key

# 替代方案：使用 DuckDuckGo（无需 API 密钥）
from langchain_community.tools import DuckDuckGoSearchRun
from crewai import tool

@tool("DuckDuckGo Search")
def ddg_search(query: str) -> str:
    """使用 DuckDuckGo 搜索网页。"""
    return DuckDuckGoSearchRun().run(query)
```

### 内存错误（ChromaDB / 嵌入）

```bash
# CrewAI 记忆使用 ChromaDB 存储向量
# 如果失败，请检查磁盘空间和权限
df -h
ls -la ~/.local/share/crewai/

# 清除损坏的记忆
rm -rf ~/.local/share/crewai/

# 或者如果不需要可以禁用记忆
Crew(memory=False)

# 如果使用 Ollama 嵌入，请确保模型已被拉取
docker exec ollama ollama pull nomic-embed-text
```

### Docker 构建因 ARM/x86 不匹配而失败

```bash
# Clore.ai 服务器为 x86_64；请明确指定平台：
docker build --platform linux/amd64 -t my-crewai-app .

# 或在 docker-compose.yml 中：
services:
  crewai:
    platform: linux/amd64
    build: .
```

### 来自 LLM API 的速率限制

```bash
# 降低每分钟请求数
Crew(max_rpm=5)   # 每分钟 5 次请求

# 在 LLM 配置中添加重试逻辑
LLM(
    model="gpt-4o",
    max_retries=3,
    timeout=60
)
```

***

## 延伸阅读

* [CrewAI 官方文档](https://docs.crewai.com)
* [CrewAI GitHub 仓库](https://github.com/crewAIInc/crewAI)
* [CrewAI 工具文档](https://docs.crewai.com/concepts/tools)
* [CrewAI 示例仓库](https://github.com/crewAIInc/crewAI-examples)
* [在 Clore.ai 上运行 Ollama](https://docs.clore.ai/guides/guides_v2-zh/yu-yan-mo-xing/ollama)
* [在 Clore.ai 上运行 vLLM](https://docs.clore.ai/guides/guides_v2-zh/yu-yan-mo-xing/vllm)
* [Clore.ai GPU 对比](https://docs.clore.ai/guides/guides_v2-zh/kuai-su-ru-men/gpu-comparison)
* [CrewAI 社区 Discord](https://discord.com/invite/X4JWnZnxPb)