Qwen-Agent DeepPlanning 旅行规划基准（Travel Planning Benchmark）完整实战指南：环境搭建、三阶段流水线与评测指标解析

Qwen-Agent DeepPlanning 旅行规划基准Travel Planning Benchmark完整实战指南环境搭建、三阶段流水线与评测指标解析【免费下载链接】Qwen-AgentAgent framework and applications built upon Qwen3.0, featuring Function Calling, MCP, Code Interpreter, RAG, Chrome extension, etc.项目地址: https://gitcode.com/GitHub_Trending/qw/Qwen-AgentDeepPlanning 是一个用于评估 AI Agent 规划能力的综合基准其中 Travel Planning旅行规划域要求 Agent 在航班、酒店、餐厅、景点等真实结构化数据库的基础上调用工具完成多城市、多天数的完整旅行方案规划。本文以 benchmark/deepplanning/travelplanning/README.md 为骨架结合 benchmark/deepplanning/travelplanning 目录下的源码实现完整讲解该基准从环境搭建、数据准备、模型配置到三段式流水线Inference → Conversion → Evaluation的落地步骤并深入剖析delivery_rate、commonsense_score、personalized_score、composite_score、case_acc等核心指标的计算逻辑与断点续跑机制。读完后你将能够独立在本地复现该旅行规划评测实验并读懂每一份评估报告背后的约束检查逻辑。一、基准概览Travel Planning 在 DeepPlanning 中的定位DeepPlanning Benchmark 是一个横跨多领域、专门评测 AI Agent 规划能力的基准包含两大领域Travel Planning旅行规划评测 Agent 在给定出发地、天数、人数与个性化约束如指定航班/酒店品牌、预算上限的前提下规划完整旅行行程的能力Shopping Planning电商购物评测 Agent 完成多级电商购物任务的能力。两个领域既可以通过 run_all.sh 作为统一基准运行官方推荐用于复现论文实验也可以各自独立运行。本文聚焦于旅行域的独立运行方式相关领域总览与跨域聚合逻辑可参考 benchmark/deepplanning/README.md。在旅行域中Agent 需要基于一套“沙箱化”的本地数据库航班、酒店、餐厅、景点、城际交通等完成规划评测系统再逐项核对方案是否满足常识约束行程可达性、营业时间、成本核算等与个性化硬约束如“必须乘坐某航班”“必须入住某品牌酒店”。二、Step 1安装依赖统一环境在benchmark/deepplanning 项目根目录下搭建即travelplanning/的上一级所有领域共用同一份依赖清单# 若当前位于 travelplanning/ 目录先回到项目根目录 cd .. # 创建新的 conda 环境推荐 Python 3.10 conda create -n deepplanning python3.10 -y # 激活环境 conda activate deepplanning # 从统一 requirements.txt 安装全部依赖 pip install -r requirements.txt # 回到 travelplanning 目录 cd travelplanning依赖清单位于 benchmark/deepplanning/requirements.txt。从源码看运行链路主要依赖openaiSDK用于调用兼容 OpenAI 协议的模型服务、python-dotenv风格的环境变量读取等底层模型调用封装在 agent/call_llm.py 中。三、Step 2 3下载并解压数据库旅行域需要两份数据库压缩包需放置到travelplanning/database/目录下该目录默认不存在需自行创建文件说明database/database_zh.zip中文数据库航班、酒店、餐厅、景点database/database_en.zip英文数据库两份数据来自 HuggingFace 上的Qwen/DeepPlanning数据集。下载后将压缩包放入travelplanning/database/然后解压# 进入数据库目录 cd database # 解压两种语言的数据库 unzip database_zh.zip # 中文数据库flights, hotels, restaurants, attractions unzip database_en.zip # 英文数据库 # 返回 travelplanning 目录 cd ..解压后的数据目录结构对应到评测与推理阶段会被如下代码使用run.py 中的args.database_dir base_dir / database / fdatabase_{language}评测阶段的 evaluation/constraints_commonsense.py 通过database_dir加载restaurants/restaurants.csv、hotels/hotels.csv、attractions/attractions.csv、locations/locations_coords.csv、transportation/distance_matrix.csv等索引文件用于校验。四、Step 4配置模型models_config.json模型配置由所有领域共享位于项目根目录travelplanning/的上一级下的 models_config.json。README 中给出的配置示例{ 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 }, 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 } } }仓库中实际的 models_config.json 比示例更完整额外包含qwen3-max、gpt-5-2025-08-07-high并为每个模型统一设置了temperature: 0.0保证评测结果可复现、降低随机性其中gpt-5还通过extra_body.reasoning_effort: high开启深度推理。你可以按同样格式增删模型条目。关于qwen-plus的重要说明qwen-plus配置是必需的。因为在转换阶段evaluation/convert_report.py默认使用它来解析和格式化 Agent 生成的旅行方案如果你想换用其他模型做转换可以修改 evaluation/convert_report.py 中的conversion_model变量。从源码看该变量当前硬编码为qwen-plus即默认情况下转换阶段始终调用qwen-plus与推理阶段所用模型相互独立。支持的模型类型openaiOpenAI 及其兼容协议模型GPT-4、Qwen、DeepSeek 等通过 OpenAI SDK 以base_urlapi_key_env指定的环境变量来访问。五、Step 5配置 API KeysAPI Key 统一在项目根目录配置。根目录提供 env.example 模板其中声明了两个变量# 用于 Qwen 模型通过 DashScope DASHSCOPE_API_KEYyour_dashscope_api_key_here # 用于 OpenAI 模型 OPENAI_API_KEYyour_openai_api_key_here两种配置方式任选其一# 方式一在项目根目录创建 .env 文件 cd .. cp .env.example .env # 编辑 .env 填入你的 API Key # 方式二直接设置环境变量 export DASHSCOPE_API_KEYyour_dashscope_api_key export OPENAI_API_KEYyour_openai_api_key从源码看evaluation/convert_report.py 和 agent/tools_fn_agent.py 都在模块加载时实现了一套.env加载逻辑优先读取项目根目录.env其次回退到领域目录travelplanning/下的.env且已存在的环境变量不会被覆盖——这意味着你既可以把密钥放在根目录统一管理也可以为旅行域单独放置.env。六、Step 6运行基准run.sh 环境变量详解6.1 推荐方式环境变量 bash run.shBENCHMARK_MODELqwen-plus \ BENCHMARK_LANGUAGE \ BENCHMARK_WORKERS10 \ BENCHMARK_MAX_LLM_CALLS400 \ BENCHMARK_START_FROMinference \ BENCHMARK_OUTPUT_DIR \ bash run.sh可用环境变量一览环境变量作用默认值BENCHMARK_MODEL指定 models_config.json 中的模型名支持空格分隔的多个模型并发评测qwen-plusBENCHMARK_LANGUAGE语言版本zh、en或留空表示中英双语都跑zhBENCHMARK_WORKERS并行 worker 数量每个任务的并发度40BENCHMARK_MAX_LLM_CALLS每个任务允许的最大 LLM 调用次数400BENCHMARK_START_FROM起点阶段inference、conversion、evaluationinferenceBENCHMARK_OUTPUT_DIR自定义输出目录空默认results/BENCHMARK_VERBOSE是否输出详细日志true/falsefalseBENCHMARK_DEBUG是否开启调试模式true/falsefalse6.2 直接修改 run.sh 中的默认值也可以直接编辑 run.sh修改:-后面的默认值实现永久生效MODEL${BENCHMARK_MODEL:-${TRAVEL_AGENT_MODEL:-qwen-plus}} # 改 qwen-plus LANGUAGE${BENCHMARK_LANGUAGE-zh} # 改 zh WORKERS${BENCHMARK_WORKERS:-40} # 改 40 MAX_LLM_CALLS${BENCHMARK_MAX_LLM_CALLS:-400} # 改 400 START_FROM${BENCHMARK_START_FROM:-inference} # 改 inference OUTPUT_DIR${BENCHMARK_OUTPUT_DIR:-} # 设置自定义路径然后直接运行bash run.sh几个源码层面的细节值得注意LANGUAGE用的是${BENCHMARK_LANGUAGE-zh}冒号省略允许空字符串传入从而支持BENCHMARK_LANGUAGE触发双语运行多模型场景下run.sh会对每个模型并行启动一个python run.py子进程并通过mktemp -d创建的临时日志目录分别收集输出同时注册了trap处理 CtrlC中断时会杀掉所有后台子进程每个模型的子进程调用命令形如python run.py --model $MODEL_NAME --workers $WORKERS \ --max-llm-calls $MAX_LLM_CALLS --start-from $MODEL_START \ ${LANGUAGE:--language $LANGUAGE} \ ${OUTPUT_DIR:--output-dir $OUTPUT_DIR} \ ${VERBOSE:--verbose} ${DEBUG:--debug}6.3 直接使用 run.py 的 CLI 参数run.py 是完整的三段式整合运行器直接调用同样可行python run.py --model qwen-plus --language zh --workers 40其 CLI 参数与默认值如下注意与run.sh默认值的差异参数类型默认值说明--modelstr必填models_config.json 中的模型配置名--languagestrNonezh/en默认两者都运行--workersint10并发 worker 数--max-llm-callsint150每个样本最大 LLM 调用次数--output-dirstrNone输出目录默认results/{model}_{lang}--save-intermediateflag关每步之后保存中间结果--start-fromstrinferenceinference/conversion/evaluation--rerun-idsstrNone指定要重跑的任务 ID支持0,5,10或0-10,15,20-25格式--verbose/--debugflag关详细输出 / 调试模式run.py会自动为zh/en各生成独立的输出目录results/{model}_{language}并按阶段打印运行摘要样本数、成功数、平均分、通过率。七、智能缓存与断点续跑当使用run.sh且START_FROMinference时脚本会自动执行智能续跑检查检查同一模型名下的既有结果避免重复劳动先扫描reports/目录找出缺失的报告文件如id_0_report.txt、id_1_report.txt等再扫描converted_plans/目录找出缺失的转换方案文件如id_0_converted.json、id_1_converted.json等识别缺失的任务 ID全部任务共 120 个ID 为 0119自动确定起始步骤报告齐全但转换方案缺失 → 从conversion阶段开始报告缺失 → 从inference阶段开始两者齐全 → 直接跳过该模型✅ All models are already complete. Nothing to run!。这一机制允许你随时中断长时间运行的评测并在之后安全续跑而不丢失进度。其背后的实现逻辑同样存在于 run.py 中detect_missing_ids()通过正则id_(\d)解析已有文件编号并与range(120)求差集推理与转换两个步骤都会先自动检测缺失 ID只对缺失部分重跑--rerun-ids参数则用于显式指定要重跑的任务支持单 ID、逗号列表与区间三种写法。八、深入理解三段式流水线整个基准按三个阶段串行推进对应 run.py 中的三个步骤函数。Stage 1InferenceAgent 规划做什么从 data/travelplanning_query_zh.json或_en版本加载旅行规划任务调用 LLM Agent 生成旅行方案Agent 通过工具查询数据库航班、酒店、餐厅、景点保存 Agent 轨迹trajectory与执行日志按要求的格式生成人类可读的报告report。Agent 侧的实现位于 agent/tools_fn_agent.py是一个框架无关的轻量级 Function Calling Agent从 tools/tool_schema_zh.json或_en版本加载工具 Schema动态实例化所有BaseTravelTool子类然后迭代式地调用 LLM 并在tool_calls与工具执行之间循环直到产出最终答案。可用工具包括工具文件功能flight_query_tool.py航班查询train_query_tool.py火车查询hotel_query_tool.py酒店查询restaurant_query_tool.py餐厅查询attraction_query_tool.py景点查询location_search_tool.py地点搜索roadroute_query_tool.py路线查询输出results/{model}_{lang}/ ├── trajectories/ # Agent 执行轨迹 │ └── id_0_trajectory.json └── reports/ # 人类可读报告 └── id_0_report.txtStage 2Conversion方案解析做什么使用一个 LLM默认qwen-plus可配置转换方案解析 Agent 输出的Markdown 格式旅行方案转换为标准化 JSON 格式以供自动化评测将转换结果存入converted_plans/目录校验方案结构与完整性。为什么需要转换Agent 生成的是人类可读的 Markdown 方案而评测代码需要结构化 JSON 才能自动核对约束满足情况并计算指标。从 evaluation/convert_report.py 源码看转换实现有几个关键设计转换模型硬编码为qwen-plusconversion_model qwen-plus由load_model_configcreate_client创建 OpenAI 兼容客户端提示词通过get_format_convert_prompt(language)按语言获取见 agent/prompts.py每个报告文件由process_single_report处理将报告原文作为 user 消息、格式转换提示作为 system 消息调用 LLM并从响应中提取JSON.../JSON标签内的内容无标签时尝试直接解析解析失败时进行最多 30 次重试max_retries: int 30每次失败间隔 1 秒json.JSONDecodeError与网络异常都会被捕获重试通过ThreadPoolExecutor并行转换skip_existingTrue时自动跳过已有输出文件。输出results/{model}_{lang}/ ├── converted_plans/ # 结构化旅行方案 │ └── id_0_converted.jsonStage 3Evaluation评测做什么检查交付率是否生成了方案评估常识得分8 个维度校验个性化约束计算最终得分。评测核心实现在 evaluation/eval_converted.py它会根据测试数据中的meta_info找到每个样本的元信息定位该样本专属的数据库目录database_dir/id_{sample_id}然后并行执行两套约束检查常识约束调用 constraints_commonsense.py 中的eval_commonsense个性化硬约束调用 constraints_hard.py 中的eval_hard。输出results/{model}_{lang}/ └── evaluation/ ├── evaluation_summary.json # 总体指标与统计 ├── id_0_score.json # 单个任务得分 ├── id_1_score.json └── ... # 每个任务一个得分文件九、评测指标详解八维常识约束与个性化硬约束9.1 核心指标定义汇总结果 evaluation_summary.json运行后生成于results/{model}_{lang}/evaluation/中包含以下指标指标含义delivery_rate交付率是否成功生成了方案生成的方案数 / 总测试样本数commonsense_score常识约束加权得分01personalized_score个性化硬约束满足得分0/1 二值或平均composite_score综合得分 常识得分 个性化得分/ 2case_acc案例准确率常识与个性化两项均为满分才算通过的样本占比9.2 常识约束8 个维度 × 12.5% 权重从 constraints_commonsense.py 的EVALUATION_DIMENSIONS定义可见常识约束被组织为8 个等权维度各 12.5%每个维度内含若干检查项维度权重包含的检查项Route Consistency路线一致性12.5%valid_trip_duration、closed_loop_route_structure、seamless_intercity_transfersSandbox Compliance沙箱合规性12.5%validated_accommodation、validated_attractions、validated_meals、validated_transportationItinerary Structure行程结构12.5%traceable_accommodation、ends_with_accommodation、essential_meal_coverage、essential_attraction_coverageTime Feasibility时间可行性12.5%no_time_overlaps、reasonable_transfer_timeBusiness Hours营业时间12.5%attraction_visit_within_opening_hours、dining_within_service_hours、avoidance_of_closure_daysDuration Rationality时长合理性12.5%reasonable_duration_at_attractions、reasonable_meal_durationCost Calculation Accuracy成本核算准确性12.5%cost_calculation_correctnessActivity Diversity活动多样性12.5%diverse_meal_options、diverse_attraction_options打分规则每个维度内“一票否决”维度内所有检查项全部通过→ 该维度得分 1.0维度内任一检查项失败→ 该维度得分 0.0总加权得分 Σ(维度得分 × 权重)。该逻辑在 eval_converted.py 的calculate_weighted_score()中实现。源码中还能看到若干有意思的检查细节例如check_route_closed_loop校验第一天从org出发、最后一天返回org的闭环路线check_intercity_transportation_consistency按时间顺序追踪位置变化校验城际交通完整性——若current_city写为 from A to B则必须存在对应的travel_intercity_public活动且起终点城市匹配check_meal_necessity非城际日必须安排两餐且间隔 ≥ 2 小时城际到达/离开日根据到达与离开时间动态决定餐次要求check_attraction_necessity非城际日景点相关时长需 ≥ 4 小时或景点数 ≥ 2 个沙箱合规性会逐项核对酒店/餐厅/景点/城际交通的名称与价格是否真实存在于数据库索引中如酒店价格必须与hotels.csv中的price_per_night一致航班的number、from、to、cost字段缺一不可。9.3 个性化硬约束一票否决constraints_hard.py 依据测试数据meta_info.hard_constraints中的约束键前缀进行分发评测支持的约束类型包括航班类flight_*flight_seat_class、flight_seat_status、flight_cheapest_airline_direct、flight_cheapest_direct、flight_earliest_departure_direct、flight_shortest_duration_direct、flight_departure_time_range、flight_arrival_time_range等统一检查往返航班号是否出现在方案中火车类train_*train_seat_class、train_seat_status、train_shortest_duration_direct、train_cheapest_direct、train_earliest_departure_direct、train_latest_arrival_direct、train_cheapest_train_type等酒店类hotel_*hotel_cheapest_brand、hotel_highest_rated、hotel_cheapest_star、hotel_newest_decoration、hotel_brand_highest_rated、hotel_star_highest_rated、hotel_price_range、hotel_star_service_required等餐厅类restaurant_*restaurant_cheapest_nearby_attraction、restaurant_highest_rated、restaurant_must_eat_named、restaurant_closest_to_attraction、restaurant_specific_cuisine_nearby等景点类attraction_*attraction_must_visit_named、attraction_all_of_type、attraction_top_rated_must_visit、attraction_all_free_attractions、attraction_type_highest_rated等预算约束budget_constraint按人数/房间数重新核算交通、住宿、餐饮、景点与市内打车成本校验实际总预算是否超过max_budget。硬约束打分规则全部硬约束通过 → 得分 1.0任一硬约束失败 → 得分 0.0同样是一票否决。该逻辑在calculate_hard_score()中实现。最终composite_score (commonsense_score personalized_score) / 2 case_acc 1.0 当且仅当 commonsense_score 1.0 且 personalized_score 1.0其中case_acc是旅行域论文中的主指标之一与购物域的weighted_average_case_score一起参与跨域聚合指标avg_acc的计算详见 benchmark/deepplanning/README.md。十、查看结果10.1 总体统计cat results/{model}_{lang}/evaluation/evaluation_summary.jsonREADME 中的示例输出对应某个模型与语言组合{ 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 } }需要说明的是仓库实际生成的evaluation_summary.json见 eval_converted.py 的summary_data字段比示例更丰富还包括plan_files_found、evaluation_failed_count、elapsed_time、max_workers、commonsense_dimensions每个维度的得分与满分样本数以及error_statistics。10.2 单任务详情# 查看某个任务的具体得分 cat results/{model}_{lang}/evaluation/id_0_score.json # 查看某个任务的人类可读报告 cat results/{model}_{lang}/reports/id_0_report.txt单个id_X_score.json中会包含四个分数的明细、8 个常识维度的逐项得分与检查详情commonsense_dimension_details、个性化硬约束的逐条通过与失败信息personalized_dimension_score可直接定位具体失败原因。10.3 错误分析汇总结果中还包含错误统计展示最常见的失败模式帮助定位 Agent 的薄弱环节error_statistics: [ { rank: 1, error_type: [Hard] train_seat_status, count: 15, affected_samples: [0, 12, 25, ...] } ]从 eval_converted.py 的源码看错误统计对常识约束与硬约束分开归因常识约束错误标记为[Commonsense] {check_name}硬约束错误标记为[Hard] {constraint_name}按出现次数降序排列每条记录包含count、affected_samples与sample_messages示例错误消息并在终端按 Top 10 打印整个评测完成后终端还会输出各维度的加权得分明细与最终综合得分。十一、注意事项与常见问题qwen-plus配置缺失会导致转换阶段失败即使推理模型用的是其他模型convert_report.py仍默认调用qwen-plus请确保它在models_config.json中且对应 API Key 已配置.env优先级源码优先加载项目根目录.env不存在时回退到travelplanning/.env且不覆盖已存在的系统环境变量数据库目录必须就绪database/database_{zh|en}需先下载解压否则推理阶段工具查询与评测阶段索引加载都会失败断点续跑120 个任务ID 0119中任意缺失的报告或转换文件都会在下次run.shSTART_FROMinference启动时被自动补齐也可用run.py --rerun-ids 0-10,15,20-25精确重跑指定样本双语运行BENCHMARK_LANGUAGE或run.py不传--language时会依次运行zh与en两个语言版本输出分别落在results/{model}_zh/与results/{model}_en/跨领域聚合若需将旅行域与购物域结果统一聚合可使用 run_all.sh 统一运行聚合结果输出到aggregated_results/{model}_aggregated.json聚合逻辑见 aggregate_results.py。十二、总结Travel Planning 基准通过“推理生成 → LLM 结构化转换 → 自动约束评测”三段式流水线将 Agent 的开放式旅行规划能力转化为可量化、可复现的指标体系。本文所涉及的配置、脚本与评测逻辑均可在仓库中逐一对应入口脚本 run.sh 与 run.pyAgent 实现 agent/tools_fn_agent.py转换逻辑 evaluation/convert_report.py以及评测核心 evaluation/eval_converted.py、evaluation/constraints_commonsense.py、evaluation/constraints_hard.py。按照本文的六个步骤即可完整复现旅行规划基准评测并借助断点续跑、逐任务得分与错误统计系统性地定位并改进 Agent 的规划能力。【免费下载链接】Qwen-AgentAgent framework and applications built upon Qwen3.0, featuring Function Calling, MCP, Code Interpreter, RAG, Chrome extension, etc.项目地址: https://gitcode.com/GitHub_Trending/qw/Qwen-Agent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考