新增 沐曦通用GPU MXMACA编译器内建函数编程指南 入口

FAQ.md

@@ -0,0 +1,329 @@
+# 常见问题 FAQ
+
+> 最后整理：2026-07-13
+
+本文档汇总沐曦“揭榜挂帅”两项赛题的常见问题。使用 `Ctrl+F`（Windows/Linux）或 `⌘F`（macOS）搜索关键词。
+
+环境版本、评测配置、时间安排可能调整。请以仓库 README、XPU-OJ 公告、比赛群通知和容器中的实际版本为准。发现内容过期或未覆盖的问题，请[提交 Issue](https://gitlink.org.cn/metax-maca/op_optimization/issues)。
+
+## 快速导航
+
+- [重要入口与咨询方式](#entry)：XPU-OJ 开放情况、问题反馈渠道和赛事联系人。
+- [XPU-OJ、提交与排行榜](#xpuoj)：账号申请、提交环境、测试样例、评测硬件和排名指标。
+- [赛题一：TileLang 与 Fused MoE](#track-one)：提交限制、算子实现、Baseline、性能优化和决赛加分规则。
+- [赛题二：AI Agent 与推理算子库](#track-two)：任务范围、Agent 参与证明、Baseline、测试参数和上游代码引用。
+- [评测规则与通用技术问题](#evaluation)：技术资料发布、正确性与稳定性要求，以及 FAQ 内容纠错。
+- [环境、镜像与算力资源](#environment)：比赛镜像、MACA 与 PyTorch 版本、开发工具、算力券和资源申请。
+- [报名、组队与资格审核](#registration)：参赛资格、跨校组队、指导教师、材料盖章和审核流程。
+
+<a id="entry"></a>
+
+## 重要入口与咨询方式
+
+<a id="q-xpuoj-open"></a>
+
+### ❓ 问题 1：XPU-OJ 平台是否已经上线？
+
+**回答：** XPU-OJ 已开放。账号申领流程和使用指南见[赛事 XPU-OJ 账号申领说明](赛事XPUOJ账号申领说明.md)。
+
+<a id="q-contact"></a>
+
+### ❓ 问题 2：两个赛题的联系人不同，遇到问题应该联系谁？
+
+**回答：** 请先通过 [GitLink Issue](https://gitlink.org.cn/metax-maca/op_optimization/issues) 提问，维护者会把可复用的答案更新到本文档。比赛群用于接收赛事通知和临时信息。需要单独沟通时，请按对应比赛方案联系章老师或杨老师。
+
+## XPU-OJ、提交与排行榜
+
+<a id="q-moe-score-decrease"></a>
+
+### ❓ 问题 1：XPUOJ测评 MoE 耗时减少了但是分数反而降低了
+
+**回答：**
+
+针对近期部分同学反馈的“XPU.OJ”第三方评测系统中基线（baseline）不稳定的问题，我们高度重视，并已第一时间组织排查与测试。在此，我们对因此给大家带来的困扰深表歉意，也衷心感谢各位同学提出的宝贵意见。
+目前，相关问题已修复完毕。为确保评测的公平性与准确性，我们将对现有榜单进行清空处理。历史提交记录仍可查看，但后续排名将统一以基线修复后重新提交的算子成绩为准。
+
+比赛期间，我们将持续关注系统运行状态，也欢迎大家继续向我们反馈建议。
+祝大家比赛顺利，取得理想成绩！
+
+<a id="q-xpuoj-environment"></a>
+
+### ❓ 问题 2：XPU-OJ 与模力方舟的运行环境一致吗？
+
+**回答：** 排行榜评测环境与模力方舟开发环境保持一致。版本调整时以 XPU-OJ 公告为准。
+
+<a id="q-xpuoj-account"></a>
+
+### ❓ 问题 3：如何申请 XPU-OJ 账号？
+
+**回答：** 请按照[赛事 XPU-OJ 账号申领说明](赛事XPUOJ账号申领说明.md)提交申请。账号发放进度以赛事通知和回复邮件为准。
+
+<a id="q-official-ranking"></a>
+
+### ❓ 问题 4：赛题一 MoE 初赛排名以哪个入口为准？
+
+**回答：** 正式排名和初筛结果以 XPU-OJ 的评测结果为准。Sample benchmark 用于本地功能验证、调试和性能对比，不作为正式榜单依据。
+
+<a id="q-test-cases"></a>
+
+### ❓ 问题 5：MACA C++、Triton 和 TileLang 是否分别设榜？
+
+**回答：** 不按语言分别设榜。每个任务支持 MACA C++、Triton 和 TileLang，团队可以使用一种或多种语言提交。排行榜采用通过正确性和稳定性测试后的最高成绩。
+
+<a id="q-ranking-metric"></a>
+
+### ❓ 问题 6：排行榜使用 latency、speedup 还是综合 score？
+
+**回答：** 当前 XPU-OJ 以 speedup 作为核心排名指标。赛事方调整计算方式时，以 XPU-OJ 公告为准。
+
+<a id="track-one"></a>
+
+## 赛题一：TileLang 与 Fused MoE
+
+<a id="q-track-one-submission"></a>
+
+### ❓ 问题 1：赛题一的提交要求有哪些调整？
+
+**回答：** 正式提交禁止使用 `MACA Maca running` 方式，也不能使用 PyTorch 实现算子。参赛者需使用 TileLang 实现并提交。
+
+<a id="q-ops-reference"></a>
+
+### ❓ 问题 2：OPS 目录中的 TileLang、CUDA、CUTLASS 和 MACA 代码有什么用途？
+
+**回答：** 这些代码用于解释算子的实现原理和设计思路，可作为 TileLang 实现的参考。
+
+<a id="q-baseline-modification"></a>
+
+### ❓ 问题 3：官方 Baseline 可以修改到什么范围？
+
+**回答：** 参赛者可以重新设计和优化算子实现，但需保持与统一 Workload 测试框架的接口兼容。
+
+<a id="q-gemm-optimization"></a>
+
+### ❓ 问题 4：GEMM 计算中可以引入其他优化策略吗？
+
+**回答：** 可以，前提是实现符合赛题规则和评测要求。
+
+<a id="q-benchmark-modification"></a>
+
+### ❓ 问题 5：可以优化 `fusedmoe_benchmark` 吗？
+
+**回答：** 本地修改 benchmark 不会提高正式成绩，XPU-OJ 使用赛事方的评测框架。参赛者应把优化工作放在规定的算子实现和允许修改的接口上。
+
+<a id="q-forward-modification"></a>
+
+### ❓ 问题 6：可以修改 `fusedmoe_benchmark.py` 中的 MoE forward 吗？
+
+**回答：** 正式成绩以 XPU-OJ 的独立评测为准。本地修改 forward 不能替代对提交算子的优化，也不会改变赛事方的评测代码。
+
+<a id="q-async-copy"></a>
+
+### ❓ 问题 7：赛题一允许使用异步拷贝吗？
+
+**回答：** 不允许。当前比赛规则禁用异步拷贝。
+
+<a id="q-baseline-performance"></a>
+
+### ❓ 问题 8：Fused MoE 初赛成绩如何影响决赛？
+
+**回答：** 当前规则只给初赛前 10 名决赛加分，第 11 名及之后不获得额外初赛加分。
+
+<a id="track-two"></a>
+
+## 赛题二：AI Agent 与推理算子库
+
+<a id="q-track-two-update"></a>
+
+### ❓ 问题 1：赛题二的内容有什么调整？
+
+**回答：** “Agent 推理算子库优化 - FlashAttention KV Cache Decode”新增 `mctlass/cute` 要求。参赛者需基于 `mctlass/cute` 实现或优化对应任务。
+
+<a id="q-track-two-selection"></a>
+
+### ❓ 问题 2：赛题二可以选择几个任务？
+
+**回答：** 参赛团队可以从 FlashInfer、FlashAttention、MCTLASS/Fused MoE 等方向选择一项或多项。提交多个任务时，每个任务按赛事规则取有效最高成绩。支持语言包括 Triton、MXMACA C++ 和 TileLang。
+
+<a id="q-agent-proof"></a>
+
+### ❓ 问题 3：如何证明 AI Agent 参与了优化过程？
+
+**回答：** 参赛团队应保留 Agent 配置、Skill 文件、关键提示词、操作日志、代码变更记录、测试结果和复现实验步骤，等待赛事方发布核验细则。
+
+<a id="q-agent-baseline"></a>
+
+### ❓ 问题 4：Agent 赛题的性能 baseline 使用哪个版本？
+
+**回答：** 当前评测使用赛事方提供的 baseline，标准环境为 `PyTorch-Agent / 2.8.0 / Python 3.12 / MACA 3.7.1.5`。赛事方变更 baseline 或评测方式时会发布通知。
+
+<a id="q-mla-dimensions"></a>
+
+### ❓ 问题 5：MLA 的 `QK dim = 576, VO dim = 512` 与 `race_tests` 参数冲突吗？
+
+**回答：** 不冲突。`race_tests` 中的 `dim=512, pe_dim=64` 对应 `QK dim = 576, V dim = 512`。
+
+<a id="q-nsa-ranking"></a>
+
+### ❓ 问题 6：NSA 的 109 个测试 case 如何计算榜单成绩？
+
+**回答：** XPU-OJ 通过统一接口统计测试总运行时间，再根据 baseline 计算整体 speedup。
+
+<a id="q-upstream-code"></a>
+
+### ❓ 问题 7：可以引用或修改 FlashInfer、FlashAttention 等上游代码吗？
+
+**回答：** 可以。参赛团队需遵守上游项目许可证，保留版权和许可证声明，并在提交材料中说明引用范围、迁移工作和自主优化内容。
+
+<a id="evaluation"></a>
+
+## 环境、镜像与算力资源
+
+<a id="q-environment-image"></a>
+
+### ❓ 问题 1：比赛使用哪个在线算力环境？
+
+**回答：** 比赛使用模力方舟沐曦算力专区。仓库 README 当前标注的统一镜像为：
+
+```text
+PyTorch-Agent / 2.8.0 / Python 3.12 / MACA 3.7.1.5
+```
+
+创建实例和连接环境的步骤见[模力方舟快速使用 SOP](模力方舟快速使用SOP.md)。
+
+<a id="q-download-maca"></a>
+
+### ❓ 问题 2：如何获取 MACA 镜像或安装包？
+
+**回答：** 参赛者可以在[模力方舟沐曦算力专区](https://ai.gitee.com/compute/metax)选择 `PyTorch-Agent` 镜像。需要单独获取软件包时，请前往[沐曦开发者社区软件中心](https://developer.metax-tech.com/softnova/docker?chip_name=%E6%9B%A6%E4%BA%91C500%E7%B3%BB%E5%88%97&package_kind=AI&dimension=docker)，并选择与比赛标准环境一致的 MACA `3.7.1.5` 版本。
+
+<a id="q-download-pytorch"></a>
+
+### ❓ 问题 3：比赛使用的 PyTorch 镜像可以下载吗？
+
+**回答：** 可以。请在[沐曦开发者社区](https://developer.metax-tech.com/)或其 [PyTorch 镜像列表](https://developer.metax-tech.com/softnova/docker?chip_name=%E6%9B%A6%E4%BA%91C500%E7%B3%BB%E5%88%97&package_kind=AI&dimension=docker&deliver_type=%E5%88%86%E5%B1%82%E5%8C%85&ai_frame=pytorch)中查询。下载前请核对比赛镜像的 Python、PyTorch 和 MACA 版本。
+
+<a id="q-version-mismatch"></a>
+
+### ❓ 问题 4：页面标注的 MACA 版本与容器内版本不一致怎么办？
+
+**回答：** 比赛标准版本为 MACA `3.7.1.5`。
+
+<a id="q-pytorch-source"></a>
+
+### ❓ 问题 5：Linux 版本的 mcprofiler 是否可用？
+
+**回答：** mcprofiler 的 Linux 版本已经打包进模力方舟上的 pytorch-agent 比赛镜像。
+
+<a id="q-compute-coupons"></a>
+
+### ❓ 问题 6：算力券按团队还是按个人领取？
+
+**回答：** 新人礼和启悟社区算力券按学生个人发放，符合条件的团队成员均可领取。团队主申请人的额度用完后，其他成员可以继续申请资源。
+
+- [沐曦开发者社区新人礼](https://developer.metax-tech.com/activities/6)
+- [启悟社区学生算力券](https://developer.metax-tech.com/activities/11)
+- [赛事算力券活动](https://developer.metax-tech.com/activities/17)
+
+<a id="q-more-compute"></a>
+
+### ❓ 问题 7：算力额度不足时可以追加申请吗？
+
+**回答：** 可以先领取上述活动中的算力券。仍需额外资源时，请发送需求邮件至 `opensource@metax-tech.com`。
+
+<a id="q-commercial-agent-cost"></a>
+
+<a id="registration"></a>
+
+## 报名、组队与资格审核
+
+<a id="q-register-both"></a>
+
+### ❓ 问题 1：同一团队或个人可以同时参加两个赛题吗？
+
+**回答：** 可以。同一团队或个人可以同时报名两个赛题。
+
+<a id="q-register-multiple-tracks"></a>
+
+### ❓ 问题 2：同一名学生可以报名不同赛道的不同赛题吗？
+
+**回答：** 可以。赛事不统一限制学生报名不同赛道或不同赛题，但同一作品不得用相同核心技术内容重复申报不同赛题。
+
+<a id="q-new-graduate"></a>
+
+### ❓ 问题 3：本科应届毕业、尚未正式入学的研一新生可以报名吗？
+
+**回答：** 可以。参赛者可联系原本科学校完成认证手续，并以本科生身份报名。
+
+<a id="q-advisor-required"></a>
+
+### ❓ 问题 4：参赛必须配备指导教师吗？
+
+**回答：** 不强制。填写指导教师时，每支队伍可以设置 1 至 3 名指导教师。
+
+<a id="q-advisor-team-limit"></a>
+
+### ❓ 问题 5：一名指导教师最多可以指导几支队伍？
+
+**回答：** 赛事暂未设置统一的硬性上限。指导教师应根据可投入的时间控制队伍数量。
+
+<a id="q-cross-school-stamp"></a>
+
+### ❓ 问题 6：跨校组队时，报名表应该由哪所学校盖章？
+
+**回答：** 资格审批阶段，每名参赛者需到本人学校的校团委或院团委完成盖章确认。后续材料由团队牵头学生统一整理和提交。
+
+<a id="q-upload-stamped-form"></a>
+
+### ❓ 问题 7：提交报名后还可以补充已盖章的报名表扫描件吗？
+
+**回答：** 审核人员发现材料缺少盖章时，会退回申请。团队补齐材料后可以重新提交。尚未完成盖章的团队应先与学院、校团委或学校相关部门确认办理方式。
+
+<a id="q-stamp-department"></a>
+
+### ❓ 问题 8：资格审查材料应该加盖哪个部门的公章？
+
+**回答：** 各高校的管理口径不同。教务处、学生处等学籍或学生管理部门通常可以办理，参赛团队应以本校校团委或相关管理部门的要求为准。
+
+<a id="q-no-youth-league"></a>
+
+### ❓ 问题 9：学校未设校团委，可以用院系公章替代吗？
+
+**回答：** 赛事原则上要求校级部门公章。学校未设校团委时，可以联系校级学工、双创或教务部门盖章，并提交情况说明。院系公章不能直接替代校级部门公章。
+
+<a id="q-student-status-proof"></a>
+
+### ❓ 问题 10：学校无法配合盖章，可以用学籍证明替代吗？
+
+**回答：** 不可以。参赛团队应使用报名系统导出的报名表，并按要求完成学校盖章。
+
+<a id="q-public-notice"></a>
+
+### ❓ 问题 11：公示材料需要包含哪些内容？
+
+**回答：** 请参考赛事工作群发布的参考文本，并按学校要求调整。跨校团队涉及的学校应分别在学校官网公示，公示渠道原则上使用学校官网。
+
+<a id="q-review-deadline"></a>
+
+### ❓ 问题 12：报名审核需要在报名截止日前完成吗？
+
+**回答：** 原则上需要。往届出现过系统延后关闭的情况，但本届参赛团队不应据此推迟材料提交或审核。
+
+<a id="q-review-flow"></a>
+
+### ❓ 问题 13：报名材料的审核顺序是什么？
+
+**回答：** 学生提交材料后，学校校团委先审核；学校审核通过后，企业再审核。企业审核通过即视为报名成功。
+
+<a id="q-school-review-account"></a>
+
+### ❓ 问题 14：后台显示“校团委审核”，但学校不了解审核事项，怎么办？
+
+**回答：** 校团委需在报名系统内完成审核。省级团委通常会向各高校团委发放账号和密码。学校未收到或不了解安排时，请学校联系省级团委确认。
+
+## FAQ 维护约定
+
+1. 参赛者通过 Issue 提交问题。
+2. 维护者确认答案后更新本文档。
+3. 每个答案保留稳定锚点；需要时附上来源 Issue 或公告。
+4. 维护者在原 Issue 中回复 FAQ 锚点链接，并关闭已经解决的问题。
+5. 涉及版本、日期、评测参数的答案应标注确认日期。

README.md

@@ -1,5 +1,22 @@
 # 降低Token 成本，攻坚国产推理生态｜沐曦两大赛题登陆 2026 揭榜挂帅擂台赛，邀青年共破局！
 
+## 常用入口
+
+- [常见问题 FAQ](FAQ.md)
+- [沐曦通用GPU MXMACA编译器内建函数编程指南](https://developer.metax-tech.com/api/client/document/preview/1395/index.html)
+
+## XPU-OJ 基线修复及榜单调整通知
+
+针对近期部分同学反馈的“XPU.OJ”第三方评测系统中基线（baseline）不稳定的问题，我们高度重视，并已第一时间组织排查与测试。在此，我们对因此给大家带来的困扰深表歉意，也衷心感谢各位同学提出的宝贵意见。
+目前，相关问题已修复完毕。为确保评测的公平性与准确性，我们将对现有榜单进行清空处理。历史提交记录仍可查看，但后续排名将统一以基线修复后重新提交的算子成绩为准。
+
+比赛期间，我们将持续关注系统运行状态，也欢迎大家继续向我们反馈建议。
+祝大家比赛顺利，取得理想成绩！
+
+- XPU-OJ 地址：[https://xpuoj.com/](https://xpuoj.com/)
+- 账号申领说明：[赛事 XPU-OJ 账号申领说明](赛事XPUOJ账号申领说明.md)
+- 账号申领邮箱：`opensource@metax-tech.com`
+
 2026 年度中国青年科技创新「揭榜挂帅」擂台赛正式启幕。沐曦股份重磅发布两大 AI 算力硬核榜题，聚焦国产 GPU 大模型推理算子优化，以硬核赛事搭建科研攻关平台，邀全国青年学子、科研人才揭榜攻坚，用技术重构推理效率，用创新拉低每 Token 算力成本！
 
 ## 两大重磅赛题 直击推理成本核心痛点
@@ -29,7 +46,7 @@
 
 ### 赛题二：基于 AI Agent 开发范式的国产 GPU 大模型推理算子库优化
 
-大模型推理具有高并发、长序列、高调用频次等特点，FlashInfer、FlashAttention、Fused MoE 等核心算子直接决定模型服务的吞吐、延迟与显存开销，影响单 Token 综合推理成本。
+大模型推理具有高并发、长序列、高<EFBFBD><EFBFBD><EFBFBD>用频次等特点，FlashInfer、FlashAttention、Fused MoE 等核心算子直接决定模型服务的吞吐、延迟与显存开销，影响单 Token 综合推理成本。
 
 本赛题面向沐曦国产 GPU 及 MXMACA 软件栈，鼓励参赛团队构建或使用 AI Agent / Skill 工作流，围绕推理算子库开展代码理解、算子迁移、性能分析、Kernel 优化、自动调优、Benchmark 验证和多轮迭代，探索“Agent 驱动算子优化”的新型开发范式。