Qwen-Agent DeepPlanning 基准实战：可验证约束下的长程 Agent 规划能力评测

Qwen-Agent DeepPlanning 基准实战：可验证约束下的长程 Agent 规划能力评测

【免费下载链接】Qwen-AgentAgent framework and applications built upon Qwen>=3.0, featuring Function Calling, MCP, Code Interpreter, RAG, Chrome extension, etc.项目地址: https://gitcode.com/GitHub_Trending/qw/Qwen-Agent

DeepPlanning 是 Qwen-Agent 仓库内置的一个面向长程（long-horizon）Agent 规划能力的评测基准，围绕"多日旅行规划"与"多商品购物规划"两大真实场景，考察 Agent 在信息主动获取、局部约束推理与全局约束优化三个维度的表现。本文将结合仓库中的基准文档与benchmark/deepplanning目录下的源码实现，从基准设计理念、任务统计、三大核心能力、统一运行编排到各域独立运行与结果指标解读，给出可复制、可运行的完整实战指南。

DeepPlanning 基准的提出背景

现有 Agent 评测虽然已逐渐转向长程任务，但绝大多数基准仍侧重于局部的、单步的推理能力，而非真正规划能力所要求的全局约束优化（例如时间预算与财务预算的联合优化）。与此同时，既有的 LLM 规划基准往往低估了真实世界中普遍存在的主动信息获取与细粒度局部约束。DeepPlanning 正是为了弥合这一差距而设计：它是一个面向实用长程 Agent 规划的挑战性基准，包含多日旅行规划与多商品购物规划两类任务，要求 Agent 同时具备主动信息获取、局部约束推理与全局约束优化能力。评测结果表明，即使是前沿的 Agent 型 LLM 在这些任务上依然表现吃力，这凸显了可靠显式推理模式与并行工具调用在"效果-效率"权衡中的重要性。

如上图所示，DeepPlanning 的评测流水线包含五个环节：分层任务生成（在基础骨架之上注入个性化约束与环境约束）、用户查询、Agent 轨迹（Agent 调用专用 API 主动收集信息）、规划报告（结构化输出）与自动评估（按常识约束与个性化约束打分）。

基准总体设计一览

DeepPlanning 覆盖两个现实且长程的场景，两者都要求 Agent 在严格可验证的全局约束下探索复杂环境。下表是基准的统计概览（源自 benchmarks/deepplanning/index.mdx）：

从 benchmark/deepplanning 目录的源码结构看，两个域都实现了完整的"推理（inference）→ 评估（evaluation）"流水线，并统一由根目录的 run_all.sh 编排，最终通过 aggregate_results.py 跨域聚合出单一总分。

域一：旅行规划（Travel Planning）

Agent 扮演私人旅行助手，组织多日行程，其中时间、地点与预算紧密耦合：

• 输入：自然语言查询（目的地、日期、预算）及具体偏好（例如"带烘干机的三星级酒店"）。
• 工具：9 个用于搜索航班、火车、酒店、餐厅与景点的 API。对应源码位于 benchmark/deepplanning/travelplanning/tools，包括flight_query_tool（航班）、train_query_tool（火车）、hotel_query_tool（酒店）、restaurant_query_tool（餐厅）、attraction_query_tool（景点）、location_search_tool（地点检索）与roadroute_query_tool（道路路线）等。
• 输出：结构化的规划报告，包含逐项成本与分钟级时刻表。
• 核心技能：时空推理——确保航班时刻、景点开放时间与交通耗时相互对齐，无重叠、无超支。

任务数据存放于 benchmark/deepplanning/travelplanning/data，包括travelplanning_query_zh.json（中文任务）与travelplanning_query_en.json（英文任务）。

域二：购物规划（Shopping Planning）

Agent 需要求解一个组合优化问题：在最大化折扣效用的前提下找到最优商品组合：

