Spark-X2.5

[!Note] 本仓库包含采用 Hugging Face Transformers 格式的后训练模型权重和配置文件。

简介

我们发布 Spark-X2.5-4B 和 Spark-X2.5-1.7B，两款紧凑的通用语言模型，旨在让能力更强的 AI 更加实用、高效和易用。模型在广泛日常任务中表现出色，包括对话、写作、翻译、推理、编码、工具使用以及智能体工作流，并在同等规模的开源模型中取得领先表现。Spark-X2.5 结合了面向效率的架构、原生支持最高 1M tokens 的上下文窗口，以及超过 200 种语言的支持。

技术亮点：

高效架构与原生 1M-token 上下文：模型采用混合注意力架构，将一个全注意力层与三个滑动窗口注意力层相结合。该设计在原生支持最高 1M tokens 上下文窗口的同时，显著降低了长上下文模型通常带来的计算开销。
强大的编码与智能体能力：模型与主流智能体运行环境深度集成，包括 Codex、Claude Code、OpenClaw 和 Hermes。在日常编码、智能体工作流、推理和指令跟随任务中，它们取得了同等规模模型中的最先进表现。
广泛的软硬件兼容性：模型支持广泛的硬件平台，包括 NVIDIA、Huawei、Hygon、HOUMO.AI 等，并与 vLLM、SGLang、llama.cpp、MLX 等主流推理框架兼容，可通过 Ollama 和 LM Studio 等平台快速部署。模型还可使用 LLaMA-Factory 等主流微调框架进行定制。在多个硬件平台上，与同规模模型相比，它们在 TTFT、TOPT 和整体推理效率方面表现更优。
先进训练算法：模型在 Huawei Ascend 集群上训练。大规模强化学习和 MOPD 等后训练技术显著增强了其推理、编码、智能体和指令跟随能力。

Spark-X2.5 benchmark comparison

模型概述

对于智能体任务，性能、推理速度与缓存占用之间的平衡长期以来一直是制约模型表现的关键瓶颈。Spark-X2.5 系统化地整合并优化了成熟的注意力技术，将滑动窗口注意力（SWA）与混合全注意力架构相结合。该方法兼具两种机制的优势，同时避免单一结构依赖带来的局限，在性能、推理效率和 KV 缓存规模之间实现有效平衡，从而提升模型在实际部署场景中的实用性与有效性。

Spark-X2.5 混合架构

训练方法

Spark-X2.5 基于约 20 万亿词元的多样化语料进行预训练，语料来源涵盖网页、书籍、学术论文、代码和百科资料。我们重点关注数据质量、领域覆盖以及不同数据类别的采样权重，并通过大量数据配比研究，确定数学、逻辑、代码及其他高价值领域之间的有效平衡。这使得模型在获得广泛通用知识的同时，具备更强的复杂推理与代码生成能力。长上下文能力通过专门的训练阶段发展，该阶段使用数千亿词元，序列长度可扩展至 100 万词元。

后训练从基于精心筛选语料的监督微调开始。该阶段建立了稳健的指令遵循、结构化生成和任务完成能力，并为强化学习提供了稳定的策略初始化。随后，我们在语言理解、推理、编程、工具增强的智能体行为以及指令遵循等多个能力领域开展大规模强化学习。该过程生成了一组领域专用的教师策略，并通过 MOPD 将其互补优势整合到一个可部署模型中。

Spark-X2.5 混合架构

基准测试

我们对模型进行了评估，并与相近规模的主流端侧模型在多类任务上展开对比，任务覆盖智能体、代码、数学、通用与知识。

