基于AI Agent开发范式的国产GPU大模型推理算子库优化/START_HERE.md

@@ -0,0 +1,116 @@
+# START HERE — 赛题二：AI Agent 驱动 GPU 算子优化
+
+## 比赛任务
+
+将三个开源推理算子库的核心算子迁移至沐曦国产 GPU（MACA 软件栈），并完成性能优化。借助 AI Agent 完成代码理解、迁移适配、性能调优与测试验证。
+
+三个方向，任选其一或多个：
+
+| 方向 | 任务 | 技术约束 |
+|------|------|---------|
+| **FlashInfer** | 将 BatchPrefill / BatchDecode / MLA 等 Attention Kernel 迁移至 MACA 平台并完成性能优化。重点调优维度：headdim、seqlen、page_size | MACA C++，BF16，headdim 64/128/256，seqlen 1K–180K |
+| **FlashAttention** | 将 `flash_attn_with_kvcache` 接口迁移至 MACA 平台并完成性能优化。重点调优维度：headdim（高优 128/256/512）、seqlen | MACA C++，BF16，headdim 32–512，page_size=16 |
+| **Fused MoE** | 将 INT8 量化 MoE 算子迁移至 MACA 平台并完成性能优化。重点调优维度：token 路由、专家计算、访存路径 | Tilelang / Triton / MACA C，INT8 W8A8，真实模型 shape |
+
+## 提交物
+
+提交一个压缩包至 opensource@metax-tech.com，截止 **2026 年 9 月 5 日**。压缩包内包含：
+
+**可运行代码。** 按对应方向的任务要求完成算子实现。提交至 XPU-OJ 平台，通过正确性测试后进入性能排名。正确性测试为硬性门槛，未通过的作品不参与排名。
+
+**Agent 工作流。** 证明 AI Agent 参与了优化过程。Agent 对话日志、Skill 脚本、prompt 模板、自动化工作流脚本均可。评审方将按照提交记录重跑流程，复现程度直接影响得分。
+
+**Benchmark 对比报告与演示 PPT。** 说明优化方案、性能提升幅度、Agent 在流程各环节的参与方式。
+
+## 评分构成
+
+100 分制，三个维度：
+
+- **性能提升（60 分）**：相比 baseline，在延迟、吞吐、Token/s、显存占用等维度的提升
+- **Agent 可复现（20 分）**：功能能复现得 5 分；性能复现达提交标称的 60% 以上得 10 分，80% 以上得 15 分，90% 以上得 20 分
+- **文档质量（20 分）**：技术报告、README、运行说明、演示视频、答辩材料的完备程度
+
+## 推进流程
+
+**第一步：获取算力。** 赛事提供曦云 C500 在线算力，无需自备硬件。在沐曦开发者社区领取算力券，于模力方舟平台租用实例，选择镜像 `PyTorch-Agent / 2.8.0 / Python 3.12 / maca 3.7.2.1`。详见 [模力方舟快速使用 SOP](../模力方舟快速使用SOP.md)。
+
+**第二步：部署 Agent。** 推荐安装 OpenCode，通过模力方舟 API 接入 MiniMax-M2.7 模型。部署后执行 `mx-smi` 确认 Agent 可操作当前环境。详见 [模力方舟 Agent 部署准备教程](模力方舟Agent部署准备教程.md)。
+
+**第三步：环境验证与冒烟提交。** 课程材料不提供可直接提交的 baseline 源代码或标准答案代码；仅提供冒烟级示例代码，用于验证功能、环境、语言和 `run_kernel(...)` 接口。选手需根据 XPU-OJ 题包接口自行实现 `run_kernel(...)`，并可参考 FlashInfer、FlashAttention、vLLM、Triton、TileLang、MCTLASS 等开源仓库或官方文档，组合完成算子实现与性能优化。
+
+先跑通冒烟示例，确认编译、测试、OJ 提交链路正常，再记录首次 benchmark 性能数据作为后续优化对比基准。
+
+- FlashInfer → [FlashInfer 关键算子迁移与优化](FlashInfer关键算子迁移与优化.md) · [冒烟代码](operator_task_package/flashinfer_task_package/starter/%E7%A4%BA%E4%BE%8B%E5%86%92%E7%83%9F%E4%BB%A3%E7%A0%81.md)
+- FlashAttention → [FlashAttention 关键算子迁移与优化](FlashAttention关键算子迁移与优化.md)
+- Fused MoE → [MCTLASS Fused MoE 算子优化](MCTLASS_Fused%20MoE%20算子优化.md)
+
+可参考的开源仓库：
+
+- [MetaX-MACA/flashattn](https://github.com/MetaX-MACA/flashattn)
+- [MetaX-MACA/McFlashInfer](https://github.com/MetaX-MACA/McFlashInfer)
+- [MetaX-MACA/mcTriton](https://github.com/MetaX-MACA/mcTriton)
+
+**第四步：迭代优化。** 每轮仅修改一处代码，修改后执行 build → test → benchmark 并记录结果，验证无误后再进入下一轮。保存每轮 Agent Prompt、代码改动、OJ 结果和性能变化，形成可复现的 Agent/Skill 优化流程。详见 [Agent 使用说明](Agent说明.md)。
+
+**第五步：OJ 提交。** 将 `run_kernel(...)` 按对应题包接口规范整理，提交至 XPU-OJ。先确保正确性通过，再优化性能冲榜。
+
+- FlashAttention 提交指南：[operator_task_package/flashattn_task_package/guide.md](operator_task_package/flashattn_task_package/guide.md)
+- FlashInfer 题包：[operator_task_package/flashinfer_task_package/](operator_task_package/flashinfer_task_package/)（含四个子问题，各自有独立接口约定）
+
+## 相关文档
+
+| 需求 | 对应文档 |
+|------|---------|
+| 比赛规则、评分标准、提交方式全文 | [基于 AI Agent 开发范式的国产 GPU 大模型算子推理库优化方案](基于AI%20Agent开发范式的国产GPU大模型算子推理库优化方案.md) |
+| 算力环境配置与 Agent 部署 | [模力方舟 Agent 部署准备教程](模力方舟Agent部署准备教程.md) |
+| FlashInfer API 与核心概念（Paged KV Cache、Ragged Tensor、MLA） | [赛题说明](赛题说明.md) Track 1 部分 |
+| FlashInfer 冒烟示例与 benchmark | [FlashInfer 关键算子迁移与优化](FlashInfer关键算子迁移与优化.md) |
+| FlashAttention 冒烟示例与 benchmark | [FlashAttention 关键算子迁移与优化](FlashAttention关键算子迁移与优化.md) |
+| Fused MoE 冒烟示例与 benchmark | [MCTLASS Fused MoE 算子优化](MCTLASS_Fused%20MoE%20算子优化.md) |
+| Agent 使用方式与 prompt 模板 | [Agent 说明](Agent说明.md) |
+| XPU-OJ 提交流程 | [FlashAttention OJ guide](operator_task_package/flashattn_task_package/guide.md) · [FlashInfer 题包](operator_task_package/flashinfer_task_package/) |
+| 模力方舟操作 | [模力方舟快速使用 SOP](../模力方舟快速使用SOP.md) |
+
+## 备忘
+
+- 报名：2026 年 5 月 30 日 – 6 月 30 日，[挑战杯官网](https://2026.tiaozhanbei.net/)
+- 作品提交截止：2026 年 9 月 5 日
+- 团队上限 10 人，指导教师上限 3 人
+- 统一开发与评测镜像：`PyTorch-Agent / 2.8.0 / Python 3.12 / maca 3.7.2.1`
+- Benchmark 须使用整张单卡（64 GB），日常开发建议 16–32 GB
+- 正确性测试为硬性门槛，未通过的作品不参与性能排名
+
+## 常见问题
+
+**Q：课程材料是否提供可直接提交的 baseline 代码？**
+
+A：不提供。课程材料仅提供冒烟级示例代码，用于验证环境、语言、提交链路和 `run_kernel(...)` 接口。选手需根据 XPU-OJ 题包接口自行实现算子，并可参考 FlashInfer、FlashAttention、vLLM、Triton、TileLang、MCTLASS 等开源仓库。
+
+**Q：Benchmark 性能基线、OJ 参考实现和选手提交代码之间是什么关系？**
+
+A：三者不同。(1) benchmark 脚本用于建立性能基线，理解目标 API 的调用方式和性能表现；(2) OJ 题包中的 `baseline()` 是后台参考实现，用于生成 `output_ref`，不是选手提交代码；(3) 选手需要自行实现 `run_kernel(...)` 并提交至 OJ。
+
+**Q：精度误差要求是多少？**
+
+A：正式精度要求以对应 OJ 题包中的 `testcase_config.py` 和题面说明为准。不同算子的容差可能不同，不可统一设为一个固定值。当前各题包的容差示例：
+
+| 题包 | rtol | atol |
+|------|------|------|
+| FlashInfer Ragged Prefill（20001） | 1e-2 | 1e-2 |
+| FlashInfer Paged Prefill（20002） | 1e-2 | 1e-2 |
+| FlashInfer MLA Paged Attention（20003） | 1e-2 | 1e-2 |
+| FlashInfer Paged Decode（20004） | 1e-2 | 1e-2 |
+| FlashAttention KV Cache Decode | 1e-2 | 1e-2 |
+| Fused MoE i8 tn | 0.0 | 1e-2 |
+
+**Q：登录 XPU-OJ 后看不到题目？**
+
+A：七月份组委会统一发放 XPU-OJ 账号，请确认使用的是组委会发放的账号而非自行注册账号。如仍无法看到题目，联系助教或赛事运营确认账号权限。
+
+**Q：OJ 得分怎么算？**
+
+A：以各算子 baseline 性能为基准（约 50 分），硬件理论上限约 100 分。评测程序统计作品在目标测试集上的延迟、吞吐、显存占用、稳定性等维度的综合表现，按加权平均计算最终得分。测试点时间为 iter 平均时间。详见 [XPU-OJ 代码评测指南](https://xpuoj.com/d/2)。
+
+**Q：排行榜怎么排？**
+
+A：每个任务单独计分，一个任务一个榜。两个赛题在 XPU-OJ 的榜单得分规则一致。多次提交取最好一次有效提交。正确性测试不通过的作品不计入排行榜。