• 输入：带有详细属性要求与总预算上限的购物清单。
• 工具：15 个用于语义搜索、多属性过滤与优惠券管理的 API。对应源码位于 benchmark/deepplanning/shoppingplanning/tools，涵盖search_products_tool（商品搜索）、get_product_details_tool（商品详情）、filter_by_brand_tool/filter_by_color_tool/filter_by_size_tool/filter_by_range_tool（按品牌、颜色、尺码、价格区间过滤）、add_product_to_cart_tool/delete_product_from_cart_tool（购物车管理）、add_coupon_to_cart_tool/delete_coupon_from_cart_tool（优惠券管理）、get_cart_info与get_user_info等。
• 输出：包含最优商品集合与已用优惠券的结构化 JSON 购物车。
• 核心技能：组合优化——计算复杂的优惠券叠加规则（例如跨店 vs 同品牌），实现绝对最低的最终价格。

购物任务按难度划分为三个层级（Level 1/2/3），查询元数据分别存放在 benchmark/deepplanning/shoppingplanning/data 下的level_1_query_meta.json、level_2_query_meta.json与level_3_query_meta.json。

DeepPlanning 评测的三大核心规划能力

DeepPlanning 系统性地考察 Agent 的三项关键能力：

1. 主动信息获取（Proactive Information Acquisition）：主动调用 API 去发现隐藏的环境状态（例如景点是否闭园、商品是否有货），而不是凭空臆造事实。从框架图中可以看到，Agent 会先调用query_flight_info、recommend_attractions等工具获取候选信息，再基于结果决定下一步动作。
2. 局部约束推理（Local Constrained Reasoning）：满足单步逻辑约束，例如匹配用户指定的品牌、尺码或酒店设施。
3. 全局约束优化（Global Constrained Optimization）：管理整体边界——如总预算上限与多日时间可行性，其中任何一处局部失误都会导致整个方案失效。

快速上手：统一运行 DeepPlanning 基准

benchmark/deepplanning/README.md 提供了统一编排（Unified Run）的推荐路径，可直接复现论文中的实验结果；两个域也可独立运行（分别见 travelplanning/README.md 与 shoppingplanning/README.md）。以下六步为统一运行流程。

第一步：安装依赖

基准根目录提供了统一的依赖清单 requirements.txt，建议使用 Python 3.10：

conda create -n deepplanning python=3.10 -y conda activate deepplanning pip install -r requirements.txt

依赖包含核心 Agent 包qwen-agent>=0.0.10、openai>=1.0.0（同时支持 OpenAI 与 DashScope 兼容接口）、dashscope>=1.11.0、数据处理的pandas/numpy、购物搜索所用的rank-bm25，以及旅行域转换与校验所需的json5、jsonschema、pydantic等。

第二步与第三步：下载并解压数据库

需要先从 DeepPlanning 数据集（Hugging Face 上的 Qwen/DeepPlanning）下载数据库压缩包，放置到对应目录：

• 购物域：将database_level1.tar.gz、database_level2.tar.gz、database_level3.tar.gz放入shoppingplanning/database_zip/；
• 旅行域：将database_zh.zip、database_en.zip放入travelplanning/database/。

随后解压：

# 解压购物数据库 cd shoppingplanning/database_zip tar -xzf database_level1.tar.gz -C .. tar -xzf database_level2.tar.gz -C .. tar -xzf database_level3.tar.gz -C .. cd ../.. # 解压旅行数据库（中文库含航班、酒店、餐厅、景点数据） cd travelplanning/database unzip database_zh.zip unzip database_en.zip cd ../..

第四步：配置模型

编辑基准根目录下的 models_config.json，添加被测模型。仓库自带配置示例如下：