评测基准	Spark‑X2.5‑4B	Spark‑X2.5‑1.7B	Qwen3.5‑9B	Qwen3.5‑4B	Qwen3.5‑2B	Gemma4‑12B	Gemma4‑E4B	Gemma4‑E2B
智能体
BFCL‑V4	65.1	46.9	66.1*	50.3*	43.6*	37.4	36.9	30.2
τ²‑bench	75.1	65.3	79.1*	79.9*	48.8*	69.0*	42.2*	24.5*
τ³‑bench	30.4	20.1	9.3	6.7	4.1	13.3	10.1	8.8
MCP‑Atlas	54.6	23.4	47.4*	40.8*	14.8	30.5*	15.0*	12.6
MCP‑Mark	14.2	2.3	13.4	12.5	–	–	–	–
Workspace Bench	31.2	18.9	25.5	21.3	7.7	–	–	–
VitaBench2.0	25.2	8.3	15.6	18.2	5.2	12.4	4.8	4.4
BrowseComp	40.9	29.7	8.3	14.3	3.1	10.0	8.3	3.7
代码
SWE‑Bench Pro	44.4	10.4	33.8*	29.4*	1.9	21.9*	4.0*	–
SWE‑Bench Verified	41.6	28.3	53.1*	38.8*	6.8	44.2*	14.0*	–
SWE‑Bench Multilingual	53.3	23.3	43.3	27.7	5.0	32.5*	–	–
SciCode	34.7	18.2	32.7*	24.0	6.0	39.8	27.5	20.5
数学
Gaokao 2026	133.4	114.8	135.5	130.3	94.0	130.6	102.4	81.8
AIME 2026	90.7	69.4	88.2	83.0	30.8	82.1*	42.5*	37.5*
HMMT Feb 2026	81.2	48.4	70.8	69.7	21.5	65.6	34.2	20.5
IMO‑AnswerBench	74.2	45.4	69.8	68.5	–	57.2	26.9	22.6
通用与知识
IFEval	93.0	89.5	91.5*	89.8*	78.6*	94.8	45.3	34.8
IFBench	75.0	66.3	64.5	59.2	41.3*	73.5*	44.0*	22.7
AA‑LCR	56.3	24.3	63.0*	57.0*	25.6*	55.3*	34.7	18.3
HLE	12.3	6.3	14.3	8.6	2.1	13.1	3.9	2.5
GPQA	67.4	43.8	77.2	67.2	44.6	72.8	54.5	43.8

* 表示来自公开发布的模型卡 / 论文的已报告结果，- 表示分数尚未公布。
所有评估均在思考模式下进行。Spark-X2.5 的推荐采样参数为 temperature=1.0、top_p=0.95、top_k=-1。
Gaokao 2026 由 2026 年五套中国高考试卷组成（全国 I 卷、全国 II 卷、北京、上海、天津），每套试卷满分 150 分。

快速开始

以下示例用于为本地 Spark-X2.5-4B checkpoint 提供模型服务。在启动容器前，请将 MODEL_PATH 设置为其绝对路径：

export MODEL_PATH=/absolute/path/to/Spark-X2.5-4B

SGLang

安装 SGLang

使用与 Spark-X2.5 运行时相匹配的预构建镜像：

适用于 NVIDIA GPU：

docker pull lmsysorg/sglang:nightly-dev-cu13-20260827-20621aa1

适用于昇腾 NPU：

# A3 daily build
export SGLANG_IMAGE=quay.io/ascend/sglang:main-cann9.0.0-a3

# A2 daily build (use this instead on A2 hardware)
export SGLANG_IMAGE=quay.io/ascend/sglang:main-cann9.0.0-910b

docker pull "$SGLANG_IMAGE"

运行推理

以下命令将启动一个兼容 OpenAI 的 API 服务器，并配置为最大上下文长度为 1,048,576 tokens。该设置需要足够的设备内存；必要时请调低 --context-length。

Server

NVIDIA GPU:

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

Ascend NPU：

docker run -it --rm -e ASCEND_USE_FIA=1 --network=host --ipc=host --shm-size=16g \
    --device=/dev/davinci0 --device=/dev/davinci1 --device=/dev/davinci2 --device=/dev/davinci3 \
    --device=/dev/davinci4 --device=/dev/davinci5 --device=/dev/davinci6 --device=/dev/davinci7 \
    --device=/dev/davinci8 --device=/dev/davinci9 --device=/dev/davinci10 --device=/dev/davinci11 \
    --device=/dev/davinci12 --device=/dev/davinci13 --device=/dev/davinci14 --device=/dev/davinci15 \
    --device=/dev/davinci_manager \
    --device=/dev/devmm_svm \
    --device=/dev/hisi_hdc \
    --volume /usr/local/sbin:/usr/local/sbin \
    --volume /usr/local/Ascend/driver:/usr/local/Ascend/driver \
    --volume /usr/local/Ascend/firmware:/usr/local/Ascend/firmware \
    --volume /etc/ascend_install.info:/etc/ascend_install.info \
    --volume /var/queue_schedule:/var/queue_schedule \
    --volume ~/.cache/:/root/.cache/ \
    --volume "$MODEL_PATH:/root/Spark-X2.5-4B:ro" \
    --entrypoint=python \
    "$SGLANG_IMAGE" \
    -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

