JANG Studio — HuggingFace 모델을 JANG 및 JANGTQ 형식으로 변환하는 macOS 전용 네이티브 위저드(wizard)입니다. 실시간 로그가 포함된 5단계 흐름, 10행 사전 점검 게이트(preflight gate), 12행 변환 후 검증기(post-convert verifier), 앱 내 채팅 미리보기, 그리고 클릭 한 번으로 진행되는 HuggingFace 게시 기능을 제공합니다. 서명된 DMG 형식으로 배포됩니다.

설치 + 위저드 단계별 안내 + CLI 사용법 + Swift 통합에 대한 전체 사용자 가이드를 확인하세요.

앱 지원: MLX Studio는 완전한 네이티브 JANG 지원을 제공합니다. oMLX는 JANG 통합을 추가했습니다 (PR #364). LM Studio, Ollama, 그리고 Inferencer는 아직 JANG를 지원하지 않습니다 — 선호하는 앱의 개발자에게 지원 추가를 요청하거나, pip install "jang[mlx]"를 사용하세요.

MLX를 위한 GGUF 대응 방식 — 모델이 전체 Metal 속도로 GPU 메모리에 양자화(quantized)된 상태로 유지됩니다.

웹사이트 • 모델 • PyPI • 형식 사양 (Format Spec)

128 GB Mac에서 397B 구동 — JANG_1L: 112 GB, 36 tok/s, 추론 성능 포함 MMLU 86.5%
DeepSeek-V4-Flash 런타임 — DSV4의 하이브리드 SWA + CSA + HSA 어텐션(sliding-window + compressor-pool + hash-sparse)을 위한 최초의 MLX 런타임이며, mHC 잔차(residuals) 및 1M 컨텍스트 풀 양자화 캐시를 지원합니다.
routed-MoE를 위한 JangPress — mmap + madvise 콜드 티어 축출(cold-tier eviction)을 통해 128 GB Mac에서 167 GB Kimi-K2.6을 로드합니다 (docs/JANGPRESS.md 참조).
10 GB 내의 Nemotron-Cascade-2 — 16 GB MacBook에서 130 tok/s로 구동되는 IMO 금메달급 추론 모델.
MiniMax: 오직 JANG만 작동 — MLX는 25%(무작위) 점수를 기록하는 반면, JANG는 74% 점수를 기록합니다.
43 GB 내의 Nemotron-3-Super-120B — Apple Silicon을 위한 최초의 작동 가능한 Nemotron-H 양자화.
Mistral Small 4 (119B) — Apple Silicon 최초 지원 — 82 tok/s, MLX Community 4-bit보다 5배 빠른 프리필(prefill) 속도, 코드/수학/추론/VLM 모두 작동.
bfloat16 자동 감지 — 512-전문가(expert) 모델에서 float16 오버플로(overflow) 문제를 해결합니다.
추론 모드 (Reasoning mode) — <think>...</think> / [THINK]...[/THINK] 형식을 사용하며, 사고(thinking) 기능을 구성 가능하게 켜거나 끌 수 있습니다.

모델	사고 없음 (No-Think)	추론 (Reasoning)	크기	속도
JANG_1L	81.0%	86.5%	112 GB	36 tok/s
JANG_2L	79.5%	92.0%	187 GB	36 tok/s
MLX 4-bit	81.5%	94.0%	209 GB	~36 tok/s
MLX 2/3-bit	NaN	NaN	—	—

MLX는 397B 모델을 4-bit 미만으로 양자화할 수 없습니다 (float16 오버플로 발생). JANG은 bfloat16을 사용하여 이 문제를 해결합니다.

모델	No-Think	Reasoning	크기	속도
JANG_2L	59.0%	88.0%	10.3 GB	130 tok/s
JANG_4M	69.0%	93.0%	17 GB	55 tok/s
MLX 4-bit	69.0%	92.5%	16.6 GB	—
MLX 6-bit	71.0%	94.5%	23.9 GB	—

JANG_4M은 동일한 크기에서 MLX 4-bit를 능가합니다 (93.0% vs 92.5%).

모델	크기	Gen tok/s	Prefill tok/s	RAM	특징
JANG_2L	30 GB	82	216	40 GB	코드, 수학, [THINK] 추론 (reasoning), VLM
JANG_4M	57 GB	80	202	68 GB	코드, 수학, [THINK] 추론 (reasoning), VLM
JANG_6M	84 GB	74	160	95 GB	코드, 수학, [THINK] 추론 (reasoning), VLM
MLX Community 4-bit	63 GB	84	43	68 GB	VLM

2-bit (JANG_2L)에서 94.0% MMLU 달성 — 5개 과목에서 100% 기록. MLX Community보다 5배 빠른 프리필 (prefill). JANG_2L은 절반의 크기로 48 GB Mac에 탑재 가능합니다.

총 119B 파라미터, 토큰당 6B 활성 파라미터. MLA 어텐션 (attention) + 128 MoE 전문가 (experts) + Pixtral 비전. Apple Silicon에서 MLA + MoE 양자화를 지원하는 최초의 모델입니다.

과목	점수
추상 대수학 (Abstract Algebra)	13/20 (65%)
...	합계
	188/200 (94.0%)

모델	No-Think	Reasoning	크기	속도
JANG_2L	75.0%	86.0%	43 GB	52 tok/s
JANG_4M	72.5%	93.0%	63 GB	55 tok/s
MLX 4-bit	71.0%	93.5%	63 GB	60 tok/s
MLX 3-bit	충돌 (Crashes)	—	—	—

MLX mlx_lm.convert는 Nemotron의 mtp.* 가중치에서 충돌이 발생합니다. 오직 JANG만이 4-bit 미만의 결과물을 생성할 수 있습니다.

모델	MMLU	크기
JANG_2L	74%	63 GB
JANG_3M	74.5%	82 GB
MLX 4-bit	26.5%	120 GB
MLX 3-bit	24.5%	93 GB
MLX 2-bit	25%	—

MLX는 모든 비트 수준에서 MiniMax 모델에 대해 작동하지 않습니다 (~25% = 무작위 수준). MiniMax는 256개의 전문가 (experts)를 가지고 있는데, MLX는 어텐션 (attention)을 전문가 MLP와 동일한 비트로 압축하여 일관성 (coherence)을 파괴합니다.

모델	JANG	MLX 4비트	JANG 크기	MLX 크기
122B JANG_4K	86%	85%	69 GB	64 GB
122B JANG_2S	79%	56.5% (2비트)	38 GB	36 GB
35B JANG_4K	77.5%	77.0%	16.7 GB	18 GB
35B JANG_2S	65.5%	~20% (2비트)	12 GB	10 GB

| 모델 | JANG Best | MLX Best | JANG 크기 | MLX 크기 | MLX 고장 여부? |
|---|---|---|---|---|
| Qwen3.5-397B | 92.0% | 94.0% | 187 GB | 209 GB | NaN (4비트 이하) |
| Qwen3.5-397B (128 GB Mac) | 86.5% | — | 112 GB | Can't fit | — |
| Nemotron-Cascade-2 | 93.0% | 92.5% | 17 GB | 16.6 GB | — |
| Nemotron-Cascade-2 (16 GB Mac) | 88.0% | — | 10.3 GB | Can't fit | — |
| Nemotron-Super-120B | 93.0% | 93.5% | 63 GB | 63 GB | 4비트 이하에서 충돌 (Crashes below 4-bit) |
| Nemotron-Super-120B (64 GB Mac) | 86.0% | — | 43 GB | Can't fit | — |
| MiniMax-M2.5 | 74.5% | 26.5% | 82 GB | 120 GB | 모든 비트에서 고장 (Broken at ALL bits) |
| Qwen3.5-122B | 86% | 85% | 69 GB | 64 GB | 2비트에서 56.5% |
| Qwen3.5-35B | 77.5% | 77.0% | 16.7 GB | 18 GB | 2비트에서 ~20% |

모든 크기 지점에서 JANG이 우세합니다. 동등한 크기에서는 JANG이 MLX와 같거나 더 나은 성능을 보입니다. 더 작은 크기에서는 MLX가 문자 그대로 실행할 수 없는 곳(NaN, 충돌 또는 무작위 출력)에서 JANG이 작동합니다.

MoE 모델의 경우, 어텐션 (attention)은 전체 파라미터의 **1~5%**에 불과하지만 일관성 (coherence)을 100% 제어합니다. MLX는 모든 것을 균등하게 압축합니다:

MLX 4비트: 어텐션 (attention)은 4비트로, 전문가 (experts)는 4비트로 → 작동하지만 전문가에 비트를 낭비함
MLX 2비트: 어텐션 (attention)은 2비트로, 전문가 (experts)는 2비트로 → 어텐션이 깨짐 → 모델이 깨짐
JANG 2비트: 어텐션 (attention)은 8비트로, 전문가 (experts)는 2비트로 → 어텐션이 보존됨 → 모델 작동```

모델이 가진 전문가가 많을수록 MLX의 저비트 성능은 더 나빠집니다:

**128개 전문가**(Cascade-2): MLX 4비트는 여전히 작동하며, JANG이 약간 더 우수함
**256개 전문가**(122B, MiniMax): MLX 2비트가 심하게 깨지지만, JANG이 지배적임
**512개 전문가**(397B, Super-120B): MLX는 4비트 이하에서 NaN/충돌을 일으키며, 오직 JANG만이 작동함

DSV4-Flash는 어텐션 (Attention) 구조가 단순한 MLA가 **아닌** 최초의 DeepSeek급 모델입니다. JANG은 다음 세 가지 레이어 유형을 모두 올바르게 처리하는 유일한 Apple-Silicon 런타임을 제공합니다:

| 레이어 유형 | 설명 | JANG 경로 |
|---|---|---|
| SWA (Sliding-Window Attention) | 로컬 윈도우 어텐션 (local windowed attention); 저비용 고속 레이어 | `jang_tools.dsv4.mlx_model.DSV4SlidingWindow` |
| CSA (Compressor / Compressed-State Attention) | 레이어별 컴프레서 풀 (compressor pool) + 윈도우 버퍼; 전체 컨텍스트에 걸쳐 풀링된 K/V를 전달 | `DeepseekV4Cache` + `accumulate_windows` + `update_pool` |
| HSA (Hash-Sparse Attention via Indexer) | 인덱서 (indexer)가 토큰당 상위 K개의 해시 버킷을 선택; 글로벌 압축 풀에 대한 희소 어텐션 (sparse attention) | `Indexer` 모듈 + `DSV4LayerCache` 인덱서 상태 |
| mHC residuals | multi-Head-Compressed 잔차 스트림 (residual stream)이 43개 레이어의 284B 모델을 안정화함 | `mlx_model.py` 내 잔차 축(residual-axis) 수정 |
| Pool quant cache | 비례적 `trim()` 기능이 포함된 양자화된 스트리밍 KV 풀 (`llama.cpp`의 `dsv4_clear_rows`와 동일) | `DeepseekV4Cache.trim(n)` |

엔드 투 엔드 (End-to-end) 검증 완료: 1M 컨텍스트 풀 누적, 프리픽스 캐시 (prefix-cache) 재사용을 포함한 멀티턴 `/v1/chat/completions`, 듀얼 모드 추론(dual-mode reasoning), M3 Ultra @ JANGTQ2 (79.5 GB)에서 20.5 tok/s 디코딩, Swift에서 24.5 tok/s.

JangPress는 `osaurus-ai/vmlx-swift-lm`에 포함된 로드 타임 메모리 정책으로, mmap 기반의 safetensors, 정형화된 라우팅된 전문가 페이지(canonical routed-expert pages)에 대한 토큰별 라우터 인식 `MADV_DONTNEED`, 그리고 선택 사항인 prestack 오버레이를 결합합니다. 이를 통해 RAM보다 큰 라우팅된 MoE 번들을 단일 Mac에서 서비스할 수 있습니다:

| 번들 | 크기 | 호스트 RAM | 로드 후 RSS |
|---|---|---|---|
| Kimi-K2.6-Small-JANGTQ | 153 GB | 128 GB | ~0.7 GB |
| ... | | | |

Python 서빙 + 벤치마크 스크립트: `scripts/jangpress/`

전체 가이드: `docs/JANGPRESS.md`

`pip install "jang[mlx]>=2.5.18"`

시각-언어 모델 (Vision-Language models)용:

`pip install "jang[vlm]>=2.5.18"`

K-quant 4-bit (MLX와 크기는 동일하지만 더 스마트한 할당)

jang convert Qwen/Qwen3.5-35B-A3B -p 4

극한의 압축을 위한 2-bit

...

from jang_tools.loader import load_jang_model
from mlx_lm import generate
model, tokenizer = load_jang_model("JANGQ-AI/Qwen3.5-397B-A17B-JANG_1L")
...

from jang_tools.loader import load_jang_vlm_model
from mlx_vlm import generate as vlm_generate
model, processor = load_jang_vlm_model("JANGQ-AI/Qwen3.5-397B-A17B-JANG_2L")
...

`python -m jang_tools.benchmark /path/to/model --max-thinking 1024`

Smart two-pass: no-thinking first, then reasoning retry on wrong answers. Checkpointing, forced answers, full output logging.

| Model | Profile | MMLU | Size | Fits |
|---|---|---|---|---|
| Qwen3.5-397B JANG_1L | 2.1-bit | 86.5%* | 112 GB | 128 GB Mac |
| ... | 
** with reasoning mode*

| Profile | Type | Bits | Best for |
|---|---|---|---|
`JANG_4K` | K-quant | 4.0 | Same size as MLX 4-bit, smarter |
`JANG_4M` | Profile | 4.0 | 8-bit attention, 4-bit experts |
`JANG_4S` | Profile | 4.0 | Dense models (27B) |
`JANG_3K` | K-quant | 3.0 | Same size as MLX 3-bit, smarter |
`JANG_2L` | Profile | ~2.3 | Quality 2-bit, best for MoE |
`JANG_1L` | Profile | ~2.1 | Maximum quality 2-bit |

**JANG 모델은 표준 MLX safetensors입니다.** 앱이 MLX 양자화 모델을 로드하는 경우, JANG 추가는 최소한의 작업입니다.

JANG 모델 감지

from pathlib import Path
is_jang = (Path(model_path) / "jang_config.json").exists()
...

**혼합 비트 폭(Mixed bit widths)**—다른 텐서는 다른 비트를 가집니다 (어텐션은 8-bit, 전문가(experts)는 2-bit). 각 `QuantizedLinear`는 텐서 모양으로부터 `bits`와 `group_size`를 설정해야 합니다.**대규모 모델을 위한 bfloat16**—512개 이상의 전문가 모델은 float16 오버플로우를 방지하기 위해 `model.set_dtype(mx.bfloat16)`가 필요합니다.**Nemotron-H 가중치 이름 변경**—`switch_mlp.up_proj→fc1`, `down_proj→fc2`, 게이트 디양자화(gate dequantization).

전체 단계별 코드 예시는 **INTEGRATION.md**를 참조하십시오:

- jang-tools 의존성 없이 로드
- 형상(shapes)으로부터 텐서별 비트 추론 (Per-tensor bit inference)
- bfloat16 자동 감지 (auto-detection)
- Nemotron-H 특수 처리
- 사고(thinking) On/Off 기능이 포함된 채팅 템플릿 (Chat template)
- VLM 지원
- 예외 케이스 및 주의 사항 (Edge cases and gotchas)

**Qwen3.5**(hybrid SSM + MoE + VLM) — 4B, 9B, 27B, 35B, 122B, 397B
**Nemotron-H**(Mamba-2 + Latent MoE + Attention) — Cascade-2 30B, Super-120B
**MiniMax-M2.5**(256-expert MoE, FP8 source)
**DeepSeek-V2/V3**(MLA + MoE)
**Mixtral / Qwen2-MoE**(standard MoE)
**Dense Transformers**(Llama, Mistral, Gemma, Phi)
**Vision-Language**(Qwen3.5-VL, Pixtral)
**Mamba / Hybrid SSM**(Jamba, Nemotron-H)
**FP8 source models**(auto-dequantization)
Mistral Small 4**(119B MoE + MLA + Pixtral VL) — 94% MMLU, 82 tok/s, 30-84 GB

**Nemotron-H loader**: fc1/fc2 이름 변경, 게이트 가중치 역양자화 (gate weight dequantization), mtp.* 키 필터링
**bfloat16 자동 감지 (auto-detection)**: 512개 이상의 전문가(expert) 모델용 (float16 오버플로 방지)
**MLP 비대칭 하한선 (MLP asymmetry floors)**: 512개 이상의 전문가 모델에 대해 gate_proj=4-bit, down_proj=3-bit 적용
**벤치마크 스크립트 (Benchmark script)**: 추론(reasoning), 체크포인팅, 강제 답변 기능이 포함된 스마트 2패스 MMLU
**eos_token_id 자동 수정 (auto-fix)**: Qwen3.5용 (248044→248046)
**모든 .py 파일 자동 복사 (Auto-copy)**: trust_remote_code 모델용
- Nemotron-3-Super-120B: 43 GB에서 86% MMLU
- Qwen3.5-397B: 187 GB에서 92% MMLU, 112 GB에서 86.5% MMLU

- 512-expert 모델을 위한 MLP 비대칭 수정 (MLP asymmetry fix)
- Qwen3.5를 위한 eos_token_id 자동 수정 (auto-fix)
- 커스텀 .py 파일 자동 복사

- 텐서별 group_size (150개 이상의 전문가 모델의 경우 router=64, experts=128)
- 공유 전문가(shared expert)를 위한 정밀도 하한선 규칙 (Precision floor rules)
- 모든 Qwen3.5 모델에 대한 VLM 지원

JANG은 텐서 민감도(tensor sensitivity)를 기반으로 비트를 재분배합니다 — 전체 크기는 동일하지만, 더 스마트한 할당을 수행합니다:

CRITICAL (attention, MoE routers, MLA latent) → 6-8 bit → 일관성(coherence) 제어
IMPORTANT (embeddings, linear attention) → 4-6 bit → 중간 정도의 민감도
COMPRESS (MLP, MoE experts) → 2-4 bit → 파라미터의 95% 이상

MoE (Mixture-of-Experts) 모델에서 어텐션 (Attention)은 파라미터의 1~5%에 불과합니다. 이를 8-bit로 높이는 것은 약 2%의 오버헤드를 발생시키지만 품질을 극적으로 향상시킵니다. MLX는 모든 것을 동일하게 압축하며, 이것이 낮은 비트에서 MoE 모델이 깨지는 이유입니다.

**bfloat16 연산 (compute)**: 512개 이상의 전문가 (expert) 모델에 대해 자동 감지됩니다. 공유 전문가 (shared expert)의 down_proj에서 발생하는 float16 오버플로 (overflow)를 방지합니다.
**MLP 비대칭성 (asymmetry)**: gate_proj는 4-bit 하한선 (SiLU 증폭기)을 가지며, 512개 이상의 전문가 모델의 경우 down_proj는 3-bit 하한선을 가집니다.
**FP8 역양자화 (dequantization)**: FP8 소스 모델 (MiniMax, Nemotron)을 자동으로 처리합니다.
**잠재 MoE (Latent MoE)**: Nemotron-H의 fc1/fc2_latent_proj 압축을 지원합니다.
**v2 포맷**: MLX 네이티브 safetensors를 사용하여 즉각적인 mmap 로딩이 가능하며, 재포장 (repack)이 필요 없습니다.

**Python**: 3.11+
**변환 (Conversion)**: 모든 플랫폼 (numpy + safetensors)
**추론 (Inference)**: MLX를 사용하는 Apple Silicon Mac (M1/M2/M3/M4)
**의존성 (Dependencies)**:
`safetensors>=0.4`
,`numpy>=1.24`
,`tqdm>=4.60`
,`huggingface_hub>=0.20`

**선택 사항 (Optional)**:
`mlx>=0.22`
,`mlx-lm>=0.20` (추론용)
,`mlx-vlm>=0.1` (VLM용)

- GitHub | HuggingFace | MLX Studio | PyPI | 포맷 사양 (Format Spec)

**JANG**은 Apple Silicon을 위한 혼합 정밀도 (mixed-precision) 양자화 포맷입니다. MLX를 위한 GGUF입니다.

| 모델 | MMLU | 크기 | 최소 Mac |
|---|---|---|---|
| Qwen3.5-397B JANG_1L | 86.5%* | 112 GB | 128 GB |
| ... |
* 추론 모드 사용

`pip install "jang[mlx]>=2.1.5"`