Instructions to use Motif-Technologies/Motif-3-Beta with libraries, inference providers, notebooks, and local apps. Follow these links to get started.
- Libraries
- Transformers
How to use Motif-Technologies/Motif-3-Beta with Transformers:
# Use a pipeline as a high-level helper from transformers import pipeline pipe = pipeline("text-generation", model="Motif-Technologies/Motif-3-Beta", trust_remote_code=True) messages = [ {"role": "user", "content": "Who are you?"}, ] pipe(messages)# Load model directly from transformers import AutoModel model = AutoModel.from_pretrained("Motif-Technologies/Motif-3-Beta", trust_remote_code=True, device_map="auto") - Notebooks
- Google Colab
- Kaggle
- Local Apps Settings
- vLLM
How to use Motif-Technologies/Motif-3-Beta with vLLM:
Install from pip and serve model
# Install vLLM from pip: pip install vllm # Start the vLLM server: vllm serve "Motif-Technologies/Motif-3-Beta" # Call the server using curl (OpenAI-compatible API): curl -X POST "http://localhost:8000/v1/chat/completions" \ -H "Content-Type: application/json" \ --data '{ "model": "Motif-Technologies/Motif-3-Beta", "messages": [ { "role": "user", "content": "What is the capital of France?" } ] }'Use Docker
docker model run hf.co/Motif-Technologies/Motif-3-Beta
- SGLang
How to use Motif-Technologies/Motif-3-Beta with SGLang:
Install from pip and serve model
# Install SGLang from pip: pip install sglang # Start the SGLang server: python3 -m sglang.launch_server \ --model-path "Motif-Technologies/Motif-3-Beta" \ --host 0.0.0.0 \ --port 30000 # Call the server using curl (OpenAI-compatible API): curl -X POST "http://localhost:30000/v1/chat/completions" \ -H "Content-Type: application/json" \ --data '{ "model": "Motif-Technologies/Motif-3-Beta", "messages": [ { "role": "user", "content": "What is the capital of France?" } ] }'Use Docker images
docker run --gpus all \ --shm-size 32g \ -p 30000:30000 \ -v ~/.cache/huggingface:/root/.cache/huggingface \ --env "HF_TOKEN=<secret>" \ --ipc=host \ lmsysorg/sglang:latest \ python3 -m sglang.launch_server \ --model-path "Motif-Technologies/Motif-3-Beta" \ --host 0.0.0.0 \ --port 30000 # Call the server using curl (OpenAI-compatible API): curl -X POST "http://localhost:30000/v1/chat/completions" \ -H "Content-Type: application/json" \ --data '{ "model": "Motif-Technologies/Motif-3-Beta", "messages": [ { "role": "user", "content": "What is the capital of France?" } ] }' - Docker Model Runner
How to use Motif-Technologies/Motif-3-Beta with Docker Model Runner:
docker model run hf.co/Motif-Technologies/Motif-3-Beta
Bug report: shipped modeling code cannot run (3 fixable bugs) + checkpoint–code semantic mismatch (questions for the team) [KR/EN]
TL;DR (EN): The shipped modeling_motif.py cannot run as-is (3 deterministic bugs: yarn-RoPE dim mismatch crash, missing GQA repeat in the custom eager attention, and a silent grouped_mm dispatch defect that applies expert 0's PolyNorm coefficients to all 384 experts). With all three worked around, two independent implementations (patched torch + my MLX port, agreeing to KL ~1e-7/token) still produce confidently-wrong output from position 0 — while the embedding table is semantically healthy and extensive weight-statistics forensics say the tensor layouts match the code's view()/split() assumptions. I believe the remaining gap is in layer semantics (PolyNorm output scale, mHC gate factors, embedding scaling, or RoPE schedule) and would love authoritative answers from the team. Full details, measurements, and suggested fixes below (Korean). Repro scripts for every claim are ready and I'm happy to share.
안녕하세요 — Motif-3-Beta의 MLX 포팅(Apple Silicon)을 진행하며 발견한 버그 리포트와, 엔지니어링 팀 확인이 필요한 질문을 정리해 올립니다. 저는 배포된 modeling_motif.py와의 수치 패리티(4층 절단, KL ~1e-7/token)를 확보한 독립 구현을 보유하고 있어, 아래 내용은 모두 재현 스크립트와 실측 수치로 뒷받침됩니다.
1. 환경
- macOS (Apple Silicon M3 Ultra, 512GB), CUDA 없음 / Python 3.13.3 / transformers 5.12.1 / torch 2.12.1 / mlx 0.31.2
- 모델:
Motif-Technologies/Motif-3-Beta@32b0305(bf16, 155샤드)
2. 배포 코드 버그 3건 (+MLX 참고 1건) — 모두 결정론적
BUG 1 — yarn RoPE 이중 결함. (a) trust_remote_code 없이 config를 읽는 경로(AutoTokenizer 포함)가 예비 파싱에서 AttributeError: 'PreTrainedConfig' object has no attribute 'max_position_embeddings'로 크래시. (b) trust_remote_code=True여도 MotifRotaryEmbedding의 yarn 분기가 rope_head_dim=64 인자를 무시하고 config.head_dim=192 기준 inv_freq(96주파수)를 만들어 64차원 q_pe와의 곱에서 shape 크래시 — 배포된 코드로는 첫 forward가 실행되지 않습니다.
제안: yarn 분기에서 rope_head_dim 사용(또는 DeepSeek-V3 config처럼 head_dim=qk_rope_head_dim 별도 설정). 아울러 rope_scaling에 "mscale_all_dim": 1.0 누락으로 HF generic yarn이 cos/sin에 ≈1.4159를 곱하게 됩니다(DeepSeek은 두 키로 1.0 상쇄) — 의도 확인 부탁드립니다.
BUG 2 — 자체 eager_attention_forward의 GQA repeat 누락. attn_implementation="eager" 시 RuntimeError: The size of tensor a (80) must match the size of tensor b (16) (L386). 우회: "sdpa".
BUG 3 — grouped_mm 디스패치의 침묵 오답 (가장 중대). 비-ROCm 기본값 grouped_mm에서 transformers의 grouped_mm_experts_forward가 self._apply_gate(proj_out)를 expert_idx 없이 호출 → 기본값 0으로 전체 384 expert가 expert 0의 GroupedPolyNorm 계수로 활성화됩니다. 3층 절단 실측: 라우팅 동일 조건에서 MoE 출력 max|Δ|=1.58, 최종 로짓 max|Δ|=7.18, KL=0.34/token, top-1 일치 63.6%.
제안: grouped 경로에 expert id 전달(또는 configuration_motif.py의 ROCm 한정 force-eager 가드를 전 플랫폼으로 확장 — 1줄), README에 experts_implementation="eager" 명시.
BUG 4 (참고, MLX 업스트림). mx.split이 2³¹ 요소 초과 텐서(gate_up_proj 8GB)에서 4GiB 오프셋(expert 205/384)부터 조용히 잘못된 값을 반환 (ml-explore/mlx#3836, 0.31.2·0.32.0 미수정). MLX 사용자는 일반 슬라이스로 우회 필요.
3. 핵심 이슈 — 버그를 모두 우회해도 체크포인트와 코드 의미가 불일치
BUG 1-3 우회(64차원 plain rotary + sdpa + eager experts) 상태에서, 상호 KL ~1e-7로 일치하는 두 독립 구현이 동일하게:
- 위치 0(BOS 단독)에서도 top-1이 정크 토큰(id 26857)에 p=0.938 — L=1에선 softmax=1이라 위치 인코딩·q·k 전체가 무관 → 결함은 위치-무관 경로
- held-out NLL ≈ 22 nats (균등분포 ln(220160)≈12.3보다 나쁨)
- 반면 임베딩은 건강: cos(' Paris',' London')=0.263, (' king',' queen')=0.281, ('한국','서울')=0.177 (무관쌍 ~0.02)
- lm_head 최대-노름 행들이 정확히 출력을 지배하는 정크 토큰 = 최종 히든이 잡음이라는 지문
- 깊이 프로브: dense 층(0-2)은 그럴듯한 연속 → 첫 MoE 층에서 붕괴 시작, 4-wide residual RMS가 3-4층에서 ×10.9 폭발
- 레이아웃은 코드와 정합함을 자체 검증: 가중치 통계 포렌식(gate/up의 CV·왜도 시그니처, wkv_b k/v의 q_nope 부분공간 정렬, rope 주기-32 쌍 상관, group-major noise 슬롯 아웃라이어)과 64콤보 기능 탐색이 상호 확증 —
wq_b/wkv_a/wkv_b/gate_up_proj/헤드 순서 모두 코드의 view/split 가정과 일치 (대안 해석은 +5~6 nats로 강기각) - 추가 배제: 8-bit 양자화(역양자화 대조 rel ~0.008, bf16 동일), RoPE 8콤보({plain,yarn}×{half,interleaved}×{amp 1.0,1.4159}), 임베딩 입력 스케일(×8/×64),
polynorm_output_scale=0.5·h_post=σ·res 전치 단독 적용
즉 레이아웃이 아니라 레이어 수식 의미론의 차이로 좁혀졌습니다. (제 해석 오류 가능성도 열어두고 있습니다 — 그래서 아래 확인이 필요합니다.)
4. 엔지니어링 팀 확인 요청 (7개)
titan 학습 스택 기준으로:
polynorm_output_scale=0.5/polynorm_bias_clamp=0.5/hidden_clamp— 학습 시 실제 적용되나요? 적용된다면 정확한 수식/적용 지점(예:0.5 * PolyNorm(x)? gate 활성화에만? dense/shared/routed 모두?)을 알려주세요. 배포된 modeling 코드는 이 키들을 읽지 않습니다.- mHC:
h_post가2·sigmoid(...)인가요sigmoid(...)인가요? 스트림 진입은 임베딩 복제(×4)인가요, 다른 초기화인가요? 종료 축약은 mean인가요?proj_res의 4×4 행렬 방향(einsumij,jdvs 전치)과 Sinkhorn(20회, 행→열 순서)도 확인 부탁드립니다. - 임베딩 입력 스케일:
embed × sqrt(hidden)같은 곱이 있나요? (residual RMS 폭발 패턴상 스케일 체제 불일치 의심) - 라우터: sigmoid 점수 +
expert_bias(선택에만), raw 점수 gather → 합으로 정규화 → ×2.0 (route_scale) — 이 순서가 학습과 일치하나요?score_before_experts=false확인도 부탁드립니다. - RoPE: (a) 익스포트된 rope 64차원이 NeoX half-split로 순열돼 있나요, titan interleaved 원형인가요? (공개 activation 커널 저장소의 "interleaved→contiguous reorder" 관행은 확인했습니다) (b) 추론 시 yarn 보간(factor 64, β 32/1) 적용 여부 (c) cos/sin 진폭(≈1.4159)과 softmax mscale² 중 학습과 일치하는 쪽.
- softmax scale:
head_dim^-0.5 × mscale²(≈×2.005)가 학습 시에도 적용됐나요? - 가장 빠른 해결로: HF 체크포인트와 정합하는 실행 가능한 레퍼런스(수정된 modeling_motif.py, 또는 내부 vLLM 구현 —
MotifTechnologies/vllm의motif브랜치가 현재 404입니다)를 공개해 주실 수 있나요?
버그별 self-contained 재현 스크립트 4종(실제 트레이스백 포함), 깊이 프로브·임베딩 검사 스크립트, 그리고 MLX 포팅+패리티 하니스를 준비해 두었습니다 — 요청 주시면 즉시 공유하고, 답변 주시는 대로 제 MLX 포팅을 정합해 검증 결과(양자화 빌드 포함)를 커뮤니티에 공유하겠습니다. 감사합니다.
Update — independent corroboration & ablation-based localization
Since posting, I found the community FP8 quantization (0ppxnhximxr/Motif-3-Beta-FP8) independently reached the same conclusion, stated in its README warning: the base checkpoint "produces incoherent output in every configuration we tested (teacher-forced NLL ~20 vs. 2-4 expected), before any quantization is applied", and "the published modeling code and weights most likely belong to different architecture revisions." This matches my measurements (NLL ≈ 22 nats; confidently-wrong output from position 0) from two further independent implementations.
추가로 제가 그 사이 배제 완료한 항목(모두 실측):
- mHC: arXiv 2512.24880 수식과 조문 대조 — 2σ post-gate 포함 구현이 논문과 정합 (용의 제외)
- 텐서 레이아웃 전체: 가중치 통계 포렌식(gate/up의 CV·왜도 시그니처, wkv_b k/v의 q_nope 부분공간 정렬, rope 주기-32 쌍 상관, group-major noise 슬롯 아웃라이어)이 배포 코드의 view/split 가정과 일치 — 익스포트 손상이 아니라 의미론 리비전 차이라는 미러 제작자의 결론을 지지
- 임베딩 입력 스케일(×√D 류): 없음 확인 + 기능 테스트 음성
컴포넌트 절제(ablation) 매트릭스 — 리비전 델타의 위치 특정에 도움이 되길 바랍니다 (풀 모델, 20개 절제, held-out NLL 768토큰 EN/KO, 음수=개선):
| 절제 | ΔNLL (nats) |
|---|---|
| shared expert 제거 (routed만) | −9.11 — 최대 단일 레버; BOS 예측이 정상 영어 조각으로 전환 |
| route_norm 제거 (raw sigmoid ×2.0) | −6.18 |
| diff-attn 결합 제거 (λ:=0 / signal-only) | −4.8 |
| mHC h_post:=1 / h_res:=I | −3.9 / −3.5 |
| polynorm_output_scale=0.5 / bias_clamp=±0.5 적용 | −2.5 / ±0.0 (bias 전부 ±0.5 내 — 기각) |
| shared만 남기고 routed 제거 | −0.7 (여전히 붕괴) |
즉 routed 경로에는 실제 신호가 있고, shared expert의 무가중 합산(y + shared(x))과 라우팅 가중의 normalize-then-×2.0 관례가 학습 리비전과 다른 것으로 보입니다 (diff-attn 결합·mHC 게이트는 3군 기여). 가장 빠른 해결은 이 가중치와 정합하는 modeling 코드 리비전 공개(또는 재익스포트) 입니다. 재현 스크립트는 준비돼 있으니 필요하시면 말씀해 주세요.
I've also been working on this with AI to figure out how to run inference on this and hit the same roadblock. Here's where we got to (AI summary since it's doing the heavy lifting):
Follow-up: fault isolated to the shared-expert branch (evidence from systematic ablations)
We ran systematic ablations on an independent MLX port (which matches the patched reference implementation). Key results, using the depth-wise residual RMS and position-0 logits as signals:
- Zeroing only the shared expert at MoE layers: final-layer RMS drops 15.9 → 3.7, the position-0 junk token (id 26857) disappears, and generation recovers real words with loose grammar. This is the strongest single-change rescue we found.
- Zeroing the routed experts instead makes output worse (junk-token confidence rises 0.24 → 0.83) — the routed experts appear to partially compensate for the shared branch.
- Not the fix (all tested): shared-output scaling ×0.5/×0.25/×0.125 (monotonic RMS improvement but still incoherent), gate/up swap, SiLU replacement, alternate input points (unnormed read, mean-of-streams, attention input), alternate write paths (uniform/single-stream/÷4), and ±1 layer weight shift. Export forensics show no duplicated or shifted shared tensors.
This suggests the shipped modeling_motif.py composes the shared expert differently from training. Could the team share:
- The exact training-time computation of the shared expert (input point, normalization, any scaling such as polynorm_output_scale, and how its output enters the mHC streams)?
- The delta of "Modified mHC" vs. the mHC paper (arXiv 2512.24880)?
Even a short code snippet of the shared-expert + mHC composition from the training stack, or one known-good input→logits fixture, would let the community fix inference immediately.
Thank you!
Hi @avlp12 ,
Thank you for this — it's an exceptionally thorough report, and we really appreciate the time and rigor behind it.
You're right about the issues in the shipped modeling code, and we're sorry for the trouble it caused you. The team is actively working on a fix, including modeling code that is consistent with the released checkpoint. We'll post an update here as soon as we have something concrete, and we'll come back to your specific questions as well.
Thanks again for caring enough about the model to dig this deep.
Sorry for the delay in addressing the issue.
We're currently working on the bug you reported, but it may take some time to fix.
In the meantime, we've made our vLLM Docker image public so you can use the model without relying on the current modeling_motif.py implementation.
Please refer to the README for instructions on how to run the model with vLLM.
Thank you for your patience, and we'll update you as soon as the fix is ready.
Hi @avlp12 , @ahames — update from the Motif team.
We've pushed fixes to the shipped modeling code (modeling_motif.py + configuration_motif.py) for the bugs you reported — notably the RoPE inv_freq init (meta-device → identity RoPE, the position-0 collapse) and the per-expert PolyNorm dispatch (BUG 3). HF .generate now runs and produces coherent output. For production/high-throughput serving, vLLM stays recommended.
Sorry for the trouble, and thank you for the exceptional, rigorous reports — they made this much faster to pin down. 🙏
A note on the mHC post-gate: our implementation uses a sigmoid gate (coefficient 1.0), not the 2·sigmoid in the paper (arXiv 2512.24880).
This is intentional — a deliberate design choice, not an export/versioning artifact. We'll document the reasoning behind it in our upcoming tech report.
Confirmed: the fix works, and it resolves the MLX port too — thank you @dongseokmotif @iamwyldecat ! 🎉
I pulled the updated modeling_motif.py (SHA d2c9ac6) and diffed it. The decisive change for the incoherence was the PolyNorm activation, not RoPE: the shipped GroupedPolyNorm/PolyNormTorch now (a) pass the 3 coefficients through sigmoid(weight) (sigmoid_weight=True), (b) apply output_scale=0.5 (polynorm_output_scale), and (c) clamp the routed bias to ±0.5 (polynorm_bias_clamp) — exactly the config keys that were present-but-unread before. Since PolyNorm runs on every token at every layer and the experts are 97.84% of params, raw-vs-sigmoid coefficients is a position-independent, dominant divergence (which is why I saw garbage even at position 0, and why my earlier ablation only dampened rather than fixed it).
I applied the same three changes to my independent MLX port and, on the existing checkpoint (no re-export needed on my side — it's a runtime-activation change), held-out NLL dropped from ~23 → ~2.1 nats, and generation is now fluent in both languages:
"The capital of France is"→" Paris. True or False? ...""대한민국의 수도는"→" 서울입니다. 서울은 대한민국의 수도로서 정치, 경제, 사회, 문화 …""Once upon a time"→", there was a young girl named Lily who lived in a small village. …"
The per-layer RoPE (YaRN on full-attention layers, plain swa_rope_theta on SWA layers) is a smaller refinement on top (≈neutral at short context, minor KO gain), and I've matched that too. This unblocks my MLX quantization work — I'll follow up with the quantized builds. Really appreciate the fast, precise fix and the vLLM image in the meantime. 🙏
Thanks for the mHC clarification, @dongseokmotif — that's really helpful. I see it in the fixed code: mhc_h_post_coeff = 1.0 + mhc_h_post_alpha_end, which is 1.0 for Motif‑3 (alpha_end absent → 0), so the post‑gate is a plain sigmoid, not the paper's 2·sigmoid. I'll match 1.0 in my port for exact parity, and I'll watch for the reasoning in the tech report.
One data point that might be useful for you and for others reading this thread, in case it helps triage similar reports: on my independent MLX port, the PolyNorm activation (sigmoid(weight) coefficients + output_scale=0.5 + routed bias_clamp=±0.5) was by far the dominant term for the incoherence — applying just that, on the unmodified checkpoint, took held‑out NLL from ~23 → ~2.1 and produced fluent output at position 0 onward. The per‑layer RoPE (YaRN on full‑attention layers, plain swa_rope_theta on SWA layers, layer_idx % period for the SWA assignment) and the mHC h_post coefficient were both ≈neutral refinements on top of that (each < ~0.1 nat at short context in my tests). So for anyone porting from the checkpoint, PolyNorm is the load‑bearing fix. Thanks again for the fast turnaround and for surfacing the mHC design intent. 🙏
Thanks, @avlp12 — exactly right. The shipped PolyNorm used the raw coefficients (weight[i] * …) and was missing the sigmoid on them; adding sigmoid(weight) (together with output_scale=0.5 and the bias_clamp) is the load-bearing fix, which is why it moved your NLL the most.
Thanks again for the numbers. 🙏
Thank you + MLX builds are up 🙏 (Apple Silicon)
First, a sincere thank-you to the Motif team (@dongseokmotif , @iamwyldecat ) — this would not have been possible without your remarkably fast turnaround on the modeling-code fixes (SHA d2c9ac6) and the mHC design clarification in discussion #6. Once the reference matched the checkpoint, my independent MLX port fell straight into place (KL ≈1e-7/token vs the fixed reference). The speed of your fix is the only reason these builds exist today — so I wanted to share them back with the community as a thank-you.
세 줄 요약 (KR): 팀의 빠른 modeling 코드 수정 덕분에 Motif-3-Beta를 Apple Silicon용 MLX로 포팅·양자화했습니다. 수정 레퍼런스와 수치 일치(KL ≈1e-7)를 확인했고, 세 체급으로 공개합니다. 한국어·영어·코드 생성 모두 유창합니다.
MLX builds (avlp12, non-commercial research — base license carried forward)
| Build | bpw | Size | Best for | Repo |
|---|---|---|---|---|
| 8-bit | 8.50 | 312 GB | 512 GB Mac / reference | avlp12/Motif-3-Beta-Alis-MLX-8bit |
| Dynamic 4.5bpw | 4.55 | 167 GB | 256–512 GB Mac (golden daily) | avlp12/Motif-3-Beta-Alis-MLX-Dynamic-4.5bpw |
| Dynamic 2.3bpw | 2.31 | 85 GB | 128 GB Mac (floor) | avlp12/Motif-3-Beta-Alis-MLX-Dynamic-2.3bpw |
Collection: https://huggingface.co/collections/avlp12/motif-3-beta-alis-mlx-apple-silicon-6a60e77168abddcfb5f8c2d8
Run it:
pip install git+https://github.com/avlp12/mlx-lm.git@motif
mlx_lm.generate --model avlp12/Motif-3-Beta-Alis-MLX-Dynamic-2.3bpw \
--prompt "대한민국의 수도와 특징을 알려줘." --temp 1.0 --top-p 0.95
(The Motif model class isn't in upstream mlx-lm yet — the @motif fork branch adds it; an upstream PR is planned.)
How they were made
Mixed-bit affine quantization + clip-search + layerwise DWQ distillation (4.5bpw teacher, 45% Korean calibration) via the alis-dwq pipeline. The 2.3bpw floor: raw quant → clip (fixes greedy degeneration) → DWQ (cuts KL 58–72% vs the 8-bit reference). Eval + build-ladder charts are on each model card.
Honest notes
- Non-commercial research license (carried forward from the base model). Please respect it.
- These are quantizations of the Beta checkpoint; I'll re-quantize when the final release lands.
- Very-long-tail factual recall can be weak at 2.3bpw (a base-model property, not a quant artifact).
- One MLX-core bug (
mx.split>2³¹-element silent corruption, ml-explore/mlx#3836) is worked around in the port.
Thanks again for building a genuinely strong Korean-capable open model — and for the fast, precise fixes that made this port possible. Happy to answer any questions about the MLX side. 🙏
This is fantastic, @avlp12 — thank you. Bringing Motif-3 to Apple Silicon with this much care is a genuine gift to the community.
The kind words mean a lot, but the credit really runs the other way: your report is what made the fix fast and precise in the first place. We're really glad it enabled this.
You can re-quantize when the final checkpoint lands. Thanks again for building these, sharing them back with the community. 🙏
Thank you @dongseokmotif - I was also able to make progress and successfully run inference on this now. Thank you and your team for the quick turnaround!