🧠 EulerPilot-MA：面向 openEuler 的自适应资源管控 Agent

_{📌 提交说明：受官方提交渠道账号关联异常影响，队伍注销原账号并重新提交后，早期 GitLink 开发活动记录未能迁移；当前仓库已保留重建后的分阶段提交记录。😢}

EulerPilot-MA 是一个面向 openEuler 的用户态资源管控 Agent 框架。项目以 CPU 资源管控为首个验证场景：系统从 eBPF、procfs、压力停顿信息（Pressure Stall Information，PSI）和应用侧指标中提取运行特征，识别 workload 类型与竞争风险；本地大语言模型（Large Language Model，LLM）在慢环中生成受约束的策略意图；确定性状态机快环在安全边界内执行、续租、降级和回滚。

系统的核心数据与控制链路如下：

eBPF / procfs / PSI / 应用指标精细感知
    -> 决策树 workload 分类与风险特征提取
    -> 本地 LLM 慢环生成目标条件化策略边界
    -> 状态机快环在安全边界内执行、续租、降级和回滚
    -> cgroup v1/cpuset 或 sched_ext/scx 后端执行

系统并不让大模型实时调度 CPU。LLM 仅在慢环中输出可校验的策略意图或策略描述语言（Policy Domain-Specific Language，Policy DSL）；500 ms 快环只执行经 Skill/Tool 注册表、JSON Schema 和资源守护器校验后的动作，从而将模型推理延迟隔离在在线控制关键路径之外。

🧩 系统架构

EulerPilot-MA 系统架构与闭环流程

_{图 1｜EulerPilot-MA 的观测、感知、策略规划、确定性执行与反馈闭环。}

查看高清框架及流程图（PDF）

📦 提交材料

技术报告：技术报告.pdf
原创承诺书：原创承诺书.pdf
演示视频：演示视频.mp4
答辩演示：答辩演示.pptx（文档目录同步副本：docs/presentation/EulerPilot-MA-Competition-Presentation.pptx）
GitLink 提交指南：docs/submission/GITLINK_SUBMISSION_GUIDE.md

✨ 1. 主要设计与实现要点

Agent 双环闭环：500 ms 快环负责实时控制，LLM 慢环负责策略边界规划，避免大模型推理阻塞在线调度。
结构化 Skill/Tool 机制：大模型只能选择 SkillRegistry 中的 Skill 和 profile，不能直接写 cgroup、cpuset 或 scx。
受约束 Policy DSL：模型输出必须经过语法、Schema、能力白名单、参数范围和幂等性校验，校验失败或超时均回退到规则策略。
决策树 workload 感知：轻量模型根据 eBPF 可见任务特征输出 LatencySensitive、Throughput、Background 等标签，为风险评分和快环转移提供输入。
Memory-Guard 记忆复用：重复压力指纹出现时复用已验证策略，降低相似场景的慢环等待，并在异常时由快环安全续租或回退。
Mixture-of-Schedulers 路由：在 scx 可用时优先选择 scx 专家；不可用时透明降级到 cgroup v1/cpuset 专家。
可复现实验数据集：提供 Skill420 420 秒五路实验结果、论文数值汇总、绘图材料与工作负载感知评测结果。

🔄 从观测到执行的方法闭环

