Spark-X2.5-4B

The repository contains model weights and configuration files for the post-trained model in Hugging Face Transformers format, distributed as Safetensors: 4B parameters with BF16 tensor type. The model uses custom code (custom_code tag), so pass --trust-remote-code when serving with vLLM. The base model is XHToken/Spark-X2.5-4B-Base; this checkpoint is a fine-tune of it. The ecosystem includes 5 public fine-tunes and 18 quantizations (usable with llama.cpp, LM Studio, Jan, and Ollama), and the models are also part of the Spark-X2.5 collection on Hugging Face.

If you find the work helpful, feel free to cite it:

@misc{sparkx2.5,
    title  = {Spark-X2.5 4B&1.7B: Pushing the Limits of Agentic Capabilities in On-Device Models},
    author = {SparkLLM Team},
    year   = {2026}
}

The Spark-X2.5 model series is licensed under the Apache 2.0 License (see the LICENSE file in the model repository).

• Sampling parameters: the recommended settings for Spark-X2.5 are temperature=1.0, top_p=0.95, and top_k=-1 (example requests also use repetition_penalty=1, presence_penalty=0, frequency_penalty=0).
• Thinking mode: thinking is enabled by default; to disable it for a single request, set "chat_template_kwargs": {"enable_thinking": false} in the request body.
• Long outputs: example requests use max_tokens up to 131,072 for long-form generation.
• Context length vs device memory: serving with the full 1,048,576-token context requires sufficient device memory; reduce --context-length when necessary.
• Fine-tuning: use LLaMA-Factory to customize the model.
• Agent harnesses: the models are deeply integrated with popular agent harnesses including Codex, Claude Code, OpenClaw, and Hermes.

Spark-X2.5 runs on a wide range of hardware — NVIDIA GPUs, Huawei Ascend NPUs (A2, A3, and Ascend 950DT), Apple silicon, and Linux CPU — and is compatible with leading inference frameworks such as vLLM, SGLang, llama.cpp, and MLX, plus quick deployment through Ollama and LM Studio.

SGLang (NVIDIA GPU). Use the pre-built image that tracks the Spark-X2.5 runtime (lmsysorg/sglang:nightly-dev-cu13-20260827-20621aa1; Ascend NPU daily builds are published under quay.io/ascend/sglang). Serve an OpenAI-compatible API with:

docker run --rm -it --gpus '"device=0"' --ipc=host -p 30000:30000 \
  -v "$MODEL_PATH:/root/Spark-X2.5-4B:ro" \
  lmsysorg/sglang:nightly-dev-cu13-20260827-20621aa1 \
  python -m sglang.launch_server \
    --model-path /root/Spark-X2.5-4B \
    --served-model-name spark2.5 \
    --tool-call-parser spark25 \
    --reasoning-parser qwen3 \
    --tp-size 1 --mem-fraction-static 0.8 \
    --context-length 1048576 \
    --chat-template /root/Spark-X2.5-4B/chat_template.jinja \
    --host 0.0.0.0 --port 30000

Set MODEL_PATH to the absolute path of the local Spark-X2.5-4B checkpoint before starting the container.

vLLM (NVIDIA GPU). Use the official vllm/vllm-openai:latest image with --trust-remote-code and the model's chat_template.jinja (prefix caching optional):

docker run --rm --gpus all --ipc=host -p 30000:30000 \
  -v "$MODEL_PATH:/models/Spark-X2.5-4B:ro" \
  vllm/vllm-openai:latest \
  --model /models/Spark-X2.5-4B --port 30000 \
  --trust-remote-code --served-model-name spark25 \
  --tensor-parallel-size 1 --gpu-memory-utilization 0.7 \
  --enable-prefix-caching \
  --chat-template /models/Spark-X2.5-4B/chat_template.jinja

For Ascend NPUs, use the official quay.io/ascend/vllm-ascend images (nightly-main for A2, nightly-main-a3 for A3, nightly-main-a5 for Ascend 950DT), then install the Spark plugin inside the container:

git clone https://github.com/XHToken/Spark-plugin.git
cd Spark-plugin
uv pip install .

MLX (Spark-MLX-LLM). Runs the original Spark-X2.5 Hugging Face checkpoints locally on Apple silicon GPU, Linux CPU, and NVIDIA CUDA on Linux — no GGUF conversion required:

git clone https://github.com/XHToken/Spark-MLX-LLM.git
cd Spark-MLX-LLM
python3 -m venv .venv && source .venv/bin/activate
python -m pip install -e .   # Apple silicon (extras: '.[cpu]', '.[cuda12]', '.[cuda13]')
spark-mlx-generate --device gpu --dtype bfloat16 \
  --model XHToken/Spark-X2.5-4B \
  --prompt "What is the capital of Anhui Province?" \
  --max-tokens 512 --temp 0

