【零基础部署】Docker 部署 CrewAI 多 Agent 编排框架保姆级教程

Lumbrologist2026-06-01 23:41

CrewAI 是一个热门的多 Agent 编排框架，它让多个 AI Agent 像一个团队一样协作完成复杂任务。每个 Agent 有自己的角色、目标和工具，通过任务分配和协作来完成工作。本教程将手把手教你用 Docker 部署 CrewAI，并运行一个多 Agent 协作的示例。

1. CrewAI 简介

1.1 什么是 CrewAI？

CrewAI 是一个 Python 框架，核心理念是：

  • Agent：AI 角色，有特定的专业领域和工具
  • Task：具体任务，分配给某个 Agent 执行
  • Crew：一组 Agent 和 Task 的组合，负责协调执行
  • Process：执行策略，支持顺序执行和层级管理

1.2 架构概览

复制代码 
┌─────────────────────────────────────────┐
│                  Crew                    │
│  ┌─────────┐  ┌─────────┐  ┌─────────┐ │
│  │ Agent A  │  │ Agent B  │  │ Agent C  │ │
│  │ 研究员    │  │ 写作者    │  │ 编辑者    │ │
│  └────┬────┘  └────┬────┘  └────┬────┘ │
│       │            │            │       │
│  ┌────▼────┐  ┌────▼────┐  ┌────▼────┐ │
│  │ Task 1   │  │ Task 2   │  │ Task 3   │ │
│  │ 搜索资料  │  │ 撰写文章  │  │ 审核修改  │ │
│  └─────────┘  └─────────┘  └─────────┘ │
└─────────────────────────────────────────┘

1.3 环境要求

  • 操作系统：Ubuntu 20.04+ / Debian 11+
  • Docker：20.10+
  • Docker Compose：V2
  • 内存：至少 2GB
  • 磁盘：至少 5GB 可用空间
  • LLM API Key：OpenAI、Anthropic 或其他兼容 API

2. 项目结构

在开始之前，先创建项目目录：

bash 复制代码 
mkdir -p ~/crewai-project
cd ~/crewai-project

创建以下目录结构：

复制代码 
crewai-project/
├── docker-compose.yml
├── Dockerfile
├── requirements.txt
├── .env
└── app/
    ├── main.py
    ├── agents.py
    ├── tasks.py
    └── tools/
        └── search_tool.py

3. 编写 Dockerfile

dockerfile 复制代码 
FROM python:3.11-slim

WORKDIR /app

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

# 安装 Python 依赖
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# 复制应用代码
COPY app/ ./app/

# 设置环境变量
ENV PYTHONPATH=/app
ENV PYTHONUNBUFFERED=1

CMD ["python", "app/main.py"]

4. 编写 requirements.txt

txt 复制代码 
crewai[tools]==0.108.0
crewai-tools==0.38.1
langchain-openai==0.3.8
python-dotenv==1.1.0
requests==2.32.3

5. 配置环境变量

创建 .env 文件，填入你的 LLM API Key：

bash 复制代码 
# 使用 OpenAI
OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxx
OPENAI_MODEL_NAME=gpt-4o-mini

# 或者使用兼容的 API（如 DeepSeek、Qwen）
# OPENAI_API_KEY=your-api-key
# OPENAI_API_BASE=https://api.deepseek.com/v1
# OPENAI_MODEL_NAME=deepseek-chat

注意：请将 sk-xxxxxxxxxxxxxxxxxxxxxxxx 替换为你的真实 API Key。不要将 .env 文件提交到版本控制系统。

6. 编写 Agent 定义

创建 app/agents.py：

python 复制代码 
from crewai import Agent


def create_researcher(llm):
    """创建研究员 Agent"""
    return Agent(
        role="资深研究员",
        goal="深入搜索和分析指定主题的最新信息",
        backstory="""你是一位经验丰富的研究员，擅长从多个信息源
        获取和整合信息。你能够快速识别关键数据和趋势，
        并以清晰的方式呈现研究结果。""",
        verbose=True,
        allow_delegation=False,
        llm=llm,
    )


def create_writer(llm):
    """创建写作者 Agent"""
    return Agent(
        role="技术写作者",
        goal="将复杂的技术概念转化为通俗易懂的文章",
        backstory="""你是一位优秀的技术写作者，擅长将复杂的
        技术概念用简单易懂的语言解释。你的文章结构清晰、
        逻辑严密，深受读者喜爱。""",
        verbose=True,
        allow_delegation=False,
        llm=llm,
    )


def create_editor(llm):
    """创建编辑者 Agent"""
    return Agent(
        role="资深编辑",
        goal="确保文章质量，修正错误，优化表达",
        backstory="""你是一位资深编辑，拥有敏锐的文字感知力。
        你能够发现文章中的逻辑漏洞、事实错误和表达不当之处，
        并提出具体的修改建议。""",
        verbose=True,
        allow_delegation=False,
        llm=llm,
    )

7. 编写 Task 定义

创建 app/tasks.py：

python 复制代码 
from crewai import Task


