# Kimi-K3 REAP50 Width50 UD GGUF

[English](./README.md)

![Kimi-K3 REAP50とWidth50の概要](./reduction-overview.png)

[Kimi-K3](https://huggingface.co/moonshotai/Kimi-K3)を二段階で軽量化した実験的なGGUFです。

## キャリブレーションと選択

日本語チャット、コード生成、推論、ツール使用の応答文をtokenizeし、元のKimi-K3でforward passしました。評価したのはassistantの意味内容にあたるtokenだけです。prompt、制御token、構造tokenは除外しています。

### REAP50: expert軸

expert `e`のスコアは次のように計算しています。

```text
REAP(e) = mean[tがeへroute](Top-16内で再正規化したルータ重み × ||重み付け前のexpert出力||₂)
```

92のMoE層ごとに896 expertsを個別に並べ、上位448を残しました。手動で固定したexpertはありません。

### Width50: intermediate軸

キャリブレーションtoken `t`がexpert `e`へrouteされたとき、実際のexpert MLPに沿って次を計算しました。

```text
a(t,e)     = SiTU(Wgate,e × h(t), Wup,e × h(t))
y(t,e,b)   = router_weight(t,e) × Wdown,e[:,b] × a(t,e)[b]
score(e,b) = Σ[tがeへroute] ||y(t,e,b)||₂²
```

`b`は3072-channelのintermediate activationから切り出した32-channel部分です。その部分だけを対応する`Wdown`列へ通してhidden-sizeの出力vectorを作り、ルータ重みを掛けた二乗L2 normをassistantの意味token全体で加算しました。

隣接する8個の32-channel scoreを合計して、物理的なQK256 blockひとつのscoreにします。各expertで12 blocks中の上位6を残しました。観測tokenが少ないexpertでは、このactivation scoreをweight-based priorで補っています。width mapは元のexpert IDで計測し、GGUFをsliceする前にREAP50のkeep listへ対応付けました。

各blockは独立に評価しており、block間の打ち消しとmixture後のRMSNormはこの順位付けには含めていません。

## GGUFの作成順

```text
Kimi-K3 weights
  → Quantization
  → Q1 / Q2 GGUF
  → REAP50 expert-axis slice
  → Width50 QK256-block slice
  → final split GGUF
```

REAP50では、各MoE層の`ffn_gate_inp.weight`、`exp_probs_b.bias`、`ffn_{gate,up,down}_exps.weight`をexpert軸で896から448へsliceしました。

Width50では、`ffn_gate_exps.weight`、`ffn_up_exps.weight`、`ffn_down_exps.weight`のintermediate軸を3072から1536へsliceしました。量子化blockを丸ごとコピーしているため、残したデータの逆量子化や再量子化は行っていません。

| | 元モデル | このモデル |
|---|---:|---:|
| MoE層あたりのrouted experts | 896 | 448 |
| routed expertのFFN width | 3072 | 1536 |
| 1トークンあたりの使用expert数 | 16 | 16 |

ほかのtensorデータは変更していません。shared expertの物理的な幅6144をllama.cpp上で維持するため、メタデータ上は`2 × 3072`から`4 × 1536`へ表現を変えています。

## ファイル

| フォルダ | shard数 | サイズ |
|---|---:|---:|
| `UD-IQ1_S` | 14 | 約181 GiB |
| `UD-IQ1_M` | 15 | 約194 GiB |
| `UD-Q2_K_XL` | 19 | 約243 GiB |

使用するフォルダの先頭shardを読み込んでください。

## 使い方

llama.cppの[Kimi-K3 Width対応ブランチ](https://github.com/mmnga/llama.cpp/tree/kimi-k3-width-support)を使用します。

```bash
git clone --branch kimi-k3-width-support https://github.com/mmnga/llama.cpp
cmake -S llama.cpp -B llama.cpp/build -DGGML_CUDA=ON -DCMAKE_BUILD_TYPE=Release
cmake --build llama.cpp/build -j --target llama-server
```

`UD-IQ1_S`を使う例です。

```bash
./llama.cpp/build/bin/llama-server \
  -m ./UD-IQ1_S/Kimi-K3-UD-IQ1_S-00001-of-00014.gguf \
  -ot ".*.ffn_.*_exps.*=CPU" \
  -ngl 45 \
  --ctx-size 8192 \
  --flash-attn on \
  --jinja \
  --override-kv kimi-k3.expert_shared_count=int:2 \
  --override-kv kimi-k3.expert_shared_feed_forward_length=int:6144 \
  --override-kv kimi-k3.expert_used_count=int:16
```

この例はrouted expertsをCPUに置き、32 GBのRTX 5090で動作確認しています。使用可能なVRAMとRAMに合わせて`-ngl`とcontext sizeを調整してください。別の量子化を使う場合も、そのフォルダの先頭shardを指定します。

強く削減した実験モデルのため、元のKimi-K3とは品質や安定性が異なる場合があります。