{ "models": { "qwen-plus": { "model_name": "qwen-plus", "model_type": "openai", "base_url": "https://dashscope.aliyuncs.com/compatible-mode/v1", "api_key_env": "DASHSCOPE_API_KEY", "temperature": 0.0 }, "qwen3-max": { "model_name": "qwen3-max", "model_type": "openai", "base_url": "https://dashscope.aliyuncs.com/compatible-mode/v1", "api_key_env": "DASHSCOPE_API_KEY", "temperature": 0.0 }, "gpt-4o-2024-11-20": { "model_name": "gpt-4o-2024-11-20", "model_type": "openai", "base_url": "https://api.openai.com/v1/models", "api_key_env": "OPENAI_API_KEY", "temperature": 0.0 } } }

配置项说明（可结合 travelplanning/agent/call_llm.py 的加载逻辑理解）：

• model_name：实际传给 API 的模型标识，缺省时回退为配置键名；
• model_type：目前支持openai（OpenAI 及其兼容接口，如 Qwen、DeepSeek）；
• base_url：API 端点地址；
• api_key_env：读取 API Key 的环境变量名，缺失时 create_client 会直接抛错；
• temperature：采样温度，基准建议设为0.0以保证结果可复现；
• 可选参数还包括max_retries（默认 30）、backoff（重试退避，默认 1.5 秒）、tool_choice（默认auto）与extra_body（用于传递reasoning_effort等额外字段，配置中gpt-5-2025-08-07-high即以此开启高推理强度）。

重要提示：qwen-plus配置是必需的，因为旅行域的转换阶段（evaluation/convert_report.py）默认用它来解析和格式化 Agent 生成的旅行计划；如需更换转换模型，可修改 benchmark/deepplanning/travelplanning/evaluation/convert_report.py 中的conversion_model变量。此外，call_llm.py 会自动识别o1、o3、o4-mini、reasoner等推理模型并跳过temperature参数。

第五步：设置 API 密钥

以 env.example 为模板创建.env文件并填入密钥：

cp .env.example .env # 编辑 .env，填写 DASHSCOPE_API_KEY 与 OPENAI_API_KEY

第六步：运行统一基准

编辑 run_all.sh 中的配置后执行bash run_all.sh。脚本的核心配置项如下：

DOMAINS="travel shopping" # 要运行的域 BENCHMARK_MODEL="qwen-plus" # 所有域的默认模型（可空格分隔多个模型） # 购物域配置 SHOPPING_LEVELS="1 2 3" # 难度层级 SHOPPING_WORKERS=50 # 并行 worker 数 SHOPPING_MAX_LLM_CALLS=400 # 每个样本的最大 LLM 调用次数 # 旅行域配置 TRAVEL_LANGUAGE="" # 语言：zh / en / 空（两者都跑） TRAVEL_WORKERS=50 TRAVEL_MAX_LLM_CALLS=400 TRAVEL_START_FROM="inference" # 起点：inference / conversion / evaluation TRAVEL_OUTPUT_DIR="" # 自定义输出目录（可选） TRAVEL_VERBOSE="false" TRAVEL_DEBUG="false"

脚本的执行逻辑（对应 run_all.sh）：

1. 按模型逐一遍历所有指定域（旅行域会跑中英文两个版本，购物域按 Level 1 → 2 → 3 顺序）；
2. 为每个域导出BENCHMARK_MODEL、BENCHMARK_WORKERS、BENCHMARK_MAX_LLM_CALLS等环境变量并调用对应域的run.sh；
3. 每个模型完成后调用python aggregate_results.py --model_name <模型名>（可选--travel-output-dir指定旅行结果目录）做跨域聚合；
4. 聚合结果保存到aggregated_results/{model_name}_aggregated.json。

脚本启动时会校验models_config.json是否存在，并自动加载.env；多个模型之间默认间隔 60 秒，避免 API 限流。

旅行域独立运行与三阶段流水线

旅行域可在 benchmark/deepplanning/travelplanning 下独立运行，推荐通过环境变量覆盖默认值（对应 run.sh 的变量定义）：

