Incredible.AI

OpenClaw on Ubuntu + Docker Isolation

Sun, 01 Feb 2026 01:00:00 +0000

1. Installation

$ git clone git@github.com:openclaw/openclaw.git 

# go to openclaw directory
$ ./docker-setup.sh

Change docker-compose.yml.
I added extra_hosts : "host.docker.internal:host-gateway".

services:
  openclaw-gateway:
    image: ${OPENCLAW_IMAGE:-openclaw:local}
    extra_hosts:
      - "host.docker.internal:host-gateway"

install brew manually.
it seesm the docker container doesn’t have brew and during installation it fails if brew is not installed.

mkdir ~/.linuxbrew && curl -L https://github.com/Homebrew/brew/tarball/master | tar xz --strip 1 -C ~/.linuxbrew

# set up environment variables 
echo 'export PATH="$HOME/.linuxbrew/bin:$HOME/.linuxbrew/sbin:$PATH"' >> ~/.bashrc
echo 'export MANPATH="$HOME/.linuxbrew/share/man:$MANPATH"' >> ~/.bashrc
echo 'export INFOPATH="$HOME/.linuxbrew/share/info:$INFOPATH"' >> ~/.bashrc

# 3. 현재 세션에 적용
source ~/.bashrc

Model Provider

vLLM

you can serve local LLM like this.

vllm serve openai/gpt-oss-20b \
    --host 127.0.0.1 \
    --port 8045 \
    --tensor-parallel-size 1 \
    --gpu-memory-utilization 0.3 \
    --trust-remote-code \
    --async-scheduling \
    --max-num-batched-tokens 8192 \
    --max-model-len 35096 \
    --api-key 1234

connect to Docker terminal and then change the connection information like this.
no need to restart the openclaw container.

# change address to host.docker.internal
sed -i 's/127.0.0.1/host.docker.internal/' ~/.openclaw/openclaw.json

# change vLLM API key (1234)
sed -i 's/"VLLM_API_KEY"/"1234"/' ~/.openclaw/openclaw.json

Setup OpenClaw Gateway

connect to Docker terminal and you can get a gateway token

$ echo $OPENCLAW_GATEWAY_TOKEN
05c5df07ef01<eradicated>

http://127.0.0.1:18789/overview
in Gateway Access, put the token in Gateway Token

Token Issue

If you happen to run ./docker-setup.sh multiple times, it generates a new random gateway token.
this creates a mismatch between .env and ~/.openclaw/openclaw.json

$ grep OPENCLAW_GATEWAY_TOKEN .env
OPENCLAW_GATEWAY_TOKEN=05c5df0<eradicated>

$ grep -o '"token": "[^"]*"' ~/.openclaw/openclaw.json
"token": "05c5df0<eradicated>"

if both configurations are different, you need to update ~/.openclaw/openclaw.json file to match the .env token
and then restart docker

$ docker restart openclaw-openclaw-gateway-1

Slack

$ ./openclaw.mjs pairing list --channel slack

Nvidia RTX 6000 Pro Blackwell Workstation Settings

Thu, 29 Jan 2026 01:00:00 +0000

1. Install Pytorch

1.1 Pytorch with CUDA 13.0

create requirements.txt

--index-url https://pypi.org/simple
--extra-index-url https://download.pytorch.org/whl/cu130
nvidia-cudnn-cu13
nvidia-cublas
nvidia-cufft
nvidia-curand
nvidia-cusolver
nvidia-cusparse
nvidia-nccl-cu13
torch 
torchvision 
transformers

$ uv pip install -r requirements.txt --system

1.2 Pytorch with CUDA 12.8

create requirements.txt

--index-url https://pypi.org/simple
--extra-index-url https://download.pytorch.org/whl/cu128
nvidia-cudnn-cu12
nvidia-cublas-cu12
nvidia-cufft-cu12
nvidia-curand-cu12
nvidia-cusolver-cu12
nvidia-cusparse-cu12
nvidia-nccl-cu12
torch 
torchvision 
transformers

또는

uv pip install nvidia-cudnn-cu12 \
    nvidia-cublas-cu12 \
    nvidia-cufft-cu12 \
    nvidia-curand-cu12 \
    nvidia-cusolver-cu12 \
    nvidia-cusparse-cu12 \
    nvidia-nccl-cu12 \
    torch \
    torchvision \
    transformers \
    --index-url https://pypi.org/simple \
    --extra-index-url https://download.pytorch.org/whl/cu128

$ uv pip install -r requirements.txt --system

1.3 setting .bashrc

modify ~/.bashrc
NVIDIA_HOME is different, depending on your python version

# CUDA
NVIDIA_HOME="$HOME/.pyenv/versions/3.12.10/lib/python3.12/site-packages/nvidia"

# 2. Add necessary libraries into LD_LIBRARY_PATH에
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:${NVIDIA_HOME}/cu13/lib
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:${NVIDIA_HOME}/cudnn/lib
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:${NVIDIA_HOME}/cublas/lib
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:${NVIDIA_HOME}/cufft/lib
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:${NVIDIA_HOME}/curand/lib
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:${NVIDIA_HOME}/cusolver/lib
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:${NVIDIA_HOME}/cusparse/lib
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:${NVIDIA_HOME}/nccl/lib

1.4 Test

$ python -c "import torch; print(torch.__version__)"

import time
import os

# Suppress TF logs for cleaner output
os.environ['TF_CPP_MIN_LOG_LEVEL'] = '3' 

def test_pytorch():
    print("--- PyTorch Check ---")
    import torch
    
    if torch.cuda.is_available():
        device = torch.device("cuda")
        gpu_name = torch.cuda.get_device_name(0)
        vram = torch.cuda.get_device_properties(0).total_memory / 1e9
        print(f"✅ GPU Detected: {gpu_name} ({vram:.2f} GB VRAM)")
        
        # Simple Compute Test
        x = torch.randn(5000, 5000, device=device)
        y = torch.randn(5000, 5000, device=device)
        start = time.time()
        result = torch.matmul(x, y)
        torch.cuda.synchronize() # Wait for compute to finish
        print(f"✅ Matrix Mul (5k x 5k) Time: {time.time() - start:.4f}s")
    else:
        print("❌ PyTorch cannot see the GPU.")

test_pytorch()

2. Install Unsloth

my conclusion, Unsloth doesn’t work with Tensorflow Nightly version.
I decided not to install tensorflow in system level (I will use Tensorflow in virtualenv)

$ pip install unsloth
#$ pip install tf-keras transformers --no-deps

# must install it again to upgrade torch and torchvision. 
# as of this writing, torch==2.10.0, torchao==0.15.0, torchaudio==2.9.1, torchvision==0.25.0
# these versions work well with unsloth==2026.1.4, unsloth_zoo==2026.1.4
$ pip install --upgrade torch torchvision

테스트

import torch
from unsloth import FastLanguageModel

def test_unsloth():
    # 설정
    max_seq_length = 2048
    dtype = None # None으로 설정 시 자동으로 bfloat16 (RTX 6000 지원) 감지
    load_in_4bit = True # Unsloth의 핵심인 4bit QLoRA 로딩 테스트
    
    print(f"🔹 GPU Check: {torch.cuda.get_device_name(0)}")
    print(f"🔹 VRAM: {torch.cuda.get_device_properties(0).total_memory / 1024**3:.2f} GB")

    # 1. 모델 및 토크나이저 로드 테스트
    print("\n[1/3] Loading Llama-3.2-1B model...")
    try:
        model, tokenizer = FastLanguageModel.from_pretrained(
            model_name = "unsloth/Llama-3.2-1B-Instruct", 
            max_seq_length = max_seq_length,
            dtype = dtype,
            load_in_4bit = load_in_4bit,
        )
        print("✅ Model loaded successfully.")
    except Exception as e:
        print(f"❌ Model load failed: {e}")
        return

    # 2. Inference 테스트 (FastLanguageModel 최적화 동작 확인)
    print("\n[2/3] Running Inference...")
    FastLanguageModel.for_inference(model) # Native 2x faster inference
    
    inputs = tokenizer(
        [
            "unsloth 라이브러리의 주요 장점은 무엇인가요? 짧게 요약해주세요."
        ], return_tensors = "pt"
    ).to("cuda")

    outputs = model.generate(**inputs, max_new_tokens = 64, use_cache = True)
    decoded_output = tokenizer.batch_decode(outputs)[0]
    
    # 결과 출력 (내용보다는 에러 없이 생성되었는지가 중요)
    print("✅ Inference completed.")
    
    # 3. LoRA 어댑터 부착 테스트 (학습 준비 상태 확인)
    print("\n[3/3] Testing LoRA Adapter attachment...")
    try:
        model = FastLanguageModel.get_peft_model(
            model,
            r = 16,
            target_modules = ["q_proj", "k_proj", "v_proj", "o_proj"],
            lora_alpha = 16,
            lora_dropout = 0,
            bias = "none",
            use_gradient_checkpointing = True,
        )
        print(f"✅ LoRA Adapters attached. Trainable parameters: {model.print_trainable_parameters()}")
    except Exception as e:
        print(f"❌ LoRA attachment failed: {e}")

test_unsloth()

3. Install TLR

import torch
import transformers
from transformers import AutoConfig, AutoModelForCausalLM, AutoTokenizer, TrainingArguments
from datasets import Dataset
from peft import LoraConfig, get_peft_model
from trl import SFTTrainer, DPOTrainer, PPOConfig, AutoModelForCausalLMWithValueHead, SFTConfig, DPOConfig
import os
import tempfile
import warnings

# Suppress minor warnings for clean output
warnings.filterwarnings("ignore")


def print_status(message):
    print(f"\n[TRL TEST] >> {message}")


def run_trl_health_check():
    print_status("Starting TRL Health Check...")

    # 1. Environment & Device Check
    device = "cuda" if torch.cuda.is_available() else "cpu"
    print_status(f"Device: {device}")

    # 2. Setup Resources (Correct Vocab Size Match)
    print_status("Initializing dummy model and tokenizer...")

    # 먼저 토크나이저를 로드합니다.
    tokenizer = AutoTokenizer.from_pretrained("gpt2")
    tokenizer.pad_token = tokenizer.eos_token

    # 모델 설정: vocab_size를 토크나이저와 동일하게 맞춤 (매우 중요)
    model_config = AutoConfig.from_pretrained("gpt2")
    model_config.n_layer = 2
    model_config.n_head = 2
    model_config.n_embd = 32
    model_config.vocab_size = len(tokenizer)  # <--- 여기가 수정되었습니다. (50257)

    model = AutoModelForCausalLM.from_config(model_config).to(device)

    # 3. Test SFTTrainer (Supervised Fine-Tuning)
    print_status("Testing SFTTrainer (1 training step)...")

    sft_data = {
        "text": [
                    "User: Hello\nAssistant: Hi there!",
                    "User: Code for me\nAssistant: Sure, here is python code.",
                    "User: Bye\nAssistant: Goodbye!"
                ] * 10
    }
    sft_dataset = Dataset.from_dict(sft_data)

    with tempfile.TemporaryDirectory() as tmp_dir:
        sft_config = SFTConfig(
            output_dir=tmp_dir,
            dataset_text_field="text",
            max_length=16,
            per_device_train_batch_size=2,
            max_steps=1,
            learning_rate=1e-4,
            logging_steps=1,
            report_to="none",
            save_strategy="no",
        )

        sft_trainer = SFTTrainer(
            model=model,
            train_dataset=sft_dataset,
            args=sft_config,
            processing_class=tokenizer,  # it was "tokenizer" previously
        )

        sft_trainer.train()
        print_status("SFTTrainer executed successfully.")

    # 4. Test DPOTrainer (Direct Preference Optimization)
    print_status("Testing DPOTrainer initialization...")

    dpo_data = {
        "prompt": ["Question 1", "Question 2"] * 5,
        "chosen": ["Good answer 1", "Good answer 2"] * 5,
        "rejected": ["Bad answer 1", "Bad answer 2"] * 5,
    }
    dpo_dataset = Dataset.from_dict(dpo_data)

    with tempfile.TemporaryDirectory() as tmp_dir:
        dpo_config = DPOConfig(
            output_dir=tmp_dir,
            per_device_train_batch_size=2,
            max_steps=1,
            report_to="none",
            learning_rate=1e-5,
        )

        # DPO용 새 모델 (동일 설정)
        dpo_model = AutoModelForCausalLM.from_config(model_config).to(device)

        dpo_trainer = DPOTrainer(
            model=dpo_model,
            ref_model=None,
            args=dpo_config,
            train_dataset=dpo_dataset,
            processing_class=tokenizer,  # it was "tokenizer" previously
        )

        dataloader = dpo_trainer.get_train_dataloader()
        batch = next(iter(dataloader))
        print_status("DPOTrainer initialized and data processed successfully.")

    # 5. Test PPO Integration (Value Head)
    print_status("Testing PPO ValueHead Model Wrapper...")

    try:
        # PPO 모델은 기본 모델 위에 Value Head를 얹는 구조
        ppo_base_model = AutoModelForCausalLM.from_config(model_config).to(device)
        ppo_model = AutoModelForCausalLMWithValueHead.from_pretrained(ppo_base_model)

        if hasattr(ppo_model, "v_head"):
            print_status("AutoModelForCausalLMWithValueHead successfully attached 'v_head'.")
        else:
            raise ValueError("v_head not found in PPO model.")

        inputs = tokenizer("Test input", return_tensors="pt").to(device)
        with torch.no_grad():
            output = ppo_model(**inputs)
        print_status("PPO Model forward pass successful.")

    except Exception as e:
        print(f"PPO Test Failed: {e}")
        # PPO is tricky with dummy models sometimes, but we proceed if minor error
        pass

    # 6. Test PEFT Integration (LoRA)
    print_status("Testing PEFT (LoRA) Integration with TRL...")

    peft_config = LoraConfig(
        r=4,
        lora_alpha=8,
        lora_dropout=0.05,
        bias="none",
        task_type="CAUSAL_LM",
    )

    base_model_peft = AutoModelForCausalLM.from_config(model_config).to(device)
    peft_model = get_peft_model(base_model_peft, peft_config)

    print_status(f"PEFT Model created. Trainable params: {peft_model.print_trainable_parameters()}")

    print_status("\n---------------------------------------------------")
    print_status("SUCCESS: All TRL components checked thoroughly.")
    print_status("---------------------------------------------------")


