---
language:
- zh
- en
library_name: peft
tags:
- lora
- peft
- 蒸餾
- svd
- 跨架構
- 自適應rank
- gemma
- llama
- nemotron
base_model: Changgil/google-gemma-3-27b-it-text
---

# Nemotron-70B → Gemma-3 27B（Text）SVD-LoRA Adapter（自適應 Rank）

English version: **[README.md](README.md)**

本 Repo 提供一個 **PEFT LoRA adapter**，基於 `Changgil/google-gemma-3-27b-it-text`（學生 / base model），以 `nvidia/Llama-3.1-Nemotron-70B-Instruct-HF`（教師）為參考來源，採用 **權重差分（Δ）SVD-LoRA 蒸餾**產生（跨架構）。

- **Base model（Student / 必要）**：`Changgil/google-gemma-3-27b-it-text`
- **Teacher model（參考）**：`nvidia/Llama-3.1-Nemotron-70B-Instruct-HF`
- **交付物**：LoRA adapter（PEFT）—— *不是* 合併後完整權重
- **作用範圍**：attention + MLP（`self_attn|mlp`）

---

## 這是什麼？

此 adapter 以 teacher→student 的**權重差分**（Δ）為目標，對每個線性層差分矩陣做低秩近似，並輸出為 LoRA 因子矩陣（adapter 權重）。

本 adapter 的設計重點是 **跨架構蒸餾**（teacher / student 層數與 hidden size 不相同）：

- **SVD 後端**：`aurora`（AURORA-SVD）
- **Adaptive rank**：透過能量門檻自動決定每個模組的 rank
- **Teacher mixing**：`lsq`（逐矩陣 least-squares 混合）
- **校準**：使用 Alpaca 格式樣本做 RMS 校準

---

## 使用方式（Transformers + PEFT）

> 這是 adapter。推論時必須先載入 base model，再套用本 LoRA。

```python
import torch
from transformers import AutoTokenizer, AutoModelForCausalLM
from peft import PeftModel

base_id = "Changgil/google-gemma-3-27b-it-text"
adapter_id = "win10/Nemotron2Gemma-AURORA-LoRA-27B-IT-0p95"

tokenizer = AutoTokenizer.from_pretrained(base_id, use_fast=True)

base = AutoModelForCausalLM.from_pretrained(
    base_id,
    torch_dtype=torch.bfloat16,
    device_map="auto",
)

model = PeftModel.from_pretrained(base, adapter_id)
model.eval()

messages = [
    {"role": "system", "content": "你是一個有幫助的助理。"},
    {"role": "user", "content": "請用 5 點條列說明知識蒸餾。"},
]

inputs = tokenizer.apply_chat_template(
    messages,
    add_generation_prompt=True,
    tokenize=True,
    return_tensors="pt",
)

with torch.no_grad():
    out = model.generate(
        inputs.to(model.device),
        max_new_tokens=512,
        do_sample=False,
    )

print(tokenizer.decode(out[0], skip_special_tokens=True))
```

---

## 可選：合併 LoRA 到 base model（輸出單一權重）

```python
from peft import PeftModel

merged = model.merge_and_unload()
merged.save_pretrained("./merged_model", safe_serialization=True)
tokenizer.save_pretrained("./merged_model")
```

---

## 可重現性（蒸餾命令）

本 adapter 的產生指令等價於：

```bash
python universal_distill_v4_1_0_aurora_svd_innovations.py \
  --teacher E:\text-generation-webui-1.14\user_data\models\Llama-3.1-Nemotron-70B-Instruct-HF \
  --student E:\text-generation-webui-1.14\user_data\models\google-gemma-3-27b-it-text \
  --output  ./Llama-3.1-Nemotron-70B-Instruct-HF-gemma-3-27b-it-text-lora-adaptive \
  --svd-mode aurora \
  --energy-threshold 0.95 \
  --min-rank 256 \
  --max-rank 5376 \
  --interp-mode lsq \
  --svd-rand-iter 2 \
  --svd-rand-oversamples 8 \
  --svd-aurora-steps 100 \
  --svd-aurora-order 2 \
  --calib-format alpaca \
  --calib-alpaca-template classic \
  --calib-max-samples 128 \
  --calib-max-length 65536 \
  --calib-batch-size 2 \
  --calib-save .\calib_stats_Yi-70B-200k_alpaca-taiwan-dataset.safetensors \
  --calib-mode rms \
  --include "self_attn|mlp"
```

執行摘要（示例 log）：
- Teacher tensors：723
- Student tensors：808
- Teacher：GQA + SwiGLU，80 layers，hidden 8192
- Student：GQA + standard FFN，62 layers，hidden 5376
- TIES：啟用（density=0.3）
- DARE：關閉

---

## 相容性注意事項

- 本 adapter 針對 `Changgil/google-gemma-3-27b-it-text` 的 module 命名與 shape 製作。
- 若你改用其他 Gemma-3 27B 變體，必須 shape 相容（否則無法載入 adapter）。

---

## 限制

- 本方法屬於**權重空間蒸餾**（近似權重差分），可轉移部分行為/風格，但不保證在所有任務完全等同 teacher。
- 效果會依 base model 的 chat template 與解碼設定而變化。

---

## 源模型連結

- Base model：https://huggingface.co/Changgil/google-gemma-3-27b-it-text
- Teacher model：https://huggingface.co/nvidia/Llama-3.1-Nemotron-70B-Instruct-HF

---

## License

請依 Hugging Face 上 **base model** 與 **teacher model** 的頁面所標示之授權條款與使用限制執行。本 Repo 僅提供 adapter 權重；下游使用需自行確保符合上游條款。