convert: add @ModelBase.example

conversion/afmoe.py

@@ -13,6 +13,7 @@
 
 
 @ModelBase.register("AfmoeForCausalLM")
+@ModelBase.example("arcee-ai/Trinity-Large-Thinking")
 class AfmoeModel(LlamaModel):
     model_arch = gguf.MODEL_ARCH.AFMOE
 

conversion/arctic.py

@@ -16,6 +16,7 @@
 
 
 @ModelBase.register("ArcticForCausalLM")
+@ModelBase.example("Snowflake/snowflake-arctic-instruct")
 class ArcticModel(TextModel):
     model_arch = gguf.MODEL_ARCH.ARCTIC
 

conversion/baichuan.py

@@ -9,6 +9,7 @@
 
 
 @ModelBase.register("BaichuanForCausalLM", "BaiChuanForCausalLM")
+@ModelBase.example("baichuan-inc/Baichuan2-7B-Chat", "baichuan-inc/Baichuan-7B")
 class BaichuanModel(TextModel):
     model_arch = gguf.MODEL_ARCH.BAICHUAN
 

conversion/bailingmoe.py

@@ -11,6 +11,7 @@
 
 
 @ModelBase.register("BailingMoeForCausalLM")
+@ModelBase.example("inclusionAI/Ling-lite")
 class BailingMoeModel(TextModel):
     model_arch = gguf.MODEL_ARCH.BAILINGMOE
 
@@ -108,6 +109,7 @@ def prepare_tensors(self):
 
 
 @ModelBase.register("BailingMoeV2ForCausalLM")
+@ModelBase.example("inclusionAI/Ling-mini-2.0")
 class BailingMoeV2Model(TextModel):
     model_arch = gguf.MODEL_ARCH.BAILINGMOE2
 
@@ -189,6 +191,7 @@ def prepare_tensors(self):
 
 
 @ModelBase.register("SarvamMoEForCausalLM", "modeling_sarvam_moe.SarvamMoEForCausalLM")
+@ModelBase.example("sarvamai/sarvam-30b")
 class SarvamMoEModel(BailingMoeV2Model):
     model_arch = gguf.MODEL_ARCH.BAILINGMOE2
     # Sarvam-MoE shares the BailingMoeV2 architecture; only differences:

conversion/bailingmoe3.py

@@ -13,6 +13,7 @@
 
 
 @ModelBase.register("BailingMoeV3ForCausalLM")
+@ModelBase.example("inclusionAI/Ling-3.0-tiny", "inclusionAI/Ling-3.0-flash")
 class BailingMoeV3Model(TextModel):
     model_arch = gguf.MODEL_ARCH.BAILINGMOE3
     supports_mtp_export = True

conversion/base.py

@@ -1149,6 +1149,14 @@
             return modelcls
         return func
 
+    @classmethod
+    def example(cls, *hf_repos: str) -> Callable[[AnyModel], AnyModel]:
+        del hf_repos  # unused
+
+        def func(modelcls: AnyModel) -> AnyModel:
+            return modelcls
+        return func
+
     @classmethod
     def print_registered_models(cls):
         for model_type, model_classes in cls._model_classes.items():
@@ -1410,15 +1418,15 @@
 
         from transformers import AutoTokenizer
         tokenizer = AutoTokenizer.from_pretrained(self.dir_model)
         vocab_size = self.hparams.get("vocab_size", len(tokenizer.vocab))  # ty: ignore[unresolved-attribute]
         assert max(tokenizer.vocab.values()) < vocab_size  # ty: ignore[unresolved-attribute]
 
         tokpre = self.get_vocab_base_pre(tokenizer)
 
         reverse_vocab = {id_: encoded_tok for encoded_tok, id_ in tokenizer.vocab.items()}  # ty: ignore[unresolved-attribute]
         added_vocab = tokenizer.get_added_vocab()  # ty: ignore[unresolved-attribute]
 
         added_tokens_decoder = tokenizer.added_tokens_decoder  # ty: ignore[unresolved-attribute]
 
         for i in range(vocab_size):
             if i not in reverse_vocab:
@@ -1431,7 +1439,7 @@
                     # To avoid unexpected issues - we make sure to normalize non-normalized tokens
                     if not added_tokens_decoder[i].normalized:
                         previous_token = token
                         token = tokenizer.decode(tokenizer.encode(token, add_special_tokens=False))  # ty: ignore[unresolved-attribute, invalid-assignment]
                         if previous_token != token:
                             logger.info(f"{repr(previous_token)} is encoded and decoded back to {repr(token)} using AutoTokenizer")
 