run_trl_health_check()

3. Install Tensorflow

you need to install latest version of tensorflow “tf-nightly” with cuda option.
Also it doesn’t work with Unsloth well.
I decided not to install Tensorflow nightly version on system
instead, I will use tensorflow in virtualenv

# Create tensorflow env
$ pyenv virtualenv tensroflow-nightly
$ pyenv activate tensroflow-nightly

# Install tensorflow nightly version with cuda support
$ pip install "tf-nightly[and-cuda]"
#
# 테스트
$ python -c "import tensorflow as tf; print(tf.config.list_physical_devices('GPU'))"

modify ~/.bashrc

# CUDA for Tensorflow
NVIDIA_HOME="$HOME/.pyenv/versions/3.12.10/lib/python3.12/site-packages/nvidia"

# 2. 필요한 라이브러리 경로들을 LD_LIBRARY_PATH에 추가
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:${NVIDIA_HOME}/cudnn/lib
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:${NVIDIA_HOME}/cublas/lib
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:${NVIDIA_HOME}/cufft/lib
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:${NVIDIA_HOME}/curand/lib
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:${NVIDIA_HOME}/cusolver/lib
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:${NVIDIA_HOME}/cusparse/lib
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:${NVIDIA_HOME}/nccl/lib

here’s a bit more complex test.

import time
import os

def test_tensorflow():
    print("\n--- TensorFlow Check ---")
    import tensorflow as tf
    
    gpus = tf.config.list_physical_devices('GPU')
    if gpus:
        print(f"✅ GPU Detected: {len(gpus)} device(s)")
        for gpu in gpus:
            print(f"   - {gpu.device_type}: {gpu.name}")
            
        # Simple Compute Test
        with tf.device('/GPU:0'):
            a = tf.random.normal([5000, 5000])
            b = tf.random.normal([5000, 5000])
            start = time.time()
            c = tf.matmul(a, b)
            _ = c.numpy() # Force execution
            print(f"✅ Matrix Mul (5k x 5k) Time: {time.time() - start:.4f}s")
    else:
        print("❌ TensorFlow cannot see the GPU.")


test_tensorflow()

4. Install vLLM

WARNING! here we can’t install both torch and vllm at the same time!

when you need to run, you need to run in virtualenv. if you install both torch and vllm, vllm downgrade your torch -> the downgraded torch will not work on RTX 6000 PRO.

# Run in virtualenv
$ pyenv virtualenv 3.12.12 vllm
$ pyenv activate vllm
$ pip install vllm 

vllm serve openai/gpt-oss-20b \
    --host 127.0.0.1 \
    --port 8082 \
    --tensor-parallel-size 1 \
    --gpu-memory-utilization 0.3 \
    --trust-remote-code \
    --async-scheduling \
    --max-num-batched-tokens 8192 \
    --max-model-len 35096

5. Stable Diffusion WebUI

python: 3.10.17

$ export STABLE_DIFFUSION_REPO=https://github.com/joypaul162/Stability-AI-stablediffusion.git

# Install specific setuptools
$ source ./venv/bin/activate
$ pip install https://github.com/openai/CLIP/archive/d50d76daa670286dd6cacf3bcd80b5e4823fc8e1.zip --no-build-isolation
$ pip install setuptools==69.5.1 wheel
$ deactivate 

# 설치
$ ./webui.sh

disk error issue (this is just a personal issue. just skip it)

$ lsblk -f
$ sudo umount -l /dev/nvme1n1p2
$ sudo ntfsfix -d /dev/nvme1n1p2
$ sudo mount /dev/nvme1n1p2 /media/anderson/HynixP41

6. CONTINUE on Pycharm

CONTINUE is a plugin for llm in Pycharm.

config.yaml

name: Local Config
version: 1.0.0
schema: v1
models:
  - name: Llama 3.1 8B
    provider: ollama
    model: llama3.1:8b
    roles:
      - chat
      - edit
      - apply
  - name: Qwen2.5-Coder 1.5B
    provider: ollama
    model: qwen2.5-coder:1.5b-base
    roles:
      - autocomplete
  - name: Nomic Embed
    provider: ollama
    model: nomic-embed-text:latest
    roles:
      - embed
  - name: Qwen3-Coder-30B (Local)
    provider: openai
    model: Qwen/Qwen3-Coder-30B-A3B-Instruct
    apiBase: http://localhost:8045/v1
#    apiKey: my-secret-key
    roles:
      - chat
      - edit
      - apply
      - autocomplete
  - name: Nomic Embed
    provider: ollama
    model: nomic-embed-text:latest
    roles:
      - embed

you can create vllm

python3 -m vllm.entrypoints.openai.api_server \
    --model Qwen/Qwen3-Coder-30B-A3B-Instruct \
    --dtype auto \
    --tensor-parallel-size 1 \
    --gpu-memory-utilization 0.95 \
    --trust-remote-code \
    --max-model-len 50000 \
    --port 8045

Precision and Kernel Selection - Only Hopper swizzling is supported for values

Sun, 04 Jan 2026 01:00:00 +0000

1. Only Hopper swizzling is supported for values

Recently I got this error, while running Unsloth with GPT-OSS-120B on Nvidia 6000 Pro blackwell. (workstation).
This is due to using incorrect dtype.

from unsloth import FastLanguageModel

model, tokenizer = FastLanguageModel.from_pretrained(
    model_name='unsloth/gpt-oss-20b-BF16',
    dtype=None,  # "bfloat16", <- it works for Nvidia RTX 6000 PRO Blackwell.
    max_seq_length=2000,
    load_in_4bit=False,
    full_finetuning=False,
    low_cpu_mem_usage=True,
    device_map="cuda"  # Explicitly load to CUDA
)

When I run the inference code, it raises an error, saying “only Hopper swizzling is supported.” This is because the runtime entered Hopper-only kernel path
but my GPU (Nvidia RTX 6000 PRO Blackwell) does not support Hopper Kernel.
in short, the safest workaround is to avoid “MXFP4” and use “BF16”.

2. Kernel Selection Flow

This is a simplified internal routing view.
The actual checks are more granular and framework-specific.

Kernel Selection
├─ Op: GEMM / Linear / Matmul
│  ├─ Check device capability (SM, architecture)
│  │  ├─ Hopper? -> allow TMA/Swizzle paths
│  │  ├─ Blackwell? -> allow FP4/NVFP4 paths
│  │  └─ Other -> generic Tensor Core or CUDA paths
│  ├─ Check precision / format
│  │  ├─ FP32/TF32 -> cuBLAS / TF32-enabled GEMM
│  │  ├─ BF16/FP16 -> Tensor Core GEMM
│  │  ├─ FP8 -> FP8 kernels (often Hopper-optimized)
│  │  ├─ FP4/NVFP4 -> FP4 kernels (often Blackwell-optimized)
│  │  └─ MXFP4 -> MXFP4 kernels (specialized, high constraints)
│  ├─ Check library availability
│  │  ├─ Triton kernel exists? -> Triton path
│  │  ├─ CUTLASS/TensorRT path? -> vendor path
│  │  └─ Fallback -> cuBLAS / default GEMM
│  └─ Check runtime flags
│     ├─ load_in_4bit / quant config -> quantized kernel
│     ├─ use_cache -> cache-aware kernel
│     └─ debug/disable flags -> safe fallback

Practical takeaway: selection is multi-stage.
If any stage assumes unsupported hardware, compilation can fail early.

3. Precision

Depending on the precision (BF16/FP16/FP8/MXFP4/etc…), it selects different kernels.
Here I summarized the precisions and kernels.

Precision/Format
├─ FP32
│  └─ GEMM (CUDA/cuBLAS default, dtype="float32")
├─ TF32
│  └─ GEMM (Tensor Core path, dtype="float32" + TF32 enabled)
├─ FP16
│  └─ GEMM (Tensor Core path, dtype="float16")
├─ BF16
│  └─ GEMM (Tensor Core path, dtype="bfloat16", stable default)
├─ FP8 (E4M3/E5M2)
│  ├─ GEMM (FP8 kernels, dtype="float8_e4m3fn"/"float8_e5m2", Hopper-optimized)
│  └─ Swizzle/TMA (Hopper-only optimization)
├─ FP4 (NVFP4)
│  ├─ GEMM (FP4 kernels, NVFP4 format, dtype="float4"/"nvfp4", Blackwell-centered)
│  └─ Micro-tensor scaling (Blackwell-only flavor)
├─ MXFP4
│  ├─ GEMM (MXFP4 kernels, MXFP4 format)
│  └─ Swizzle/TMA (often assumes Hopper)
└─ INT8/INT4/NF4
   ├─ GEMM (int kernels, dtype="int8"/"int4", includes NF4)
   └─ Dequant (scale restore path)

Unsloth - Lora Fine-Tuning Hyperparameters

Sat, 03 Jan 2026 01:00:00 +0000

1. LoRA 핵심 개념

1.1 문제: Full Fine-Tuning

Full Fine-Tuning은 모든 파라미터 $W \in \mathbb{R}^{d \times k}$를 업데이트한다.