BENCHMARK_MODEL="qwen-plus" \ BENCHMARK_LANGUAGE="" \ BENCHMARK_WORKERS=10 \ BENCHMARK_MAX_LLM_CALLS=400 \ BENCHMARK_START_FROM="inference" \ BENCHMARK_OUTPUT_DIR="" \ bash run.sh

可用的环境变量及默认值：

智能缓存与断点续跑：当START_FROM="inference"时，run.sh 会自动扫描reports/（如id_0_report.txt）与converted_plans/（如id_0_converted.json）目录，对比 120 个任务 ID（0-119）找出缺失项，并自动决定起点：报告完整但转换计划缺失 → 从conversion开始；报告缺失 → 从inference开始；两者都完整 → 跳过该模型。因此长时间评测可以安全中断并续跑而不丢失进度。

旅行域基准由三个阶段组成：

• Stage 1：推理（Inference）——从data/travelplanning_query_{lang}.json加载任务，调用 LLM Agent 生成旅行计划；Agent 通过工具查询航班、酒店、餐厅、景点等数据库，保存轨迹与执行日志，并生成符合格式要求的可读报告。输出到results/{model}_{lang}/trajectories/与results/{model}_{lang}/reports/。
• Stage 2：转换（Conversion）——用 LLM（默认qwen-plus）将 Markdown 格式的旅行计划解析为标准化 JSON，供自动评估使用。转换原因是：Agent 输出的是人类可读的 Markdown，而评估代码需要结构化 JSON 来逐条校验约束。输出到results/{model}_{lang}/converted_plans/。
• Stage 3：评估（Evaluation）——检查交付率（是否生成了计划）、按 8 个维度评估常识得分、校验个性化约束并计算最终分数。输出到results/{model}_{lang}/evaluation/，包含evaluation_summary.json总体指标与每个任务单独的id_{n}_score.json。评估实现见 benchmark/deepplanning/travelplanning/evaluation 下的constraints_commonsense.py（常识约束）、constraints_hard.py（硬约束）与eval_converted.py。

购物域独立运行与两阶段流水线

购物域可在 benchmark/deepplanning/shoppingplanning 下独立运行：

SHOPPING_AGENT_MODEL="qwen-plus" \ SHOPPING_LEVELS="1 2 3" \ SHOPPING_WORKERS=50 \ SHOPPING_MAX_LLM_CALLS=400 \ bash run.sh

关键环境变量包括：SHOPPING_AGENT_MODEL（可空格分隔多个模型）、SHOPPING_LEVELS（要跑的层级）、SHOPPING_WORKERS（并行 worker 数）、SHOPPING_MAX_LLM_CALLS（每个样本最大 LLM 调用次数）。脚本内部还会自动兼容BENCHMARK_MODEL、BENCHMARK_LEVELS、BENCHMARK_WORKERS、BENCHMARK_MAX_LLM_CALLS等通用变量。

一个值得注意的设计是隔离数据库副本：每次运行会创建带唯一时间戳的数据库拷贝（如database_run_qwen-plus_level1_20250105143022_12345/），因此可以在不同模型上并行运行多个基准互不干扰。推理完成后结果会移入database_infered/，随后运行评估管线（对应 evaluation/evaluation_pipeline.py），并在 evaluation/score_statistics.py 中跨层级汇总统计。

购物域的两阶段流水线：

• Stage 1：推理（Inference）——从data/level_{level}_query_meta.json加载任务，Agent 调用商品搜索、属性过滤、加购、优惠券等工具，轨迹与购物车保存在database/case_{id}/（messages.json为执行轨迹、cart.json为最终购物车、validation_cases.json为参考答案）。
• Stage 2：评估（Evaluation）——将 Agent 生成的购物车与参考答案对比，计算商品匹配、优惠券匹配的准确率并校验任务完成度。报告输出到result_report/database_{MODEL}_level{LEVEL}_{TIMESTAMP}/，含summary_report.json与每个 case 的case_{id}_report.json。注意：评估报告无论模型是否有效都会保存，便于在完成率低时排查问题。

