Skip to content

Latest commit

 

History

History
550 lines (392 loc) · 19.2 KB

README_zh.md

File metadata and controls

550 lines (392 loc) · 19.2 KB

🦉 OWL: Optimized Workforce Learning for General Multi-Agent Assistance in Real-World Task Automation 🦉 OWL: 优化劳动力学习的通用智能体,用于处理现实世界的自动化任务

文档 Discord X Reddit 微信 微信 Hugging Face Star 软件许可证


🏆 OWL 在 GAIA 基准测试中取得 58.18 平均分,在开源框架中排名 🏅️ #1! 🏆

🦉 OWL 是一个前沿的多智能体协作框架,推动任务自动化的边界,构建在 CAMEL-AI Framework

我们的愿景是彻底变革 AI 智能体协作解决现实任务的方式。通过利用动态智能体交互,OWL 实现了跨多领域更自然、高效且稳健的任务自动化。


📋 目录

🔥 新闻

🌟🌟🌟 OWL社区用例征集令! 🌟🌟🌟

我们请社区成员贡献创新的OWL用例!
前十名提交将获得特别社区礼物和认可。

了解更多并提交

提交截止日期:2025年3月31日

  • [2025.03.12]: 在SearchToolkit中添加了Bocha搜索功能,集成了火山引擎模型平台,并更新了Azure和OpenAI Compatible模型的结构化输出和工具调用能力。
  • [2025.03.11]: 我们添加了 MCPToolkit、FileWriteToolkit 和 TerminalToolkit,增强 OWL Agent的工具调用、文件写入能力和终端命令执行功能。
  • [2025.03.09]: 我们添加了基于网页的用户界面,使系统交互变得更加简便。
  • [2025.03.07]: 我们开源了 🦉 OWL 项目的代码库。
  • [2025.03.03]: OWL 在 GAIA 基准测试中取得 58.18 平均分,在开源框架中排名第一!

🎬 演示视频

371254613005d51d73c82424e56a1d22.mp4
d106cfbff2c7b75978ee9d5631ebeb75.mp4

✨️ 核心功能

  • 在线搜索:使用维基百科、谷歌搜索等,进行实时信息检索
  • 多模态处理:支持互联网或本地视频、图片、语音处理
  • 浏览器操作:借助Playwright框架开发浏览器模拟交互,支持页面滚动、点击、输入、下载、历史回退等功能
  • 文件解析:word、excel、PDF、PowerPoint信息提取,内容转文本/Markdown
  • 代码执行:编写python代码,并使用解释器运行
  • 丰富工具包:提供丰富的工具包,包括ArxivToolkit(学术论文检索)、AudioAnalysisToolkit(音频分析)、CodeExecutionToolkit(代码执行)、DalleToolkit(图像生成)、DataCommonsToolkit(数据共享)、ExcelToolkit(Excel处理)、GitHubToolkit(GitHub交互)、GoogleMapsToolkit(地图服务)、GoogleScholarToolkit(学术搜索)、ImageAnalysisToolkit(图像分析)、MathToolkit(数学计算)、NetworkXToolkit(图形分析)、NotionToolkit(Notion交互)、OpenAPIToolkit(API操作)、RedditToolkit(Reddit交互)、SearchToolkit(搜索服务)、SemanticScholarToolkit(语义学术搜索)、SymPyToolkit(符号计算)、VideoAnalysisToolkit(视频分析)、WeatherToolkit(天气查询)、BrowserToolkit(网页交互)等多种专业工具,满足各类特定任务需求。

🛠️ 安装

选项1:使用 uv(推荐)

# 克隆 GitHub 仓库
git clone https://github.com/camel-ai/owl.git

# 进入项目目录
cd owl

# 如果你还没有安装 uv,请先安装
pip install uv

# 创建虚拟环境并安装依赖
# 我们支持使用 Python 3.10、3.11、3.12
uv venv .venv --python=3.10

# 激活虚拟环境
# 对于 macOS/Linux
source .venv/bin/activate
# 对于 Windows
.venv\Scripts\activate

# 安装 CAMEL 及其所有依赖
uv pip install -e .

# 完成后退出虚拟环境
deactivate

选项2:使用 venv 和 pip

# 克隆 GitHub 仓库
git clone https://github.com/camel-ai/owl.git

# 进入项目目录
cd owl

# 创建虚拟环境
# 对于 Python 3.10(也适用于 3.11、3.12)
python3.10 -m venv .venv

# 激活虚拟环境
# 对于 macOS/Linux
source .venv/bin/activate
# 对于 Windows
.venv\Scripts\activate

# 从 requirements.txt 安装
pip install -r requirements.txt

选项3:使用 conda

# 克隆 GitHub 仓库
git clone https://github.com/camel-ai/owl.git

# 进入项目目录
cd owl

# 创建 conda 环境
conda create -n owl python=3.10

# 激活 conda 环境
conda activate owl

# 选项1:作为包安装(推荐)
pip install -e .

# 选项2:从 requirements.txt 安装
pip install -r requirements.txt