\[W' = W_0 + \Delta W\]

문제점: 70B 모델 기준 $\Delta W$만 해도 140GB+ 메모리 필요.

1.2 LoRA의 핵심

Fine-tuning시 weight 변화량 $\Delta W$는 Low-Rank 구조를 가진다.
Low-Rank = 압축 가능하다는 뜻
JPEG 압축처럼 원본 10MB → 500KB로 줄여도 품질이 비슷한 이유는,
정보에 중복과 패턴이 있기 때문.

LLM Fine-tuning도 마찬가지.
연구 결과, weight 변화량이 엄청 복잡하게 변하는 게 아니라
몇 개의 주요 방향으로만 변한다는 것을 발견 이미 언어를 잘 아는 LLM에게 “의료 용어 좀 더 잘 알아듣게” 같은 미세 조정만 하면 되기 때문

즉, $\Delta W$를 두 개의 작은 행렬로 분해 가능:

\[\Delta W = BA\] \[\begin{align} B &\in \mathbb{R}^{d \times r} \\ A &\in \mathbb{R}^{r \times k} \\ r &\ll \min(d, k) \end{align}\]

1.3 파라미터 비교

	Full Fine-Tuning	LoRA (r=8)
파라미터 수	$d \times k$	$d \times r + r \times k$
예시 (4096×4096)	16.7M	65K
압축률	1x	~256x

2. 수학적 구조

2.1 Forward Pass

\[h = W_0 x + \frac{\alpha}{r} \cdot BAx\]

Input x
    │
    ├─────────────────┐
    ▼                 ▼
┌───────┐         ┌───────┐
│  W₀   │         │   A   │ (r × k)
│frozen │         └───┬───┘
└───┬───┘             ▼
    │             ┌───────┐
    │             │   B   │ (d × r)
    │             └───┬───┘
    │                 │ × (α/r)
    ▼                 ▼
    └────────(+)──────┘
              │
              ▼
           Output h

Matrix 크기 예제

구체적인 숫자로 이해해보자. d=64, k=32, r=4로 설정한 경우:

행렬	크기	파라미터 수	설명
$W_0$	64 × 32	2,048	원본 weight (frozen)
$A$	4 × 32	128	LoRA down-projection
$B$	64 × 4	256	LoRA up-projection
$\Delta W = BA$	64 × 32	-	$W_0$와 같은 크기로 복원

LoRA 파라미터: $A + B = 128 + 256 = 384$ (Full의 18.75%)

2.2 초기화

A: Kaiming/Gaussian 초기화
B: Zero 초기화 → 학습 시작 시 $\Delta W = BA = 0$

nn.init.kaiming_uniform_(self.lora_A, a=math.sqrt(5))
nn.init.zeros_(self.lora_B)  # 핵심: 0으로 시작

2.3 Scaling Factor α

\[\text{scaling} = \frac{\alpha}{r}\]

r	α	α/r	효과
8	8	1.0	기본
8	16	2.0	LoRA 효과 2배
16	16	1.0	rank↑, 스케일 유지

3. 적용 위치 (Target Modules)

Transformer에서 LoRA 적용 가능한 위치:

[Attention]           [MLP (SwiGLU)]
├── q_proj  ✓         ├── gate_proj  ✓
├── k_proj  ✓         ├── up_proj    ✓
├── v_proj  ✓         └── down_proj  ✓
└── o_proj  ✓

권장: 전부 적용 (Unsloth 기본값)

4. Hyperparameters 정리

Parameter	권장값	설명
`r`	16~64	rank. 높을수록 표현력↑, 메모리↑
`lora_alpha`	r과 동일	scaling = α/r
`lora_dropout`	0	필요시 0.05
`target_modules`	all	Attention + MLP 모두

5. QLoRA

Base model을 4-bit 양자화 + LoRA:

Base: 4-bit (frozen)
LoRA adapters: 16-bit (trainable)

\[\text{메모리}: 140\text{GB} \rightarrow \sim24\text{GB}\]

6. Unsloth Code

실제 Text-to-SQL 파인튜닝을 위한 코드 구현입니다.
앞서 다룬 LoRA Hyperparameters가 코드에 어떻게 적용되는지 확인합니다.

6.1 Model & LoRA Configuration

Scaling Factor($\frac{\alpha}{r}$)를 설정하는 단계입니다.

# Initialize Model with LoRA settings
model = GptOssModel(
    model_config=ModelConfig(
        model_name="unsloth/gpt-oss-20b",
        max_seq_length=4096
    ),
    lora_config=LoRAConfig(
        r=16,           # Rank (r): SQL 로직 학습을 위해 8보다 높은 16 설정
        lora_alpha=32   # Alpha (α): Scaling factor = 32/16 = 2.0
    )
)

r=16: SQL 쿼리 생성과 같은 복잡한 논리 구조를 학습하기 위해 기본값(8)보다 Rank를 높여 표현력(Expressiveness)을 확보
lora_alpha=32: $\Delta W$의 영향력을 2배로 설정하여($\text{scaling}=2.0$), 새로운 데이터셋(SQL)의 특징을 더 강하게 반영

6.2 Trainer Configuration (SFT)

Unsloth의 장점인 메모리 효율성을 극대화하기 위한 SFTTrainer 설정입니다.

trainer = SFTTrainer(
    model=model.model,
    processing_class=model.tokenizer,
    train_dataset=train_dataset,
    args=SFTConfig(
        # Memory Optimization
        per_device_train_batch_size=8,
        gradient_accumulation_steps=32,  # Effective Batch Size = 8 * 32 = 256
        
        # Optimizer & Precision
        optim="adamw_8bit",              # Optimizer State 메모리 절약
        fp16=False,
        bf16=True,                       # Ampere(RTX 30/40/6000) 이상에서 필수
        
        # Learning Rate Schedule
        learning_rate=2e-4,
        warmup_steps=5,
        max_steps=30,
        output_dir="outputs",
    ),
)

gradient_accumulation_steps=32:
- 물리적 메모리 한계로 Batch Size를 작게(8) 가져가는 대신, 32번의 step 동안 gradient를 누적해 업데이트
- 결과적으로 대용량 배치(256)로 학습하는 것과 유사한 수렴 안정성을 확보
- per_device_train_batch_size=8 이게 실제 batch size
- 수식: $\text{Effective Batch Size} = \text{Micro Batch Size} \times \text{Accumulation Steps} \times \text{Num GPUs}$
  - \[\text{Total Batch Size} = 8 \times 32 \times 1 = \mathbf{256}\]
- 메모리는 배치 8만큼만 쓰면서, 학습 효과는 배치 256인 것처럼 낼 수 있음
optim=”adamw_8bit”:
- 일반 AdamW(32-bit) 대비 Optimizer state가 차지하는 VRAM을 1/4 수준으로 줄여 OOM(Out of Memory)을 방지
bf16=True:
- FP16보다 표현 가능한 수의 범위(Dynamic Range)가 넓어 학습 중 발산(NaN)할 확률이 낮습니다.
- RTX 6000 Pro 환경에 최적화

6.3 Training & Saving

전체 파라미터($W$)가 아닌 LoRA Adapter($A, B$)만 학습을 진행합니다.

# Start Training (Updates only A and B matrices)
trainer.train()

# Save LoRA Adapters
model.save("./text2sql_lora_model")

학습이 끝나면 원본 모델(GB 단위)은 그대로 두고, 학습된 LoRA weight(MB 단위)만 저장합니다.
추론 시에는 원본 모델에 이 Adapter를 동적으로 로드하여 사용하게 됩니다.

Unsloth - Model Visualization

Fri, 02 Jan 2026 01:00:00 +0000

Model Visualization

from transformers import BatchEncoding, TextStreamer
from unsloth import FastLanguageModel

model, tokenizer = FastLanguageModel.from_pretrained(
    model_name="unsloth/gpt-oss-20b",
    dtype=None,  # torch.bfloat16,  # None for auto detection
    max_seq_length=1000,
    load_in_4bit=False,
    full_finetuning=False,
    low_cpu_mem_usage=True,
    device_map="cuda",  # Explicitly load to CUDA
)

VIsualization Codes

import torch
from rich.tree import Tree
from rich import print as rprint

def visualize_model_structure(model):
    # 1. Create root node
    tree = Tree(f"🏗️ [bold blue]Model: {getattr(model.config, '_name_or_path', 'Unknown')}[/bold blue]")
    
    # Dictionary to keep track of created nodes: {path_string: rich_tree_node}
    node_lookup = {"": tree}

    for name, module in model.named_modules():
        if name == "": continue
        
        # Split path: 'model.layers.0.self_attn' -> ['model', 'layers', '0', 'self_attn']
        parts = name.split('.')
        parent_path = ".".join(parts[:-1])
        current_part = parts[-1]

        # Calculate Size Info
        # Get parameter count for this specific module
        params_count = sum(p.numel() for p in module.parameters(recurse=False))
        
        # Get shape if it's a leaf layer (like Linear or Embedding)
        shape_info = ""
        if hasattr(module, 'weight') and isinstance(module.weight, torch.Tensor):
            shape_info = f" [yellow]({list(module.weight.shape)})[/yellow]"
        elif params_count > 0:
            shape_info = f" [green]({params_count:,} params)[/green]"

        # 2. Find or Create Node
        if parent_path in node_lookup:
            parent_node = node_lookup[parent_path]
            # Add new node with style and size info
            new_node = parent_node.add(f"[bold magenta]{current_part}[/bold magenta]{shape_info}")
            node_lookup[name] = new_node

    rprint(tree)

# Execution
visualize_model_structure(model)

here’s the result

🏗️ Model: unsloth/gpt-oss-20b
├── model
│   ├── embed_tokens ([201088, 2880])
│   ├── layers
│   │   ├── 0
│   │   │   ├── self_attn (64 params)
│   │   │   │   ├── q_proj ([4096, 2880])
│   │   │   │   ├── k_proj ([512, 2880])
│   │   │   │   ├── v_proj ([512, 2880])
│   │   │   │   └── o_proj ([2880, 4096])
│   │   │   ├── mlp
│   │   │   │   ├── router ([32, 2880])
│   │   │   │   └── experts (796,538,880 params)
│   │   │   ├── input_layernorm ([2880])
│   │   │   └── post_attention_layernorm ([2880])
│   │   ├── 1
│   │   │   ├── self_attn (64 params)
│   │   │   │   ├── q_proj ([4096, 2880])
│   │   │   │   ├── k_proj ([512, 2880])
│   │   │   │   ├── v_proj ([512, 2880])
│   │   │   │   └── o_proj ([2880, 4096])
│   │   │   ├── mlp
│   │   │   │   ├── router ([32, 2880])
│   │   │   │   └── experts (796,538,880 params)
│   │   │   ├── input_layernorm ([2880])
│   │   │   └── post_attention_layernorm ([2880])
│   │   ├── 2
│   │   │   ├── self_attn (64 params)
│   │   │   │   ├── q_proj ([4096, 2880])
│   │   │   │   ├── k_proj ([512, 2880])
│   │   │   │   ├── v_proj ([512, 2880])
│   │   │   │   └── o_proj ([2880, 4096])
│   │   │   ├── mlp
│   │   │   │   ├── router ([32, 2880])
│   │   │   │   └── experts (796,538,880 params)
│   │   │   ├── input_layernorm ([2880])
│   │   │   └── post_attention_layernorm ([2880])
│   │   ├── 3
│   │   │   ├── self_attn (64 params)
│   │   │   │   ├── q_proj ([4096, 2880])
│   │   │   │   ├── k_proj ([512, 2880])
│   │   │   │   ├── v_proj ([512, 2880])
│   │   │   │   └── o_proj ([2880, 4096])
│   │   │   ├── mlp
│   │   │   │   ├── router ([32, 2880])
│   │   │   │   └── experts (796,538,880 params)
│   │   │   ├── input_layernorm ([2880])
│   │   │   └── post_attention_layernorm ([2880])
│   │   ├── 4
│   │   │   ├── self_attn (64 params)
│   │   │   │   ├── q_proj ([4096, 2880])
│   │   │   │   ├── k_proj ([512, 2880])
│   │   │   │   ├── v_proj ([512, 2880])
│   │   │   │   └── o_proj ([2880, 4096])
│   │   │   ├── mlp
│   │   │   │   ├── router ([32, 2880])
│   │   │   │   └── experts (796,538,880 params)
│   │   │   ├── input_layernorm ([2880])
│   │   │   └── post_attention_layernorm ([2880])
│   │   ├── 5
│   │   │   ├── self_attn (64 params)
│   │   │   │   ├── q_proj ([4096, 2880])
│   │   │   │   ├── k_proj ([512, 2880])
│   │   │   │   ├── v_proj ([512, 2880])
│   │   │   │   └── o_proj ([2880, 4096])
│   │   │   ├── mlp
│   │   │   │   ├── router ([32, 2880])
│   │   │   │   └── experts (796,538,880 params)
│   │   │   ├── input_layernorm ([2880])
│   │   │   └── post_attention_layernorm ([2880])
│   │   ├── 6
│   │   │   ├── self_attn (64 params)
│   │   │   │   ├── q_proj ([4096, 2880])
│   │   │   │   ├── k_proj ([512, 2880])
│   │   │   │   ├── v_proj ([512, 2880])
│   │   │   │   └── o_proj ([2880, 4096])
│   │   │   ├── mlp
│   │   │   │   ├── router ([32, 2880])
│   │   │   │   └── experts (796,538,880 params)
│   │   │   ├── input_layernorm ([2880])
│   │   │   └── post_attention_layernorm ([2880])
│   │   ├── 7
│   │   │   ├── self_attn (64 params)
│   │   │   │   ├── q_proj ([4096, 2880])
│   │   │   │   ├── k_proj ([512, 2880])
│   │   │   │   ├── v_proj ([512, 2880])
│   │   │   │   └── o_proj ([2880, 4096])
│   │   │   ├── mlp
│   │   │   │   ├── router ([32, 2880])
│   │   │   │   └── experts (796,538,880 params)
│   │   │   ├── input_layernorm ([2880])
│   │   │   └── post_attention_layernorm ([2880])
│   │   ├── 8
│   │   │   ├── self_attn (64 params)
│   │   │   │   ├── q_proj ([4096, 2880])
│   │   │   │   ├── k_proj ([512, 2880])
│   │   │   │   ├── v_proj ([512, 2880])
│   │   │   │   └── o_proj ([2880, 4096])
│   │   │   ├── mlp
│   │   │   │   ├── router ([32, 2880])
│   │   │   │   └── experts (796,538,880 params)
│   │   │   ├── input_layernorm ([2880])
│   │   │   └── post_attention_layernorm ([2880])
│   │   ├── 9
│   │   │   ├── self_attn (64 params)
│   │   │   │   ├── q_proj ([4096, 2880])
│   │   │   │   ├── k_proj ([512, 2880])
│   │   │   │   ├── v_proj ([512, 2880])
│   │   │   │   └── o_proj ([2880, 4096])
│   │   │   ├── mlp
│   │   │   │   ├── router ([32, 2880])
│   │   │   │   └── experts (796,538,880 params)
│   │   │   ├── input_layernorm ([2880])
│   │   │   └── post_attention_layernorm ([2880])
│   │   ├── 10
│   │   │   ├── self_attn (64 params)
│   │   │   │   ├── q_proj ([4096, 2880])
│   │   │   │   ├── k_proj ([512, 2880])
│   │   │   │   ├── v_proj ([512, 2880])
│   │   │   │   └── o_proj ([2880, 4096])
│   │   │   ├── mlp
│   │   │   │   ├── router ([32, 2880])
│   │   │   │   └── experts (796,538,880 params)
│   │   │   ├── input_layernorm ([2880])
│   │   │   └── post_attention_layernorm ([2880])
│   │   ├── 11
│   │   │   ├── self_attn (64 params)
│   │   │   │   ├── q_proj ([4096, 2880])
│   │   │   │   ├── k_proj ([512, 2880])
│   │   │   │   ├── v_proj ([512, 2880])
│   │   │   │   └── o_proj ([2880, 4096])
│   │   │   ├── mlp
│   │   │   │   ├── router ([32, 2880])
│   │   │   │   └── experts (796,538,880 params)
│   │   │   ├── input_layernorm ([2880])
│   │   │   └── post_attention_layernorm ([2880])
│   │   ├── 12
│   │   │   ├── self_attn (64 params)
│   │   │   │   ├── q_proj ([4096, 2880])
│   │   │   │   ├── k_proj ([512, 2880])
│   │   │   │   ├── v_proj ([512, 2880])
│   │   │   │   └── o_proj ([2880, 4096])
│   │   │   ├── mlp
│   │   │   │   ├── router ([32, 2880])
│   │   │   │   └── experts (796,538,880 params)
│   │   │   ├── input_layernorm ([2880])
│   │   │   └── post_attention_layernorm ([2880])
│   │   ├── 13
│   │   │   ├── self_attn (64 params)
│   │   │   │   ├── q_proj ([4096, 2880])
│   │   │   │   ├── k_proj ([512, 2880])
│   │   │   │   ├── v_proj ([512, 2880])
│   │   │   │   └── o_proj ([2880, 4096])
│   │   │   ├── mlp
│   │   │   │   ├── router ([32, 2880])
│   │   │   │   └── experts (796,538,880 params)
│   │   │   ├── input_layernorm ([2880])
│   │   │   └── post_attention_layernorm ([2880])
│   │   ├── 14
│   │   │   ├── self_attn (64 params)
│   │   │   │   ├── q_proj ([4096, 2880])
│   │   │   │   ├── k_proj ([512, 2880])
│   │   │   │   ├── v_proj ([512, 2880])
│   │   │   │   └── o_proj ([2880, 4096])
│   │   │   ├── mlp
│   │   │   │   ├── router ([32, 2880])
│   │   │   │   └── experts (796,538,880 params)
│   │   │   ├── input_layernorm ([2880])
│   │   │   └── post_attention_layernorm ([2880])
│   │   ├── 15
│   │   │   ├── self_attn (64 params)
│   │   │   │   ├── q_proj ([4096, 2880])
│   │   │   │   ├── k_proj ([512, 2880])
│   │   │   │   ├── v_proj ([512, 2880])
│   │   │   │   └── o_proj ([2880, 4096])
│   │   │   ├── mlp
│   │   │   │   ├── router ([32, 2880])
│   │   │   │   └── experts (796,538,880 params)
│   │   │   ├── input_layernorm ([2880])
│   │   │   └── post_attention_layernorm ([2880])
│   │   ├── 16
│   │   │   ├── self_attn (64 params)
│   │   │   │   ├── q_proj ([4096, 2880])
│   │   │   │   ├── k_proj ([512, 2880])
│   │   │   │   ├── v_proj ([512, 2880])
│   │   │   │   └── o_proj ([2880, 4096])
│   │   │   ├── mlp
│   │   │   │   ├── router ([32, 2880])
│   │   │   │   └── experts (796,538,880 params)
│   │   │   ├── input_layernorm ([2880])
│   │   │   └── post_attention_layernorm ([2880])
│   │   ├── 17
│   │   │   ├── self_attn (64 params)
│   │   │   │   ├── q_proj ([4096, 2880])
│   │   │   │   ├── k_proj ([512, 2880])
│   │   │   │   ├── v_proj ([512, 2880])
│   │   │   │   └── o_proj ([2880, 4096])
│   │   │   ├── mlp
│   │   │   │   ├── router ([32, 2880])
│   │   │   │   └── experts (796,538,880 params)
│   │   │   ├── input_layernorm ([2880])
│   │   │   └── post_attention_layernorm ([2880])
│   │   ├── 18
│   │   │   ├── self_attn (64 params)
│   │   │   │   ├── q_proj ([4096, 2880])
│   │   │   │   ├── k_proj ([512, 2880])
│   │   │   │   ├── v_proj ([512, 2880])
│   │   │   │   └── o_proj ([2880, 4096])
│   │   │   ├── mlp
│   │   │   │   ├── router ([32, 2880])
│   │   │   │   └── experts (796,538,880 params)
│   │   │   ├── input_layernorm ([2880])
│   │   │   └── post_attention_layernorm ([2880])
│   │   ├── 19
│   │   │   ├── self_attn (64 params)
│   │   │   │   ├── q_proj ([4096, 2880])
│   │   │   │   ├── k_proj ([512, 2880])
│   │   │   │   ├── v_proj ([512, 2880])
│   │   │   │   └── o_proj ([2880, 4096])
│   │   │   ├── mlp
│   │   │   │   ├── router ([32, 2880])
│   │   │   │   └── experts (796,538,880 params)
│   │   │   ├── input_layernorm ([2880])
│   │   │   └── post_attention_layernorm ([2880])
│   │   ├── 20
│   │   │   ├── self_attn (64 params)
│   │   │   │   ├── q_proj ([4096, 2880])
│   │   │   │   ├── k_proj ([512, 2880])
│   │   │   │   ├── v_proj ([512, 2880])
│   │   │   │   └── o_proj ([2880, 4096])
│   │   │   ├── mlp
│   │   │   │   ├── router ([32, 2880])
│   │   │   │   └── experts (796,538,880 params)
│   │   │   ├── input_layernorm ([2880])
│   │   │   └── post_attention_layernorm ([2880])
│   │   ├── 21
│   │   │   ├── self_attn (64 params)
│   │   │   │   ├── q_proj ([4096, 2880])
│   │   │   │   ├── k_proj ([512, 2880])
│   │   │   │   ├── v_proj ([512, 2880])
│   │   │   │   └── o_proj ([2880, 4096])
│   │   │   ├── mlp
│   │   │   │   ├── router ([32, 2880])
│   │   │   │   └── experts (796,538,880 params)
│   │   │   ├── input_layernorm ([2880])
│   │   │   └── post_attention_layernorm ([2880])
│   │   ├── 22
│   │   │   ├── self_attn (64 params)
│   │   │   │   ├── q_proj ([4096, 2880])
│   │   │   │   ├── k_proj ([512, 2880])
│   │   │   │   ├── v_proj ([512, 2880])
│   │   │   │   └── o_proj ([2880, 4096])
│   │   │   ├── mlp
│   │   │   │   ├── router ([32, 2880])
│   │   │   │   └── experts (796,538,880 params)
│   │   │   ├── input_layernorm ([2880])
│   │   │   └── post_attention_layernorm ([2880])
│   │   └── 23
│   │       ├── self_attn (64 params)
│   │       │   ├── q_proj ([4096, 2880])
│   │       │   ├── k_proj ([512, 2880])
│   │       │   ├── v_proj ([512, 2880])
│   │       │   └── o_proj ([2880, 4096])
│   │       ├── mlp
│   │       │   ├── router ([32, 2880])
│   │       │   └── experts (796,538,880 params)
│   │       ├── input_layernorm ([2880])
│   │       └── post_attention_layernorm ([2880])
│   ├── norm ([2880])
│   └── rotary_emb
└── lm_head ([201088, 2880])

Unsloth - Odds Ratio Preference Optimization (ORPO)

Thu, 01 Jan 2026 01:00:00 +0000

1. What is Post Training

Pre-training을 통해서 언어 자체를 배웁니다.
간단하게 설명하면, GPT계열 (Llama 3, Mistral, Gemma) 등은, 앞의 문장을 보고 다음 단어를 맞추는 방식으로 학습합니다. 보통 생성형 계열에서 많이 합니다.
Masked Language Modeling 방식은 빈칸 채우기 인데 Bert, RoBERTa 계열에서 많이 쓰입니다.
문장의 의미를 파악하거나, 분류하는데 좋지만, 긴 글을 지어내는 능력은 떨어집니다.

Post Training 은 이렇게 언어 자체에 대해서 학습한 모델에 대해서
원하는 목적에 맞게 튜닝하는 과정입니다.

1.1 Supervised Fine Tuning

초기 이렇게 Post Training을 했습니다.

Supervised Fine-Tuning (SFT)
- Instruction (질문) 과 Response (모범 답안) 쌍으로 이루어진 데이터로 학습
- Next token prediction 을 사용하되, 데이터 품질과 도메인 지식을 따라하도록 학습
- Limitation: 해보면, 흉내는 냄. 근데 이게 안전한지, 유용한지에 대한 가치 판단을 하지 못함,
- Hallucination 심함

1.2 LLM Alignment

이전에는 지식을 그냥 넣었다면, 사람이 원하는 목적에 맞게 다듬는 과정

[1세대] Reinforcement Learning from Human Feedback (RLHF)
- ChatGPT 에서 만든 정석 방법
- 사람이 매긴 점수를 바탕으로 보상 모델 (Reward Model) 을 만들고, 이를 통해 강화학습 (PPO) 수행
- 성능은 정말 압도적. 실제 인간과 대화하는 듯한 자연스러운 성능
- Limitation
  - 학습 과정 자체가 너무 복잡
  - GPU 메모리를 많이 사용 -> 개인이 시도하기에는 어려움
  - 학습시 모4개의 모델을 메모리에 올려야 함
    - Policy Model (학습 대상)
    - Reference Model (비교 대상)
    - Reward Model (점수 매김)
    - Critical Model (가치 판단 - PPO 내부용)
[2세대] Direct Preference Optimization (DPO)
- 선호하는 답변 (Choosen), 거부된 답변 (Rejected) 쌍을 이용해서 학습
- 현재 업계 표준. 학습이 훨씬 안정적으로 빠름
- Limitation
  - 여전히 SFT 가 선행되야 함 (2-stage)
  - 학습시 2개의 모델이 필요
    - Policy Model (실제 학습하는 모델)
    - Reference Model (비교 대상)
[3세대] Odds Ratio Preference Optimization (ORPO)
- SFT + Alignment 를 하나로 합쳤음 (1-Stage)
- Reference Model 이 필요없음
- 한정된 자원으로 (GPU VRAM) 으로 학습시킬때 이 방식이 최고
- Loss Function 안에서 직접 Rejected Answer에 대한 Penalty를 사용
- Unsloth 추천
- Limitation
  - SFT + Alignment를 동시에 하기 때문에 -> Chosen 답변이 정말 모범 답안이어야 함
  - 수렴이 잘 안되기도 함, hyperparameter에 따라서 학습 불안정
[4세대] Group Relative Policy Optimization (GRPO)
- DeepSeek-V3 그리고 R1 으로 대중화 됨
- RLHF의 강력한 성능은 유지
- 하나의 질문에 여러개의 답변 그룹을 생성 -> 그 안에서 상대적인 점수를 매김
- 평균보다 잘한 답변은 강화, 못한 답변은 멀어지게 만듬
- 메모리 효율
  - RLHF처럼 4개의 모델을 띄울 필요 X
  - Policy Model 1개 학습시 필요
  - 비교를 위해서 Reference Model을 vLLM등으로 따로 띄워서 사용 (Optional)
- Limitation
  - Group Size 에 따른 VRAM 부담 -> 8개 16개 답변을 동시 생성해야됨 (많은 자원 소모)
  - 명확한 보상 함수 필요
    - 친절한 말투 -> 이런 모호한건 학습 잘 안됨
    - 수학문제처럼 명확한거를 잘함

가장 중요한 메모리 필요 부분을 정리하면

RLHF: 🟥🟥🟥🟥 (모델 4개 분량) - Out of Memory!
DPO: 🟦🟦 (모델 2개 분량) - Heavy
ORPO: 🟩 (모델 1개 분량) - Lightweight & Fast
GRPO: 🟨🟨 (모델 1~2개 수준 - RLHF 대비 훨씬 가벼움)

해당 문서에서는 ORPO 를 기술적 방법을 설명합니다.

K3s + Nvidia Container Toolkit + vLLM

Sat, 20 Dec 2025 01:00:00 +0000

1. Installation

1.1 Install K3s

curl -sfL https://get.k3s.io | sh -

# 이후 설정
mkdir -p ~/.kube
sudo cp /etc/rancher/k3s/k3s.yaml ~/.kube/config
sudo chown $(id -u):$(id -g) ~/.kube/config
chmod 600 ~/.kube/config
export KUBECONFIG=$HOME/.kube/config

.bashrc 에 저장

# K3s
export KUBECONFIG=$HOME/.kube/config

1.2 Install Helm

helm은 package manager로서 apt, yum, brew 같은 것

Ubuntu 설치시

# Snap 으로 설치시
sudo snap install helm --classic

# Apt 로 설치시 (위에 걸로 하면됨)
sudo apt-get install curl gpg apt-transport-https --yes
curl -fsSL https://packages.buildkite.com/helm-linux/helm-debian/gpgkey | gpg --dearmor | sudo tee /usr/share/keyrings/helm.gpg > /dev/null
echo "deb [signed-by=/usr/share/keyrings/helm.gpg] https://packages.buildkite.com/helm-linux/helm-debian/any/ any main" | sudo tee /etc/apt/sources.list.d/helm-stable-debian.list
sudo apt-get update
sudo apt-get install helm

설치 확인

helm version
helm list

1.3 Nvidia Container Tookit

K3s는 기본적으로 containerd를 사용합니다.
따라서 “Docker 컨테이너에서 GPU 사용”과 “K3s Pod에서 GPU 사용”은 설정 위치가 다릅니다.

# Install prerequisites
$ sudo apt-get update && sudo apt-get install -y --no-install-recommends curl gnupg2

# Configure the production repository
$ curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg \
  && curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list | \
    sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | \
    sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list

# Install
$ sudo apt-get update

# 설치
$ export NVIDIA_CONTAINER_TOOLKIT_VERSION=1.18.1-1
  sudo apt-get install -y \
      nvidia-container-toolkit=${NVIDIA_CONTAINER_TOOLKIT_VERSION} \
      nvidia-container-toolkit-base=${NVIDIA_CONTAINER_TOOLKIT_VERSION} \
      libnvidia-container-tools=${NVIDIA_CONTAINER_TOOLKIT_VERSION} \
      libnvidia-container1=${NVIDIA_CONTAINER_TOOLKIT_VERSION}

아래처럼 설정하면 Docker Container 가 Nvidia GPU 를 사용 하도록 설정해 줍니다.
nvidia-ctk runtime configure --runtime=docker 실행시 /etc/docker/daemon.json 에 세팅값이 설정됩니다

# Docker 에서 GPU 사용 가능하게 해줌
# Docker runtime config
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

# Verify (Docker)
docker run --rm --gpus all nvidia/cuda:12.4.1-base-ubuntu22.04 nvidia-smi

Containerd 에서 GPU 사용은 다음과 같이 합니다.
K3s는 Containerd 를 사용 (반드시 설치 해야 함)

# K3s 에서 GPU 사용 가능하게 해줌 (K3s 는 Containerd 사용)
sudo nvidia-ctk runtime configure \
  --runtime=containerd \
  --config=/var/lib/rancher/k3s/agent/etc/containerd/config.toml

sudo systemctl restart containerd
sudo systemctl restart k3s
kubectl rollout restart daemonset nvdp-nvidia-device-plugin -n nvidia-device-plugin

1.4 Nvidia Device Plugin + GPU Feature Discovery (GFD)

Kubernetes 에서 GPU를 자원(resource)로 인식하게 만드는 컴포넌트
cpu, memory 지정은 기본적으로 지원되는데, gpu: 2 이런건 Nvidia device plugin을 설치해야지 됨

RuntimeClass 생성

K3s의 팟이 nvidia-container-runtime을 사용하도록 RuntimeClass를 먼저 생성합니다.

cat <<EOF | kubectl apply -f -
apiVersion: node.k8s.io/v1
kind: RuntimeClass
metadata:
  name: nvidia
handler: nvidia
EOF

실제 설치

(여기서는 helm 으로 설치 방법을 알려줌)

gfd.enabled=true
- GPU Feature Discovery 활성화
- GPU가 존재하는 노드에 자동으로 라벨 부착
- nodeAffinity 조건을 만족시켜 Device Plugin DaemonSet이 정상적으로 실행됨

helm repo add nvdp https://nvidia.github.io/k8s-device-plugin
helm repo update

# 어떤 버젼 있는지 확인
helm search repo nvdp --devel

# 위에서 확인한 버젼을 사용해서 설치/업그레이드
helm upgrade -i nvdp nvdp/nvidia-device-plugin \
  --namespace nvidia-device-plugin \
  --create-namespace \
  --set gfd.enabled=true \
  --set runtimeClassName=nvidia \
  --version 0.18.0

설치 확인

# DaemonSet 확인
$ kubectl get pods -n nvidia-device-plugin -o wide
NAME                                                    READY   STATUS    RESTARTS        AGE    IP           NODE                   NOMINATED NODE   READINESS GATES
nvdp-node-feature-discovery-gc-6476cc6bf4-t655p         1/1     Running   0               55m    10.42.0.23   anderson-ubuntu-3090   <none>           <none>
nvdp-node-feature-discovery-master-58788687cc-tzl9v     1/1     Running   0               55m    10.42.0.22   anderson-ubuntu-3090   <none>           <none>
nvdp-node-feature-discovery-worker-849zk                1/1     Running   1 (2m25s ago)   55m    10.42.0.26   anderson-ubuntu-3090   <none>           <none>
nvdp-nvidia-device-plugin-gpu-feature-discovery-m2fz8   1/1     Running   0               2m4s   10.42.0.34   anderson-ubuntu-3090   <none>           <none>
nvdp-nvidia-device-plugin-prt9m                         1/1     Running   0               2m4s   10.42.0.33   anderson-ubuntu-3090   <none>           <none>

$ kubectl get ds -n nvidia-device-plugin
NAME                                              DESIRED   CURRENT   READY   UP-TO-DATE   AVAILABLE   NODE SELECTOR                 AGE
nvdp-node-feature-discovery-worker                1         1         1       1            1           <none>                        72m
nvdp-nvidia-device-plugin                         1         1         1       1            1           <none>                        72m
nvdp-nvidia-device-plugin-gpu-feature-discovery   1         1         1       1            1           <none>                        72m
nvdp-nvidia-device-plugin-mps-control-daemon      0         0         0       0            0           nvidia.com/mps.capable=true   72m

1.5 Kubernetes Operation Tools

k9s

터미널용 툴

wget https://github.com/derailed/k9s/releases/latest/download/k9s_Linux_amd64.tar.gz
tar -xzf k9s_Linux_amd64.tar.gz
sudo mv k9s /usr/local/bin/

2. vLLM

2.1 vllm namespace

kubectl create ns vllm || true

2.1 Persistent Volume 생성

PVC 생성

k3s 디렉토리 만들고 그 안에다가 다음의 파일들을 생성합니다.

cat <<'EOF' | kubectl apply -f -
# pvc-gpt-oss-20b.yaml
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: gpt-oss-20b
  namespace: vllm
spec:
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 50Gi  # Adjust based on model size
EOF

확인은 다음과 같이 합니다.

kubectl get pvc -n vllm

2.2 Secret 생성 (Hugging Face Token)

Gated model이거나 인증이 필요한 경우 Secret 설정이 필수입니다. CreateContainerConfigError가 발생한다면 이 설정이 빠졌는지 확인하세요.

# 터미널에서 직접 생성하는 것이 편합니다.
kubectl create secret generic hf-token-secret \
  -n vllm \
  --from-literal=token="YOUR_HUGGINGFACE_TOKEN"

2.3 Deploy vLLM

실제 vLLM을 배포합니다.
vLLM의 주요 옵션들을 정리하면 다음과 같습니다.

Option	Description	Usage
`--model`	사용할 모델의 이름 또는 경로	`vllm serve facebook/opt-125m`
`--tensor-parallel-size`, `-tp`	Tensor Parallelism을 위한 GPU 개수	`-tp 2`
`--pipeline-parallel-size`, `-pp`	Pipeline Parallelism을 위한 GPU 개수	`-pp 2`
`--gpu-memory-utilization`	GPU 메모리 사용률 (기본값 0.9)	`--gpu-memory-utilization 0.95`
`--max-model-len`	모델의 최대 컨텍스트 길이 제한	`--max-model-len 4096`
`--trust-remote-code`	모델의 커스텀 코드 실행 허용 (필요시)	`--trust-remote-code`
`--dtype`	데이터 타입 설정 (auto, float16, bfloat16 등)	`--dtype bfloat16`
`--quantization`, `-q`	양자화 설정 (awq, gptq, bitsandbytes 등)	`-q awq`
`--enforce-eager`	CUDA Graph 대신 Eager 모드 사용 (디버깅용)	`--enforce-eager`
`--served-model-name`	API에서 노출될 모델 이름 변경	`--served-model-name my-gpt`
`--api-key`	API 접속을 위한 API Key 설정	`--api-key mysecret`
`--enable-lora`	LoRA 어댑터 사용 활성화	`--enable-lora`

# vllm-deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: gpt-oss-20b
  namespace: vllm
  labels:
    app: gpt-oss-20b
spec:
  replicas: 1
  selector:
    matchLabels:
      app: gpt-oss-20b
  template:
    metadata:
      labels:
        app: gpt-oss-20b
    spec:
      runtimeClassName: nvidia  # RuntimeClass 추가 (K3s에서 필수)
      volumes:
      - name: cache-volume
        persistentVolumeClaim:
          claimName: gpt-oss-20b
      # vLLM needs to access the host's shared memory for tensor parallel inference.
      - name: shm
        emptyDir:
          medium: Memory
          sizeLimit: "8Gi"
      containers:
      - name: gpt-oss-20b
        image: vllm/vllm-openai:latest
        command: ["/bin/sh", "-c"]
        args: [
          "vllm serve openai/gpt-oss-20b \
            --trust-remote-code \
            --enable-chunked-prefill \
            --max-model-len 4096 \
            --gpu-memory-utilization 0.90 \
            --dtype auto"
        ]
        env:
        - name: HUGGING_FACE_HUB_TOKEN
          valueFrom:
            secretKeyRef:
              name: hf-token-secret
              key: token
        ports:
        - containerPort: 8000
        resources:
          limits:
            cpu: "8"
            memory: 32Gi
            nvidia.com/gpu: "1"
          requests:
            cpu: "2"
            memory: 16Gi
            nvidia.com/gpu: "1"
        volumeMounts:
        - mountPath: /root/.cache/huggingface
          name: cache-volume
        - name: shm
          mountPath: /dev/shm
        livenessProbe:
          httpGet:
            path: /health
            port: 8000
          initialDelaySeconds: 300
          periodSeconds: 10
        readinessProbe:
          httpGet:
            path: /health
            port: 8000
          initialDelaySeconds: 300
          periodSeconds: 5

설치가 완료되었으면 실제로 API가 동작하는지 테스트해 봅니다.
K3s 환경에서는 Cluster IP에 직접 접근이 가능하므로, Pod IP를 확인하여 바로 테스트할 수 있습니다.

먼저 Pod의 IP를 확인합니다.

$ kubectl get pod -n vllm -o wide

NAME                           READY   STATUS    RESTARTS   AGE   IP            NODE                   NOMINATED NODE   READINESS GATES
gpt-oss-20b-6b44fc66b6-kkr8t   1/1     Running   0          28m   10.42.0.114   anderson-ubuntu-3090   <none>           <none>

출력된 IP를 확인한 후 curl 명령어로 health 엔드포인트를 호출합니다.

# 예: IP가 10.42.0.114 인 경우
curl http://10.42.0.114:8000/health -v

아무런 내용 없이 200 OK 응답이 오면 정상적으로 실행 중인 상태입니다.

2.4 Production-Level Access (Ingress & Service)

앞서 Test 단계에서는 Pod IP로 직접 테스트했지만,
실제 운영 환경(Production)에서는 절대 Pod IP를 직접 사용하지 않습니다.
Pod는 언제든 죽었다 살아나며 IP가 바뀌기 때문입니다.

이를 해결하기 위해 Service와 Ingress를 사용합니다.

1) Service (Load Balancer)

