6 Common Pitfalls in Sharing Models on Hugging Face - FriendliAI

# 6 Common Pitfalls in Sharing Models on Hugging Face ... In this post, we share key insights we’ve gained through hands-on work with customers uploading **Transformer** models to Hugging Face. From fine-tuned LLMs to quantized adapters and custom pipelines, we’ve seen the common pitfalls developers run into—and how to fix them. These tips come from real-world experience and will help you make your models not just functional, but easy to find and use. Uploading your model with the right metadata and documentation isn’t just a nice-to-have—it directly influences how easily models can be found. Even a great model can be overlooked if it lacks proper tags, templates, or a clear model card. In contrast, a well-documented model is more likely to be featured, appear in search and filters, and even trend on the Hugging Face Hub. … ##### ### 1. Intended Use & Limitations 🎯 What to include: - Primary use cases for the model. - Who the intended users are (e.g., developers, researchers, end-users). - Known limitations or failure cases. - Recommended and discouraged uses. Best Practices: - Use a table or bulleted list to distinguish “Appropriate Uses” vs. “Out-of-Scope Uses.” - Add real-world examples and potential misuse cases. - Be honest about limitations—this increases trust and encourages responsible usage. … ### 7. YAML Front Matter (Metadata) 🤖 YAML Front Matter is metadata located on top of `README.md` file that contains important tags. These tags significantly boost visibility by enabling auto-detection and filtering on the Hugging Face Hub. What to Include: - Metadata tags used for auto-discovery and categorization. Best Practices: - Follow Hugging Face's official model card guide for supported tags. - Be sure to include tags like `pipeline_tag`, `library_name`, and `license`. … ### 1. Missing chat_template.jinja File or chat_template Field **Why it matters:** Hugging Face’s chat interface relies on a chat template to format inputs. Without it, your chat model may not work as expected. **Fix:** - Include a `chat_template.jinja` file in your repo. - For legacy support, add `chat_template` field to `tokenizer_config.json`. ### 2. Missing or Incorrect eos_token **Why it matters:** The `eos_token` controls when generation stops. If undefined, models can encounter runtime failures, producing infinite output or failing silently. **Fix:** Define `eos_token` in config.json (and optionally in tokenizer_config.json and generation_config.json). ### 3. Missing pipeline_tag or library_name **Why it matters:** These fields enable the “Use this model” button, inference widgets, and filtering on the Hugging Face Hub. **Fix:** Add them to the YAML front matter in your model card yaml … ### 5. Not setting base_model_relation **Why it matters:** While Hugging Face tries to infer relationships (e.g., fine-tuned, quantized), being explicit helps avoid misclassification. **Recommended:** Declare it in your metadata: yaml … Allowed relations include: `finetune`, `quantized`, `adapter`, and `merge`. ### TL;DR |Pitfall|Why It Matters|Fix| |--|--|--| |` chat_template `|Chat UI and inference may break|Add ` chat_template.jinja ` file| |` eos_token `|Infinite or malformed outputs|Define in ` config.json `| |` pipeline_tag `|Missing inference widget and filters|Add to model card metadata| |` library_name `|UI and filtering issues|Add to model card metadata| |` base_model `|Loss of model lineage|Add to metadata for traceability| |` base_model_relation `|Misclassified model relationship|Set explicitly in metadata| … 💡 Tip: **Deploy your Hugging Face models with one click** to scalable, efficient endpoints ready for real production.