# 完成后退出 conda 环境
conda deactivate

设置环境变量

OWL 需要各种 API 密钥来与不同的服务进行交互。owl/.env_template 文件包含了所有必要 API 密钥的占位符,以及可以注册这些服务的链接。

选项 1:使用 .env 文件(推荐)

  1. 复制并重命名模板

    cd owl
    cp .env_template .env
  2. 配置你的 API 密钥: 在你喜欢的文本编辑器中打开 .env 文件,并在相应字段中插入你的 API 密钥。

    注意:对于最小示例(run_mini.py),你只需要配置 LLM API 密钥(例如,OPENAI_API_KEY)。

选项 2:直接设置环境变量

或者,你可以直接在终端中设置环境变量:

  • macOS/Linux (Bash/Zsh)

    export OPENAI_API_KEY="你的-openai-api-密钥"
  • Windows (命令提示符)

    set OPENAI_API_KEY="你的-openai-api-密钥"
  • Windows (PowerShell)

    $env:OPENAI_API_KEY = "你的-openai-api-密钥"

注意:直接在终端中设置的环境变量仅在当前会话中有效。

使用Docker运行

如果您希望使用Docker运行OWL项目,我们提供了完整的Docker支持:

# 克隆仓库
git clone https://github.com/camel-ai/owl.git
cd owl

# 配置环境变量
cp owl/.env_template owl/.env
# 编辑.env文件,填入您的API密钥

# 选项1:直接使用docker-compose
cd .container
docker-compose up -d
# 在容器中运行OWL
docker-compose exec owl bash -c "xvfb-python run.py"

# 选项2:使用提供的脚本构建和运行
cd .container
chmod +x build_docker.sh
./build_docker.sh
# 在容器中运行OWL
./run_in_docker.sh "您的问题"

更多详细的Docker使用说明,包括跨平台支持、优化配置和故障排除,请参阅 DOCKER_README.md

🚀 快速开始

运行以下示例:

python owl/run.py

我们还提供了一个最小化示例,只需配置LLM的API密钥即可运行:

python owl/run_mini.py

使用不同的模型

模型要求

  • 工具调用能力:OWL 需要具有强大工具调用能力的模型来与各种工具包交互。模型必须能够理解工具描述、生成适当的工具调用,并处理工具输出。

  • 多模态理解能力:对于涉及网页交互、图像分析或视频处理的任务,需要具备多模态能力的模型来解释视觉内容和上下文。

支持的模型

有关配置模型的信息,请参阅我们的 CAMEL 模型文档

注意:为获得最佳性能,我们强烈推荐使用 OpenAI 模型(GPT-4 或更高版本)。我们的实验表明,其他模型在复杂任务和基准测试上可能表现明显较差,尤其是那些需要多模态理解和工具使用的任务。

OWL 支持多种 LLM 后端,但功能可能因模型的工具调用和多模态能力而异。您可以使用以下脚本来运行不同的模型:

# 使用 Qwen 模型运行
python owl/run_qwen_zh.py

# 使用 Deepseek 模型运行
python owl/run_deepseek_zh.py

# 使用其他 OpenAI 兼容模型运行
python owl/run_openai_compatiable_model.py

# 使用 Ollama 运行
python owl/run_ollama.py

你可以通过修改 run.py 脚本来运行自己的任务:

# Define your own task
question = "Task description here."

society = construct_society(question)
answer, chat_history, token_count = run_society(society)

print(f"\033[94mAnswer: {answer}\033[0m")

上传文件时,只需提供文件路径和问题:

# 处理本地文件(例如,文件路径为 `tmp/example.docx`)
question = "给定的 DOCX 文件中有什么内容?文件路径如下:tmp/example.docx"

society = construct_society(question)
answer, chat_history, token_count = run_society(society)

print(f"答案:{answer}")

OWL 将自动调用与文档相关的工具来处理文件并提取答案。

你可以尝试以下示例任务:

  • "查询苹果公司的最新股票价格"
  • "分析关于气候变化的最新推文情绪"
  • "帮我调试这段 Python 代码:[在此粘贴你的代码]"
  • "总结这篇研究论文的主要观点:[论文URL]"

🧰 工具包与功能

重要提示:有效使用工具包需要具备强大工具调用能力的模型。对于多模态工具包(Web、图像、视频),模型还必须具备多模态理解能力。

OWL支持多种工具包,可通过修改脚本中的tools列表进行自定义:

# 配置工具包
tools = [
    *BrowserToolkit(headless=False).get_tools(),  # 浏览器自动化
    *VideoAnalysisToolkit(model=models["video"]).get_tools(),
    *AudioAnalysisToolkit().get_tools(),  # 需要OpenAI API密钥
    *CodeExecutionToolkit(sandbox="subprocess").get_tools(),
    *ImageAnalysisToolkit(model=models["image"]).get_tools(),
    SearchToolkit().search_duckduckgo,
    SearchToolkit().search_google,  # 如果不可用请注释
    SearchToolkit().search_wiki,
    *ExcelToolkit().get_tools(),
    *DocumentProcessingToolkit(model=models["document"]).get_tools(),
    *FileWriteToolkit(output_dir="./").get_tools(),
]