客户端

默认情况下，聊天模板和 Qwen3 推理解析器均会启用思考。如需在特定请求中禁用思考，请设置 "chat_template_kwargs": {"enable_thinking": false}。

curl -s http://localhost:30000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "spark2.5",
    "messages": [
      {
        "role": "user",
        "content": "What is the capital of Anhui Province?"
      }
    ],
    "max_tokens": 131072,
    "temperature": 1,
    "top_k": -1,
    "top_p": 0.95,
    "repetition_penalty": 1,
    "presence_penalty": 0,
    "frequency_penalty": 0
  }'

vLLM

部署 vLLM

vLLM 提供用于 NVIDIA GPU 部署的官方 Docker 镜像：

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

针对 Ascend NPU，请选择官方镜像，以实现最快部署。

Ascend A2:

export IMAGE=quay.io/ascend/vllm-ascend:nightly-main
docker pull "$IMAGE"

export DEVICE=/dev/davinci0
export MODEL_CACHE="${HOME}/.cache"

mkdir -p "$MODEL_CACHE"

docker run --rm \
    --name vllm-ascend \
    --shm-size=1g \
    --device "$DEVICE" \
    --device /dev/davinci_manager \
    --device /dev/devmm_svm \
    --device /dev/hisi_hdc \
    -v /usr/local/dcmi:/usr/local/dcmi \
    -v /usr/local/bin/npu-smi:/usr/local/bin/npu-smi \
    -v /usr/local/Ascend/driver/lib64/:/usr/local/Ascend/driver/lib64/ \
    -v /usr/local/Ascend/driver/version.info:/usr/local/Ascend/driver/version.info \
    -v /etc/ascend_install.info:/etc/ascend_install.info \
    -v "$MODEL_CACHE:/root/.cache" \
    -p 8000:8000 \
    -it "$IMAGE" bash

Ascend A3：

export IMAGE=quay.io/ascend/vllm-ascend:nightly-main-a3
docker pull "$IMAGE"

export DEVICE0=/dev/davinci0
export DEVICE1=/dev/davinci1
export MODEL_CACHE="${HOME}/.cache"

mkdir -p "$MODEL_CACHE"

docker run --rm \
    --name vllm-ascend \
    --shm-size=1g \
    --device "$DEVICE0" \
    --device "$DEVICE1" \
    --device /dev/davinci_manager \
    --device /dev/devmm_svm \
    --device /dev/hisi_hdc \
    -v /usr/local/dcmi:/usr/local/dcmi \
    -v /usr/local/bin/npu-smi:/usr/local/bin/npu-smi \
    -v /usr/local/Ascend/driver/lib64/:/usr/local/Ascend/driver/lib64/ \
    -v /usr/local/Ascend/driver/version.info:/usr/local/Ascend/driver/version.info \
    -v /etc/ascend_install.info:/etc/ascend_install.info \
    -v "$MODEL_CACHE:/root/.cache" \
    -p 8000:8000 \
    -it "$IMAGE" bash

Ascend 950DT：

export IMAGE=quay.io/ascend/vllm-ascend:nightly-main-a5
docker pull "$IMAGE"

export MODEL_CACHE="${HOME}/.cache"

mkdir -p "$MODEL_CACHE"

docker run --rm \
    --name vllm-ascend \
    --net=host \
    --shm-size=1g \
    --device /dev/davinci0 \
    --device /dev/davinci_manager \
    --device /dev/devmm_svm \
    --device /dev/hisi_hdc \
    -v /usr/local/dcmi:/usr/local/dcmi \
    -v /usr/local/Ascend/driver/tools/hccn_tool:/usr/local/Ascend/driver/tools/hccn_tool \
    -v /usr/local/bin/npu-smi:/usr/local/bin/npu-smi \
    -v /usr/local/Ascend/driver/lib64/:/usr/local/Ascend/driver/lib64/ \
    -v /usr/local/Ascend/driver/version.info:/usr/local/Ascend/driver/version.info \
    -v /etc/ascend_install.info:/etc/ascend_install.info \
    -v "$MODEL_CACHE:/root/.cache" \
    -it "$IMAGE" bash

