mxflashattn 1.4.0__tar.gz

mxflashattn-1.4.0/CONTRIBUTING.md

@@ -0,0 +1,22 @@
+# Contributing
+
+Contributions should include focused tests, documentation for new supported behavior, and a clear statement of which backend was exercised.
+
+## Local Checks
+
+```bash
+python -m pip install -e ".[dev]"
+python -m pytest
+```
+
+## C500 Results
+
+Do not report C500 support or performance from CPU tests. Include the C500 model, driver, MXMACA runtime, vendor PyTorch, compiler, and vLLM versions with native test results. Preserve the generated JSON and Markdown report. Never replace a native failure with an unreported reference fallback.
+
+## Scope
+
+The initial public surface is forward-only FP16/BF16 attention with head dimensions 64 and 128. Backward, FP8, multi-card execution, rotary embeddings, ALiBi, and local windows are outside the verified support matrix.
+
+## Licensing
+
+New code is contributed under Apache-2.0. List third-party code, generated assets, model weights, and benchmark datasets with their source and license; do not copy them into the repository without permission.

mxflashattn-1.4.0/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!) The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [2026] [MXFlashAttn contributors]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

mxflashattn-1.4.0/MANIFEST.in

@@ -0,0 +1,10 @@
+include README.md
+include LICENSE
+include CONTRIBUTING.md
+include requirements-c500.txt
+include requirements-vllm.txt
+recursive-include csrc/mxmac *.cpp *.h CMakeLists.txt
+recursive-include benchmarks *.py *.yaml
+recursive-include docs *.md *.json *.png
+recursive-include integrations *.py *.md
+recursive-include tests *.py

mxflashattn-1.4.0/PKG-INFO

