skills.rest
shakfu
shakfuCOMMUNITY
Explore all skills by this author →
GitHub

import-model

Ports Hugging Face model architectures into MAX with scaffold, implementation, and verification phases.

Updated Sep 15, 2026
Search Tags:#verification#llm#max#hugging face#model porting#graph implementation#weight adapters
One-click install
npx skills add https://github.com/shakfu/mdsp --skill import-model-shakfu
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: import-model
Source: https://github.com/shakfu/mdsp/tree/main/.claude/skills/import-model
Command: npx skills add https://github.com/shakfu/mdsp --skill import-model-shakfu

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires huggingface_hub, safetensors, transformers, torch, max, accelerate, and includes scripts (resource) and references (resource) components.

What problem does it solve? Bringing a new large language model architecture into MAX requires manually translating Hugging Face modeling code into a MAX graph, mapping checkpoint weights, and verifying numerical parity — a process where silent errors (wrong RoPE style, stale donor docstrings, mismatched weight names) produce garbage output with no error message. ## Core Features & Use Cases - Three-phase guided workflow: decide & plan (inspect config.json, pick a donor architecture, build a delta list), implement (scaffold files, wire config, write weight adapters, edit the graph), then verify (serve, compare logits against the Hugging Face reference). - Helper scripts: inspect_hf.py, check_walls.py, list_checkpoint_keys.py, list_native_archs.py, scaffold.py, run_oss_gates.py, and compare_layers.py automate config inspection, blocker detection, checkpoint metadata listing, and HF-vs-MAX logit comparison. - Divergence troubleshooting: a symptom-indexed catalog of common porting bugs (RoPE style, GQA repeat_kv, tied embeddings, norm order, MuP scalars) plus a handoff path to the debug-model skill for layer-by-layer divergence hunts. - Use Case: Given a Hugging Face model ID like Qwen/Qwen3-8B, the agent inspects its config, scaffolds from the closest MAX architecture, implements each structural delta, and verifies greedy output matches the HF reference. ## Quick Start Ask the agent to import a Hugging Face model into MAX by providing the model ID, for example: import Qwen/Qwen3-8B into MAX.

Frequently Asked Questions about import-model

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I import a Hugging Face model into MAX?▼

Provide the Hugging Face model ID and follow the three-phase workflow: inspect the config and pick a donor architecture, scaffold and implement the graph deltas, then serve and verify logits against the HF reference. Helper scripts like inspect_hf.py and scaffold.py automate each step.

How do I choose a donor architecture when porting a model to MAX?▼

Match attention shape (dense, GQA, MLA, MoE), MLP shape, and head layout to the closest registered MAX architecture, listed via list_native_archs.py. Llama-like models start from llama3, Qwen-like from qwen2/qwen3, and MLA models from deepseekV3.

Why does my ported MAX model output gibberish after serving?▼

Gibberish usually means the scaffolded donor graph was served without implementing the delta list, or a silent bug like wrong RoPE style, missing GQA repeat_kv, or mismatched Q/K/V weight names. Run compare_layers.py, then switch to the debug-model skill for a layer-by-layer divergence hunt.

What are the requirements for running the MAX model import workflow?▼

You need a pixi environment with MAX installed, network access to the Hugging Face Hub, and a GPU for serving and verification. All commands run through pixi (pixi run python, pixi run max serve) from the skill root.

Which model architectures cannot be ported to MAX with this workflow?▼

Models with ALiBi position embeddings, SSM or recurrent layers (Mamba, RWKV), FP8/FP4-only released weights, or custom CUDA kernels with no public reference may be blocked. The check_walls.py script scans config.json and exits with code 2 when a hard blocker is found.

How do I verify a ported model matches the Hugging Face reference?▼

Serve the model with max serve and compare greedy token output and top-1 logprobs against HF using compare_layers.py. Validation depth ranges from tier 1 smoke tests to tier 6 full logit parity, chosen during the planning phase.

Related Skills

Explore More Software Engineering Skills→
RachasumanthRachasumanth

model-publisher

Package trained AI models and publish them to Hugging Face Hub.

Community
Advanced
flagos-aiflagos-ai
18

model-verify-flagos

Diff base and multi-chip serving runs to locate failing layers.

Official
Advanced
saintgo7saintgo7

gem-llm-vllm-debug

Diagnose vLLM startup and runtime failures with validated dependency and launch configurations.

Community
Advanced
UniClipboardUniClipboard
1.6k

gen-changelog

Generate bilingual release changelogs from Git commit history.

Official
Intermediate