在容器内安装 Spark 插件：

pip install uv
uv venv ~/spark2_5
source ~/spark2_5/bin/activate
git clone https://github.com/XHToken/Spark-plugin.git
cd ./Spark-plugin
uv pip install .

服务器

vllm serve "/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

客户端

curl -s http://127.0.0.1:30000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "spark25",
    "messages": [{"role": "user", "content": "What is the capital of Anhui Province?"}],
    "temperature": 1.0, 
    "top_k": -1,
    "top_p": 0.95
  }'

MLX

Spark-MLX-LLM 可在本地运行 Spark-X2.5 的原始 Hugging Face checkpoints。它支持 Apple silicon GPU、Linux CPU，以及 Linux 上的 NVIDIA CUDA。无需进行 GGUF 转换。

安装

git clone https://github.com/XHToken/Spark-MLX-LLM.git
cd Spark-MLX-LLM

python3 -m venv .venv
source .venv/bin/activate

# Apple silicon
python -m pip install -e .
# Linux CPU
python -m pip install -e '.[cpu]'
# Linux with CUDA 12
python -m pip install -e '.[cuda12]' 
# Linux with CUDA 13
python -m pip install -e '.[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

构建

git clone https://github.com/XHToken/llama.cpp.git llama.cpp-spark
git clone https://github.com/ollama/ollama.git ollama-spark
cd ollama-spark
export OLLAMA_LLAMA_CPP_SOURCE="$(cd ../llama.cpp-spark && pwd)"
cmake -S . -B build
cmake --build build --parallel 8

创建并运行

创建模型定义后，在一个终端中启动 Ollama 服务：

printf 'FROM /absolute/path/to/your.gguf\n' > ./Modelfile.spark
./ollama serve

在另一个终端中创建并运行模型：

./ollama create Spark-X2.5-4B -f ./Modelfile.spark
./ollama run Spark-X2.5-4B

LM Studio

构建

git clone https://github.com/XHToken/llama.cpp.git llama.cpp-spark
cd llama.cpp-spark
cmake -S . -B build
cmake --build build --parallel 8

设置 LM Studio

关闭 LM Studio。

备份所选的运行时目录：

<LM_STUDIO_HOME>/extensions/backends/<selected-runtime>/

将 llama.cpp-spark 的构建输出复制到所选的运行时目录中，覆盖现有文件。
将 GGUF 模型放置在以下目录中：
```
<LM_STUDIO_HOME>/models/<org>/<name>/
```

macOS 上的示例运行时目录：

