Update README.md

README.md

@@ -1,107 +1,176 @@
-[---
-library_name: transformers
+---
+base_model: Qwen/Qwen3.5-9B
 pipeline_tag: text-generation
+library_name: transformers
 tags:
-- qwen
-- qwen3.5
-- text-generation
-- recurrent
-- linear-attention
-- cuda
-- custom-code
-base_model: Qwen/Qwen3.5-9B
+  - qwen
+  - qwen3.5
+  - recurrent
+  - linear-attention
+  - gdn
+  - cuda
+  - custom_code
+language:
+  - en
+  - ja
+# license: TODO — match the upstream Qwen/Qwen3.5-9B license
 ---
 
-# summerMC/Qwen3.5-9B-SpeedX9-GDN32
+**Language / 言語:** [English](#english) | [日本語](#日本語)
+
+---
+
+<a id="english"></a>
+
+# Qwen3.5-9B-SpeedX9-GDN32
 
-This repository contains a UNI MAX conversion of
-`Qwen/Qwen3.5-9B`.
+A recurrent linear-attention conversion of [`Qwen/Qwen3.5-9B`](https://huggingface.co/Qwen/Qwen3.5-9B), produced with the UNI MAX toolchain and designed for fast decoding.
 
-The source hybrid attention topology is converted to a recurrent
-linear-attention runtime. Full-attention layers are replaced through
-layer-wise distillation from neighboring native GDN/linear-attention
-layers.
+The source model's hybrid attention layout is converted into a fully recurrent linear-attention (GDN) runtime. Each full-attention layer is replaced by a layer initialized from a neighboring native GDN layer, then tuned with sequential layer-wise distillation.
 
-## Architecture
+> **Important:** This is a converted and distilled model, **not** the original `Qwen/Qwen3.5-9B` checkpoint. It is not numerically identical to the original, and quality has not been fully benchmarked (see [Limitations](#limitations)).
 
-- Base model: `Qwen/Qwen3.5-9B`
-- Hidden layers: `32`
-- Runtime topology: linear attention
-- Converted source full-attention layers: `3, 7, 11, 15, 19, 23, 27, 31`
-- Custom runtime: `qwen35_unimax_engine`
-- Kernel acceleration: enabled for the benchmark below
+## Overview
 
-The checkpoint should be used with the matching UNI MAX runtime code.
-It is not claimed to be numerically identical to the original
-full-attention model.
+| Item | Value |
+| --- | --- |
+| Base model | `Qwen/Qwen3.5-9B` |
+| Parameters / dtype | ~9B / BF16 |
+| Hidden layers | 32 |
+| Runtime topology | Linear attention (all layers) |
+| Converted full-attention layers | 3, 7, 11, 15, 19, 23, 27, 31 (8 layers) |
+| Custom runtime | `qwen35_unimax_engine` |
+| Kernel acceleration | CUDA kernels (enabled in the benchmark) |
+
+## How it was made
+
+1. **Layer replacement.** The 8 full-attention layers listed above were replaced with GDN/linear-attention layers, each initialized from a neighboring native GDN layer.
+2. **Distillation.** The replaced layers were optimized one after another with layer-wise distillation, using **20 optimization steps per converted layer** in this build.
+
+## Quick start
+
+The checkpoint must be loaded with the matching `qwen35_unimax_engine` runtime. Install it first.
 
-## Distillation
+```python
+from qwen35_unimax_engine import UniMaxPipeline
+
+pipe = UniMaxPipeline.from_pretrained(
+    "summerMC/Qwen3.5-9B-SpeedX9-GDN32",
+    mode="auto",
+    graph_candidates=(2, 4, 8),
+    quant_modes=("fp8", "int8"),
+    quality_steps=64,
+    min_agreement=1.0,
+    use_kernels=True,
+)
+
+print(pipe.runtime_summary())
+
+output = pipe(
+    "Explain recurrent linear attention:",
+    max_new_tokens=128,
+)
+print(output)
+```
 
-The converted full-attention layers were initialized from neighboring
-native GDN layers and then optimized with sequential layer-wise
-distillation.
+The repository is tagged `custom_code`; loading through plain `transformers` requires `trust_remote_code=True` and has not been verified here. Use the UNI MAX runtime above as the supported path.
 
-The current build used 20 optimization steps per converted layer.
+### Runtime configuration
 
-## Benchmark environment
+| Option | Value used in the benchmark |
+| --- | --- |
+| CUDA kernels | enabled |
+| Graph candidates | `(2, 4, 8)` |
+| Quantization candidates | `("fp8", "int8")` |
+| Quality verification steps | 64 |
+| Quality context | 64 |
+| Minimum fast-path agreement | 1.0 |
+
+With `mode="auto"`, the runtime may choose a different execution path depending on your hardware and the quality-verification result.
+
+## Benchmark
+
+Generated directly with `benchmark_uni_max()`.
+
+**Environment**
 
 | Item | Value |
-|---|---|
+| --- | --- |
 | GPU | NVIDIA RTX PRO 6000 Blackwell Server Edition |
 | GPU VRAM | 94.97 GiB |
 | Peak allocated VRAM during benchmark | 70.14 GiB |
 | PyTorch | 2.11.0+cu130 |
-| CUDA | 13.0 |
-| CUDA capability | 12.0 |
+| CUDA | 13.0 (compute capability 12.0) |
 | NVIDIA driver | 580.82.07 |
 | Decode steps | 64 |
-| Warmup runs | 2 |
-| Measured runs | 5 |
+| Warmup / measured runs | 2 / 5 |
 | Context lengths | 256, 1024, 4096, 16384 |
-| Benchmark wall time | 90.62 s |
+| Total wall time | 90.62 s |
 
-## Benchmark results
+**Selected configuration**
 
 | Metric | Value |
-|---|---:|
-| verified | None |
-| selected_mode | exact |
-| selected_block | 8 |
+| --- | --- |
+| Selected mode | `exact` |
+| Selected block | 8 |
+| Verified | _(not recorded in this build)_ |
+
+<!-- TODO: Replace the screenshot below with a table of tokens/s and latency per context length, taken from benchmark_results.json. The current card exposes the numbers only as an image. -->
 
-The benchmark above was generated directly from
-`benchmark_uni_max()` on the hardware shown above.
+![Raw benchmark output](https://cdn-uploads.huggingface.co/production/uploads/69e94913e947e9e6a0ae9d77/VYA_rtMMqGs3Auhdt2lyz.png)
+
+The machine-readable record is included as `benchmark_results.json`.
+
+Throughput, latency, kernel selection, quantization support, and memory use depend heavily on the GPU, CUDA/PyTorch versions, context length, and runtime settings. **Do not treat these numbers as hardware-independent performance claims.**
+
+## Validation
+
+Before publication, the checkpoint was checked with the UNI MAX checkpoint validator and the benchmark path. These layer-wise agreement checks are narrower than a full language-model evaluation suite, so please evaluate task quality yourself before deploying.
+
+## Limitations
+
+- Replacing full attention with recurrent linear attention changes the architecture. It can affect accuracy, long-context behavior, reasoning, generation quality, and numerical outputs relative to the original model.
+- Only 20 distillation steps per converted layer were used in this build.
+- No downstream task benchmarks (e.g., MMLU, long-context retrieval) are reported.
+- Benchmark results apply only to the hardware and software environment documented above.
+- Requires the matching custom runtime and an NVIDIA GPU with CUDA.
+
+## Base model and license
+
+Derived from `Qwen/Qwen3.5-9B`. Refer to the [upstream repository](https://huggingface.co/Qwen/Qwen3.5-9B) for the original documentation, license, intended use, and limitations.
+
+---
 
-Because throughput, latency, kernel selection, quantization support,
-and memory consumption depend strongly on the GPU, CUDA/PyTorch
-versions, context length, and runtime configuration, these numbers
-should not be treated as hardware-independent performance claims.
+<a id="日本語"></a>
 
-## Raw benchmark output
+# Qwen3.5-9B-SpeedX9-GDN32
 
+[`Qwen/Qwen3.5-9B`](https://huggingface.co/Qwen/Qwen3.5-9B) を、UNI MAX ツールチェーンで再帰型リニアアテンション（GDN）に変換した、高速デコード向けモデルです。
 
-![image](https://cdn-uploads.huggingface.co/production/uploads/69e94913e947e9e6a0ae9d77/VYA_rtMMqGs3Auhdt2lyz.png)
+元モデルのハイブリッドアテンション構成を、完全な再帰型リニアアテンションのランタイムに変換しています。フルアテンション層は、隣接するネイティブ GDN 層から初期化した層に置き換え、層ごとの逐次蒸留（layer-wise distillation）で調整しました。
 
-The machine-readable benchmark record is also included as
-`benchmark_results.json`.
+> **重要:** 本モデルは変換・蒸留された派生モデルであり、元の `Qwen/Qwen3.5-9B` そのものでは**ありません**。数値的に元モデルと一致するものではなく、品質も十分には評価されていません（[制限事項](#制限事項)を参照）。
 
-## Runtime configuration
+## 概要
 
-The benchmark evaluated:
+| 項目 | 値 |
+| --- | --- |
+| ベースモデル | `Qwen/Qwen3.5-9B` |
+| パラメータ数 / dtype | 約9B / BF16 |
+| 隠れ層数 | 32 |
+| ランタイム構成 | リニアアテンション（全層） |
+| 変換したフルアテンション層 | 3, 7, 11, 15, 19, 23, 27, 31（計8層） |
+| 専用ランタイム | `qwen35_unimax_engine` |
+| カーネル高速化 | CUDA カーネル（ベンチマーク時は有効） |
 
-- CUDA kernels enabled
-- graph candidates: `(2, 4, 8)`
-- quantization candidates: `('fp8', 'int8')`
-- quality verification steps: `64`
-- quality context: `64`
-- minimum fast-path agreement: `1.0`
+## 作成方法
 
-The runtime may select a different execution path depending on
-hardware support and quality verification.
+1. **層の置き換え:** 上記8つのフルアテンション層を GDN／リニアアテンション層に置き換え、各層は隣接するネイティブ GDN 層から初期化しました。
+2. **蒸留:** 置き換えた層を順番に層ごとの蒸留で最適化しました。今回のビルドでは**変換した各層につき 20 ステップ**です。
 
-## Usage
+## クイックスタート
 
-Install the matching `qwen35_unimax_engine` runtime before loading the
-checkpoint.
+チェックポイントの読み込みには、対応する `qwen35_unimax_engine` ランタイムが必要です。先にインストールしてください。
 
 ```python
 from qwen35_unimax_engine import UniMaxPipeline
@@ -122,34 +191,71 @@ output = pipe(
     "Explain recurrent linear attention:",
     max_new_tokens=128,
 )
-
 print(output)
 ```
 
-## Validation
+このリポジトリには `custom_code` タグが付いており、素の `transformers` で読み込む場合は `trust_remote_code=True` が必要ですが、動作は未検証です。上記の UNI MAX ランタイムを推奨パスとしてください。
 
-Before publication, the local checkpoint was checked with the UNI MAX
-checkpoint validator and benchmark path.
+### ランタイム設定
 
-Users should independently evaluate task quality before deploying the
-converted model. Layer-wise agreement tests are narrower than a full
-language-model evaluation suite.
+| オプション | ベンチマークでの値 |
+| --- | --- |
+| CUDA カーネル | 有効 |
+| グラフ候補 | `(2, 4, 8)` |
+| 量子化候補 | `("fp8", "int8")` |
+| 品質検証ステップ数 | 64 |
+| 品質検証コンテキスト長 | 64 |
+| 高速パスの最小一致率 | 1.0 |
 
-## Limitations
+`mode="auto"` では、ハードウェアや品質検証の結果に応じて、別の実行パスが選ばれることがあります。
+
+## ベンチマーク
+
+`benchmark_uni_max()` から直接生成した結果です。
+
+**実行環境**
+
+| 項目 | 値 |
+| --- | --- |
+| GPU | NVIDIA RTX PRO 6000 Blackwell Server Edition |
+| GPU VRAM | 94.97 GiB |
+| ベンチマーク中の最大確保 VRAM | 70.14 GiB |
+| PyTorch | 2.11.0+cu130 |
+| CUDA | 13.0（compute capability 12.0） |
+| NVIDIA ドライバ | 580.82.07 |
+| デコードステップ数 | 64 |
+| ウォームアップ / 計測回数 | 2 / 5 |
+| コンテキスト長 | 256, 1024, 4096, 16384 |
+| 総実行時間 | 90.62 秒 |
+
+**選択された構成**
+
+| 指標 | 値 |
+| --- | --- |
+| 選択モード | `exact` |
+| 選択ブロック | 8 |
+| verified | （このビルドでは記録なし） |
+
+<!-- TODO: 下の画像を、benchmark_results.json に基づくコンテキスト長ごとの tokens/s・レイテンシの表に置き換える。 -->
+
+![ベンチマーク生出力](https://cdn-uploads.huggingface.co/production/uploads/69e94913e947e9e6a0ae9d77/VYA_rtMMqGs3Auhdt2lyz.png)
+
+機械可読な結果は `benchmark_results.json` に含まれています。
+
+スループット、レイテンシ、カーネル選択、量子化対応、メモリ使用量は、GPU、CUDA/PyTorch のバージョン、コンテキスト長、ランタイム設定に大きく依存します。**これらの数値をハードウェア非依存の性能保証として扱わないでください。**
+
+## 検証
 
-This is a converted and distilled model, not the unmodified
-`Qwen/Qwen3.5-9B` checkpoint.
+公開前に、UNI MAX のチェックポイント検証ツールとベンチマーク経路で確認しています。ただし、層単位の一致確認は言語モデル全体の評価スイートよりも範囲が狭いため、運用前にご自身のタスクで品質を評価してください。
 
-Replacing full attention with recurrent linear attention changes the
-model architecture and can affect accuracy, long-context behavior,
-reasoning, generation quality, and numerical output.
+## 制限事項
 
-Benchmark results are specific to the hardware and software
-environment documented above.
+- フルアテンションを再帰型リニアアテンションに置き換えているため、元モデルと比べて、精度、長文脈での挙動、推論能力、生成品質、数値出力が変化する可能性があります。
+- 今回のビルドでは、変換した各層の蒸留は 20 ステップのみです。
+- 下流タスクのベンチマーク（MMLU、長文脈検索など）は報告していません。
+- ベンチマーク結果は、上記に記載したハードウェア・ソフトウェア環境に限られます。
+- 専用ランタイムと、CUDA 対応の NVIDIA GPU が必要です。
 
-## Base model
+## ベースモデルとライセンス
 
-Derived from `Qwen/Qwen3.5-9B`. Refer to the upstream model repository
-for the original model documentation, license, intended use, and
-limitations.
-](https://huggingface.co/summerMC/Qwen3.5-9B-SpeedX9-GDN32)
+`Qwen/Qwen3.5-9B` から派生しています。元のドキュメント、ライセンス、想定用途、制限事項は[上流リポジトリ](https://huggingface.co/Qwen/Qwen3.5-9B)をご確認ください。