Service는 쉽게 말해 “내부 로드 밸런서” 입니다.

여러 개의 Pod(replica)가 떠 있을 때, 이들을 하나의 고정된 IP(ClusterIP) 로 묶어줍니다.
트래픽이 들어오면 살아있는 Pod들 중 하나로 부하 분산(Load Balancing) 을 해줍니다.
즉, Pod가 죽고 새로 태어나도 Service의 주소는 변하지 않습니다.

# vllm-service.yaml
apiVersion: v1
kind: Service
metadata:
  name: gpt-oss-20b-service
  namespace: vllm
spec:
  selector:
    app: gpt-oss-20b  # Deployment의 label과 일치해야 함
  ports:
    - protocol: TCP
      port: 80        # Service가 노출할 포트
      targetPort: 8000 # 실제 Pod가 떠 있는 포트
  type: ClusterIP     # 외부 노출 없이 내부 전용

$ kubectl get service -n vllm

NAME                  TYPE        CLUSTER-IP     EXTERNAL-IP   PORT(S)   AGE
gpt-oss-20b-service   ClusterIP   10.43.61.210   <none>        80/TCP    81s

$ curl httP://10.43.61.210/health  -v

2) Ingress (Gateway)

Ingress는 클러스터 “외부에서 들어오는 대문” 역할을 합니다.

