可执行代码动作催生更优秀的 LLM 代理

📃 论文 • 🤗 数据 (CodeActInstruct) • 🤗 模型 (CodeActAgent-Mistral-7b-v0.1) • 🤖 与 CodeActAgent 聊天！

我们提出使用可执行的代码来将 LLM 代理的动作整合进统一的动作空间（CodeAct）。 通过与 Python 解释器集成，CodeAct 能够执行代码动作，并在多轮交互中根据新的观测结果（例如代码执行结果）动态修正先前动作或发出新动作（请查看这个示例！）。

新闻

2024年4月10日：CodeActAgent Mistral 已经正式在 ollama 上发布！

2024年3月11日：我们还增加了对 llama.cpp 的支持，以便在笔记本电脑上运行 CodeActAgent（已在 MacOS 上测试），请参阅此处的说明！

2024年3月11日：我们现在支持通过 Kubernetes 部署 CodeActAgent 的所有组件（LLM 服务、代码执行器、MongoDB、聊天界面）！请查看这篇指南！

2024年2月2日：CodeAct 正式发布！

为什么选择 CodeAct？

我们在 API-Bank 上对 17 种 LLM 以及一个新整理的基准测试集 M³ToolEval 进行了深入分析，结果显示 CodeAct 在成功率方面优于广泛使用的文本和 JSON 等替代方案（最高可高出 20%）。更多详细分析请参阅我们的论文！

CodeAct 与文本/JSON 作为动作方式的比较。

在 M³ToolEval 上对比 CodeAct 与 {文本、JSON} 的量化结果。

📁 CodeActInstruct

我们收集了一个指令微调数据集 CodeActInstruct，包含 7,000 条使用 CodeAct 的多轮对话。该数据集已在 huggingface 数据集 🤗 上发布。有关数据收集的详细信息，请参阅论文及本节。

数据集统计。标记统计使用 Llama-2 分词器计算。

🪄 CodeActAgent

CodeActAgent 基于 CodeActInstruct 和通用对话进行训练，在同类规模的开源模型中，其跨领域代理任务表现尤为出色，同时并未牺牲通用性能（如知识储备、对话能力等）。我们发布了两个版本的 CodeActAgent：

• CodeActAgent-Mistral-7b-v0.1（推荐，模型链接）：以 Mistral-7b-v0.1 为基础模型，上下文窗口为 32k。
• CodeActAgent-Llama-7b（模型链接）：以 Llama-2-7b 为基础模型，上下文窗口为 4k。

CodeActAgent 的评估结果。ID 和 OD 分别代表域内和域外评估。总体平均性能将 MT-Bench 得分标准化，使其与其他任务保持一致，并排除域内任务以确保公平比较。

有关数据收集、模型训练、评估等方面的更多细节，请参阅:page_with_curl: 我们的论文！

🚀 将 CodeActAgent 应用于您的应用！

聊天界面演示。

一个 CodeActAgent 系统包含以下组件：

• LLM 服务：我们以 vLLM 为例，但任何能够将模型部署为 OpenAI 兼容 API 的服务软件均可。
• 交互界面：
  • 通过聊天界面 + MongoDB 存储聊天记录
  • 或者 使用简单的 Python 脚本
• 代码执行引擎：该服务将启动一个 API，接收来自聊天界面或 Python 脚本的代码执行请求，然后为 每 次聊天会话启动一个独立的 Docker 容器来执行代码。

🌟 如果您拥有 Kubernetes 集群：您可以按照我们的Kubernetes 部署指南，只需一条命令即可启动所有这些组件！

请按照以下指南使用 Docker 进行设置。

将模型部署为 OpenAI 兼容 API

使用 VLLM 通过 Docker（需要 nvidia-docker）

# 首先下载模型，以下是 CodeActAgent-Mistral 的示例
cd $YOUR_DIR_TO_DOWNLOADED_MISTRAL_MODEL
git lfs install
git clone https://huggingface.co/xingyaoww/CodeActAgent-Mistral-7b-v0.1
./scripts/chat/start_vllm.sh $YOUR_DIR_TO_DOWNLOADED_MISTRAL_MODEL/CodeActAgent-Mistral-7b-v0.1
# 或者
# ./scripts/chat_ui/start_vllm.sh $YOUR_DIR_TO_DOWNLOADED_LLAMA_MODEL/CodeActAgent-Llama-7b

此脚本（需要 Docker）将基于 CUDA_VISIBLE_DEVICES 将模型托管到端口 8080，您可以通过 http://localhost:8080/v1 的 OPENAI_API_BASE 访问模型（默认设置）。有关详细说明，请参阅 OpenAI API 的官方文档。您也可以参考 vLLM 的官方说明以获取更多信息。

使用 LLama.cpp（适用于笔记本电脑！）

此方法已在 MacOS（M2 Max，Ventura 13.6）上测试过。

安装 LLama.cpp

git clone https://github.com/ggerganov/llama.cpp.git
# 可选：创建一个 conda 环境进行安装
conda create -n llamacpp python=3.10
# 安装 llama cpp 的依赖项
cd llama.cpp
conda activate llamacpp
pip install -r requirements.txt
# 构建（详情请参阅 https://github.com/ggerganov/llama.cpp?tab=readme-ov-file#build）
make

