Moatless Tools

Moatless Tools 是一个兴趣项目，我在其中尝试一些关于如何利用大型语言模型（LLM）编辑大型现有代码库的想法。我认为，与其依赖代理自行推理出解决方案，不如构建优秀的工具来为提示注入正确的上下文，并妥善处理响应。

有关论文 SWE-Search: Enhancing Software Agents with Monte Carlo Tree Search and Iterative Refinement 中所使用的实现，请参阅 moatless-tree-search。

SWE-Bench

我使用 SWE-bench 基准测试 来验证我的想法。

• Claude 4 Sonnet - 解决率为70.8%，每次实例费用为0.63美元。

试用一下

在 Docker 中运行

1. 克隆仓库：

   git clone https://github.com/aorwall/moatless-tools.git
   cd moatless-tools
   

2. 设置环境变量：

   cp .env.example .env
   

   编辑 .env 文件以设置您的 API 密钥和其他配置选项，包括必需的 MOATLESS_DIR 变量：

   MOATLESS_DIR=/path/to/your/moatless/data
   

   注意：MOATLESS_DIR 指定了 Moatless 将存储配置文件和轨迹数据的目录。该目录将在 Docker 容器中作为卷挂载。

3. 启动服务：

   make run
   

4. 访问 UI：http://localhost

从 PyPI 安装

# 仅安装基础包
pip install moatless

# 安装支持 Kubernetes 运行器的版本
pip install "moatless[kubernetes]"

从源码安装

克隆仓库并使用 Poetry 安装

# 克隆仓库
git clone https://github.com/aorwall/moatless-tools.git
cd moatless-tools

# 使用 uv 安装依赖
uv sync

代码示例

基本代理流程

from moatless.actions import Respond
from moatless.agent import ActionAgent
from moatless.completion.tool_call import ToolCallCompletionModel

completion_model = ToolCallCompletionModel(
    model="gpt-4.1-mini",
    temperature=0.0,
    model_api_key=""
)

agent = ActionAgent(
    completion_model=completion_model,
    system_prompt="您是一位能够回答问题的助手。",
    actions=[
        Respond()
    ]
)

observation = await agent.run_simple("你好")

print(observation.message)

代码检查器代理

notebooks/code_inspector_agent.ipynb

运行 SWE-Bench 评估

在运行评估之前，您需要：

1. 至少一个 LLM 提供商的 API 密钥（例如 OpenAI、Anthropic 等）
2. 一个来自 voyageai.com 的 Voyage AI API 密钥，用于 SWE-Bench 实例的预嵌入向量存储。

验证设置

在运行完整评估之前，您可以先运行一个简单的 SWE-Bench 实例来验证您的设置。

uv run python scripts/docker_run.py  --flow swebench_tools --model-id gpt-4o-mini-2024-07-18 --instance-id django__django-11099 --evaluation-name testing_setup

该脚本将针对一个 SWE-Bench 示例实例运行模型。

结果会保存在 .moatless/projects/testing_setup 中。

运行评估

用于在 Docker 容器中运行评估的脚本。

python3 scripts/run_evaluation.py  --model gpt-4o-mini-2024-07-18 --dataset-split [dataset_split] --evaluation-name [evaluation_name]

必填参数：

• --dataset-split：要使用的数据集划分
• --evaluation-name：评估名称

可选参数：

• --model：用于评估的模型（默认为 gpt-4o-mini-2024-07-18，等同于 --model-id）
• --model-id：要使用的模型配置 ID（替换整个模型配置）
• --litellm-model-name：要覆盖的 LiteLLM 模型名称（保留其他模型设置）
• --flow：用于评估的流程（默认为 “simple_coding”）
• --num-parallel-jobs：并行作业数量（默认为 1）

流程

可通过 --flow 参数指定的可用流程：

流程 ID	格式	最适合场景	默认模型
swebench_tools	函数调用	支持原生函数调用的模型	gpt-4o-mini-2024-07-18
swebench_tools_and_reasoning	函数调用	支持原生函数调用的推理模型	claude-sonnet-4-20250514
swebench_react	ReACT	不支持原生函数调用的开源模型	openrouter/mistralai/devstral-small
swebench_react_reasoning	ReACT	不支持函数调用的推理模型	openrouter/deepseek/deepseek-r1-0528

模型配置

两个评估脚本都支持通过以下选项进行灵活的模型配置：

模型选项

• --model-id：指定完整的模型配置 ID。这将替换整个完成模型配置，包括温度、最大令牌数及其他所有设置。
• --litellm-model-name：仅覆盖 LiteLLM 模型名称，同时保留来自流程或模型配置的所有其他完成模型设置（温度、最大令牌数等）。

已验证模型

为已验证模型提供了默认的模型配置。请注意，其他模型可能也能工作，但尚未经过广泛测试。
已验证模型是指已在 SWE-Bench 数据集的 Verified Mini 子集 上进行测试并确认可用的模型。

当仅指定 --model-id 参数时，将使用以下配置：

模型	响应格式	消息历史	思考过程	Verified Mini
claude-3-5-sonnet-20241022	tool_call	messages	否	46%
claude-3-5-haiku-20241022	tool_call	messages	否	28%
gpt-4o-2024-11-20	tool_call	messages	是	32%
gpt-4o-mini-2024-07-18	tool_call	messages	是	16%
o1-mini-2024-09-12	react	react	否（禁用思考）	28%
deepseek/deepseek-chat	react	react	否	36%
deepseek/deepseek-reasoner	react	react	否（禁用思考）	50%
gemini/gemini-2.0-flash-exp	react	react	否	38%
openrouter/meta-llama/llama-3.1-70b-instruct	react	react	否	-
openrouter/meta-llama/llama-3.1-405b-instruct	react	react	否	28%
openrouter/qwen/qwen-2.5-coder-32b-instruct	react	react	否	32%