./build/bin/* -> ~/.lmstudio/extensions/backends/llama.cpp-mac-arm64-apple-metal-advsimd-<version>/

使用 LM Studio 运行

打开 My Models，选择 Spark-X2.5 模型，点击 Load，然后新建一个对话。

使用 lms CLI 运行

# Replace <model> with a model listed by lms ls.
lms load <model>
lms chat <model>

微调

我们建议使用 Llama-Factory 对该模型进行微调。

许可

Spark-X2.5 模型系列采用 Apache 2.0 许可证。

引用

如果您觉得我们的工作有帮助，欢迎引用。

@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}
}

Spark-X2.5

[!Note] 本仓库包含采用 Hugging Face Transformers 格式的后训练模型权重和配置文件。

简介

技术亮点：

高效架构与原生 1M-token 上下文：模型采用混合注意力架构，将一个全注意力层与三个滑动窗口注意力层相结合。该设计在原生支持最高 1M tokens 上下文窗口的同时，显著降低了长上下文模型通常带来的计算开销。
强大的编码与智能体能力：模型与主流智能体运行环境深度集成，包括 Codex、Claude Code、OpenClaw 和 Hermes。在日常编码、智能体工作流、推理和指令跟随任务中，它们取得了同等规模模型中的最先进表现。
广泛的软硬件兼容性：模型支持广泛的硬件平台，包括 NVIDIA、Huawei、Hygon、HOUMO.AI 等，并与 vLLM、SGLang、llama.cpp、MLX 等主流推理框架兼容，可通过 Ollama 和 LM Studio 等平台快速部署。模型还可使用 LLaMA-Factory 等主流微调框架进行定制。在多个硬件平台上，与同规模模型相比，它们在 TTFT、TOPT 和整体推理效率方面表现更优。
先进训练算法：模型在 Huawei Ascend 集群上训练。大规模强化学习和 MOPD 等后训练技术显著增强了其推理、编码、智能体和指令跟随能力。

Spark-X2.5 benchmark comparison

模型概述

Spark-X2.5 混合架构

训练方法

Spark-X2.5 混合架构

基准测试

我们对模型进行了评估，并与相近规模的主流端侧模型在多类任务上展开对比，任务覆盖智能体、代码、数学、通用与知识。

评测基准	Spark‑X2.5‑4B	Spark‑X2.5‑1.7B	Qwen3.5‑9B	Qwen3.5‑4B	Qwen3.5‑2B	Gemma4‑12B	Gemma4‑E4B	Gemma4‑E2B
智能体
BFCL‑V4	65.1	46.9	66.1*	50.3*	43.6*	37.4	36.9	30.2
τ²‑bench	75.1	65.3	79.1*	79.9*	48.8*	69.0*	42.2*	24.5*
τ³‑bench	30.4	20.1	9.3	6.7	4.1	13.3	10.1	8.8
MCP‑Atlas	54.6	23.4	47.4*	40.8*	14.8	30.5*	15.0*	12.6
MCP‑Mark	14.2	2.3	13.4	12.5	–	–	–	–
Workspace Bench	31.2	18.9	25.5	21.3	7.7	–	–	–
VitaBench2.0	25.2	8.3	15.6	18.2	5.2	12.4	4.8	4.4
BrowseComp	40.9	29.7	8.3	14.3	3.1	10.0	8.3	3.7
代码
SWE‑Bench Pro	44.4	10.4	33.8*	29.4*	1.9	21.9*	4.0*	–
SWE‑Bench Verified	41.6	28.3	53.1*	38.8*	6.8	44.2*	14.0*	–
SWE‑Bench Multilingual	53.3	23.3	43.3	27.7	5.0	32.5*	–	–
SciCode	34.7	18.2	32.7*	24.0	6.0	39.8	27.5	20.5
数学
Gaokao 2026	133.4	114.8	135.5	130.3	94.0	130.6	102.4	81.8
AIME 2026	90.7	69.4	88.2	83.0	30.8	82.1*	42.5*	37.5*
HMMT Feb 2026	81.2	48.4	70.8	69.7	21.5	65.6	34.2	20.5
IMO‑AnswerBench	74.2	45.4	69.8	68.5	–	57.2	26.9	22.6
通用与知识
IFEval	93.0	89.5	91.5*	89.8*	78.6*	94.8	45.3	34.8
IFBench	75.0	66.3	64.5	59.2	41.3*	73.5*	44.0*	22.7
AA‑LCR	56.3	24.3	63.0*	57.0*	25.6*	55.3*	34.7	18.3
HLE	12.3	6.3	14.3	8.6	2.1	13.1	3.9	2.5
GPQA	67.4	43.8	77.2	67.2	44.6	72.8	54.5	43.8

* 表示来自公开发布的模型卡 / 论文的已报告结果，- 表示分数尚未公布。
所有评估均在思考模式下进行。Spark-X2.5 的推荐采样参数为 temperature=1.0、top_p=0.95、top_k=-1。
Gaokao 2026 由 2026 年五套中国高考试卷组成（全国 I 卷、全国 II 卷、北京、上海、天津），每套试卷满分 150 分。

快速开始

以下示例用于为本地 Spark-X2.5-4B checkpoint 提供模型服务。在启动容器前，请将 MODEL_PATH 设置为其绝对路径：

export MODEL_PATH=/absolute/path/to/Spark-X2.5-4B

SGLang

安装 SGLang

使用与 Spark-X2.5 运行时相匹配的预构建镜像：

适用于 NVIDIA GPU：

docker pull lmsysorg/sglang:nightly-dev-cu13-20260827-20621aa1

适用于昇腾 NPU：

# A3 daily build
export SGLANG_IMAGE=quay.io/ascend/sglang:main-cann9.0.0-a3

# A2 daily build (use this instead on A2 hardware)
export SGLANG_IMAGE=quay.io/ascend/sglang:main-cann9.0.0-910b

docker pull "$SGLANG_IMAGE"

运行推理

以下命令将启动一个兼容 OpenAI 的 API 服务器，并配置为最大上下文长度为 1,048,576 tokens。该设置需要足够的设备内存；必要时请调低 --context-length。

Server

NVIDIA GPU:

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

Ascend NPU：

docker run -it --rm -e ASCEND_USE_FIA=1 --network=host --ipc=host --shm-size=16g \
    --device=/dev/davinci0 --device=/dev/davinci1 --device=/dev/davinci2 --device=/dev/davinci3 \
    --device=/dev/davinci4 --device=/dev/davinci5 --device=/dev/davinci6 --device=/dev/davinci7 \
    --device=/dev/davinci8 --device=/dev/davinci9 --device=/dev/davinci10 --device=/dev/davinci11 \
    --device=/dev/davinci12 --device=/dev/davinci13 --device=/dev/davinci14 --device=/dev/davinci15 \
    --device=/dev/davinci_manager \
    --device=/dev/devmm_svm \
    --device=/dev/hisi_hdc \
    --volume /usr/local/sbin:/usr/local/sbin \
    --volume /usr/local/Ascend/driver:/usr/local/Ascend/driver \
    --volume /usr/local/Ascend/firmware:/usr/local/Ascend/firmware \
    --volume /etc/ascend_install.info:/etc/ascend_install.info \
    --volume /var/queue_schedule:/var/queue_schedule \
    --volume ~/.cache/:/root/.cache/ \
    --volume "$MODEL_PATH:/root/Spark-X2.5-4B:ro" \
    --entrypoint=python \
    "$SGLANG_IMAGE" \
    -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

客户端

默认情况下，聊天模板和 Qwen3 推理解析器均会启用思考。如需在特定请求中禁用思考，请设置 "chat_template_kwargs": {"enable_thinking": false}。

curl -s http://localhost:30000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "spark2.5",
    "messages": [
      {
        "role": "user",
        "content": "What is the capital of Anhui Province?"
      }
    ],
    "max_tokens": 131072,
    "temperature": 1,
    "top_k": -1,
    "top_p": 0.95,
    "repetition_penalty": 1,
    "presence_penalty": 0,
    "frequency_penalty": 0
  }'

vLLM

部署 vLLM

vLLM 提供用于 NVIDIA GPU 部署的官方 Docker 镜像：

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

针对 Ascend NPU，请选择官方镜像，以实现最快部署。

Ascend A2:

export IMAGE=quay.io/ascend/vllm-ascend:nightly-main
docker pull "$IMAGE"

export DEVICE=/dev/davinci0
export MODEL_CACHE="${HOME}/.cache"

mkdir -p "$MODEL_CACHE"

docker run --rm \
    --name vllm-ascend \
    --shm-size=1g \
    --device "$DEVICE" \
    --device /dev/davinci_manager \
    --device /dev/devmm_svm \
    --device /dev/hisi_hdc \
    -v /usr/local/dcmi:/usr/local/dcmi \
    -v /usr/local/bin/npu-smi:/usr/local/bin/npu-smi \
    -v /usr/local/Ascend/driver/lib64/:/usr/local/Ascend/driver/lib64/ \
    -v /usr/local/Ascend/driver/version.info:/usr/local/Ascend/driver/version.info \
    -v /etc/ascend_install.info:/etc/ascend_install.info \
    -v "$MODEL_CACHE:/root/.cache" \
    -p 8000:8000 \
    -it "$IMAGE" bash

Ascend A3：

export IMAGE=quay.io/ascend/vllm-ascend:nightly-main-a3
docker pull "$IMAGE"

export DEVICE0=/dev/davinci0
export DEVICE1=/dev/davinci1
export MODEL_CACHE="${HOME}/.cache"

mkdir -p "$MODEL_CACHE"

docker run --rm \
    --name vllm-ascend \
    --shm-size=1g \
    --device "$DEVICE0" \
    --device "$DEVICE1" \
    --device /dev/davinci_manager \
    --device /dev/devmm_svm \
    --device /dev/hisi_hdc \
    -v /usr/local/dcmi:/usr/local/dcmi \
    -v /usr/local/bin/npu-smi:/usr/local/bin/npu-smi \
    -v /usr/local/Ascend/driver/lib64/:/usr/local/Ascend/driver/lib64/ \
    -v /usr/local/Ascend/driver/version.info:/usr/local/Ascend/driver/version.info \
    -v /etc/ascend_install.info:/etc/ascend_install.info \
    -v "$MODEL_CACHE:/root/.cache" \
    -p 8000:8000 \
    -it "$IMAGE" bash

Ascend 950DT：

export IMAGE=quay.io/ascend/vllm-ascend:nightly-main-a5
docker pull "$IMAGE"

export MODEL_CACHE="${HOME}/.cache"

mkdir -p "$MODEL_CACHE"

docker run --rm \
    --name vllm-ascend \
    --net=host \
    --shm-size=1g \
    --device /dev/davinci0 \
    --device /dev/davinci_manager \
    --device /dev/devmm_svm \
    --device /dev/hisi_hdc \
    -v /usr/local/dcmi:/usr/local/dcmi \
    -v /usr/local/Ascend/driver/tools/hccn_tool:/usr/local/Ascend/driver/tools/hccn_tool \
    -v /usr/local/bin/npu-smi:/usr/local/bin/npu-smi \
    -v /usr/local/Ascend/driver/lib64/:/usr/local/Ascend/driver/lib64/ \
    -v /usr/local/Ascend/driver/version.info:/usr/local/Ascend/driver/version.info \
    -v /etc/ascend_install.info:/etc/ascend_install.info \
    -v "$MODEL_CACHE:/root/.cache" \
    -it "$IMAGE" bash

在容器内安装 Spark 插件：

pip install uv
uv venv ~/spark2_5
source ~/spark2_5/bin/activate
git clone https://github.com/XHToken/Spark-plugin.git
cd ./Spark-plugin
uv pip install .

服务器

vllm serve "/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

客户端

curl -s http://127.0.0.1:30000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "spark25",
    "messages": [{"role": "user", "content": "What is the capital of Anhui Province?"}],
    "temperature": 1.0, 
    "top_k": -1,
    "top_p": 0.95
  }'

MLX

Spark-MLX-LLM 可在本地运行 Spark-X2.5 的原始 Hugging Face checkpoints。它支持 Apple silicon GPU、Linux CPU，以及 Linux 上的 NVIDIA CUDA。无需进行 GGUF 转换。

安装

git clone https://github.com/XHToken/Spark-MLX-LLM.git
cd Spark-MLX-LLM

python3 -m venv .venv
source .venv/bin/activate

# Apple silicon
python -m pip install -e .
# Linux CPU
python -m pip install -e '.[cpu]'
# Linux with CUDA 12
python -m pip install -e '.[cuda12]' 
# Linux with CUDA 13
python -m pip install -e '.[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

构建

git clone https://github.com/XHToken/llama.cpp.git llama.cpp-spark
git clone https://github.com/ollama/ollama.git ollama-spark
cd ollama-spark
export OLLAMA_LLAMA_CPP_SOURCE="$(cd ../llama.cpp-spark && pwd)"
cmake -S . -B build
cmake --build build --parallel 8

创建并运行

创建模型定义后，在一个终端中启动 Ollama 服务：

printf 'FROM /absolute/path/to/your.gguf\n' > ./Modelfile.spark
./ollama serve

在另一个终端中创建并运行模型：

./ollama create Spark-X2.5-4B -f ./Modelfile.spark
./ollama run Spark-X2.5-4B

LM Studio

构建

git clone https://github.com/XHToken/llama.cpp.git llama.cpp-spark
cd llama.cpp-spark
cmake -S . -B build
cmake --build build --parallel 8

设置 LM Studio

关闭 LM Studio。

备份所选的运行时目录：

<LM_STUDIO_HOME>/extensions/backends/<selected-runtime>/

将 llama.cpp-spark 的构建输出复制到所选的运行时目录中，覆盖现有文件。
将 GGUF 模型放置在以下目录中：
```
<LM_STUDIO_HOME>/models/<org>/<name>/
```

macOS 上的示例运行时目录：

./build/bin/* -> ~/.lmstudio/extensions/backends/llama.cpp-mac-arm64-apple-metal-advsimd-<version>/

使用 LM Studio 运行

打开 My Models，选择 Spark-X2.5 模型，点击 Load，然后新建一个对话。

使用 lms CLI 运行

# Replace <model> with a model listed by lms ls.
lms load <model>
lms chat <model>

微调

我们建议使用 Llama-Factory 对该模型进行微调。

许可

Spark-X2.5 模型系列采用 Apache 2.0 许可证。

引用

如果您觉得我们的工作有帮助，欢迎引用。

@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}
}