阶段	实现方法	主要输入	输出与作用
精细感知	eBPF 调度事件、procfs、PSI 与应用指标联合采样	任务运行时间、唤醒、切换、CPU 占用、P99、SLO	形成任务特征和系统压力快照
workload 识别	16 维特征驱动的决策树分类器	eBPF 任务特征与窗口统计	输出低时延、吞吐、后台标签及干扰评分
策略规划	Qwen3-0.6B / SmolLM2-360M LoRA 慢环	压缩后的 `ResourceBrief`、当前状态与目标约束	生成 `SKILL
安全编译	Schema、白名单、参数边界和能力探测	LLM 或规则慢环给出的候选计划	生成可执行 `StrategyPlan`；失败时回退规则策略
实时控制	500 ms 确定性状态机快环	已验证计划、P99/SLO、运行队列和干扰信号	执行、续租、升级、降级或回滚资源动作
经验复用	Memory-Guard 压力指纹检索	当前压力向量与历史已验证计划	相似场景先安全续租，再异步刷新慢环计划

这套分层使学习模型负责“选择目标和策略边界”，确定性控制器负责“何时执行以及如何安全退出”。即使模型不可用、输出非法或推理超时，500 ms 快环仍能依靠最近有效租约或规则策略继续运行。

✅ 赛题要求与实现映射

赛题核心要求	EulerPilot-MA 对应实现	状态
用户态资源管控 Agent 与标准化 Tool/Skill	Agent–Skill–Tool–Backend 分层架构，统一 Schema、Registry 与安全校验	✅
workload 感知与 CPU 调度决策	eBPF、procfs、PSI 和应用指标联合感知，决策树分类与双环策略生成	✅
sched_ext/scx 专家调度器集成	Scheduler Router 与 ScxBackend 完成能力探测、专家路由、租约、健康检查和回滚	✅
eBPF Hook 与多类型 OS Agent 扩展	提供 CPU、网络、安全和通用资源管控 Agent 的统一注册接口与原型	✅
性能对比与可复现实验	Skill420 动态混合负载、五路公平对比、原始日志、指标汇总和自动绘图	✅
openEuler 编译、运行与测试	已在 openEuler 24.03 LTS-SP4 完成部署、动态负载运行与结果生成	✅

sched_ext/scx 由运行时能力探测决定：内核支持时启用 scx 专家，不支持时自动降级到当前可用的资源控制后端，并完整记录选择与回滚原因。

🔬 2. 实验概览与可核验结果

Skill420 是一条 420 秒连续 workload 时间流，覆盖低压校准、服务请求突发、批处理竞争、短任务扰动、混合过载、局部恢复、重复压力、后台噪声、路由窗口和最终冷却。所有对比方法均在同一时间流上运行，完整原始结果和统计口径保存在仓库中。

项目	配置或结果
运行环境	openEuler 24.03 LTS-SP4，8 vCPU
服务目标	滚动 P99 / 服务等级目标（SLO）：20 ms
对比方法	Baseline、规则慢环、Qwen3-0.6B、SmolLM2-360M、SmolLM2-360M + Memory-Guard
Workload 感知	14,913 条独立留出集：Accuracy 99.48%，Macro-F1 98.97%；59,649 条全量可见样本分析：Accuracy 99.54%，Macro-F1 99.12%
强规则慢环	P99 30.379 → 15.107 ms，下降 50.27%；SLO 违约率 12.349% → 0.3839%；吞吐保持率 85.33%
完整 Agent 路线	SmolLM2-360M + Memory-Guard：P99 15.109 ms，下降 50.27%；SLO 违约率 0.3513%，下降 97.16%；吞吐保持率 68.66%

🎯 Workload 感知能力

在线分类器从每个任务窗口提取 16 维特征，包括 eBPF CPU 指纹、运行时间增量、在核时间、上下文切换、唤醒频率、运行比例、窗口任务总量和 CPU 排名等。决策树将任务划分为低时延任务（LatencySensitive）、吞吐任务（Throughput）和后台任务（Background），分类结果进入 ResourceBrief，用于修正语义场景、干扰评分和快环风险判断；分类器本身不直接修改系统资源。

在线发布模型采用 75%/25% 分层划分，独立留出集包含 14,913 条样本，Accuracy 为 99.48%、Macro-F1 为 98.97%。低时延类 Precision/Recall 为 99.79% / 99.52%，吞吐类为 99.95% / 99.48%，后台类为 95.94% / 99.22%。图 2 展示的是同一模型在 59,649 条全量可见样本上的误差分析，对应 Accuracy 99.54%、Macro-F1 99.12%；该口径用于分析可见样本覆盖，不替代独立留出集指标。当模型文件或运行依赖不可用时，控制器自动回退到阈值规则感知。

决策树 workload 感知混淆矩阵

_{图 2｜59,649 条全量可见样本的决策树三分类混淆矩阵；独立留出集指标见上文。两个统计口径均来自同一训练包，但用途不同。}

🧠 本地 LLM 与 LoRA 微调

慢环采用 Qwen3-0.6B 与 SmolLM2-360M-Instruct 两种本地模型。训练任务不是开放式对话，而是把压缩资源摘要（CompactResourceBrief）映射为固定长度的 Policy DSL：SKILL|LEVEL|TTL|TOOL|REASON。18,134 条训练样本由 18,000 条覆盖边界条件的合成样本与 134 条真实 VM 轨迹样本组成，覆盖正常、批处理突发、编译突发、测试突发、内存压力、后台维护、混合压力和恢复八类场景，并按 14,507 / 1,813 / 1,814 划分训练、验证和测试集。

两种模型均采用 4 bit NF4 量化低秩适配（Quantized Low-Rank Adaptation，QLoRA）：基础模型以 4 bit 加载，LoRA 使用 rank=16、alpha=32、dropout=0.05 并作用于全部线性层，输入最长 1,024 token。训练时只计算 assistant 输出 token 的自回归交叉熵，提示词 token 使用 -100 掩码：

L_DSL = -(1 / N) Σ[t∈DSL] log pθ(y_t | x, y<t)

模型	训练终止点	最佳检查点	最佳验证损失	最终训练损失	最终验证损失
Qwen3-0.6B	11,800 step / 13.01 epoch	7,800 step	5.897 × 10⁻⁴	1.276 × 10⁻⁴	2.012 × 10⁻³
SmolLM2-360M	19,400 step / 21.39 epoch	17,200 step	1.600 × 10⁻⁵	2.081 × 10⁻⁴	1.025 × 10⁻³

验证损失用于选择 LoRA 检查点，而不是直接作为系统性能指标；最终策略仍须经过 DSL 解析、Schema、工具白名单和资源边界校验后才能进入快环。


_{Qwen3-0.6B：最佳验证损失位于 step 7,800}	_{SmolLM2-360M：最佳验证损失位于 step 17,200}

📈 Skill420 端到端调度结果

Skill420 420 秒滚动 P99 时序

_{图 3｜Skill420 连续时间流上的滚动 P99 时序。S0 低压阶段各方法接近 10 ms；混合干扰与重复压力阶段体现不同控制策略的差异。}

Skill420 五路方法汇总结果

_{图 4｜五路方法在 P99、SLO 违约率、批处理吞吐和相对改善上的汇总比较。最佳路线将 P99 从 30.38 ms 降至 15.11 ms，改善约 50%。}

五路结果体现的是服务质量与吞吐之间的策略权衡。规则慢环取得最低总体 P99 和较高吞吐保持率；完整 Agent 路线以异步 LLM 策略边界和 Memory-Guard 支持目标条件化规划、重复场景复用与安全回退，并取得 0.3513% 的总体 SLO 违约率。仓库不把“是否使用 LLM”简单等同于所有指标必然更优，所有结论均以五路原始日志和分阶段统计为准。

完整可核验数据位于 dataset/skill420_420s/paper_metrics/，包括整体、阶段、场景组、记忆、控制开销、workload 分类器和 LLM 离线评测指标。

🗂️ 3. 目录结构

adapter/                     LLM planner、Policy DSL 编译器、StrategyPlan 校验器
runtime/                     在线控制器、状态机、cgroup 后端、scx 后端、workload 分类器
registry/                    Skill 注册表、参数 profile、禁止动作
schemas/                     ResourceBrief、StrategyPlan、PolicyIntent 等 JSON Schema
models/                      workload 分类器与 Qwen3/SmolLM2 LoRA 适配器
training_packages/           Qwen3-0.6B、SmolLM2-360M、决策树训练包
bench/scripts/               workload 注入与 eBPF 采集脚本
scripts/                     远程运行、绘图、汇总、smoke 测试脚本
scx/                         sched_ext/scx 集成契约和说明
dataset/skill420_420s/       最终 420 秒数据集、图、论文数值
docs/assets/                 README 使用的架构图、高清 PDF 与结果图
docs/architecture/           Agent 架构、eBPF、scx、Skill 路由和分类器说明
docs/deployment/             openEuler 部署与复现实验指南
docs/experiments/            Skill420 场景、指标和结果说明
docs/operations/             代码审计与运行手册
docs/submission/             GitLink 提交与验收指南

🚀 4. 快速安装

openEuler VM 中安装轻量运行依赖：

dnf install -y python3 python3-pip git make gcc clang llvm bpftool stress-ng procps-ng util-linux openssh-server
python3 -m pip install -r requirements-runtime.txt

如果要在 VM 内直接运行 HuggingFace 本地模型，再安装：

python3 -m pip install -r requirements.txt

requirements-runtime.txt 只包含控制器、远程运行、决策树分类器和复现实验所需依赖；requirements.txt 包含大模型训练或推理依赖。

✅ 5. 一键 smoke 测试

在 openEuler/Linux 中执行完整 smoke：

bash scripts/smoke_test.sh

也可以逐项执行：

python3 -m py_compile runtime/controller.py runtime/workload_classifier.py runtime/scx_backend.py runtime/scheduler_router.py
python3 scripts/smoke_workload_classifier.py --model-dir models/workload_classifier/decision_tree --samples dataset/skill420_420s/raw_results/smollm2_360m_llm_memory/ebpf_sched_samples.jsonl --limit 5
python3 scripts/scx_backend_smoke.py
python3 scripts/smoke_scheduler_router.py
python3 scripts/smoke_policy_intent_compiler.py

🖥️ 6. openEuler VM 复现实验

从 Windows 主机远程运行 openEuler VM：

$env:EULERPILOT_SSH_PASSWORD='你的root密码'
python scripts\run_remote_experiment.py `
  --host <VM_IP> `
  --user root `
  --scenario skill420 `
  --duration 420 `
  --interval 0.5 `
  --service-work-us 9000 `
  --slo-ms 20 `
  --out-dir data\skill420_final_reproduce `
  --enable-ebpf `
  --enable-workload-cpuset `
  --latency-cpus 6-7 `
  --batch-cpus 0-5 `
  --background-cpus 0-5 `
  --llm-worker-cpus 5 `
  --cgroup-profile-set competition `
  --apply-scx `
  --include-local-hf-http `
  --remote-model-dir /root/eulerpilot/app/models/policy_planners/smollm2_360m_lora `
  --local-hf-max-new-tokens 16 `
  --llm-output-mode policy_dsl `
  --local-hf-torch-threads 1 `
  --planner-cache-ttl-sec 5 `
  --enable-memory-guard