Ollama and LM Studio. Build the provided llama.cpp fork (https://github.com/XHToken/llama.cpp), then either create an Ollama model from a GGUF file (./ollama create Spark-X2.5-4B -f ./Modelfile.spark and ./ollama run Spark-X2.5-4B) or copy the llama.cpp-spark build output into an LM Studio runtime directory, place the GGUF model under the LM Studio models directory, and load it (or use the lms CLI: lms load <model>, lms chat <model>).

Fine-tuning. LLaMA-Factory is recommended for fine-tuning the model.

Thinking is enabled by default by both the chat template and the Qwen3 reasoning parser (the SGLang server is started with --reasoning-parser qwen3). To disable thinking for a specific request, set "chat_template_kwargs": {"enable_thinking": false} in the request body. All reported benchmark evaluations are conducted in thinking mode.

Spark-X2.5 models are evaluated against leading on-device models of similar size across a broad range of tasks, including agent, code, math, and general & knowledge benchmarks.

Notes:

• * denotes reported results from publicly released model cards / papers; - denotes scores not yet available.
• All evaluations are conducted in thinking mode. The recommended sampling parameters for Spark-X2.5 are temperature=1.0, top_p=0.95, and top_k=-1.
• Gaokao 2026 consists of the five 2026 Chinese GAOKAO examinations (National I, National II, Beijing, Shanghai, Tianjin), each graded out of 150 points.

Pretraining. Spark-X2.5 is pretrained on approximately 20 trillion tokens from a diverse corpus spanning web pages, books, academic publications, code, and encyclopedic materials. Particular attention is paid to data quality, domain coverage, and the sampling weights assigned to different data categories. Extensive data-mixture studies determine an effective balance among mathematics, logic, code, and other high-value domains, enabling the models to acquire broad general knowledge while developing stronger capabilities in complex reasoning and code generation. Long-context capability is developed through a dedicated training stage comprising hundreds of billions of tokens, with sequence lengths extending to 1M tokens.

Post-training. Post-training begins with supervised fine-tuning (SFT) on a carefully curated corpus, establishing robust instruction following, structured generation, and task completion while providing a stable policy initialization for reinforcement learning. Large-scale reinforcement learning is then applied across several capability domains — language understanding, reasoning, programming, tool-augmented agentic behavior, and instruction following — yielding a set of domain-specialized teacher policies whose complementary strengths are consolidated into a single deployable model through MOPD. The models were trained on Huawei Ascend clusters.

Spark-X2.5 natively supports a context window of up to 1M tokens (1,048,576). Long-context capability is developed through a dedicated training stage comprising hundreds of billions of tokens, with sequence lengths extending to 1M tokens. When serving with SGLang, start the server with --context-length 1048576; this setting requires sufficient device memory, so reduce --context-length when necessary. Example client requests generate up to 131,072 tokens (max_tokens: 131072).

For agent tasks, balancing performance, inference speed, and cache usage has long been a key bottleneck limiting model performance. Spark-X2.5 systematically integrates and optimizes mature attention technologies, combining sliding-window attention (SWA) with a hybrid full-attention architecture: one full-attention layer is paired with three sliding-window attention layers. This design leverages the strengths of both mechanisms while avoiding the limitations of relying on a single structure, achieving an effective balance among performance, inference efficiency, and KV-cache size — thereby improving practicality and effectiveness in real-world deployment scenarios.

Spark-X2.5-4B and Spark-X2.5-1.7B are compact, general-purpose language models designed to make capable AI more practical, efficient, and accessible. They deliver strong performance across everyday tasks — conversation, writing, translation, reasoning, coding, tool use, and agentic workflows — achieving leading results among open-source models of comparable size. They combine an efficiency-oriented architecture with native context windows of up to 1M tokens and support for more than 200 languages.

Technical highlights

• Efficient architecture and native 1M-token context: a hybrid attention architecture combines one full-attention layer with three sliding-window attention layers, substantially reducing the computational overhead of long-context models while natively supporting a context window of up to 1M tokens.
• Strong coding and agent capabilities: deeply integrated with popular agent harnesses including Codex, Claude Code, OpenClaw, and Hermes; state-of-the-art performance among models of comparable size across everyday coding, agentic workflows, reasoning, and instruction following.
• Broad hardware and software compatibility: supports NVIDIA, Huawei, Hygon, HOUMO.AI, and other hardware platforms; compatible with leading inference frameworks such as vLLM, SGLang, llama.cpp, and MLX; deployable quickly through Ollama and LM Studio; customizable with fine-tuning frameworks such as LLaMA-Factory. Delivers superior TTFT, TOPT, and overall inference efficiency compared with similarly sized models.
• Advanced training algorithms: trained on Huawei Ascend clusters; large-scale reinforcement learning and post-training techniques such as MOPD significantly enhance reasoning, coding, agentic, and instruction-following capabilities.