def create_research_task(agent, topic):
    """创建研究任务"""
    return Task(
        description=f"""对主题 "{topic}" 进行深入研究：
        1. 搜索该主题的最新发展和趋势
        2. 整理关键概念和技术要点
        3. 收集实际应用案例
        4. 总结核心观点和结论
        
        研究主题：{topic}""",
        expected_output="""一份详细的研究报告，包含：
        - 主题概述
        - 核心概念和技术要点
        - 最新发展趋势
        - 实际应用案例
        - 总结与展望""",
        agent=agent,
    )


def create_writing_task(agent, context_tasks):
    """创建写作任务"""
    return Task(
        description="""基于研究报告，撰写一篇技术文章：
        1. 文章结构要清晰，使用标题和子标题
        2. 语言通俗易懂，适合初学者阅读
        3. 包含实际的代码示例或操作步骤
        4. 文章长度 1500-2000 字""",
        expected_output="""一篇高质量的技术文章，格式为 Markdown，
        包含完整的标题、正文和代码示例。""",
        agent=agent,
        context=context_tasks,
    )


def create_editing_task(agent, context_tasks):
    """创建编辑任务"""
    return Task(
        description="""审核和修改文章：
        1. 检查事实准确性
        2. 修正语法和表达错误
        3. 优化文章结构和逻辑
        4. 确保技术术语使用正确""",
        expected_output="""最终修改后的文章，包含编辑批注
        和修改说明。""",
        agent=agent,
        context=context_tasks,
    )

8. 编写主程序

创建 app/main.py：

python 复制代码 
import os
from dotenv import load_dotenv
from langchain_openai import ChatOpenAI
from crewai import Crew, Process

from agents import create_researcher, create_writer, create_editor
from tasks import create_research_task, create_writing_task, create_editing_task

# 加载环境变量
load_dotenv()


def main():
    # 初始化 LLM
    llm = ChatOpenAI(
        model=os.getenv("OPENAI_MODEL_NAME", "gpt-4o-mini"),
        openai_api_key=os.getenv("OPENAI_API_KEY"),
        openai_api_base=os.getenv("OPENAI_API_BASE"),
        temperature=0.7,
    )

    # 定义研究主题
    topic = "2026 年 AI Agent 技术的发展趋势与应用前景"

    # 创建 Agents
    researcher = create_researcher(llm)
    writer = create_writer(llm)
    editor = create_editor(llm)

    # 创建 Tasks
    research_task = create_research_task(researcher, topic)
    writing_task = create_writing_task(writer, [research_task])
    editing_task = create_editing_task(editor, [writing_task])

    # 创建 Crew 并执行
    crew = Crew(
        agents=[researcher, writer, editor],
        tasks=[research_task, writing_task, editing_task],
        process=Process.sequential,  # 顺序执行
        verbose=True,
    )

    print("=" * 50)
    print("CrewAI 多 Agent 协作开始")
    print(f"研究主题：{topic}")
    print("=" * 50)

    # 启动执行
    result = crew.kickoff()

    print("\n" + "=" * 50)
    print("最终结果：")
    print("=" * 50)
    print(result)


if __name__ == "__main__":
    main()

9. 编写 Docker Compose

创建 docker-compose.yml：

yaml 复制代码 
services:
  crewai:
    build: .
    container_name: crewai-app
    env_file:
      - .env
    volumes:
      - ./app:/app/app
      - ./output:/app/output
    environment:
      - PYTHONPATH=/app
      - PYTHONUNBUFFERED=1
    restart: unless-stopped
    networks:
      - crewai-net

networks:
  crewai-net:
    driver: bridge

10. 启动服务

10.1 构建并启动

bash 复制代码 
cd ~/crewai-project

# 构建镜像
docker compose build

# 启动服务
docker compose up

10.2 查看日志

bash 复制代码 
# 实时查看日志
docker compose logs -f

你会看到类似这样的输出：

复制代码 
crewai-app  | ==================================================
crewai-app  | CrewAI 多 Agent 协作开始
crewai-app  | 研究主题：2026 年 AI Agent 技术的发展趋势与应用前景
crewai-app  | ==================================================
crewai-app  | 
crewai-app  | [资深研究员] 开始执行任务...
crewai-app  | 搜索 AI Agent 最新技术发展...
crewai-app  | 整理核心概念和技术要点...
crewai-app  | 
crewai-app  | [技术写作者] 开始执行任务...
crewai-app  | 基于研究结果撰写文章...
crewai-app  | 
crewai-app  | [资深编辑] 开始执行任务...
crewai-app  | 审核文章质量...

10.3 后台运行

bash 复制代码 
# 后台运行
docker compose up -d

# 查看日志
docker compose logs -f

# 停止服务
docker compose down

11. 进阶配置

11.1 使用本地 Ollama 模型

如果你想使用本地模型而不是云端 API，可以配合 Ollama：

修改 .env：

bash 复制代码 
OPENAI_API_KEY=ollama
OPENAI_API_BASE=http://host.docker.internal:11434/v1
OPENAI_MODEL_NAME=qwen2.5:14b

修改 docker-compose.yml，添加网络配置：

