新增实验代码等

deliverables/03_验证与评估实验计划.md

@@ -0,0 +1,554 @@
+---
+title: "大规模多智能体网络流量模型"
+subtitle: "验证与评估实验计划（待执行）"
+author: "参赛团队：待填写"
+date: "2026年8月"
+toc: true
+toc-title: "目录"
+number-sections: true
+---
+
+# 本次修订说明
+
+**修订日期：2026年8月13日**
+
+本版本在实验总体框架中加入了可立即执行的模拟实验方案，主要改动如下：
+
+- 在“验证总体框架”后新增 **1.3 模拟实验设计流程**；
+- 将模拟过程拆分为场景定义、LLM 行为画像生成、画像校验、结构化日志生成、训练/验证/测试隔离、参数估计、快速实验和结果输出八个环节；
+- 设置简单问答、工具研究和多 Agent 协作分析三类初始任务场景；
+- 规定 LLM 输出固定 JSON 画像，并在缺少 API Key 或请求失败时使用版本化本地画像回退；
+- 明确训练集用于估计参数、验证集用于选择分布和调整参数、测试集只用于最终评估，避免任务级数据泄漏；
+- 增加预测验证、模型基线、到达率压力和超时重试四类快速实验的输入输出说明；
+- 规定保存原始事件 CSV、行为画像 JSON、估计参数 JSON、实验结果 CSV、图表、配置文件和随机种子；
+- 强调最终报告必须把模拟结果标注为“模拟数据”，获得真实日志后使用同一实验管线重新验证。
+
+配套实验工程位于 `agent_traffic_experiments/`，当前已经能够自动生成数据并输出预测对比图、压力曲线和重试流量放大热力图。
+
+# 文档说明
+
+本文是验证与评估报告的前置计划，不包含尚未实际获得的准确率、性能或显著性结论。实验执行后，应将本计划中的“预期图表、数据表和验收标准”替换或补充为真实结果，并保留失败实验和误差解释。
+
+实验目标是回答四个问题：
+
+1. 仿真程序是否正确实现了数学模型？
+2. 模型能否预测真实或半真实 Agent 网络的流量与延迟？
+3. 双层状态机、队列、拓扑和重试模块是否确有必要？
+4. 模型能否在更大规模网络中保持可接受的运行开销与稳定性？
+
+# 1 验证总体框架
+
+## 1.1 验证层次
+
+| 层次 | 核心问题 | 主要方法 | 输出 |
+|---|---|---|---|
+| V1 实现正确性 | 事件、消息和流量是否算对 | 手工算例、单元测试、守恒检查 | 对账表 |
+| V2 参数可信度 | 参数是否由日志稳定估计 | 分布拟合、Bootstrap、训练/验证/测试划分 | 参数表与区间 |
+| V3 预测准确性 | 能否预测测试场景 | 实测或重放对比 | 误差指标与拟合图 |
+| V4 模型有效性 | 完整模型是否优于简化模型 | 基线和消融实验 | 对比表 |
+| V5 鲁棒与扩展性 | 高负载、故障和大规模下表现如何 | 压力、故障、敏感性和规模实验 | 容量与性能曲线 |
+
+## 1.2 实验原则
+
+- 所有实验配置、随机种子和软件版本可追踪；
+- 训练数据不得进入测试集；
+- 每个随机场景至少重复多次，并报告均值和 95% 置信区间；
+- 真实数据、合成数据和假设参数必须清楚标注；
+- 不仅报告平均值，还报告 P95、P99 和最差场景；
+- 不删除对模型不利的异常结果，应分析其原因和适用边界。
+
+## 1.3 模拟实验设计流程
+
+在真实日志尚不足以覆盖全部任务类型、网络规模和故障条件时，先通过受约束的大模型模拟构建实验数据，快速验证模型与代码闭环。流程如下。
+
+```text
+任务与场景设计
+  ↓
+LLM生成行为画像
+  ↓
+画像合法性校验与默认参数回退
+  ↓
+本地随机引擎扩展结构化事件日志
+  ↓
+按任务划分训练集 / 验证集 / 测试集
+  ↓
+训练集估计状态机参数
+  ↓
+验证集选择分布和调整参数
+  ↓
+测试集聚合为模拟实测值
+  ↓
+完整模型、无上下文模型、静态均值基线对比
+  ↓
+压力实验与重试放大实验
+  ↓
+自动输出数据表、参数文件、指标和图表
+```
+
+### 1.3.1 第一步：定义模拟场景
+
+首轮至少设置三类具有复杂度梯度的任务：
+
+| 任务类型 | 主要特点 | 预期通信行为 |
+|---|---|---|
+| 简单问答 | 单节点推理为主 | 消息少、时延短、很少调用工具 |
+| 工具研究 | 需要搜索或数据查询 | 工具调用率高、响应消息较大 |
+| 多 Agent 协作分析 | 任务拆分和结果汇总 | 子任务多、路径长、队列和重试影响明显 |
+
+同时定义 Agent 数量、工具数量、并发容量、队列容量、链路带宽和基础时延。
+
+### 1.3.2 第二步：LLM生成行为画像
+
+大模型不直接输出海量日志，而是为每类任务生成有限的行为参数：工具调用概率、拆分概率、平均子任务数、处理时间、请求/响应大小、超时率和失败率。输出必须采用固定 JSON 字段，并经过范围检查。
+
+若没有 API Key 或模型调用失败，使用版本化的内置画像回退，以保证实验可离线复现；报告中记录本次实际使用的是 LLM 画像还是本地回退画像。
+
+### 1.3.3 第三步：生成结构化日志
+
+本地程序根据画像运行受约束的随机状态机，为每个任务生成外部到达、Agent 请求、工具请求、工具响应、Agent 返回、超时、重试和最终响应事件。日志必须保留：
+
+- 任务 ID、消息 ID、父消息 ID、请求响应关联 ID 和发送尝试 ID；
+- 任务类型、任务阶段和消息类型；
+- 来源节点、逻辑目标节点、实际下一跳和状态转移；
+- 时间戳、状态持续时间和队列长度；
+- 消息大小、成功状态和重试次数。
+
+### 1.3.4 第四步：训练与测试隔离
+
+按完整任务划分训练集、验证集与测试集。训练集只用于估计参数；验证集用于选择持续时间和消息大小分布、调整模型参数；测试集不得用于调参，只按任务聚合得到内部字节数、端到端延迟、消息数、工具调用数、重试数和成功率，作为最终模拟实验的对照值。
+
+### 1.3.5 第五步：快速实验
+
+| 实验 | 自变量 | 主要输出 |
+|---|---|---|
+| 预测验证 | 任务类型 | 流量、延迟、消息数预测误差 |
+| 基线对比 | 模型版本 | MAE、RMSE、MAPE |
+| 压力实验 | 外部任务到达率 | 吞吐量、P95延迟、峰值队列、丢弃率 |
+| 重试实验 | 超时概率、重试上限 | 成功率、平均重试数、流量放大系数 |
+
+### 1.3.6 第六步：结果输出与使用边界
+
+程序自动输出原始事件 CSV、行为画像 JSON、估计参数 JSON、实验结果 CSV 和图表。模拟实验主要用于验证模型机制、筛选关键参数和形成比赛报告的初步图表，所有结果必须标注“模拟数据”。获得真实运行日志后，保持相同实验管线，用真实数据重新估参和复验。
+
+# 2 实验环境与复现规范
+
+## 2.1 待记录环境
+
+| 项目 | 记录内容 |
+|---|---|
+| 硬件 | CPU型号、核数、内存、操作系统 |
+| 软件 | Python及依赖版本、仿真器提交版本 |
+| 配置 | 拓扑文件、参数文件、任务场景文件 |
+| 随机性 | 主随机种子、重复实验种子列表 |
+| 运行 | 开始时间、结束时间、预热期、仿真时长 |
+| 输出 | 原始事件日志、聚合指标、图表脚本 |
+
+## 2.2 目录建议
+
+```text
+experiments/
+  configs/          # 场景、拓扑和参数
+  raw_logs/         # 原始Agent或仿真事件日志
+  processed/        # 清洗后的标准数据
+  scripts/          # 运行、统计和绘图脚本
+  results/          # 每次实验的机器可读结果
+  figures/          # 报告图表
+  manifests/        # 环境、版本、种子与校验信息
+```
+
+## 2.3 数据划分
+
+如有真实任务日志，建议按任务而非单条消息划分，避免同一任务的消息同时出现在训练集和测试集。
+
+- 训练集：60%，用于参数估计；
+- 验证集：20%，用于选择分布和超参数；
+- 测试集：20%，只用于最终评估。
+
+若数据具有明显时间漂移，应采用前段训练、后段测试的时间切分，并额外报告随机切分结果。
+
+# 3 指标体系
+
+## 3.1 预测误差
+
+对节点流量、链路流量、吞吐量和平均延迟计算：
+
+$$
+MAE=\frac{1}{n}\sum_{i=1}^{n}|\hat y_i-y_i|
+$$
+
+$$
+RMSE=\sqrt{\frac{1}{n}\sum_{i=1}^{n}(\hat y_i-y_i)^2}
+$$
+
+$$
+MAPE=\frac{100\%}{n}\sum_{i=1}^{n}
+\left|\frac{\hat y_i-y_i}{y_i+\varepsilon}\right|
+$$
+
+对于真实值接近零的对象，MAPE 不稳定，应同时报告 MAE、SMAPE 或加权 MAPE。
+
+## 3.2 分布与尾部指标
+
+- 平均延迟、中位数、P90、P95、P99；
+- 队列长度分布及最大值；
+- 消息大小和状态持续时间分布距离；
+- 可选使用 KS 统计量或 Wasserstein 距离比较分布。
+
+## 3.3 热点识别
+
+将利用率或流量处于前 $k\%$ 的节点/链路定义为热点，计算 Precision、Recall、F1 和 Top-K 命中率。
+
+## 3.4 仿真性能
+
+- 总运行时间；
+- 峰值内存；
+- 每秒处理事件数；
+- 单任务平均事件数；
+- 节点规模增加时的时间与内存增长率。
+
+## 3.5 稳定性与可靠性
+
+- 任务成功率和失败率；
+- 超时率和平均重试次数；
+- 流量放大系数；
+- 队列是否在仿真后段持续增长；
+- 故障恢复时间和受影响任务比例。
+
+# 4 实验E1：三节点手工算例与单元验证
+
+## 4.1 目的
+
+验证消息生成、状态转换、链路累计、节点收发流量、超时取消和重试计数是否正确。
+
+## 4.2 场景
+
+```text
+外部 → A → B → C → B → A
+```
+
+消息大小依次为 2、3、1、4、2 KB。关闭随机性并固定所有处理时间。分别运行：
+
+1. 正常工具调用；
+2. 不调用工具直接返回；
+3. 第一次工具调用超时、第二次成功；
+4. 超过最大重试次数并失败；
+5. B 节点无处理资源，消息进入队列。
+
+## 4.3 检查项
+
+- 节点 A/B/C 入站和出站消息数；
+- A-B、B-C 链路累计字节数；
+- 消息路径和跳数；
+- `destination` 与逐跳 `next_hop` 的一致性；
+- 队列入队、出队和并发资源释放；
+- 节点资源状态 $q_v$ 与各消息处理上下文状态 $q_m$ 的一致性；
+- 响应成功后对应超时事件失效；
+- 任务完成或失败后不存在悬挂请求。
+
+## 4.4 通过标准
+
+确定性计数应与手工结果完全一致；浮点时间误差应低于预设容差；所有守恒检查通过。
+
+# 5 实验E2：参数估计与分布拟合
+
+## 5.1 目的
+
+检验从小规模日志估计转移概率、持续时间、消息大小和失败参数的稳定性。
+
+## 5.2 步骤
+
+1. 清洗并按任务还原调用链；
+2. 统计各状态的转移计数和样本量；
+3. 对持续时间和消息大小比较经验分布、对数正态、Gamma 等候选；
+4. 使用验证集选择分布；
+5. 对参数进行 Bootstrap，计算 95% 置信区间；
+6. 检查任务类型、阶段和负载分层后的样本稀疏问题；
+7. 为低样本组启用平滑或上级参数回退。
+
+## 5.3 输出表
+
+| 参数 | 分组条件 | 样本量 | 估计值/分布 | 95%区间 | 来源 | 置信度 |
+|---|---|---:|---|---|---|---|
+| P(Think→CallTool) | 待填写 |  |  |  | 真实/合成 |  |
+| T_Think | 待填写 |  |  |  | 真实/合成 |  |
+| S_request | 待填写 |  |  |  | 真实/合成 |  |
+| p_timeout | 待填写 |  |  |  | 压测/日志 |  |
+
+## 5.4 判定原则
+
+不预设必须选择某种理论分布。若参数分布拟合较差，正式仿真使用经验抽样，并在报告中说明样本覆盖范围。
+
+# 6 实验E3：小规模预测准确性
+
+## 6.1 目的
+
+使用训练集估计参数，在未参与估参的测试任务上预测流量、延迟和调用次数。
+
+## 6.2 场景建议
+
+- 节点规模：3、5、10；
+- 任务类型：至少 2 类；
+- 任务阶段：简单任务与工具密集任务；
+- 负载：低、中、高三个档位；
+- 每个场景包含足够任务，并运行多次随机仿真。
+
+## 6.3 比较对象
+
+- 各节点消息率和字节率；
+- 各链路累计流量；
+- 平均、P95、P99 延迟；
+- 平均工具调用数、下游消息数和重试数；
+- 吞吐量、失败率和平均队列长度。
+
+## 6.4 预期图表
+
+1. 预测值—实测值散点图及 $y=x$ 参考线；
+2. 各节点流量误差条形图；
+3. 实测与预测延迟累积分布曲线；
+4. 不同负载下的 MAPE/MAE 对比；
+5. 任务级流量放大系数箱线图。
+
+## 6.5 初步验收目标
+
+在没有比赛官方阈值时，不应预先承诺固定精度。可使用以下内部目标推动迭代：完整模型在多数主要指标上优于所有基线；测试误差的置信区间稳定；高负载误差上升能够得到合理解释。最终报告填写真实数值。
+
+# 7 实验E4：基线模型对比
+
+## 7.1 基线定义
+
+| 编号 | 基线 | 描述 |
+|---|---|---|
+| B0 | 静态平均倍数 | 外部流量乘以固定放大系数 |
+| B1 | 纯拓扑随机游走 | 仅按连接和固定路由概率传播 |
+| B2 | 简单排队模型 | 到达率和服务率驱动，不表达任务状态 |
+| B3 | 单层状态机 | 节点行为和跨节点传播不分层 |
+| M | 完整模型 | 双层状态机、分层参数、队列和重试闭环 |
+
+## 7.2 公平性要求
+
+- 各模型使用相同训练任务和测试任务；
+- 可共享的外部到达率、平均消息大小和节点总处理能力 $\mu$ 保持一致；
+- 不允许完整模型使用测试集参数；
+- 同时比较精度和运行开销，避免只比较预测误差。
+
+## 7.3 结果表模板
+
+| 模型 | 节点流量MAPE | 链路流量MAPE | 平均延迟误差 | P95误差 | 运行时间 |
+|---|---:|---:|---:|---:|---:|
+| B0 |  |  |  |  |  |
+| B1 |  |  |  |  |  |
+| B2 |  |  |  |  |  |
+| B3 |  |  |  |  |  |
+| M |  |  |  |  |  |
+
+# 8 实验E5：消融实验
+
+## 8.1 消融项
+
+| 消融版本 | 移除内容 | 要验证的假设 |
+|---|---|---|
+| A1 | 移除任务阶段修正 | 阶段信息能提升行为预测 |
+| A2 | 移除局部拓扑和邻居负载 | 拓扑负载影响目标选择与热点 |
+| A3 | 使用固定平均处理时间 | 长尾分布影响尾延迟 |
+| A4 | 移除节点队列 | 队列是高负载延迟的关键来源 |
+| A5 | 移除失败与重试 | 重试影响流量放大与稳定性 |
+| A6 | 固定节点类型替代能力向量 | 能力表示改善异构节点泛化 |
+
+## 8.2 分析方式
+
+比较完整模型与各消融版本在低、中、高负载下的误差变化。若某模块对所有场景几乎没有贡献，应检查参数是否未被正确使用，或重新评估模块复杂度是否值得保留。
+
+# 9 实验E6：压力与容量拐点
+
+## 9.1 自变量
+
+逐步提高外部到达率：
+
+$$
+\lambda\in\{0.2,0.4,0.6,0.8,1.0,1.2,1.5\}\times C_{baseline}
+$$
+
+其中 $C_{baseline}$ 是基准系统的估计处理能力。每个负载档运行足够长的预热期和统计期。
+
+## 9.2 观测指标
+
+- 吞吐量；
+- 平均、P95、P99 延迟；
+- 关键节点队列长度；
+- 超时率、失败率和重试率；
+- 节点与链路利用率；
+- 流量放大系数。
+
+## 9.3 容量拐点定义
+
+可结合以下现象定义容量拐点：吞吐量不再随到达率线性增长；队列在统计期持续增长；P95 延迟突增；失败率超过业务阈值；重试导致内部流量明显非线性增加。
+
+## 9.4 预期图表
+
+- 到达率—吞吐量曲线；
+- 到达率—P95/P99 延迟曲线；
+- 时间—队列长度曲线；
+- 到达率—超时率/重试率曲线；
+- 到达率—流量放大系数曲线。
+
+# 10 实验E7：故障与重试放大
+
+## 10.1 场景矩阵
+
+| 因素 | 建议水平 |
+|---|---|
+| 节点故障比例 | 0%、1%、5%、10% |
+| 链路带宽下降 | 0%、25%、50%、75% |
+| 基础超时概率 | 0、0.02、0.05、0.10、0.20 |
+| 最大重试次数 | 0、1、2、3、5 |
+| 退避策略 | 无退避、固定退避、指数退避 |
+| 目标选择 | 固定节点、负载感知、故障感知 |
+
+## 10.2 关键问题
+
+1. 哪种重试上限在成功率和额外流量之间更均衡？
+2. 指数退避能否减轻拥塞雪崩？
+3. 负载感知或故障感知路由能否缩小影响范围？
+4. 哪些热点节点故障会造成最大任务失败率？
+
+## 10.3 结果展示
+
+使用热力图展示“超时概率 × 重试上限”对成功率和流量放大系数的影响；使用拓扑图展示故障前后的热点迁移；使用时间曲线展示拥塞与恢复过程。
+
+# 11 实验E8：拓扑和调度策略对比
+
+## 11.1 拓扑
+
+- 星型：中心协调节点连接所有执行节点；
+- 树型：分层协调和任务拆分；
+- 随机稀疏图：一般协作网络；
+- 小世界：高聚类、少量远程连接；
+- 无标度图：少量枢纽节点拥有高连接度。
+
+## 11.2 策略
+
+- 最短跳数；
+- 随机可行邻居；
+- 最短队列；
+- 能力匹配优先；
+- 综合能力、距离、负载和可靠性的加权策略。
+
+## 11.3 指标
+
+比较平均跳数、流量集中度、最大节点利用率、任务延迟、成功率和重路由次数。重点讨论不同拓扑是否会形成单点瓶颈，以及负载感知策略是否以额外跳数换取更低尾延迟。
+
+# 12 实验E9：规模扩展与计算性能
+
+## 12.1 规模设置
+
+```text
+10、100、1 000、10 000、100 000 个仿真节点
+```
+
+对每个规模控制平均度数、任务到达率与节点数量的比例，并分别报告低负载和中负载结果。若 100000 节点无法在现有硬件完成，应如实报告达到的最大规模、瓶颈和优化方向。
+
+## 12.2 测量
+
+- 初始化时间；
+- 仿真运行时间；
+- 峰值内存；
+- 每秒事件数；
+- 事件总数；
+- 结果聚合时间；
+- 不同规模下的预测指标稳定性。
+
+## 12.3 对比版本
+
+如实现条件允许，对比：
+
+1. 固定时间步与离散事件；
+2. 全量节点与同构节点聚合；
+3. 不同优先队列实现；
+4. 单线程与分区并行版本。
+
+# 13 实验E10：敏感性与不确定性分析
+
+## 13.1 关键参数
+
+- 工具调用概率；
+- 下游任务数量；
+- 消息大小均值与方差；
+- 节点处理速度；
+- 链路带宽和时延；
+- 超时概率与重试上限；
+- 外部任务突发程度。
+
+## 13.2 方法
+
+第一阶段使用单因素局部敏感性分析；第二阶段可使用拉丁超立方抽样或 Sobol 方法分析全局敏感性。对高不确定参数从其估计区间中抽样，输出预测指标的置信区间，而不是只给单点预测。
+
+## 13.3 输出
+
+- 参数敏感性排序；
+- 龙卷风图；
+- 参数变化与输出变化曲线；
+- 预测区间随样本量的变化；
+- 最需要补采数据的参数列表。
+
+# 14 数据质量与守恒检查
+
+每次实验自动执行以下检查：
+
+- 每条消息有且仅有一个 task_id 和 message_id；
+- 除外部输入、最终输出和丢弃外，发送消息数与接收/在途消息数守恒；
+- 节点并发数不超过上限，队列长度不为负；
+- 链路累计字节数等于经过该链路消息大小之和；
+- 已完成请求不会再次触发有效超时；
+- 任务完成后未完成子请求数为零或被明确标记为取消；
+- 聚合指标能够由原始事件日志重新计算。
+
+# 15 报告图表清单
+
+最终《验证与评估报告》至少包含：
+
+1. 实验环境与数据集统计表；
+2. 参数估计及置信区间表；
+3. 三节点手工对账表；
+4. 完整模型与基线的误差对比表；
+5. 预测值—实测值散点图；
+6. 延迟 CDF 或分位数对比图；
+7. 消融实验条形图；
+8. 到达率—吞吐量—尾延迟曲线；
+9. 超时率—重试次数—流量放大热力图；
+10. 拓扑热点图；
+11. 节点规模—运行时间/内存曲线；
+12. 敏感性排序图；
+13. 失败案例及误差来源表。
+
+# 16 执行排期
+
+| 周期 | 任务 | 完成判据 |
+|---|---|---|
+| 第1阶段 | 仿真器最小闭环与E1 | 手工算例全部通过 |
+| 第2阶段 | 日志模式、合成数据与E2 | 参数表可自动生成 |
+| 第3阶段 | E3基准预测与E4基线 | 获得第一版误差结果 |
+| 第4阶段 | E5消融与E6压力 | 明确模块贡献和容量拐点 |
+| 第5阶段 | E7故障、E8拓扑 | 得到重试与路由结论 |
+| 第6阶段 | E9规模、E10敏感性 | 完成性能和不确定性分析 |
+| 第7阶段 | 报告整合与复现检查 | 图表可一键复现、结论有数据支撑 |
+
+# 17 最终报告写作模板
+
+正式报告建议按以下顺序组织：
+
+1. 验证目标与实验环境；
+2. 数据来源、清洗和参数估计；
+3. 实现正确性验证；
+4. 预测准确性与基线对比；
+5. 消融实验；
+6. 压力、故障和拓扑实验；
+7. 大规模仿真性能；
+8. 敏感性和不确定性；
+9. 失败案例、模型边界与改进；
+10. 结论。
+
+每项结论采用“实验条件—观察数据—结论—适用范围”的格式。例如，不应只写“指数退避更好”，而应写明在哪些负载、超时率和重试次数下改善了哪些指标，以及是否牺牲了任务完成时间。
+
+# 结论
+
+本实验计划通过实现正确性、参数可信度、预测精度、基线对比、消融、压力、故障、拓扑、规模和敏感性十类实验，形成从代码到结论的完整证据链。执行过程中应优先完成三节点对账和小规模预测，再逐步扩展到高负载及大规模场景；所有结果必须保留参数来源、随机种子和复现配置，确保最终参赛报告可信、透明且可重复。