@@ -1798,14 +1806,14 @@
     def _set_vocab_hybriddna(self):
         from transformers import AutoTokenizer
         tokenizer = AutoTokenizer.from_pretrained(self.dir_model, trust_remote_code=True)
         vocab_size = self.hparams.get("vocab_size", len(tokenizer.vocab))  # ty: ignore[unresolved-attribute]
         assert max(tokenizer.vocab.values()) < vocab_size  # ty: ignore[unresolved-attribute]
 
         reverse_vocab = {id_: encoded_tok for encoded_tok, id_ in tokenizer.vocab.items()}  # ty: ignore[unresolved-attribute]
         # k-mers can share text with a base-vocab BPE token (e.g. CCCCCC) and get
         # dropped by get_vocab(); a reserved marker suffix (U+E000) keeps each
         # k-mer's own id (llama.cpp strips it on detokenization)
         for kmer in tokenizer.kmers:  # ty: ignore[unresolved-attribute]
             reverse_vocab[tokenizer.dna_token_to_id[kmer]] = kmer + "\ue000"  # ty: ignore[unresolved-attribute]
         added_vocab = tokenizer.get_added_vocab()  # ty: ignore[unresolved-attribute]
         added_tokens_decoder = tokenizer.added_tokens_decoder  # ty: ignore[unresolved-attribute]

conversion/bert.py

@@ -15,6 +15,7 @@
 
 
 @ModelBase.register("BertModel", "BertForMaskedLM", "CamembertModel", "BertForSequenceClassification")
+@ModelBase.example("BAAI/bge-small-en-v1.5", "dangvantuan/sentence-camembert-base")
 class BertModel(TextModel):
     model_arch = gguf.MODEL_ARCH.BERT
 
@@ -240,6 +241,7 @@ def _xlmroberta_set_vocab(self) -> None:
 
 
 @ModelBase.register("DistilBertModel", "DistilBertForMaskedLM", "DistilBertForSequenceClassification")
+@ModelBase.example("distilbert/distilbert-base-uncased")
 class DistilBertModel(BertModel):
     model_arch = gguf.MODEL_ARCH.BERT
 