(可选) 将模型转换为 gguf 格式

或者，您也可以跳过以下步骤，直接下载预转换好的量化版本（q8_0）在这里。

# 如果尚未下载模型，请先下载
git lfs install
git clone https://huggingface.co/xingyaoww/CodeActAgent-Mistral-7b-v0.1
# 假设您当前位于 llama.cpp 目录下
python convert.py ./CodeActAgent-Mistral-7b-v0.1 --outtype f16 --outfile CodeActAgent-Mistral-7b-v0.1.f16.gguf

# （可选）量化以加快推理速度
./quantize CodeActAgent-Mistral-7b-v0.1.f16.gguf CodeActAgent-Mistral-7b-v0.1.q8_0.gguf Q8_0

部署为兼容 OpenAI 的 API

有关参数的详细说明，请参阅 此处。

./server -m CodeActAgent-Mistral-7b-v0.1.q8_0.gguf -c 8192 --port 8080

现在，您可以通过 http://localhost:8080/v1 访问兼容 OpenAI 的服务器，模型名称为 CodeActAgent-Mistral-7b-v0.1.q8_0.gguf。在下一部分的交互界面中（无论是聊天 UI 配置文件还是 Python 脚本），您需要将模型名称从 CodeActAgent-Mistral-7b-v0.1 更改为 CodeActAgent-Mistral-7b-v0.1.q8_0.gguf！

（可选）测试 OpenAI 兼容 API 是否正常工作

curl -X POST 'http://localhost:8080/v1/chat/completions' -d '{
  "model": "CodeActAgent-Mistral-7b-v0.1.q8_0.gguf",
  "messages": [
      {"role": "system", "content": "你是一个 helpful assistant。"},
      {"role": "user", "content": "如何搭建一个网站？"}
  ]
}'

启动您的代码执行引擎！

我们基于 JupyterKernelGateway 实现了一个容器化的代码执行引擎。其核心思想是为每个聊天会话启动一个 Docker 容器 内的 Jupyter 服务器，以支持来自模型的代码执行请求（该会话将在设定的时间后超时）。这需要本地已安装 Docker。

# 在 8081 端口启动代码执行服务器
./scripts/chat/code_execution/start_jupyter_server.sh 8081

与系统互动！

通过简单的 Python 脚本

如果您不想搭建复杂的界面，只想在命令行上简单体验一下，我们已经为您准备好了！

# 在运行此脚本之前，请确保已启动模型服务器（vLLM 或 llama.cpp）和代码执行引擎！
python3 scripts/chat/demo.py --model_name xingyaoww/CodeActAgent-Mistral-7b-v0.1 --openai_api_base http://$YOUR_API_HOST:$YOUR_API_PORT/v1 --jupyter_kernel_url http://$YOUR_CODE_EXEC_ENGINE_HOST:$YOUR_CODE_EXEC_ENGINE_PORT/execute

通过 Chat-UI

如果您已经部署了模型和代码执行引擎，就可以像 这个 一样运行您自己的聊天界面！

如果需要用户管理功能，您可能需要启动自己的 MongoDB 实例：

./scripts/chat/start_mongodb.sh $YOUR_MONGO_DB_PASSWORD
# 数据库将创建在 pwd/data/mongodb 目录下，并可通过 localhost:27017 访问

然后，您可以配置您的 Chat-UI 界面。

cp chat-ui/.env.template chat-ui/.env.local
# 请务必根据您的实际情况修改 .env.local 文件：
# 1. JUPYTER_API_URL
# 2. 模型端点（搜索 'TODO_OPENAI_BASE_URL'）；
#    如果您使用 llama.cpp 推理模型，还需将模型名称更改为 CodeActAgent-Mistral-7b-v0.1.q8_0.gguf
# 3. MONGODB_URL - 您可以留空，Chat-UI 会自动启动一个数据库（但容器停止后该数据库将被删除）

现在，您可以构建并启动您自己的 Web 应用程序（需使用 Docker）！

./scripts/chat/run_chat_ui.sh
# 默认会在 localhost:5173 启动界面

# 运行此脚本以进入调试模式
# ./scripts/chat/run_chat_ui_debug.sh

如需更多信息（例如不使用 Docker 的情况），请查看 Chat-UI 的 文档！

🎥 复现论文中的实验

git clone https://github.com/xingyaoww/code-act
# 克隆所有子模块
git submodule update --init --recursive

📂 数据生成（可选）

推荐： 您可以从 Hugging Face 数据集 🤗 下载处理好的 CodeActInstruct 数据集。

为复现实验： 您也可以按照 docs/DATA_GENERATION.md 中的说明，自行生成交互数据。

📘 模型训练

我们使用 Megatron-LLM 的一个分支进行训练。详细的训练步骤请参考 docs/MODEL_TRAINING.md。

📊 评估

详细的评估方法请参阅 docs/EVALUATION.md。

📚 引用