@@ -0,0 +1,242 @@
+Metadata-Version: 2.4
+Name: mxflashattn
+Version: 1.4.0
+Summary: FlashAttention-compatible forward APIs and MXMACA bring-up backend
+License-Expression: Apache-2.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: torch>=2.4
+Requires-Dist: PyYAML<7,>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest<10,>=8; extra == "dev"
+Requires-Dist: ruff<1,>=0.6; extra == "dev"
+Provides-Extra: vllm
+Requires-Dist: vllm==0.17.0; extra == "vllm"
+Provides-Extra: reports
+Requires-Dist: matplotlib<4,>=3.8; extra == "reports"
+Dynamic: license-file
+
+# MXFlashAttn
+
+> **状态（2026-10-17）：v1.4.0 C500 发布候选版本。**
+> 已完成 C500 上的算子、真实 vLLM 0.17.0 生成、dispatch、回退和近 16K 长上下文回归；
+> 生产加速范围仍限定为 M1 Split-KV Decode，不宣称 Prefill 生产加速。
+>
+> **项目边界：**这是面向 MXMACA/MetaX C500 的专项适配与 decode 优化工程，
+> 不是跨硬件 FlashAttention 替代品，也不是 MXAttention（MXFP4）复现。
+
+中文说明 · **[English](README.en.md)**
+
+MXFlashAttn 是面向 **MXMACA / MetaX C500** 的 FlashAttention 兼容前向算子与推理适配项目。
+v1.3.0 起包含**自研 device kernel**（`csrc_native/m1_kernel.cpp`，split-KV paged decode）。
+v1.4.0 在 v1.3.0 基础上完成了 C500 验证和长上下文回归。2026-10-17 的复测中，
+Qwen3-4B 在 batch=32、max_tokens=1024 的长上下文 decode 场景相对本项目 v7 路径达到约
+**3.66×** 吞吐；Qwen3-8B 在 batch=16、max_tokens=256 时约 **1.37×**。跨模型结果表明收益依赖模型、
+batch 和 KV 长度，短序列或低并发不保证加速。
+
+[![CI](https://github.com/leo1852098393-blip/MXFlashAttn/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/leo1852098393-blip/MXFlashAttn/actions/workflows/ci.yml)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
+[![Python](https://img.shields.io/badge/python-3.10%2B-3776AB.svg)](pyproject.toml)
+
+## 2026-10-13 C500 复测结果（申报主口径/历史对照）
+
+环境：MetaX C500 64G、MACA 3.5.3.20、驱动 3.8.30、PyTorch
+`2.8.0+metax3.5.3.9`、vLLM 0.17.0。所有 M1 结果均由 dispatch 日志确认进入
+`m1_split_decode`。
+
+| 模型与场景 | v7 | M1-UM2 | 相对 v7 |
+| --- | ---: | ---: | ---: |
+| Qwen3-4B，batch=128，256 token | 1375.59 tok/s | 4554.69 tok/s | **3.31×** |
+| Qwen3-4B，batch=32，1024 token | 359.82 tok/s | 1293.48 tok/s | **3.59×** |
+| Qwen3-8B，batch=16，256 token | 500.79 tok/s | 703.06 tok/s | **1.40×** |
+| PaddleOCR-VL，batch=16，64 token | 281.73 tok/s | 334.71 tok/s | **1.19×** |
+
+本轮最新复测为 Qwen3-4B `v7=357.76`、`M1-UM2=1309.15 tok/s`（约 **3.66×**），
+Qwen3-8B `v7=508.48`、`M1-UM2=695.45 tok/s`（约 **1.37×**）。
+这些数字只描述表中 C500 配置，不外推为所有模型或所有请求形态的固定倍率。
+另已完成 Qwen3-4B 真实 15,000 token prompt、`max_model_len=16384` 的
+vendor prefill + M1 decode 回归，生成 32 token 成功且 M1 dispatch 命中。
+流式 TTFT/P95 采集链路已验证，但 candidate 记录没有 M1 dispatch 事件，
+因此不把它写成 M1 TTFT 性能提升。
+
+2026-10-13 的复测表仍作为申报主口径和历史对照保留在
+[`docs/results/c500-2026-10-13.md`](docs/results/c500-2026-10-13.md)。
+
+2026-10-07 Gate 4 的更大场景矩阵（包括 3.67×、6.48× 等数字）保留在历史报告中，
+用于说明研发过程与形状覆盖，不与本轮复测混成同一组结果：
+[`docs/gate4/Gate4_收官报告.md`](docs/gate4/Gate4_收官报告.md)。
+
+支持形状 `{GQ in {2,4,8} x HD in {64,128}}` 的**全部6 个格子均有真实模型 E2E 证据**；
+M1 不支持的形状不得直接调用 binding。vLLM official-split 路径会把这些形状交还原始
+MetaX/vendor KV-cache 实现。2026-10-13 已用 Qwen3.5-9B（head_dim=256）验证：
+真实生成成功、M1 dispatch=0、M1-UM/M1-UM2 均为 4/4 文本匹配。
+
+新一轮原始证据和报告位于申报工作空间的本地目录 `02_evidence/c500_20261013/`；
+公开仓库内的历史 Gate 4 证据见
+[`docs/gate4/E2E_大模型与守卫验证.md`](docs/gate4/E2E_大模型与守卫验证.md)。
+
+## 快速复现（需要 C500）
+
+```bash
+export MACA_PATH=/opt/maca          # 缺这一行 triton import 会报NoneType
+bash csrc_native/build_m1.sh        # mxcc 编译 M1，产出 csrc_native/mxmmain.so
+python csrc_native/patch_plugin.py  # 把 M1 接线打进 vLLM 插件（幂等）
+python csrc_native/test_m1.py       # 稳健性矩阵：s1~s8192 / GQA 2,4,8 / bf16 / ovf
+```
+
+端到端基准（注意四个环境变量，缺任一项会静默全走 vendor 直连，三路对比退化为同一路径跑三遍）：
+
+```bash
+export MXFLASHATTN_GRAPH_OFFICIAL_SPLIT=1 MXFA_NATIVE_DECODE=1
+export VLLM_ENABLE_V1_MULTIPROCESSING=0   # EngineCore 是子进程，否则 env 热切换无效
+python csrc_native/bench_e2e.py --model /path/to/Qwen3-4B --batches 128 64 --max-tokens 256 --output artifacts/bench-q4b.json
+```
+
+**判据：先查 `dispatch.jsonl` 里 `m1_split_decode` 的事件计数，再信吞吐数字。**
+计数为 0 说明内核根本没被派发，数据无意义。
+
+## 能力矩阵
+
+| 能力 | 状态 |
+| --- | --- |
+| FP16 / BF16 forward | C500 已验证 |
+| Head dimension 64 / 128 | C500 已验证 |
+| GQA 比率 2 / 4 / 8 | C500 已验证 |
+| M1 不支持的 GQA 比率（历史验证 GQ=5/7） | 不进入 M1；由上层回退，未验证比率不作支持承诺 |
+| vLLM 中 head_dim > 128 | 不进入 M1；official split 回退原始 MetaX/vendor 路径 |
+| 直接调用 MXFlashAttn 公共 API 的 head_dim > 128 | 显式 `ValueError`，不静默计算 |
+| 自研 split-KV decode kernel（M1） | C500 已验证，vLLM 0.17.0 接线 |
+| dense / varlen / paged KV cache | API 已实现；paged KV append 已在 C500 验证 |
+| dispatch 后端 | `m1_split_decode`（M1）→ `native_decode`（v7）→ `vendor_direct` → `reference` |
+| PyTorch reference fallback | 需显式设置 `MXFLASHATTN_ALLOW_FALLBACK=1`，不会静默切换 |
+| TTFT / P95 | 流式采集链路已验证；candidate 未命中 M1，不作为 M1 性能证据 |
+| backward、FP8、多卡 | 首期不支持 |
+| SGLang | 未安装验证 |
+
+详细边界见 [`docs/support-matrix.md`](docs/support-matrix.md)。
+
+## 项目结构
+
+```text
+mxflashattn/       Python API、校验、reference 与 dispatch
+csrc/mxmac/        C++/ATen bring-up 扩展（朴素 O(n^2) 实现，正确性对照路径）
+csrc_native/       自研 M1 split-KV decode 内核 + v7 内核 + 基准/测试/构建脚本
+integrations/vllm/ vLLM 0.17.0 适配桥接、decoder adapter 与 preflight
+benchmarks/        固定配置、公平矩阵运行器和报告工具
+scripts/           C500 实例运维与 E2E 复现脚本（模型暂存、形状扫描、各模型 E2E 编排）
+docs/gate4/        Gate 4 技术报告（原始实例日志保留在本地工作空间）
+docs/results/      C500 原始结果、报告和图表
+tests/             CPU/reference 与 C500 条件测试
+```
+
+`csrc/mxmac/` 是 **PyTorch ATen bring-up / 正确性对照路径**，由 `at::matmul` + `softmax`
+组装的朴素实现，不是融合 kernel。自研 device kernel 在 `csrc_native/`。
+
+Gate 4 各档E2E 的实例侧复现脚本在 `scripts/`（对应文档各节）：
+`run_e2e_q4b.sh` / `run_e2e_q8b.sh`（GQ=4 主场景）、
+`run_e2e_gq7.sh`（GQ=7 守卫拒绝）、`run_e2e_gq8.sh`（GQ=8 PaddleOCR-VL）、
+`run_e2e_hd256.sh`（HD=256 回退验证）、`run_queue.sh`（单卡串行编排）、
+`scan_shapes.sh`（共享模型库形状扫描）和 `probe_paddle_vllm.sh`（架构探测）。
+这些公开脚本面向有 C500 的实例；模型下载与数据盘暂存脚本属于本地申报工作区，
+不随公开仓库发布。项目根目录支持通过 `MXFLASHATTN_ROOT` 覆盖，模型路径由各脚本中的
+`MODEL` 变量或命令行 `--model` 提供。
+
+## 前向算子 API
+
+公开接口：
+
+- `flash_attn_func`
+- `flash_attn_varlen_func`
+- `flash_attn_with_kvcache`
+
+```python
+import torch
+from mxflashattn import flash_attn_func, get_last_dispatch_info
+
+q = torch.randn(1, 32, 8, 64, dtype=torch.float16, device="cuda")
+k = torch.randn(1, 128, 2, 64, dtype=q.dtype, device=q.device)
+v = torch.randn_like(k)
+out = flash_attn_func(q, k, v, causal=True)
+print(get_last_dispatch_info())
+```
+
+在没有 MetaX provider 或编译扩展时，调用默认报错。只有主动设置
+`MXFLASHATTN_ALLOW_FALLBACK=1` 才启用 PyTorch reference fallback（会发`RuntimeWarning`）。
+dropout、局部窗口、AliBi、soft-capping、rotary embeddings、backward 和 softmax-LSE
+返回会明确报错，不会静默产生错误结果。
+
+## 历史基准（v0.9公平矩阵）
+
+v0.9 用固定 seed 覆盖 36 组 batch/seq/head_dim/GQA 比例/layout/dtype/causal 组合，
+在 C500 上做reference、Torch SDPA、MetaX vendor、MXFlashAttn API 四路公平对比：
+
+| 指标 | 结果 |
+| --- | --- |
+| 公平矩阵完成度 | C500 36/36 组 |
+| MXFlashAttn vs PyTorch reference | 中位延迟下降 60.52% |
+| MXFlashAttn vs MetaX vendor 直调 | 中位延迟**上升 32.74%** |
+| 最大绝对误差 | 0.00390625 |
+
+必须同时说清的口径：算子级基线是**同输入同设备的四路公平矩阵**，不是拿自写 reference
+单独对比得出的加速比；模型级 vendor 与 candidate **分栏列示**，不混入算子级 median。
+仓库早期那组 384 用例 benchmark基线是本项目 PyTorch reference，已被 v0.9 公平矩阵取代，
+仅作历史数据保留在 `docs/results/`。
+
+公开仓库提供脱敏结果摘要：[`docs/results/c500-2026-10-05.md`](docs/results/c500-2026-10-05.md)
+和 [`docs/results/c500-2026-10-13.md`](docs/results/c500-2026-10-13.md)。完整原始 JSON、
+dispatch 流和实例环境记录保留在本地申报工作空间，不随公开仓库发布。下面命令的
+`--output` 是**重新生成**时的本地输出目标。
+
+```bash
+# 评测输出默认写入被忽略的 artifacts/，只作为本地复现缓存。
+python -m benchmarks.fair_matrix --device cuda --count 36 --repeats 5 \
+  --output artifacts/fair-matrix-c500.json
+python benchmarks/fair_report.py artifacts/fair-matrix-c500.json \
+  --vendor-model artifacts/vllm-vendor-36.json \
+  --candidate-model artifacts/vllm-candidate-36.json \
+  --output artifacts/fair-matrix-c500.md
+```
+
+![C500 benchmark summary](docs/results/c500-speedup-summary.png)
+
+## vLLM 集成
+
+`integrations/vllm/vllm_plugin.py` 注册 MXFlashAttn backend。v1.3.0 起该插件在
+`MXFA_M1_DECODE=1` 时把 paged decode 派发给 M1 内核，不支持的形状自动落回 v7，
+再不支持则落回 MetaX vendor 直连。接线细节见
+[`docs/gate4/M3_VLLM_WIRING.md`](docs/gate4/M3_VLLM_WIRING.md)。
+
+```bash
+python integrations/vllm/smoke_generate.py --model /mnt/moark-models/Qwen3-0.6B \
+  --prompt-count 36 --max-tokens 16 --baseline-only \
+  --output artifacts/vllm-vendor-36.json
+```
+
+## 已知限制
+
+- **v7 路径上下文上限 4096**（>4096 启动失败）。
+- **M1 相对硬件上限仍有差距**：IR 分析显示 v7 走硬件融合`llvm.mxc.expadd.f32.i32`
+  做 softmax 重缩放，而 M1 走软件 shuffle 归约 + `exp2` 模拟。替换为硬件 intrinsic
+  是下一步方向，尚未实施。
+- **text_match 不可在连续批处理下作正确性判据**：batch 组成随调度漂移。文本一致性
+  必须在固定 batch 下单独验证（见 `csrc_native/diag_guard_text_match.py`）。
+- **dispatch 事件统计必须按 `(path, operation, fallback)` 三元组**，只按 path取 top-N
+  会在 M1 从未成功时误判为"没派发"。
+
+## 路线图
+
+后续优化与风险收敛路线见 [`docs/V1.5_OPTIMIZATION_PLAN.md`](docs/V1.5_OPTIMIZATION_PLAN.md)。
+其中包括 M1 硬件 intrinsic 评估、C500 Prefill kernel、可复现 TTFT 口径、
+自适应调度、vLLM 新版本兼容性以及 FP8/多卡/SGLang 评估；这些不属于
+v1.4.0 已完成能力。
+
+## 许可证
+
+本项目采用 [Apache License 2.0](LICENSE)。MXMACA runtime、vendor PyTorch、MetaX wheel、
+vLLM、模型权重和数据集分别遵循各自许可证。
+
+欢迎通过 [`CONTRIBUTING.md`](CONTRIBUTING.md) 提交问题和改进。