Hugging Face's logo

VoltageVagabond
/
spam-classifier-liquid

Text Classification
PEFT
Safetensors
spam-detection
liquid-ai
lora
gradio
nlp
Model card Files
xet
spam-classifier-liquid / docs /references /how-to.html
VoltageVagabond's picture
VoltageVagabond
Upload folder using huggingface_hub
fd24fbb verified
Raw
History Blame
10.3 kB
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Liquid AI Spam Classifier — How-To &amp; References</title>
<style>
 :root { --bg:#fafafa; --card:#fff; --text:#1a1a1a; --muted:#666; --accent:#1a4870; --accent-soft:#e3eef7; --border:#e0e0e0; --code-bg:#f4f4f4; }
 * { box-sizing: border-box; }
 body { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; background: var(--bg); color: var(--text); max-width: 900px; margin: 2rem auto; padding: 0 1.5rem; line-height: 1.6; }
 h1 { color: var(--accent); border-bottom: 3px solid var(--accent); padding-bottom: 0.5rem; }
 h2 { color: var(--accent); margin-top: 2.5rem; border-bottom: 1px solid var(--border); padding-bottom: 0.3rem; }
 h3 { margin-top: 1.8rem; color: #333; }
 .intro { background: var(--accent-soft); border-left: 4px solid var(--accent); padding: 1rem 1.2rem; border-radius: 4px; }
 .nav { display: flex; flex-wrap: wrap; gap: 0.5rem; margin: 1rem 0; }
 .nav a { background: var(--card); border: 1px solid var(--border); padding: 0.4rem 0.9rem; border-radius: 20px; text-decoration: none; color: var(--accent); font-size: 0.9rem; }
 .nav a:hover { background: var(--accent-soft); }
 .item { background: var(--card); border: 1px solid var(--border); border-radius: 6px; padding: 1rem 1.2rem; margin: 0.8rem 0; }
 .item .title { font-weight: 600; font-size: 1.05rem; }
 .item .title a { color: var(--accent); text-decoration: none; }
 .item .title a:hover { text-decoration: underline; }
 .item .meta { color: var(--muted); font-size: 0.85rem; margin-top: 0.2rem; }
 .item .desc { margin-top: 0.5rem; font-size: 0.95rem; }
 .tag { display: inline-block; font-size: 0.75rem; padding: 2px 8px; border-radius: 10px; margin-left: 6px; vertical-align: middle; }
 .tag-local { background: #d4edda; color: #155724; }
 .tag-online { background: #fff3cd; color: #856404; }
 .tag-shared { background: #d1ecf1; color: #0c5460; }
 code { background: var(--code-bg); padding: 2px 6px; border-radius: 3px; font-size: 0.88em; }
 pre { background: var(--code-bg); padding: 0.9rem 1.1rem; border-radius: 4px; border-left: 3px solid var(--accent); overflow-x: auto; font-size: 0.88em; }
 .note { background: #fffbe6; border-left: 4px solid #f0c036; padding: 0.8rem 1rem; border-radius: 4px; margin: 1rem 0; }
 footer { margin-top: 3rem; padding-top: 1.5rem; border-top: 1px solid var(--border); color: var(--muted); font-size: 0.85rem; }
</style>
</head>
<body>
<h1>Liquid AI Spam Classifier — How-To &amp; References</h1>
<div class="intro">
 <strong>What this project does:</strong> Fine-tunes Liquid AI's LFM2.5-1.2B-Instruct model on Apple Silicon using HuggingFace's TRL <code>SFTTrainer</code> with PEFT LoRA adapters, to classify emails as spam or ham. Uses the official Liquid4All cookbook configuration.
</div>
<div class="nav">
 <a href="#quickstart">🚀 Quick Start</a>
 <a href="#papers">📄 Papers</a>
 <a href="#guides">📘 Liquid Guides</a>
 <a href="#shared">🔗 Shared</a>
 <a href="#online">🌐 Online</a>
</div>
<h2 id="quickstart">🚀 Quick Start</h2>
<pre>
# 1. Activate the project virtual environment
cd "spam-classifier-liquid"
source venv/bin/activate
# 2. Install dependencies (first run only)
pip install -r requirements.txt
# 3. Copy training data from the MLX project
mkdir -p training_data
cp ../spam-classifier-mlx/training_data/train.jsonl training_data/
cp ../spam-classifier-mlx/training_data/test.jsonl training_data/
# 4. Fine-tune with LoRA via TRL SFTTrainer
python3 fine_tune.py
# 5. Launch the Gradio web app
python3 app.py
# 6. Or open the notebook
jupyter notebook spam_classifier_liquid.ipynb
</pre>
<div class="note">
 <strong>Model architecture note:</strong> LFM2.5 is a hybrid model that uses attention, GLU (gated linear units), and convolutional layers. That's why the LoRA <code>target_modules</code> list includes both <code>q_proj/k_proj/v_proj/out_proj</code> (attention) and <code>w1/w2/w3</code> (GLU) and <code>in_proj</code> (conv). These exact module names come from the Liquid4All cookbook — see the guide below.
</div>
<h2 id="papers">📄 Project-Specific Papers</h2>
<div class="item">
 <div class="title">
 <a href="papers/LFM2_TechReport.pdf">LFM2 Technical Report</a>
 <span class="tag tag-local">local</span>
 </div>
 <div class="meta">Liquid AI Team (2025) · <a href="https://arxiv.org/abs/2511.23404">arXiv:2511.23404</a></div>
 <div class="desc">The official technical report for the LFM2 model family (the parent of LFM2.5-1.2B-Instruct). Describes the hybrid architecture — a mix of attention, convolutional, and gated linear units inspired by biological neural circuits — and the training process.</div>
</div>
<h2 id="guides">📘 Liquid AI Official Documentation &amp; Cookbook</h2>
<div class="item">
 <div class="title">
 <a href="guides/Liquid_docs_home.html">Liquid AI Documentation Home</a>
 <span class="tag tag-local">local</span>
 </div>
 <div class="meta"><a href="https://docs.liquid.ai/">docs.liquid.ai</a></div>
 <div class="desc">Landing page for all Liquid AI documentation. Use this as a starting point to navigate their docs.</div>
</div>
<div class="item">
 <div class="title">
 <a href="guides/Liquid_finetuning_TRL.html">Fine-Tuning with TRL</a>
 <span class="tag tag-local">local</span>
 </div>
 <div class="meta"><a href="https://docs.liquid.ai/customization/finetuning-frameworks/trl">docs.liquid.ai TRL guide</a></div>
 <div class="desc">Liquid AI's official guide for fine-tuning LFM2 models with HuggingFace TRL. This is the method our project uses. Covers how to set up <code>SFTTrainer</code>, what LoRA parameters work well for LFM2, and example configurations.</div>
</div>
<div class="item">
 <div class="title">
 <a href="guides/Liquid_finetuning_Unsloth.html">Fine-Tuning with Unsloth</a>
 <span class="tag tag-local">local</span>
 </div>
 <div class="meta"><a href="https://docs.liquid.ai/customization/finetuning-frameworks/unsloth">docs.liquid.ai Unsloth guide</a></div>
 <div class="desc">Alternative fine-tuning method using Unsloth (2-5x faster than vanilla TRL). Not used in our project, but worth comparing if you ever want to retrain faster.</div>
</div>
<div class="item">
 <div class="title">
 <a href="guides/Liquid_dataset_formats.html">Dataset Format Guide</a>
 <span class="tag tag-local">local</span>
 </div>
 <div class="meta"><a href="https://docs.liquid.ai/customization/finetuning-frameworks/datasets">docs.liquid.ai datasets</a></div>
 <div class="desc">Explains the dataset formats LFM2 fine-tuning expects. Essential reading if you want to add new training data or change the conversation format.</div>
</div>
<div class="item">
 <div class="title">
 <a href="guides/Liquid4All_sft_with_trl.ipynb">Liquid4All SFT with TRL Notebook</a>
 <span class="tag tag-local">local</span>
 </div>
 <div class="meta"><a href="https://github.com/Liquid4All/cookbook/blob/main/finetuning/notebooks/sft_with_trl.ipynb">Liquid4All cookbook</a></div>
 <div class="desc"><strong>Source of our LoRA configuration.</strong> This is the official notebook that defines the exact <code>target_modules</code> list, rank, alpha, and training arguments the Liquid project uses. Open with Jupyter to see every step.</div>
</div>
<div class="item">
 <div class="title">
 <a href="guides/Liquid4All_sft_with_unsloth.ipynb">Liquid4All SFT with Unsloth Notebook</a>
 <span class="tag tag-local">local</span>
 </div>
 <div class="meta"><a href="https://github.com/Liquid4All/cookbook/blob/main/finetuning/notebooks/sft_with_unsloth.ipynb">Liquid4All cookbook</a></div>
 <div class="desc">Alternative notebook using Unsloth for 2-5x faster training. Uses 16-bit LoRA with gradient checkpointing.</div>
</div>
<h2 id="shared">🔗 Shared References</h2>
<p>The LoRA paper, QLoRA, the Attention Is All You Need paper, and HuggingFace PEFT/TRL/chat-template docs all apply to this project. They live in the shared folder:</p>
<div class="item">
 <div class="title">
 <a href="../../../references/how-to.html">📂 Open the Shared References Index</a>
 <span class="tag tag-shared">shared</span>
 </div>
 <div class="desc">Papers: Attention, LoRA, QLoRA, PEFT Survey. Guides: HF PEFT Quicktour, HF PEFT LoRA Conceptual, HF TRL SFTTrainer, HF Chat Templates, Unsloth docs.</div>
</div>
<h2 id="online">🌐 Online-Only References</h2>
<div class="item">
 <div class="title"><a href="https://huggingface.co/LiquidAI/LFM2.5-1.2B-Instruct">LFM2.5-1.2B-Instruct on HuggingFace</a> <span class="tag tag-online">online</span></div>
 <div class="desc">The exact model we fine-tune. Model card includes benchmarks, usage examples, and license info.</div>
</div>
<div class="item">
 <div class="title"><a href="https://huggingface.co/LiquidAI">LiquidAI HuggingFace organization</a> <span class="tag tag-online">online</span></div>
 <div class="desc">Full catalog of Liquid AI models including larger LFM2-2.6B and LFM2-8B-A1B (MoE) variants.</div>
</div>
<div class="item">
 <div class="title"><a href="https://github.com/Liquid4All/cookbook">Liquid4All cookbook (GitHub)</a> <span class="tag tag-online">online</span></div>
 <div class="desc">Full cookbook repo with all Liquid AI fine-tuning examples, not just the TRL and Unsloth notebooks we saved locally.</div>
</div>
<div class="item">
 <div class="title"><a href="https://www.liquid.ai/">Liquid AI company website</a> <span class="tag tag-online">online</span></div>
 <div class="desc">Company background, blog posts, and model announcements.</div>
</div>
<h2>📚 Citations</h2>
<pre>
Liquid AI Team. (2025). LFM2 Technical Report. arXiv:2511.23404.
 https://arxiv.org/abs/2511.23404
Hu, E., et al. (2021). LoRA: Low-Rank Adaptation of Large Language Models.
 arXiv:2106.09685.
von Werra, L., et al. (2020). TRL: Transformer Reinforcement Learning.
 https://github.com/huggingface/trl
Mangrulkar, S., Gugger, S., Debut, L., Belkada, Y., Paul, S., &amp; Bossan, B. (2022).
 PEFT: State-of-the-art Parameter-Efficient Fine-Tuning methods.
 https://github.com/huggingface/peft
</pre>
<footer>
 Spring 2026 · ENGT 375 Applied Machine Learning · ODU · spam-classifier-liquid
</footer>
</body>
</html>