llm.incredible.ai 처럼 도메인 주소를 보고 적절한 Service로 연결해 줍니다.
SSL/TLS 인증서 처리나 라우팅 규칙을 담당합니다.

# vllm-ingress.yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: gpt-oss-20b-ingress
  namespace: vllm
spec:
  rules:
  - host: llm.incredible.ai  # 1. 사용자가 이 도메인으로 접속하면
    http:
      paths:
      - path: /
        pathType: Prefix
        backend:
          service:
            name: gpt-oss-20b-service # 2. 이 서비스(내부 로드밸런서)로 보냄
            port:
              number: 80

3) Local Test (가짜 도메인 사용)

로컬 개발 환경에서는 llm.incredible.ai 같은 도메인이 실제 인터넷에 없으므로, 내 컴퓨터가 이를 인식하도록 속여야 합니다.

Linux/Mac의 경우 /etc/hosts 파일을 수정합니다.

# /etc/hosts 파일 수정
sudo vim /etc/hosts

# 맨 아래에 다음 줄 추가 (K3s가 설치된 로컬 IP)
127.0.0.1 llm.incredible.ai

이제 주소창이나 터미널에서 진짜 도메인처럼 호출할 수 있습니다.

# 이제 IP 대신 도메인으로 호출 가능!
curl http://llm.incredible.ai/health