说明：

scripts/run_remote_experiment.py 会上传 adapter/、runtime/、schemas/、registry/、configs/、models/、scripts/ 和 bench 脚本。
models/workload_classifier/decision_tree/ 会随代码上传，默认启用决策树 workload 感知。
两套 LoRA 适配器位于 models/policy_planners/；基础模型不重复分发，离线部署方式见该目录的 README。
--apply-scx 会探测 sched_ext/scx；如果当前内核不可用，会记录原因并自动降级到 cgroup v1/cpuset。
更完整的安装、传输、运行、回收和绘图步骤见 docs/deployment/OPENEULER_DEPLOYMENT.md。

📊 7. 最终数据和论文数值

最终 Skill420 数据集位于：

dataset/skill420_420s/

论文 A-J 数值汇总位于：

dataset/skill420_420s/paper_metrics/

关键文件：

paper_run_manifest.json
paper_overall_summary.csv
paper_stage_summary.csv
paper_group_summary.csv
paper_s11_detail.csv
paper_memory_summary.json
paper_overhead_summary.csv
paper_workload_classifier_detail.json
paper_llm_offline_eval.csv
paper_metrics_report.md

注意：部分图文件仍保留 strong360_*.pdf 历史命名，但本次论文统计窗口是 0 到 420 秒，具体以 paper_run_manifest.json 为准。