数据集划分

可通过 --dataset-split 参数指定的可用数据集划分如下：

划分名称	描述	实例数量
lite	lite 数据集中的所有实例	300
verified	verified 数据集中的所有实例	500
verified_mini	MariusHobbhahn/swe-bench-verified-mini，SWE-Bench Verified 的一个子集	50
lite_and_verified_solvable	同时存在于 lite 和 verified 数据集中，且至少有一份在 SWE-Bench 上被成功解决的提交的实例	84

使用示例

# 使用 Claude 3.5 Sonnet 运行评估，并采用完整的模型配置
python3 scripts/run_evaluation.py \
  --model-id claude-3-5-sonnet-20241022 \
  --flow swebench_tools_and_reasoning \
  --dataset-split verified_mini \
  --num-parallel-jobs 5

# 仅覆盖模型名称，同时保留流程的模型设置来运行评估
python3 scripts/run_evaluation.py \
  --litellm-model-name openrouter/qwen/qwen-2.5-coder-32b-instruct \
  --flow swebench_react \
  --dataset-split verified_mini \
  --num-parallel-jobs 5

Moatless Tools 快速上手指南

Moatless Tools 是一个专注于利用大语言模型（LLM）在大型现有代码库中进行代码编辑的实验性项目。其核心理念是通过构建高效的工具来精准注入上下文并处理响应，而非单纯依赖 Agent 自行推理。该项目常用于 SWE-Bench 基准测试。

环境准备

在开始之前，请确保满足以下要求：

• 操作系统: Linux 或 macOS（Windows 用户建议使用 WSL2 或 Docker Desktop）。
• Docker: 推荐使用 Docker 运行以获得最完整的体验（包含向量存储等服务）。
• Python 环境: 若选择本地安装，需 Python 3.10+。
• API Keys:
  • 至少一个大模型提供商的 API Key（如 OpenAI, Anthropic, DeepSeek 等）。
  • Voyage AI API Key: 用于 SWE-Bench 评估时加载预嵌入的向量存储（必需）。
• 包管理工具 (可选但推荐):
  • uv: 用于从源码快速安装。
  • poetry: 项目原生依赖管理工具。

国内开发者提示: 如果遇到网络连接问题，建议配置 Docker 镜像加速器，或在 pip/uv 安装时使用国内镜像源（如清华源、阿里源）。

安装步骤

你可以选择以下三种方式之一进行安装：

方式一：使用 Docker 运行（推荐）

这是最简单且功能最完整的方式，自动处理所有依赖和服务。

1. 克隆仓库:

   git clone https://github.com/aorwall/moatless-tools.git
   cd moatless-tools
   

2. 配置环境变量:

   cp .env.example .env
   

   编辑 .env 文件，填入你的 API Key 并配置数据目录：

   # 示例内容
   ANTHROPIC_API_KEY=your_key_here
   OPENAI_API_KEY=your_key_here
   VOYAGE_API_KEY=your_key_here
   
   # 指定本地数据持久化目录
   MOATLESS_DIR=/path/to/your/moatless/data
   

3. 启动服务:

   make run
   

   启动完成后，访问 http://localhost 即可使用 UI 界面。

方式二：通过 PyPI 安装

适用于仅需 Python 包功能的场景。

# 仅安装基础包
pip install moatless

# 如需 Kubernetes 运行器支持
pip install "moatless[kubernetes]"

方式三：从源码安装 (使用 uv)

适合需要修改代码或贡献项目的开发者。

git clone https://github.com/aorwall/moatless-tools.git
cd moatless-tools

# 使用 uv 同步依赖
uv sync

基本使用

1. 运行简单的 Agent 流程

以下是一个基于 Python 的最小化示例，展示如何创建一个能够回答问题的简单 Agent。

from moatless.actions import Respond
from moatless.agent import ActionAgent
from moatless.completion.tool_call import ToolCallCompletionModel

# 初始化模型配置
completion_model = ToolCallCompletionModel(
    model="gpt-4.1-mini",
    temperature=0.0,
    model_api_key="" # 在此处填入你的 API Key 或通过环境变量设置
)

# 创建 Agent
agent = ActionAgent(
    completion_model=completion_model,
    system_prompt="You are a helpful assistant that can answer questions.",
    actions=[
        Respond()
    ]
)

# 运行并获取结果
observation = await agent.run_simple("Hello")

print(observation.message)

2. 运行 SWE-Bench 评估验证

在安装完成后，建议先运行一个单例测试来验证环境配置是否正确。

验证命令:

uv run python scripts/docker_run.py  --flow swebench_tools --model-id gpt-4o-mini-2024-07-18 --instance-id django__django-11099 --evaluation-name testing_setup

• 该脚本将针对一个样本 SWE-Bench 实例运行模型。
• 结果将保存在 .moatless/projects/testing_setup 目录中。

正式评估命令: 若需批量运行评估，可使用以下脚本：

python3 scripts/run_evaluation.py  --model gpt-4o-mini-2024-07-18 --dataset-split verified_mini --evaluation-name my_eval

常用参数说明:

• --model-id: 指定预设的模型配置 ID（如 claude-3-5-sonnet-20241022）。
• --flow: 指定工作流模式。
  • swebench_tools: 适用于支持原生 Function Calling 的模型。
  • swebench_react: 适用于不支持原生 Function Calling 的开源模型。
• --dataset-split: 数据集分区，推荐初学者使用 verified_mini (50 个实例) 进行快速测试。
• --num-parallel-jobs: 并行任务数，加速评估过程。