Spark-x2.6-4B-HTML / README.md
wesjos's picture
Update README.md
b5ed04a verified
|
Raw History Blame Contribute Delete
8.56 kB
---
license: apache-2.0
base_model: XHToken/Spark-X2.6-4B
library_name: transformers
pipeline_tag: text-generation
language:
- en
- zh
tags:
- sparkx2_5
- html-generation
- web-design
- visual-ui
- reasoning
- sft
datasets:
- wesjos/mario-html-sft
---
<div align="center">
<h1>Spark-X2.6-4B · HTML</h1>
<p><b>Spark-X2.6-4B fine-tuned to answer with rendered HTML — cards, tables, metric tiles and callouts instead of prose.</b></p>
<p><sub>4.11 B params &nbsp;·&nbsp; bf16, 7.66 GiB in one shard &nbsp;·&nbsp; 1 M context &nbsp;·&nbsp; ships a WebUI &nbsp;·&nbsp; Apache-2.0</sub></p>
<p>
<a href="https://huggingface.co/XHToken/Spark-X2.6-4B"><img alt="Base" src="https://img.shields.io/badge/Base-Spark--X2.6--4B-615CED"></a>
<img alt="Params" src="https://img.shields.io/badge/Params-4.11B-2EA043">
<img alt="Output" src="https://img.shields.io/badge/Output-HTML-1F6FEB">
<img alt="License" src="https://img.shields.io/badge/License-Apache--2.0-8A8A8A">
</p>
</div>
---
> **💾 Want the same model at 2.4 GB? → [Spark-x2.6-4B-HTML-GGUF](https://huggingface.co/wesjos/Spark-x2.6-4B-HTML-GGUF)**
>
> The identical fine-tune, quantized: `Q4_K_M` at 2.42 GiB, `Q8_0` at 4.07 GiB. This repo is the full bf16
> checkpoint (7.66 GiB) plus the WebUI.
## 🖼 Demo
Both shots are the bundled WebUI (`webui/`, `theme_preset: notion`) with the **CoT toggle on** — the
`Chain of Thought` panel above each answer is the raw `<think>` stream, and the page below it is the
unmodified render.
### `can u show me what ReLU looks like?`
A definition card, a two-column grid with a plotted ReLU curve next to a domain/output/slope table, and a
"Why It Matters in ML" bullet card. **30.09 s · 129 tok/s · 3882 tokens.**
<div align="center">
<img src="demo/demo-html-1.png" alt="ReLU demo: a definition card, a two-column grid holding a plotted ReLU curve and a domain-output-slope table, a why-it-matters bullet card, and a footer showing 30.09 seconds, 129 tokens per second and 3882 tokens">
<br>
<sub><b>ReLU</b> · a definition card, a ReLU curve beside a domain/output/slope table, and a “Why It Matters in ML” card</sub>
</div>
### `how to learn C++`
A study-plan page: a "Why Start Here?" callout, four feature-list bullets, then a "Key Libraries" card with
inline code chips.
<div align="center">
<img src="demo/demo-html-2.png" alt="C++ learning demo: a why-start-here callout, four feature-list bullets for basics, control flow, functions and standard IO, and a key-libraries card with inline code chips for vector, string, map, set, algorithm and numeric">
<br>
<sub><b>C++</b> · a “Why Start Here?” callout, four feature-list bullets, and a “Key Libraries” card of inline code chips</sub>
</div>
---
## 📐 Specs
| | |
|---|---|
| Base | [`XHToken/Spark-X2.6-4B`](https://huggingface.co/XHToken/Spark-X2.6-4B) (Apache-2.0) |
| Architecture | `Spark2_5ForCausalLM` · 36 layers — **9 full-attention + 27 sliding-attention (window 512)** · hidden 2560 |
| Attention | 16 heads / 4 KV heads · head_dim 256 · partial RoPE 0.25 on full-attention layers |
| Parameters | **4,112,079,360** (bf16, measured from the safetensors header) · 335.5 M embedding / 3.78 B non-embedding |
| On disk | 1 shard, 7.66 GiB |
| Context | 1,048,576 native (`max_position_embeddings`) · tokenizer advertises 131,072 |
| Vocab | 131,072 |
| Default system prompt | `You are Mario-html. You are a helpful assistant who generates nice visual content.` |
## 🚀 Quickstart
> [!IMPORTANT]
> **This repo's `tokenizer_config.json` declares `tokenizer_class: "TokenizersBackend"`, which needs `transformers>=5.0.0`.**
> On `transformers==4.57.1` (the version upstream pins) `AutoTokenizer` raises
> `ValueError: Tokenizer class TokenizersBackend does not exist or is not currently imported.`
```bash
pip install "transformers>=5.0.0" jinja2
```
```python
import torch
from transformers import AutoModelForCausalLM, AutoTokenizer
MODEL = "wesjos/Spark-x2.6-4B-HTML"
tokenizer = AutoTokenizer.from_pretrained(MODEL, trust_remote_code=True)
model = AutoModelForCausalLM.from_pretrained(
MODEL, trust_remote_code=True, dtype=torch.bfloat16, device_map="auto"
)
messages = [{"role": "user", "content": "can u show me what ReLU looks like?"}]
inputs = tokenizer.apply_chat_template(
messages, add_generation_prompt=True, tokenize=True,
return_dict=True, return_tensors="pt",
enable_thinking=True, reasoning_effort="low",
).to(model.device)
out = model.generate(**inputs, max_new_tokens=8192, do_sample=True,
temperature=0.7, top_p=0.8, top_k=40, repetition_penalty=1.05)
print(tokenizer.decode(out[0][inputs["input_ids"].shape[-1]:], skip_special_tokens=True))
```
**llama.cpp** — native `spark2_5` support landed in [`b10828`](https://github.com/ggml-org/llama.cpp);
`v0.9.0` has it too. The GGUF carries its own chat template, so no `--chat-template-file` is needed.
```bash
llama-cli -m Spark-x2.6-4B-HTML.Q4_K_M.gguf -p "can u show me what ReLU looks like?" -n 8192
```
## 🎨 WebUI
The repo ships a self-contained WebUI (`webui/`) that renders the model's HTML output live, with a
collapsible `<think>` panel, a raw-source view and a copy-HTML button per message, plus five theme presets
(`default` · `apple` · `notion` · `cyber` · `editorial`).
```bash
cd webui
pip install -r requirements.txt
python server.py --port 8798
```
Open `http://localhost:8798`. The UI talks to an **OpenAI-compatible backend** over `webui/config.json` —
by default `http://127.0.0.1:18080` serving the alias `Spark-x2.6-4B-HTML` — and falls back to whatever the
backend actually serves if the alias has drifted.
> [!NOTE]
> `webui/config.json` ships `model_path: "/mnt/sdb/models/Spark-x2.6-4B-HTML/Spark-x2.6-4B-HTML-Q8_0.gguf"`
> — a path from the training host that does not exist on any reader's machine. Point it at your own
> quant, or set `backend_mode: "direct"` and let the UI manage the llama.cpp server for you.
### Output contract
Class list verified against the shipped `webui/static/theme.css`:
| Component | Markup |
|---|---|
| Root | `<div class="ai-view">` |
| Summary | `<div class="summary">` · `<div class="summary-card">` · `<p class="lead">` |
| Card | `<div class="card">` |
| Grid | `<div class="grid grid-2">` · `<div class="grid grid-3">` |
| Metrics | `<div class="metric-group"><div class="metric-card"><span class="metric-label">…</span><span class="metric-value">…</span><span class="metric-sub">…</span></div></div>` |
| Stepper | `<div class="stepper"><div class="step-item">…</div></div>` |
| Callout | `<div class="callout callout-info\|warning\|success\|danger"><div class="callout-header">…</div></div>` |
| Badge | `<span class="badge badge-info\|success\|warning\|danger\|accent">` |
| Table | `<div class="table-container"><table class="modern-table">…</table></div>` |
| Feature list | `<div class="feature-list"><div class="feature-item">…</div></div>` |
| Code block | `<div class="code-box"><div class="code-header"><span class="code-title">…</span></div>…</div>` |
## 💡 Notes
- **The output is HTML, not Markdown.** Render it in a container with `theme.css`, or the classes fall back
to browser defaults.
- **The persona is in the weights, and so is the system prompt.** This repo's `chat_template.jinja`
overrides the upstream default with `"You are Mario-html. You are a helpful assistant who generates nice
visual content."` — unlike the CuteHuman sibling, it *is* a template edit, not just a weight edit.
- **Its `generation_config.json` is also its own**: `temperature 0.7 / top_p 0.8 / top_k 40 /
repetition_penalty 1.05 / max_new_tokens 8192`, where upstream ships `1.0 / 0.95 / -1 / 1.0`. The WebUI
config agrees.
- **`reasoning_effort` has three levels here, not two.** The WebUI offers 低 / 中 / 高 and the server maps
`low` and `medium` to `low`, `high` and `xhigh` to `high` — because the template only understands
`low` and `high`.
## ⚠️ Limitations
- **The screenshots were taken under this repo's WebUI**, but the crops shipped here were re-taken from the
originals and the `thinking` dropdown reads `思考: 中(标准推演)` — i.e. `medium`, which the server maps
down to `reasoning_effort: low`.
- **No training metadata ships with this repo** — no data size, no steps, no rank.
- **Tool use is inherited and unaudited.**
## 📄 License
Apache-2.0, inherited from the [Spark-X2.6 model series](https://huggingface.co/XHToken/Spark-X2.6-4B/blob/main/LICENSE).