主要工具包

关键工具包包括:

多模态工具包(需要模型具备多模态能力)

  • BrowserToolkit:浏览器自动化,用于网页交互和导航
  • VideoAnalysisToolkit:视频处理和内容分析
  • ImageAnalysisToolkit:图像分析和解释

基于文本的工具包

  • AudioAnalysisToolkit:音频处理(需要 OpenAI API)
  • CodeExecutionToolkit:Python 代码执行和评估
  • SearchToolkit:网络搜索(Google、DuckDuckGo、维基百科)
  • DocumentProcessingToolkit:文档解析(PDF、DOCX等)

其他专用工具包:ArxivToolkit、GitHubToolkit、GoogleMapsToolkit、MathToolkit、NetworkXToolkit、NotionToolkit、RedditToolkit、WeatherToolkit等。完整工具包列表请参阅CAMEL工具包文档

自定义配置

自定义可用工具的方法:

# 1. 导入工具包
from camel.toolkits import BrowserToolkit, SearchToolkit, CodeExecutionToolkit

# 2. 配置工具列表
tools = [
    *BrowserToolkit(headless=True).get_tools(),
    SearchToolkit().search_wiki,
    *CodeExecutionToolkit(sandbox="subprocess").get_tools(),
]

# 3. 传递给助手代理
assistant_agent_kwargs = {"model": models["assistant"], "tools": tools}

选择必要的工具包可优化性能并减少资源使用。

🌐 网页界面

OWL 现在包含一个基于网页的用户界面,使与系统交互变得更加容易。要启动网页界面,请运行:

# 中文版本
python run_app_zh.py

# 英文版本
python run_app.py

网页界面提供以下功能:

  • 便捷的模型选择:选择不同的模型(OpenAI、Qwen、DeepSeek等)
  • 环境变量管理:直接从界面配置API密钥和其他设置
  • 交互式聊天界面:通过用户友好的界面与OWL智能体交流
  • 任务历史:查看交互的历史记录和结果

网页界面使用Gradio构建,在您的本地机器上运行。除了您配置的模型API调用所需的数据外,不会向外部服务器发送任何数据。

🧪 实验

我们提供了一个脚本用于复现 GAIA 上的实验结果。 要复现我们在 GAIA 基准测试中获得的 58.18 分:

  1. 切换到 gaia58.18 分支:
git checkout gaia58.18
  1. 运行评估脚本:
python run_gaia_roleplaying.py

⏱️ 未来计划

我们正在不断努力改进 OWL。以下是我们的路线图:

  • 撰写技术博客,详细介绍我们在现实任务中多智能体协作方面的探索与见解
  • 通过引入更多针对特定领域任务的专业工具,进一步完善工具生态系统
  • 开发更复杂的智能体交互模式和通信协议
  • 提高复杂多步推理任务的性能

📄 许可证

源代码采用 Apache 2.0 许可证。

🖊️ 引用

如果你觉得这个仓库对你有帮助,请引用:

@misc{owl2025,
  title        = {OWL: Optimized Workforce Learning for General Multi-Agent Assistance in Real-World Task Automation},
  author       = {{CAMEL-AI.org}},
  howpublished = {\url{https://github.com/camel-ai/owl}},
  note         = {Accessed: 2025-03-07},
  year         = {2025}
}

🤝 贡献

我们欢迎社区的贡献!以下是您可以提供帮助的方式:

  1. 阅读我们的贡献指南
  2. 查看开放的问题或创建新的问题
  3. 提交包含您改进的拉取请求

当前开放贡献的问题:

要认领一个问题,只需在该问题下留言表明您的兴趣即可。

🔥 社区

加入我们的 (Discord微信) 社区,一起探索智能体扩展规律的边界。

加入我们,参与更多讨论!

❓ 常见问题

Q: 为什么启动示例脚本后,我没有看到本地运行Chrome浏览器?

A: 当OWL判断某个任务可以使用非浏览器工具(如搜索、代码分析等)完成时,浏览器就不会启动。只有在判断需要使用浏览器工具的时候,本地才会弹出浏览器窗口,并进行浏览器模拟交互。

Q: 我应该使用哪个Python版本?

A: OWL支持Python 3.10、3.11和3.12。为了与所有依赖项获得最佳兼容性,我们推荐使用Python 3.10。

Q: 我如何为项目做贡献?

A: 请参阅我们的贡献部分,了解如何参与的详细信息。我们欢迎各种形式的贡献,从代码改进到文档更新。

📚 探索 CAMEL 依赖

OWL 是基于 CAMEL 框架构建的,以下是如何探索 CAMEL 源代码并了解其与 OWL 的工作方式:

访问 CAMEL 源代码

# 克隆 CAMEL 仓库
git clone https://github.com/camel-ai/camel.git
cd camel

⭐ Star History

Star History Chart