@@ -263,6 +265,7 @@ def filter_tensors(cls, item: tuple[str, Callable[[], Tensor]]) -> tuple[str, Ca
 
 
 @ModelBase.register("RobertaModel", "RobertaForSequenceClassification")
+@ModelBase.example("sentence-transformers/stsb-roberta-base")
 class RobertaModel(BertModel):
     model_arch = gguf.MODEL_ARCH.BERT
 
@@ -312,6 +315,7 @@ def modify_tensors(self, data_torch: Tensor, name: str, bid: int | None) -> Iter
 
 
 @ModelBase.register("NomicBertModel")
+@ModelBase.example("nomic-ai/nomic-embed-text-v1.5")
 class NomicBertModel(BertModel):
     model_arch = gguf.MODEL_ARCH.BERT
 
@@ -400,6 +404,7 @@ def _is_tokenizer_xlmroberta(self) -> bool:
 
 
 @ModelBase.register("NeoBERT", "NeoBERTLMHead", "NeoBERTForSequenceClassification")
+@ModelBase.example("chandar-lab/NeoBERT")
 class NeoBert(BertModel):
     model_arch = gguf.MODEL_ARCH.NEO_BERT
 
@@ -431,6 +436,7 @@ def filter_tensors(cls, item: tuple[str, Callable[[], Tensor]]) -> tuple[str, Ca
 
 
 @ModelBase.register("EuroBertModel", "JinaEmbeddingsV5Model")
+@ModelBase.example("hf-tiny-v2/tiny-random-EuroBertModel", "jinaai/jina-embeddings-v5-text-nano")
 class EuroBertModel(TextModel):
     model_arch = gguf.MODEL_ARCH.EUROBERT
 
@@ -459,6 +465,7 @@ def filter_tensors(cls, item: tuple[str, Callable[[], Tensor]]) -> tuple[str, Ca
 
 
 @ModelBase.register("XLMRobertaModel", "XLMRobertaForSequenceClassification")
+@ModelBase.example("BAAI/bge-m3")
 class XLMRobertaModel(BertModel):
     model_arch = gguf.MODEL_ARCH.BERT
     _lora_files = {}
@@ -561,6 +568,7 @@ def write(self):
 
 
 @ModelBase.register("JinaBertModel", "JinaBertForMaskedLM")
+@ModelBase.example("jinaai/jina-embeddings-v2-base-en")
 class JinaBertV2Model(BertModel):
     model_arch = gguf.MODEL_ARCH.JINA_BERT_V2
 
@@ -588,6 +596,7 @@ def set_vocab(self):
 
 
 @ModelBase.register("ModernBertModel", "ModernBertForMaskedLM", "ModernBertForSequenceClassification")
+@ModelBase.example("answerdotai/ModernBERT-base")
 class ModernBertModel(BertModel):
     model_arch = gguf.MODEL_ARCH.MODERN_BERT
 

conversion/bitnet.py

@@ -9,6 +9,7 @@
 
 
 @ModelBase.register("BitnetForCausalLM", "BitNetForCausalLM")
+@ModelBase.example("microsoft/bitnet-b1.58-2B-4T")
 class BitnetModel(TextModel):
     model_arch = gguf.MODEL_ARCH.BITNET
 

conversion/bloom.py

@@ -13,6 +13,7 @@
 
 
 @ModelBase.register("BloomForCausalLM", "BloomModel")
+@ModelBase.example("bigscience/bloom-560m")
 class BloomModel(TextModel):
     model_arch = gguf.MODEL_ARCH.BLOOM
 

conversion/chameleon.py

@@ -12,6 +12,8 @@
 
 @ModelBase.register("ChameleonForConditionalGeneration")
 @ModelBase.register("ChameleonForCausalLM")  # obsolete
+# [TAG_HF_EXAMPLE_GATED] facebook/chameleon-7b is gated
+# [TAG_HF_EXAMPLE_MISSING]
 class ChameleonModel(TextModel):
     model_arch = gguf.MODEL_ARCH.CHAMELEON
 

conversion/chatglm.py

@@ -9,6 +9,7 @@
 
 
 @ModelBase.register("GlmForCausalLM", "ChatGLMModel", "ChatGLMForConditionalGeneration")
+@ModelBase.example("THUDM/chatglm3-6b", "zai-org/glm-4-9b-chat-hf")
 class ChatGLMModel(TextModel):
     model_arch = gguf.MODEL_ARCH.CHATGLM
 

conversion/codeshell.py

@@ -4,6 +4,7 @@
 
 
 @ModelBase.register("CodeShellForCausalLM")
+@ModelBase.example("WisdomShell/CodeShell-7B")
 class CodeShellModel(TextModel):
     model_arch = gguf.MODEL_ARCH.CODESHELL
 

conversion/cogvlm.py

@@ -11,6 +11,7 @@
 
 
 @ModelBase.register("CogVLMForCausalLM")
+@ModelBase.example("THUDM/cogvlm2-llama3-chat-19B", "THUDM/cogvlm-chat-hf")
 class CogVLMVisionModel(MmprojModel):
 
     def set_gguf_parameters(self):
@@ -29,5 +30,6 @@ def filter_tensors(cls, item: tuple[str, Callable[[], Tensor]]) -> tuple[str, Ca
 
 
 @ModelBase.register("CogVLMForCausalLM")
+@ModelBase.example("THUDM/cogvlm2-llama3-chat-19B", "THUDM/cogvlm-chat-hf")
 class CogVLMModel(LlamaModel):
     model_arch = gguf.MODEL_ARCH.COGVLM

conversion/command_r.py

@@ -12,6 +12,8 @@
 
 
 @ModelBase.register("CohereForCausalLM")
+# [TAG_HF_EXAMPLE_GATED] CohereLabs/c4ai-command-r-v01 is gated
+# [TAG_HF_EXAMPLE_MISSING]
 class CommandR2Model(TextModel):
     model_arch = gguf.MODEL_ARCH.COMMAND_R
 
@@ -30,6 +32,8 @@ def set_gguf_parameters(self):
 
 
 @ModelBase.register("Cohere2ForCausalLM")
+# [TAG_HF_EXAMPLE_GATED] CohereLabs/c4ai-command-r7b-12-2024 is gated
+@ModelBase.example("hf-tiny-v2/tiny-random-Cohere2ForCausalLM")
 class Cohere2Model(TextModel):
     model_arch = gguf.MODEL_ARCH.COHERE2
 
@@ -59,6 +63,7 @@ def modify_tensors(self, data_torch: Tensor, name: str, bid: int | None) -> Iter
 
 
 @ModelBase.register("Cohere2MoeForCausalLM")
+@ModelBase.example("CohereLabs/North-Mini-Code-1.0")
 class Cohere2MoeModel(TextModel):
     model_arch = gguf.MODEL_ARCH.COHERE2MOE
     _n_main_layers: int | None = None

conversion/dbrx.py

@@ -9,6 +9,7 @@
 
 
 @ModelBase.register("DbrxForCausalLM")
+@ModelBase.example("alpindale/dbrx-instruct")
 class DbrxModel(TextModel):
     model_arch = gguf.MODEL_ARCH.DBRX
 

conversion/deci.py

@@ -13,6 +13,7 @@
 
 
 @ModelBase.register("DeciLMForCausalLM")
+@ModelBase.example("nvidia/Llama-3_1-Nemotron-51B-Instruct", "Deci/DeciLM-7B")
 class DeciModel(TextModel):
     model_arch = gguf.MODEL_ARCH.DECI
 

conversion/deepseek.py

@@ -18,6 +18,7 @@
 
 
 @ModelBase.register("DeepseekOCRForCausalLM")
+@ModelBase.example("deepseek-ai/DeepSeek-OCR")
 class DeepseekOCRVisionModel(MmprojModel):
     # HF dynamic_preprocess() max_num, which differs per model
     preproc_max_tiles = 9
@@ -100,11 +101,13 @@ def filter_tensors(cls, item: tuple[str, Callable[[], Tensor]]) -> tuple[str, Ca
 
 
 @ModelBase.register("UnlimitedOCRForCausalLM")
+@ModelBase.example("baidu/Unlimited-OCR")
 class UnlimitedOCRVisionModel(DeepseekOCRVisionModel):
     preproc_max_tiles = 32
 
 
 @ModelBase.register("DeepseekOCR2ForCausalLM")
+@ModelBase.example("deepseek-ai/DeepSeek-OCR-2")
 class DeepseekOCR2VisionModel(DeepseekOCRVisionModel):
     preproc_max_tiles = 6
 
@@ -134,6 +137,7 @@ def get_vision_config(self) -> dict[str, Any]:
 
 
 @ModelBase.register("DeepseekForCausalLM")
+@ModelBase.example("deepseek-ai/deepseek-moe-16b-chat")
 class DeepseekModel(TextModel):
     model_arch = gguf.MODEL_ARCH.DEEPSEEK
 
@@ -228,6 +232,7 @@ def prepare_tensors(self):
     "YoutuForCausalLM",
     "YoutuVLForConditionalGeneration",
 )
+@ModelBase.example("deepseek-ai/DeepSeek-V2-Lite", "deepseek-ai/DeepSeek-V3")
 class DeepseekV2Model(TextModel):
     model_arch = gguf.MODEL_ARCH.DEEPSEEK2
 
@@ -457,6 +462,7 @@ def prepare_tensors(self):
 
 
 @ModelBase.register("DeepseekV32ForCausalLM")
+@ModelBase.example("deepseek-ai/DeepSeek-V3.2-Exp")
 class DeepseekV32Model(DeepseekV2Model):
     model_arch = gguf.MODEL_ARCH.DEEPSEEK32
     skip_mtp = False
@@ -517,6 +523,7 @@ def set_gguf_parameters(self):
 
 
 @ModelBase.register("DeepseekV4ForCausalLM")
+@ModelBase.example("deepseek-ai/DeepSeek-V4-Flash-Base")
 class DeepseekV4Model(TextModel):
     model_arch = gguf.MODEL_ARCH.DEEPSEEK4
     supports_mtp_export = True
@@ -911,6 +918,7 @@ def prepare_tensors(self):
 
 
 @ModelBase.register("DeepseekV4DSparkModel")
+@ModelBase.example("deepseek-ai/DeepSeek-V4-Flash-DSpark")
 class DeepseekV4DSparkModel(DeepseekV4Model):
     model_arch = gguf.MODEL_ARCH.DFLASH
 

conversion/dots1.py

@@ -11,6 +11,7 @@
 
 
 @ModelBase.register("Dots1ForCausalLM")
+@ModelBase.example("rednote-hilab/dots.llm1.inst")
 class Dots1Model(Qwen2MoeModel):
     model_arch = gguf.MODEL_ARCH.DOTS1
 

conversion/dotsocr.py

@@ -9,6 +9,7 @@
 
 
 @ModelBase.register("DotsOCRForCausalLM")
+@ModelBase.example("rednote-hilab/dots.ocr")
 class DotsOCRVisionModel(MmprojModel):
     def __init__(self, *args, **kwargs):
         super().__init__(*args, **kwargs)

conversion/dream.py

@@ -9,6 +9,7 @@
 
 
 @ModelBase.register("DreamModel")
+@ModelBase.example("Dream-org/Dream-v0-Instruct-7B")
 class DreamModel(TextModel):
     model_arch = gguf.MODEL_ARCH.DREAM
 

conversion/ernie.py

@@ -15,6 +15,7 @@
 
 
 @ModelBase.register("Ernie4_5_ForCausalLM", "Ernie4_5ForCausalLM")
+@ModelBase.example("baidu/ERNIE-4.5-0.3B-PT")
 class Ernie4_5Model(TextModel):
     model_arch = gguf.MODEL_ARCH.ERNIE4_5
 
@@ -73,6 +74,7 @@ def modify_tensors(self, data_torch: Tensor, name: str, bid: int | None) -> Iter
 
 
 @ModelBase.register("Ernie4_5_MoeForCausalLM")
+@ModelBase.example("baidu/ERNIE-4.5-21B-A3B-PT")
 class Ernie4_5MoeModel(Ernie4_5Model):
     model_arch = gguf.MODEL_ARCH.ERNIE4_5_MOE
     _experts: list[dict[str, Tensor]] | None = None
@@ -156,11 +158,13 @@ def prepare_tensors(self):
 
 
 @ModelBase.register("PaddleOCRVLForConditionalGeneration")
+@ModelBase.example("PaddlePaddle/PaddleOCR-VL")
 class PaddleOCRModel(Ernie4_5Model):
     model_arch = gguf.MODEL_ARCH.PADDLEOCR
 
 
 @ModelBase.register("PaddleOCRVisionModel")
+@ModelBase.example("PaddlePaddle/PaddleOCR-VL")
 class PaddleOCRVisionModel(MmprojModel):
     # PaddleOCR-VL uses a modified version of Siglip
     min_pixels: int = 0

conversion/exaone.py

@@ -15,6 +15,7 @@
 
 
 @ModelBase.register("ExaoneForCausalLM")
+@ModelBase.example("LGAI-EXAONE/EXAONE-3.5-2.4B-Instruct")
 class ExaoneModel(TextModel):
     model_arch = gguf.MODEL_ARCH.EXAONE
 
@@ -60,6 +61,7 @@ def generate_extra_tensors(self) -> Iterable[tuple[str, Tensor]]:
 
 
 @ModelBase.register("Exaone4ForCausalLM")
+@ModelBase.example("LGAI-EXAONE/EXAONE-4.0-32B")
 class Exaone4Model(TextModel):
     model_arch = gguf.MODEL_ARCH.EXAONE4
 
@@ -126,6 +128,7 @@ def generate_extra_tensors(self) -> Iterable[tuple[str, Tensor]]:
 # note: transformers >= 5.1 renamed the class to "ExaoneMoeForCausalLM" (lowercase 'e'),
 #       so accept both spellings - LG AI have updated the configs of already-released models
 @ModelBase.register("ExaoneMoEForCausalLM", "ExaoneMoeForCausalLM")
+@ModelBase.example("LGAI-EXAONE/K-EXAONE-236B-A23B")
 class ExaoneMoEModel(Exaone4Model):
     model_arch = gguf.MODEL_ARCH.EXAONE_MOE
 
@@ -214,6 +217,7 @@ def prepare_tensors(self):
 
 
 @ModelBase.register("Exaone4_5_ForConditionalGeneration")
+@ModelBase.example("LGAI-EXAONE/EXAONE-4.5-33B")
 class Exaone4_5_TextModel(Exaone4Model):
     """Text tower of EXAONE 4.5; Tensors match EXAONE4"""
 
@@ -267,6 +271,7 @@ def modify_tensors(self, data_torch: Tensor, name: str, bid: int | None) -> Iter
 
 
 @ModelBase.register("Exaone4_5_ForConditionalGeneration")
+@ModelBase.example("LGAI-EXAONE/EXAONE-4.5-33B")
 class Exaone4_5VisionModel(Qwen2VLVisionModel):
     """Vision tower for EXAONE 4.5; Qwen2-VL-style ViT (GQA) + patch merger"""