@inproceedings{wang2024executable,
      title={Executable Code Actions Elicit Better LLM Agents}, 
      author={Xingyao Wang and Yangyi Chen and Lifan Yuan and Yizhe Zhang and Yunzhu Li and Hao Peng and Heng Ji},
      year={2024},
      eprint={2402.01030},
      booktitle={ICML}
}

CodeAct 快速上手指南

CodeAct 是一个通过可执行代码统一大语言模型（LLM）智能体动作空间的框架。它结合 Python 解释器，支持多轮交互、动态修正动作及执行代码，在复杂任务中表现优于传统的 Text 或 JSON 动作格式。

环境准备

系统要求

• 操作系统: Linux (推荐), macOS (支持 llama.cpp 本地运行), Windows (需 WSL2)
• GPU: NVIDIA GPU (推荐使用 vLLM 部署时)，显存建议 16GB+ (运行 7B 模型)
• CPU: 若使用 llama.cpp 在笔记本运行，建议较新的多核 CPU (如 Apple M 系列)

前置依赖

请确保已安装以下工具：

• Docker & Docker Compose (用于隔离代码执行环境和部署服务)
• NVIDIA Docker (若使用 GPU 加速推理，参考 nvidia-docker)
• Git & Git LFS (用于下载模型权重)
• Python 3.10+ (用于运行脚本和数据处理)
• Conda (可选，用于管理 llama.cpp 环境)

国内加速提示：

• 下载 HuggingFace 模型较慢时，建议使用镜像站 hf-mirror.com。
• 设置环境变量：export HF_ENDPOINT=https://hf-mirror.com

---

安装步骤

1. 克隆项目

git clone https://github.com/xingyaoww/code-act
cd code-act
git submodule update --init --recursive

2. 下载模型

推荐使用 CodeActAgent-Mistral-7b-v0.1 (支持 32k 上下文)。

# 设置国内镜像加速 (可选)
export HF_ENDPOINT=https://hf-mirror.com

git lfs install
git clone https://huggingface.co/xingyaoww/CodeActAgent-Mistral-7b-v0.1
# 模型将下载到当前目录下的 CodeActAgent-Mistral-7b-v0.1 文件夹

(可选) 若需在笔记本使用 llama.cpp 运行，可下载量化版本:

git clone https://huggingface.co/xingyaoww/CodeActAgent-Mistral-7b-v0.1.q8_0.gguf

---

基本使用

本指南演示最核心的三种组件启动方式：模型服务、代码执行引擎、交互界面。

第一步：启动模型服务 (LLM Serving)

选择以下任一方式启动模型，使其提供 OpenAI 兼容的 API。

方案 A：使用 vLLM (推荐，需 GPU)

此脚本会自动构建 Docker 容器并在端口 8080 启动服务。

# 替换为你的模型实际路径
MODEL_PATH=$(pwd)/CodeActAgent-Mistral-7b-v0.1

./scripts/chat/start_vllm.sh $MODEL_PATH

服务地址默认为：http://localhost:8080/v1

方案 B：使用 llama.cpp (适用于 MacBook/无 GPU 环境)

需先编译 llama.cpp (参考 README 中的详细编译步骤)，然后启动服务器：

# 假设已在 llama.cpp 目录下完成编译，且模型文件在同级目录
./server -m CodeActAgent-Mistral-7b-v0.1.q8_0.gguf -c 8192 --port 8080

注意：若使用此方案，后续配置中的模型名称需改为 CodeActAgent-Mistral-7b-v0.1.q8_0.gguf。

第二步：启动代码执行引擎

CodeAct 的核心能力是执行代码。该引擎会为每个会话启动独立的 Docker 容器运行 Jupyter Kernel。

# 在端口 8081 启动代码执行服务
./scripts/chat/code_execution/start_jupyter_server.sh 8081

第三步：开始交互

方式 1：命令行快速测试 (最简单)

无需配置前端，直接通过 Python 脚本对话。

python3 scripts/chat/demo.py \
  --model_name xingyaoww/CodeActAgent-Mistral-7b-v0.1 \
  --openai_api_base http://localhost:8080/v1 \
  --jupyter_kernel_url http://localhost:8081/execute

输入类似 "计算 100 以内的素数" 或 "画一个正弦波图" 的指令，观察模型生成并执行代码的过程。

方式 2：启动 Web 聊天界面 (Chat-UI)

若需要图形化界面（类似 ChatGPT）：

1. 配置环境变量

   cp chat-ui/.env.template chat-ui/.env.local
   

   编辑 chat-ui/.env.local，确保修改以下项：

   • JUPYTER_API_URL: http://localhost:8081/execute
   • OPENAI_BASE_URL: http://localhost:8080/v1 (搜索 TODO_OPENAI_BASE_URL 进行替换)
   • MODEL_NAME: 若使用 llama.cpp 量化模型，请填写 CodeActAgent-Mistral-7b-v0.1.q8_0.gguf，否则保持默认。

2. 启动界面

   ./scripts/chat/run_chat_ui.sh
   

   访问 http://localhost:5173 即可开始使用。

(可选) 如需保存聊天记录，可先启动 MongoDB:

./scripts/chat/start_mongodb.sh your_password