yaml 复制代码 
services:
  crewai:
    build: .
    container_name: crewai-app
    env_file:
      - .env
    extra_hosts:
      - "host.docker.internal:host-gateway"
    volumes:
      - ./app:/app/app
    restart: unless-stopped

11.2 添加自定义工具

创建 app/tools/search_tool.py：

python 复制代码 
from crewai.tools import BaseTool
from typing import Type
from pydantic import BaseModel, Field
import requests


class SearchInput(BaseModel):
    query: str = Field(description="搜索关键词")


class WebSearchTool(BaseTool):
    name: str = "web_search"
    description: str = "搜索互联网获取最新信息"
    args_schema: Type[BaseModel] = SearchInput

    def _run(self, query: str) -> str:
        # 这里可以接入真实的搜索 API
        # 例如 Tavily、SerpAPI 等
        try:
            response = requests.get(
                "https://api.search.example.com/search",
                params={"q": query, "limit": 5},
                timeout=10,
            )
            return response.text
        except Exception as e:
            return f"搜索失败：{str(e)}"

在 Agent 中使用工具：

python 复制代码 
from tools.search_tool import WebSearchTool

researcher = Agent(
    role="资深研究员",
    goal="搜索最新信息",
    tools=[WebSearchTool()],
    # ...
)

11.3 使用层级管理

python 复制代码 
crew = Crew(
    agents=[researcher, writer, editor],
    tasks=[research_task, writing_task, editing_task],
    process=Process.hierarchical,      # 层级管理
    manager_llm=llm,                   # 管理者使用的模型
    verbose=True,
)

12. 常见问题排查

12.1 API Key 错误

复制代码 
错误：AuthenticationError: Incorrect API key

解决方法：

  • 检查 .env 中的 OPENAI_API_KEY 是否正确
  • 确认 API Key 没有过期
  • 如果使用第三方 API，确认 OPENAI_API_BASE 配置正确

12.2 模型不可用

复制代码 
错误：Model not found

解决方法：

  • 检查 OPENAI_MODEL_NAME 是否拼写正确
  • 确认你的账户有权限使用该模型
  • 尝试使用更常见的模型名称

12.3 网络连接问题

复制代码 
错误：ConnectionError

解决方法：

  • 检查服务器是否能访问外部 API
  • 如果使用代理，在 .env 中配置 HTTPS_PROXY
  • 如果使用本地 Ollama，确认 Ollama 服务已启动

12.4 依赖安装失败

bash 复制代码 
# 重新构建镜像
docker compose build --no-cache

13. 总结

通过本教程，你已经成功部署了 CrewAI 多 Agent 编排框架：

  • 使用 Docker 容器化部署，环境隔离、一键启动
  • 创建了三个协作 Agent：研究员、写作者、编辑者
  • 配置了顺序执行的任务流水线
  • 学会了使用云端 API 和本地 Ollama 模型
  • 掌握了自定义工具和层级管理的进阶用法

CrewAI 的核心价值在于让 AI Agent 之间实现真正的协作，而不是简单的链式调用。通过合理的角色设计和任务分配，你可以构建出强大的 AI 工作流。

相关推荐
XIAOHEZIcode1 天前
Linux系统鼠标偏移常见原因以及修复方案
linux·运维·游戏
用户0328472220702 天前
如何搭建本地yum源(上)
运维
武子康2 天前
调查研究-183 Apple container：Mac 上用轻量 VM 跑 Linux 容器，Swift 会改写本地容器体验吗？
docker·容器·apple
大树885 天前
金刚石散热越强，管路越先见顶
大数据·运维·服务器·人工智能·ai
摇滚侠5 天前
Linux CentOS7 rpm 安装 MySQL 5.7
linux·运维·mysql
霸道流氓气质5 天前
领域驱动设计（DDD）在 Spring Boot 微服务中的实践指南
运维·spring boot·微服务
Inhand陈工5 天前
基于台达PLC与映翰通IG502的智慧水产养殖精准投喂与远程运维解决方案
运维·人工智能·物联网·阿里云·信息与通信
Alsn865 天前
等待学习-学习目录：Docker 容器安全攻防
学习·安全·docker
酣大智5 天前
ARP代理--工作原理
运维·网络·arp·arp代理
shushangyun_5 天前
2026年快消品B2B系统推荐：支持终端门店订货、促销政策自动化的工具？
java·运维·网络·数据库·人工智能·spring·自动化
热门推荐
012026年6月AI大模型全景报告：GPT-5.6、Claude Opus 4.8、Gemini 3.5，中美AI三足鼎立谁主沉浮？022026年6月AI行业全景：从百模大战到Agent元年，这30天发生了什么？032026 年 AI 编程工具终极横评：Cursor vs Claude Code vs Copilot vs Windsurf04【AI】2026 年具身智能模型和世界模型总结05GitHub 镜像站点06AI科技热点日报 | 2026年6月1日07Claude Code、Codex、Cursor三分天下：2026年AI编程Agent生态全景剖析08AI一周事件 · 2026-06-03 至 2026-06-0909上线仅72小时被强制下架：Claude Fable 5 的短命10Codex 下载安装指南：Windows 和 macOS 官方版下载