Skill420 的场景含义、指标口径和结果解读见 docs/experiments/SKILL420_SCENARIOS.md 与 docs/experiments/SKILL420_RESULTS.md。

⚙️ 8. sched_ext/scx 说明

scx 集成代码在：

runtime/scx_backend.py
runtime/scheduler_router.py
configs/scx_profiles.json
scx/README.md

真实 scx 运行需要 /sys/kernel/sched_ext 存在、内核启用 CONFIG_SCHED_CLASS_EXT=y，并且系统中有 allowlist 内的 scx_* scheduler 工具。当前 Skill420 最终结果记录显示 scx 不可用，真实执行后端是 cgroup v1/cpuset/cpu.shares，不能把性能提升归因于 scx。

📤 9. 提交说明

GitLink 提交建议见：

docs/submission/GITLINK_SUBMISSION_GUIDE.md

最终代码审计和运行手册见：

docs/operations/CODE_AUDIT_AND_RUNBOOK.md

openEuler 部署细节见：

docs/deployment/OPENEULER_DEPLOYMENT.md

⚖️ 10. 开源许可

EulerPilot-MA 自研源代码采用 Apache License 2.0 发布。第三方 Python 依赖、基础模型、Linux/openEuler 系统组件及 sched_ext/scx 继续遵循各自的上游许可证；仓库中的 LoRA 文件仅包含本项目训练得到的适配器，不重复分发基础模型权重。

完整的依赖来源和许可边界见 THIRD_PARTY_NOTICES.md。