Uninstall

helm uninstall nvdp -n nvidia-device-plugin
kubectl delete namespace nvidia-device-plugin

확인

bash kubectl get pods -A | grep -i nvidia || true kubectl get ds -A | grep -i nvidia || true

Antigravity Personal Settings

Mon, 01 Dec 2025 01:00:00 +0000

혹시 윈도우면, wsl –install 이걸로 우분투 사용 가능함. 이후 wsl 로 ubuntu 처럼 사용

1. Hot Keys

1.1 Hot Keys

Category	Title	Hot Key	Description
Antigravity	Open Command	CTRL + SHIFT + P
	Terminal	CTRL + `	Open/focus terminal
	Word Wrap	ALT + Z	Toggle Word Wrap

1.2 Command

Category	Command	Description
Python	Python: Select Interpreter	특정 버젼 Python 선택
	Python: Configure Test	Pytest등의 test 툴을 선택

2. Extensions

2.1 Python Support in Antigravity

Python 실행하고 하려면 해당 extensions 도 설치해야 함.
실제 Python을 설치하는게 아니라, Python을 실행할수 있도록 도와주는 extension

아래와 같이 검색

@category:debuggers Python

2.2 Remote-SSH: Connect to SSH Host…

먼저 ~/.ssh/config 에 다음을 작성

Host oracle
    HostName 134.185.117.137
    Port 22
    User ubuntu
    IdentityFile C:\Users\anderson\.ssh\id_ed25519
    ControlMaster auto
    ControlPath ~/.ssh/cm-%r@%h:%p
    ControlPersist 10m

윈도우에서는 Multiplexing (한번 만든 SSH연결을 여러 세션이 같이 쓰게 하는 기능) 끄는게 좋아

Host oracle
    HostName 134.185.117.137
    Port 22
    User ubuntu
    IdentityFile C:\Users\anderson\.ssh\id_ed25519

Bastion 에서는 다음과 같이 설정

# Bastion 호스트 서버
Host oracle-bastion
    HostName 1.2.3.4
    Port 22
    User ec2-user
    IdentityFile C:/Users/anderson/.ssh/bastion.pem
    IdentitiesOnly yes
    ServerAliveInterval 60
    ServerAliveCountMax 3
    
# 실제 내부 서버 정의
Host oracle
    HostName 10.0.1.15
    Port 22
    User ubuntu
    IdentityFile C:/Users/anderson/.ssh/id_ed25519
    IdentitiesOnly yes
    
    ProxyJump oracle-bastion

    ControlMaster auto
    ControlPath ~/.ssh/cm-%r@%h:%p
    ControlPersist 10m

2.3 FTP/SFTP/SSH Sync Tool

FTP/SFTP/SSH Sync 툴에서 + 를 클릭
여기서 해당 remote를 대표하는 이름을 적어 넣습니다.

SFTP 선택 (따로 FTP 21을 오픈할 필요없이 22번 SSH로 접속 가능)

다음을 선택

Real-time submission after saving
is this the default configuration

다른거 선택하면 안됨!!

이후에 sync_config.jsonc 가 나오고 여기서 실제 설정.
다음을 반드시 설정

host
port
privateKeyPath
remotePath

{
  "oracle_server": {
    "type": "sftp",
    "host": "134.185.117.137",
    "port": 22,
    "username": "ubuntu",
    "privateKeyPath": "C:/Users/anderson/.ssh/id_ed25519",
    "proxy": false,
    "upload_on_save": true,
    "watch": false,
    "submit_git_before_upload": false,
    "submit_git_msg": "",
    "build": "",
    "compress": false,
    "remote_unpacked": false,
    "delete_remote_compress": false,
    "delete_local_compress": false,
    "deleteRemote": false,
    "upload_to_root": false,
    "distPath": [],
    "remotePath": "/home/ubuntu/projects",
    "excludePath": [],
    "downloadPath": "",
    "downloadExcludePath": [],
    "default": true
  }
}

ToolFormer - Language Models Can Teach Themselves to Use Tools

Sun, 10 Aug 2025 01:00:00 +0000

1. Introduction

Key	Value
Paper	https://arxiv.org/pdf/2302.04761
Publication Date	2023

1.1 TL;DR

Problem

대형 언어 모델은 언어 생성 능력은 강하지만, 정확한 산술 계산, 최신 사실 조회, 날짜 연산 등에서는 취약합니다.
가장 단순한 해결책은 검색엔진·계산기·캘린더 같은 외부 도구를 쓰게 하는 것이지만, 기존 접근은

(1) 대량의 사람 주석에 의존
(2) 특정 과제 전용 설계에 묶여 일반성이 떨어진다는 한계 존재

Brief Solution

ToolFormer는 최소한의 데모만으로 모델이 스스로 도구 사용을 학습하도록 합니다. 핵심 요건은 다음과 같습니다.

LLM이 스스로 외부 API 를 호출할지, self supervised 학습.
- 데이터 레이블을 스스로 직접 생성하고 자동으로 미세 조정
- 실제 NLL(negative log likelihood)을 낮추는 호출을 남김
계산기·검색·번역·캘린더 등 다양한 도구를 하나의 통일된 포맷으로 다룸

1.2 Examples

계산기: [Calculator(400 / 1400) → 0.29]
QA: [QA(“Who is the publisher of The New England Journal of Medicine?”) → Massachusetts Medical Society]
Wiki Search: [WikiSearch(“BrownAct”) → The Ralph M. Brown Act is an act of the California State Legislature that guarantees the public’s right to attend and participate in meetings of local legislative bodies.]

1.3 Pipeline

2. How it works

2.1 Format & Notation

API 호출 표현: $c = (a_c, i_c)$
- a_c: API 이름 (예: Calculator, WikiSearch)
- i_c: API arguments (예: 질의, 수식 등)

위의 수식적 표현은 Tuple 로 이루어져 있습니다. (수학적 관점에서)
하지만 Language Model에서는 문자열 즉 Token Sequence 를 다룰수 있기 때문에 Tuple 같은 구조체를 다룰수 없습니다.
따라서 $(a_c, i_c, r)$ 같은 구조를 -> 일렬의 문자열로 바꿔야 합니다.
이것을 논문에서는 Linearized Sequence 라고 부릅니다.

\[\begin{aligned} \mathbf{e}(c) &= \langle \text{API} \rangle\, a_c(i_c)\, \langle /\text{API} \rangle \\ \mathbf{e}(c, r) &= \langle \text{API} \rangle\, a_c(i_c) \to r\, \langle /\text{API} \rangle \end{aligned}\]

여기서 는 special token입니다.

2.2 Sampling API Calls

Prompt 를 만듬 (P(x))
- 각 API 마다 prompt 템플릿을 만듬
- prompt는 모델한테 해당 텍스트 안에 API call을 생성하도록 힌트를 줌

Question Answering API Prompt 예시

Your task is to add calls to a Question Answering API to a piece of text.
The questions should help you get information required to complete the text. 
You can call the API by writing "[QA(question)]" where "question" is the
question you want to ask. 

Here are some examples of API calls:

Input: Joe Biden was born in Scranton, Pennsylvania.
Output: Joe Biden was born in [QA("Where was Joe Biden born?")] Scranton, [QA("In which state is Scranton?")] Pennsylvania.

Calculator API Prompt 예시

Your task is to add calls to a Calculator API to a piece of text.
The calls should help you get information required to complete the text. 
You can call the API by writing "[Calculator(expression)]" 
where "expression" is the expression to be computed. 

Here are some examples of API calls:

Input: The number in the next term is 18 + 12 x 3 = 54.
Output: The number in the next term is 18 + 12 x 3 = [Calculator(18 + 12 * 3)] 54.

API Call 위치 후보 찾기
- Input Text의 i위치 마다, <API> 토큰이 나올 확률을 모델한테 계산
- \[p_i = P_M (\langle \text{API} \rangle | P(x), x_{1:i-1})\]
- 여기서 나온 확률이 특정 threshold 보다 크면, 해당 positions 을 들고 있음.
- 관련 positions 이 너무 많으면 상위 K 개만 선택함

다음은 예제 코드. (이렇게 돌리면 안됨. 그냥 예제)

# ------------------------------
# 1. Prompt P(x) 준비
# ------------------------------
text = "Joe Biden was born in Scranton, Pennsylvania."
prompt = "Add helpful API calls to clarify this text:\n"  # P(x)
inputs = tokenizer(prompt + text, return_tensors="pt").to(model.device)

# ------------------------------
# 2. 각 위치별로 <API> 시작 확률 계산
# ------------------------------
input_ids = inputs["input_ids"][0]  # shape: [seq_len]
seq_len = input_ids.size(0)

# special token 정의 (논문에서는 실제론 '[' 사용)
API_START = tokenizer.convert_tokens_to_ids("[")

threshold = 0.01
top_k = 5

api_probs = []
with torch.no_grad():
    for i in range(1, seq_len):  
        prefix_ids = input_ids[:i].unsqueeze(0)  # prefix
        outputs = model(prefix_ids)
        logits = outputs.logits[:, -1, :]  # last token logits
        probs = torch.softmax(logits, dim=-1)
        p_api = probs[0, API_START].item()
        api_probs.append((i, p_api))

# threshold filtering + top-k
candidates = [(i, p) for (i, p) in api_probs if p > threshold]
candidates = sorted(candidates, key=lambda x: x[1], reverse=True)[:top_k]

2.3 API 호출

여기서 전체 API 호출을 합니다.
구현에 달려 있는 것이기 때문에, python 함수를 실행할지, API 를 호출할지, 다른 model 을 호출할지 등등 모두 자유

2.4 Filtering API Calls

$\mathcal{L}_{\text{plain}}$ : API 호출 없이, plain LM loss
$\mathcal{L}_{\text{aug}}$ : API call + 결과를 포함한 LM Loss
$\Delta^{(i)}$ : loss 의 개선 정도
- $\Delta^{(i)} \gt 0$ : API Call 이 실제로 두움이 됨
- $\Delta^{(i)} \ge \gamma_f$ : API Call 이 충분히 도움이 된다고 판단 -> 해당 API 호출을 유지

\[\begin{aligned} \mathcal{L}_{\text{plain}}^{(i)} &= - \sum_{t \in \mathcal{W}_i} \log p_\theta(x_t \mid x_{\le i}) \\ \mathcal{L}_{\text{aug}}^{(i)} &= - \sum_{t \in \mathcal{W}_i} \log p_\theta(x_t \mid x_{\le i}, \mathbf{e}(c_i, r)) \\ \Delta^{(i)} &= \mathcal{L}_{\text{plain}}^{(i)} - \mathcal{L}_{\text{aug}}^{(i)} \\ \end{aligned}\]

이중에서 Delta 값이 특정 threshold 이상인 것만 남김니다.

\[\mathcal{L}_{\text{plain}}^{(i)} - \mathcal{L}_{\text{aug}}^{(i)} \ge \gamma_f\]

2.5 Model Finetuning After Sampling & Filtering

이렇게 필터링된 API 호출들을 포함한 결과 (\mathcal{C}^*) 를 가지고, 모델을 파인튜닝합니다.
삽입 과정은 다음과 같이 합니다.

# Input text
User: What’s the weather in Seoul today?

# Internal API call
[API CALL] weather_api("seoul", "today")
[API_RESULT] {"temperature": "25°C", "condition": "Sunny"}

# 다음과 같이 결과가 만들어 집니다. 
<API> weather_api("seoul", "today") -> {"temperature": "25°C", "condition": "Sunny"} </API>
 
# 위의 API 호출 결과를 LLM이 참조후에 최정 답변을 생성
[Target Label] IT's 25°C and Sunny in Seoul today.

3. Implementation

3.1 Open WebUI

예제 구현 코드.

“dragon fire 343 는 몇이야?” 이런식으로 질문하면, 아래의 함수를 실행하고 답변을 줍니다.
답변은 테스트 용이기 때문에, 지정된 답변을 줍니다.

"""
title: Dragon Fire Bitcoin Analyzer
author: Anderson
description: A tool that analyzes Bitcoin's dragon fire intensity level
version: 1.0.0
license: MIT
"""

from typing import Optional

# Optional manifest
manifest = {
    "title": "Dragon Fire Bitcoin Analyzer",
    "author": "Anderson",
    "version": "1.0.0",
    "license": "MIT",
    "description": "A tool that analyzes Bitcoin's dragon fire intensity level"
}


class Tools:
    def __init__(self):
        pass

    def dragon_fire(
        self, 
        value: int,
        __event_emitter__: Optional[object] = None
    ) -> str:
        """
        Calculate dragon fire intensity by squaring the input value.
        
        Args:
            value: Integer value to calculate dragon fire for
            __event_emitter__: Optional event emitter for status updates
        
        Returns:
            Dragon fire result with squared value
        """
        
        if __event_emitter__:
            __event_emitter__({
                "type": "status",
                "data": {"description": f"Calculating dragon fire for {value}...", "done": False}
            })
        
        result = value ** 2
        
        if __event_emitter__:
            __event_emitter__({
                "type": "status",
                "data": {"description": "Dragon fire calculation completed", "done": True}
            })
        
        return f"dragon fire {result}"

아래는 실제로 돌려본 예제 입니다.

Switch Transformer - Scaling to Trillion Parameter Models with Simple and Efficient Sparsity

Sun, 01 Jun 2025 01:00:00 +0000

Switch Transformer - Scaling to Trillion Parameter Models with Simple and Efficient Sparsity

Key	Value
Paper	https://arxiv.org/pdf/2101.03961
publication Date	2021

Problem

MoE (Mixture of Experts) 모델은 inputs 마다 서로다른 parameters 사용하기 때문에, 전체 parameters 수는 폭발적으로 늘어나도, 실제 사용하는 부분은 소수라 연산량은 일정합니다.

하지만 실제 적용은 어렵습니다.

기존 MoE 모델의 문제점
- 복잡한 Routing 알고리즘이 필요
- communication overhead가 큼
- 학습 불안정성 gradient exploding 현상 발생
Switch Transformer 는 이러한 기존의 문제들을 해결하였음.

Model

핵심은

Sparse Training
궁극적으로 parameter 갯수 자체를 maximize 하는 것. (매우 효율적인 방식으로)
이렇게 parameters 를 늘리지만, Floating point operations (FLOPs) 를 constant 값으로 바꾸는 것.
- 즉 parameters 는 늘리지만, 연산은 constant 하게 됨.

기존 MOE 모델 방식 - Mixture of Experts Routing

MOE (Mixture of Experts) 개념은 이미 2017년 Shazeer et al에 의해 제안되었음.
route 에 해당하는 $W_r$ 값이 존재하고, input값과 곱해져서 logits을 생성함 $h(x) = W_r \cdot x$
이후에 softmax를 적용하고, top-k 개의 experts 를 선택함. 포인트는 여러개의 experts를 선택함

아래는 구체적인 공식

\[h(x) = W_r \cdot x\]

W_r : route matrix (이게 학습이 되면서 experts를 선택하는 역활을 함)
x: input vector

이후에 softmax를 적용하여, top-k개의 experts를 선택함.

\[p_i(x) = \frac{e^{h(x)_i}}{\sum^N_j e^{h(x)_j}}\]

만약 T가 선택된 experts의 집합이라면, 최종 output은 다음과 같이 계산됩니다.

\[y = \sum_{i \in T} p_i(x) E_i(x)\]

E_i(x): 선택된 experts에서 i번째 expert의 output
그냥 곱하기 하면 됨

이걸 Pytorch 로 구현하면 다음과 같습니다.

import torch
import torch.nn as nn
import torch.nn.functional as F

class MoELayer(nn.Module):
    def __init__(self, input_dim, output_dim, num_experts=4, k=2):
        super().__init__()
        self.k = k
        self.num_experts = num_experts

        # Router: logits = W_r · x
        self.router = nn.Linear(input_dim, num_experts)

        # Experts: each is a small MLP (or Linear here)
        self.experts = nn.ModuleList([
            nn.Linear(input_dim, output_dim) for _ in range(num_experts)
        ])

    def forward(self, x):
        """
        x: (batch_size, input_dim)
        returns: (batch_size, output_dim)
        """
        # Compute routing logits
        logits = self.router(x)  # (B, N)
        gate_probs = F.softmax(logits, dim=-1)  # (B, N)

        # Select top-k experts per example
        topk_vals, topk_idx = torch.topk(gate_probs, self.k, dim=-1)  # (B, k)

        # Initialize output
        output = torch.zeros(x.size(0), self.experts[0].out_features, device=x.device)

        for i in range(self.k):
            idx = topk_idx[:, i]  # expert index
            weight = topk_vals[:, i].unsqueeze(1)  # (B, 1)

            # For batch-wise selection
            expert_outputs = torch.stack([
                self.experts[expert_id](x[j].unsqueeze(0))
                for j, expert_id in enumerate(idx)
            ]).squeeze(1)  # (B, output_dim)

            output += weight * expert_outputs  # weighted sum

        return output

The problem of MOE Routing

2017년도에 나온 Mixture of Experts의 모델은 복잡한 routing알고리즘이 필요했습니다. 특히 1개 이상의 expersts를 선택하는 방식을 취했는데, 그 이유는 non-trivial gradients 를 갖기 때문이라고 합니다.

trivial gradients: gradients 값이 0에 가까운 매우 작은 수 -> 학습이 안됨
non-trivial gradients: 실제로 의미있는 (학습이 가능한) gradients

만약 softmax 의 결과값 중에서 하나만 취하게 된다면, argmax 를 사용할수 있습니다.

idx = torch.argmax(logits)

문제는 argmax를 사용하게 되면 non-differentiable 연산이기 때문에, backpropagation이 불가능하게 됩니다.
(그냥 큰 값을 선택해서 index를 리턴하는 것기 때문에 discrete operation 이며, discontinuous function임 -> 미분 안됨) 즉 해당 값이 왜 선택되었는지, gradient 정보가 없습니다.

따라서 여러개를 선택하는 방식이 필요했습니다.

Expert Capacity

Switch Transformer 를 배우기 전에, 먼저 Expert Capacity 개념을 이해해야 합니다.

Imbalance는 expert 가 선택되는 빈도에 따라서 발생하기도 합니다.

예를 들어서 “Mixture of Experts is AWESOME” 이라는 문장이 Router를 거쳤을때, 특정 Expert 만 선택된다면 undertraining이 발생할수 있습니다.

Token      Softmax(logits)                  Selected Expert
------------------------------------------------------------
Mixture    [0.7, 0.1, 0.1, 0.1]             Expert 0
of         [0.8, 0.1, 0.0, 0.1]             Expert 0
Experts    [0.6, 0.1, 0.1, 0.2]             Expert 0
is         [0.5, 0.2, 0.1, 0.2]             Expert 0
AWESOME    [0.1, 0.1, 0.7, 0.1]             Expert 2

즉 어떤 expert가 선택 되느냐가 아니라, 얼마나 많이 특정 expert가 선택되느냐가 중요합니다.
해당 문제를 해결하기 위해서, Expert Capacity 개념이 도입되었습니다.
특정 expert의 capacity (token의 갯수)를 정해놓고, 해당 capacity를 초과하는 경우에는 다른 expert를 선택하도록 합니다.
이것을 “token overflow” 라고 합니다.

Transformer 모델 쓰는데, 어떻게 이게 가능하냐 라고 생각이 들면 아키텍쳐를 보면 이해가 됩니다.

Input Sentence (문장)
    ↓
Tokenization
    ↓
Embedding
    ↓
Multi-Head Attention (공통 처리)
    ↓
FFN (token마다 expert 선택!)
    ↓
Output

즉 FFN 부분에서 expert가 선택되고 FFN가 처리되기 때문에, token마다 다른 expert가 선택될 수 있습니다.
그래서 expert capacity를 정해놓고, 해당 capacity를 초과하는 경우에는 다른 expert를 선택하도록 정할수 있습니다. 또는 dropped token 이라고 해서, 해당 token을 처리하지 않고, 넘어가도록 할수도 있습니다.

\[\text{Expert Capacity} = \left( \frac{\text{tokens_per_batch}}{\text{num_experts}} \times \text{capacity_factor} \right)\]

tokens_per_batch: 배치당 토큰의 갯수
num_experts: 전체 expert의 갯수
capacity_factor: expert의 capacity를 조정하는 factor (예를 들어서 1.0 이면, 각 expert가 배치당 토큰의 갯수 / 전체 expert의 갯수 만큼의 capacity를 갖게 됨)

예제

\[\text{Expert Capacity} = \left( \frac{100}{4} \times 1.0 \right) = 25\]

각 Expert는 배치당 25개의 토큰을 처리할 수 있습니다.
만약 어떤 expert가 25개를 초과하는 경우에는 다른 expert를 선택하거나, dropped token 으로 그냥 스킵합니다.
보통 capacity_factor는 1.0 에서 1.5 사이로 설정합니다.

capacity_factor 가 높을수록: dropped token이 줄어듬 -> 반면에 연산량이 늘어남
capacity_factor 가 낮을수록: dropped token이 늘어남 -> 반면에 연산량이 줄어듬

아래는 Switch Transformer 사용시 capacity factor가 줄어들면서 , 연산량이 줄어드는 것을 보여줍니다.

Switch Transformer

Switch Routing: Rethinking Mixture of Experts

Switch Transformer 는 이러한 복잡한 Routing 알고리즘을 단순화 하면서, 더 높은 성능을 보여줍니다.
즉 k=1 routing은 Switch Routing이라고 부릅니다.

이로인 인한 장점은 다음과 같습니다.

Router computation 이 단순해지며, 오직 single expert만 선택합니다.
expert capacity가 반으로 줄어들수 있습니다.
routing implementaion이 단순해집니다.

1번은 single expert만 선택하기 때문에, routing computation이 단순해집니다.
2번은 expert capacity에서 쉽게 말하면, dropped token이 발생하면서 연산량이 줄어들수 있습니다.
3번은 그냥 구현이 단순해집니다.

Differentiable Load Balancing Loss

\[\begin{align} P_i &= \frac{1}{T} \sum_{x \in \beta} p_i(x) \\ fi &= \frac{1}{T} \sum_{x \in \beta} \mathbf{1} \{ argmax p(x) = i \} \\ loss &= \alpha \cdot N \cdot \sum^N_{i=1} f_i \cdot P_i \\ \end{align}\]

P_i
- $P_i (X)$: token x가 expert i로 갈 확률. (softmax의 결과값)
f_i
- T: batch안의 token 갯수
- argmax p(x): token x를 라우팅할때 선택된 expert의 index
- 쉽게 설명하면, batch 안의 token이 expert i로 라우팅 됐는지 비율
- 예를 들어서 batch안에 token이 100개가 있고, 그중에 20개가 expert i로 라우팅 됐다면, f_i = 0.2 가 됩니다.
loss
- a (alpha): scaling factor (hyperparameter 이며 보통 0.01로 설정)
- N: number of experts
- f_i: 실제 routing된 token 중에서 expert i에 할당된 비율 (fraction of tokens dispatched to expert i)
- P_i: expert i에 할당된 확률 총합 (평균)

즉, 실제 token 분배 분포 f_i 와 router (softmax)의 분포 P_i 의 dot product를 계산 -> scaling 계수를 곱한것
f_i (token 분배 분포) 와 P_i (softmax의 분포)가 일치할수록 loss가 작아집니다.
(이때 gradient계산 할때 f 는 non-differentiable 이며, P는 differentiaible 입니다.)

즉 다음은 “완벽히 균형 잡힌 상태 (ideal case)” 입니다.

Expert:       E1     E2     E3     E4
f_i:          0.25   0.25   0.25   0.25   (실제 라우팅 분포)
P_i:          0.25   0.25   0.25   0.25   (softmax 기대 확률)

f_i * P_i:    0.0625 0.0625 0.0625 0.0625
Sum(f ⋅ P):   0.25   (최소값!)

만약 편향된 상태가 된다면, 다음과 같습니다.

Expert:       E1     E2     E3     E4
f_i:          0.70   0.10   0.10   0.10   (거의 E1만 쓰임)
P_i:          0.40   0.20   0.20   0.20   (softmax도 약간 E1 치우침)

f_i * P_i:    0.28   0.02   0.02   0.02
Sum(f ⋅ P):   0.34   (커짐 → loss ↑)

Router Implementation

import torch
import torch.nn.functional as F
from torch import nn

class Router(nn.Module):
    """
    The router module determines which expert each token is sent to.
    It also computes the load balancing loss.
    """
    def __init__(self, d_model, num_experts):
        super().__init__()
        self.num_experts = num_experts
        self.gate = nn.Linear(d_model, num_experts)

    def forward(self, x):
        # x: (batch_size, seq_len, d_model)
        logits = self.gate(x)
        # logits: (batch_size, seq_len, num_experts)
        
        # Get the top-1 expert for each token
        top1_logits, top1_indices = logits.max(dim=-1)
        # top1_indices: (batch_size, seq_len)
        
        # Create a one-hot encoding of the expert indices
        # This will be used to dispatch tokens to the correct expert
        expert_mask = F.one_hot(top1_indices, self.num_experts).float()
        # expert_mask: (batch_size, seq_len, num_experts)
        
        # Calculate the load balancing loss
        # This loss encourages all experts to be used equally.
        
        # Count how many tokens are sent to each expert
        tokens_per_expert = expert_mask.sum(dim=(0, 1)) # (num_experts)
        # Total number of tokens
        total_tokens = x.size(0) * x.size(1)
        
        # Calculate the fraction of tokens sent to each expert
        fraction_tokens_per_expert = tokens_per_expert / total_tokens
        
        # Calculate the expert probabilities from the logits
        expert_probs = F.softmax(logits, dim=-1).mean(dim=(0, 1)) # (num_experts)
        
        # The load balancing loss is the dot product of these two quantities
        load_balancing_loss = self.num_experts * torch.dot(fraction_tokens_per_expert, expert_probs)
        
        return expert_mask, load_balancing_loss

Expert Capacity

Implementation

여기서 전체 코드가 아닌 핵심이 되는 코드만 공유 합니다.

Switch Transformer Model

Input Tokens
     │
     ▼
[Embedding Layer] ──► nn.Embedding(ntoken, d_model)
     │
     ▼
[Positional Encoding] ──► PositionalEncoding(d_model, dropout)
     │
     ▼
[Transformer Encoder Stack]
     │
     └─► (L layers of)
           └─► [Multi-head Attention]
           └─► [LayerNorm + Residual]
           └─► [Switch FFN (MoE Layer)]
               └─► Router → Expert selection
               └─► Dispatch token to Expert
               └─► Gather output
           └─► [LayerNorm + Residual]
     │
     ▼
[Final Linear Decoder] ──► nn.Linear(d_model, ntoken)
     │
     ▼
Vocabulary Logits (for language modeling)

class SwitchTransformerLM(nn.Module):
    def __init__(self, ntoken: int, d_model: int, nhead: int, d_ff: int, num_experts: int, num_layers: int,
                 dropout: float = 0.5):
        super().__init__()
        self.model_type = 'Transformer'
        self.d_model = d_model
        self.encoder = nn.Embedding(ntoken, d_model)
        self.pos_encoder = PositionalEncoding(d_model, dropout)

        encoder_layer = SwitchTransformerEncoderLayer(d_model, nhead, d_ff, num_experts, dropout)
        self.transformer_encoder = SwitchTransformerEncoder(encoder_layer, num_layers)

        self.decoder = nn.Linear(d_model, ntoken)

SwitchTransformer Encoder Layer + MoE Layer

Input: Token Hidden States (src)
     │
     ▼
[Multi-Head Self-Attention]
     │
     ▼
🟦 MoELayer  ← ← ← ← ← ← ← ← ← ← ← ← ← 🧠 핵심 포인트!
     │
     ├─► Router(x)
     │     └─► Routing logits (W_r · x)
     │     └─► Softmax → Top-1 Expert 선택
     │     └─► expert_mask 생성 (one-hot)  
     │
     ├─► Capacity 계산 (token overflow 방지)
     │
     ├─► 각 Expert 별로:
     │     └─ Token dispatch (x[expert_indices])
     │     └─ Expert FFN 처리
     │     └─ Output scatter to original positions
     │
     └─► 최종 Output (sparse computation 결과)
             + Load Balancing Loss
     ▼
Dropout + Residual
     ▼
LayerNorm #2
     ▼
Output Hidden States, Load Balancing Loss

SwitchTransformerEncoderLayer 에서 가장 중요한 부분은 아래 코드이며,
기존 TransformerEncoderLayer와 MoELayer를 결합한 것입니다.
Attention 연산 후에 MoE layer를 적용하여, 각 토큰마다 다른 expert를 선택하고 처리합니다.

class SwitchTransformerEncoderLayer(nn.Module):
    def __init__(self, d_model: int, nhead: int, d_ff: int, num_experts: int, dropout: float = 0.1) -> None:
        super().__init__()
        self.self_attn = nn.MultiheadAttention(d_model, nhead, dropout=dropout)
        self.moe_layer = MoELayer(d_model, d_ff, num_experts)

        self.norm1 = nn.LayerNorm(d_model)
        self.norm2 = nn.LayerNorm(d_model)
        self.dropout = nn.Dropout(dropout)

    def forward(self, src: Tensor,
                src_mask: Optional[Tensor] = None,
                src_key_padding_mask: Optional[Tensor] = None) -> Tuple[Tensor, Tensor]:
        # Multi-head self-attention
        src2 = self.self_attn(src, src, src, attn_mask=src_mask, key_padding_mask=src_key_padding_mask)[0]
        src = src + self.dropout(src2)
        src = self.norm1(src)

        # MoE layer
        src2, load_balancing_loss = self.moe_layer(src)
        src = src + self.dropout(src2)
        src = self.norm2(src)

        return src, load_balancing_loss

MoE Layer

Input (x): (batch_size, seq_len, d_model)
   │
   ▼
Router (W_r · x → softmax → top-1 expert 선택)
   │
   ▼
Expert Mask (one-hot): (batch_size, seq_len, num_experts)
   │
   ▼
Flatten: x → (B×T, d_model), mask → (B×T, num_experts)
   │
   ▼
for each expert i in num_experts:
    - token 선택 (해당 expert로 라우팅된 것만)
    - capacity 초과 시 overflow drop
    - expert_i(input) → FFN 처리
    - 결과를 final_output 에 다시 index_add

   ▼
Reshape: (B×T, d_model) → (batch_size, seq_len, d_model)

Return: final_output, load_balancing_loss

class MoELayer(nn.Module):
    """
    The Mixture-of-Experts (MoE) layer, which replaces the FFN layer in a standard Transformer.
    """
    def __init__(self, d_model: int, d_ff: int, num_experts: int, capacity_factor: float = 1.25) -> None:
        super().__init__()
        self.d_model = d_model
        self.num_experts = num_experts
        self.capacity_factor = capacity_factor

        self.router = Router(d_model, num_experts)
        self.experts = nn.ModuleList([Expert(d_model, d_ff) for _ in range(num_experts)])
        
    def forward(self, x: Tensor) -> Tuple[Tensor, Tensor]:
        """
        Example: Let's say we have:
        - batch_size=2, seq_len=4, d_model=8, num_experts=2
        - Input x: shape (2, 4, 8) - 2 sequences, each with 4 tokens of 8 dimensions
        """
        # x: (batch_size, seq_len, d_model)
        # Example: x.shape = (2, 4, 8)
        batch_size, seq_len, d_model = x.shape
        
        # Get the expert mask and load balancing loss from the router
        # The router decides which expert should process each token
        expert_mask, load_balancing_loss = self.router(x)
        # expert_mask: (batch_size, seq_len, num_experts)
        # Example: expert_mask.shape = (2, 4, 2)
        #   expert_mask[0, 0, :] = [1, 0] means token 0 goes to expert 0
        #   expert_mask[0, 1, :] = [0, 1] means token 1 goes to expert 1
        
        # Determine the capacity of each expert
        capacity = int((seq_len / self.num_experts) * self.capacity_factor)
        
        # Reshape tensors for easier processing - flatten batch and sequence dimensions
        x_flat = x.view(-1, d_model) # (batch_size * seq_len, d_model)
        expert_mask_flat = expert_mask.view(-1, self.num_experts) # (batch_size * seq_len, num_experts)

        # Initialize output tensor with zeros - same shape as flattened input
        final_output = torch.zeros_like(x_flat)
        # Example: final_output.shape = (8, 8)
        
        # Process each expert separately
        for i, expert in enumerate(self.experts):
            # Find which tokens should go to this expert (non-zero entries in the mask)
            expert_indices = torch.where(expert_mask_flat[:, i] > 0)[0]
            # Example for expert 0: expert_indices might be [0, 2, 4] (tokens 0, 2, 4)
            # Example for expert 1: expert_indices might be [1, 3, 5, 6, 7] (tokens 1, 3, 5, 6, 7)
            
            # Apply capacity constraint - if too many tokens assigned, keep only the first 'capacity' tokens
            if expert_indices.shape[0] > capacity:
                expert_indices = expert_indices[:capacity]
                # Example: if expert 1 has 5 tokens but capacity=2, keep only [1, 3]

            # Process tokens assigned to this expert
            if expert_indices.shape[0] > 0:
                # Extract the tokens that should go to this expert
                expert_input = x_flat[expert_indices]
                # Example: if expert_indices=[1, 3], expert_input.shape = (2, 8)
                
                # Process the tokens through the expert network
                expert_output = expert(expert_input)
                # Example: expert_output.shape = (2, 8) - same as expert_input
                
                # Ensure dtype consistency
                expert_output = expert_output.to(final_output.dtype)

                # Place the expert's output back to the final output at the correct positions
                # Switch Transformer uses exclusive routing: each token goes to exactly ONE expert
                # So we use assignment (=) not addition (+=)
                # Example: if expert_indices=[1, 3] and expert_output has 2 rows
                #   final_output[1] = expert_output[0]  # Place expert's output for token 1
                #   final_output[3] = expert_output[1]  # Place expert's output for token 3
                for j, token_idx in enumerate(expert_indices):
                    final_output[token_idx] = expert_output[j]

        # Reshape back to original dimensions
        final_output = final_output.view(batch_size, seq_len, d_model)
        # Example: final_output.shape = (2, 4, 8) - back to original shape
        
        return final_output, load_balancing_loss

	Full Fine-Tuning	LoRA (r=8)
파라미터 수	\(d \times k\)	\(d \times r + r \times k\)
예시 (4096×4096)	16.7M	65K
압축률	1x	~256x

행렬	크기	파라미터 수	설명
\(W_0\)	64 × 32	2,048	원본 weight (frozen)
\(A\)	4 × 32	128	LoRA down-projection
\(B\)	64 × 4	256	LoRA up-projection
\(\Delta W = BA\)	64 × 32	-	\(W_0\)와 같은 크기로 복원