结果解读：各域指标与跨域聚合

旅行域指标

查看汇总结果：

cat results/{model}_{lang}/evaluation/evaluation_summary.json

示例输出：

{ "total_test_samples": 120, "evaluation_success_count": 115, "metrics": { "delivery_rate": 0.958, "commonsense_score": 0.875, "personalized_score": 0.742, "composite_score": 0.809, "case_acc": 0.683 } }

其中composite_score（常识分与个性化分的加权组合）与case_acc（通过全部约束的用例占比）是论文中的主要指标；汇总中还包含error_statistics错误统计，按频次列出常见失败模式（如[Hard] train_seat_status），便于进行错误分析。

购物域指标

查看跨层级统计：

cat result_report/{MODEL}_statistics.json

关键指标含义：

• match_rate：正确匹配的预期商品占比，是论文主指标；
• weighted_average_case_score：按各层级用例数加权后的平均用例得分，是论文主指标；
• successful_rate：达到满分（全部商品与优惠券均匹配）的用例占比；
• valid：模型结果是否有效（各层级incomplete_rate≤ 10% 视为有效）。

跨域聚合指标

运行完两个域后，aggregate_results.py 会将结果汇总为aggregated_results/{model}_aggregated.json，其中：

• 旅行域取中英文两版composite_score、case_acc的平均值；
• avg_acc=（购物域weighted_average_case_score+ 旅行域case_acc）/ 2，是唯一的跨域主指标。

完整聚合示例（字段结构对应 aggregate_results.py 的组装逻辑）：

{ "model_name": "qwen-plus", "domains": { "shopping": { "total_cases": 120, "successful_cases": 17, "successful_rate": 0.1417, "match_rate": 0.6209, "weighted_average_case_score": 0.1417, "valid": true, "levels_completed": [1, 2, 3] }, "travel": { "total_cases": 240, "successful_cases": 238, "successful_rate": 0.9917, "composite_score": 0.2813, "case_acc": 0.0, "commonsense_score": 0.4292, "personalized_score": 0.1333, "valid": true, "languages_completed": ["zh", "en"] } }, "overall": { "total_cases": 360, "successful_cases": 255, "successful_rate": 0.5667, "valid": true, "num_domains": 2, "avg_acc": 0.0708 } }

从示例可以看出：即便模型在购物域交付率（successful_rate 0.9917）很高，组合优化类任务的全局得分依然很低——这正是 DeepPlanning 想要暴露的规划能力短板。

版本更新记录

基准文档（benchmarks/deepplanning/index.mdx）记录了以下版本演进：

• v1.1（2026-03-03）：更新了购物规划基准中的若干任务并修正了部分题目的错误答案标注（数据集可在 Qwen/DeepPlanning 获取）；排行榜新增了多款模型（如 Claude-4.6-Opus、Qwen-3.5-Plus、GLM-5、Seed-2.0-pro-high、Kimi-K2.5-thinking）。
• v1.0（2026-01）：DeepPlanning 基准首个版本，包含旅行规划与购物规划两个域。

小结

DeepPlanning 以"可验证约束下的长程规划"为核心，通过旅行规划与购物规划两个互补的真实场景，系统评测了 Agent 的主动信息获取、局部约束推理与全局约束优化能力。仓库不仅提供了开箱即用的统一运行编排（run_all.sh）、跨域聚合脚本（aggregate_results.py）与两套领域 Agent 实现（travelplanning/agent 与 shoppingplanning/agent），还通过智能缓存断点续跑、隔离数据库副本等工程细节，让研究者可以低成本地复现结果、评估新模型并开展针对长程规划能力的错误分析。

【免费下载链接】Qwen-AgentAgent framework and applications built upon Qwen>=3.0, featuring Function Calling, MCP, Code Interpreter, RAG, Chrome extension, etc.项目地址: https://gitcode.com/GitHub_Trending/qw/Qwen-Agent