如何在10分钟内部署Spark-X2.5-4B-FP8：SGLang/vLLM/Ollama一站式快速上手指南

Spark-X2.5-4B-FP8 是 SparkLLM 团队推出的 4B 参数、FP8 量化版语言模型，原生支持 100 万 token 上下文，擅长对话、写作、推理、编码与 Agent 任务。本文是一份面向新手的 Spark-X2.5-4B-FP8 快速部署指南，带你用 SGLang、vLLM、Ollama 三条主流路线，在 10 分钟内跑起属于自己的模型服务。

Spark-X2.5-4B-FP8 是什么？为什么值得本地部署？

• 小而强：4B 参数规模 + FP8 量化（见 config.json），权重仅约 4~5 GB，消费级显卡即可运行；
• 100 万 token 长上下文：max_position_embeddings 达 1,048,576（见 config.json），可一次"读完"整本小说；
• 混合注意力架构：每 4 层中 1 层全注意力 + 3 层滑动窗口注意力（sliding_window: 512，36 层结构见 config.json），大幅降低长文本的 KV-Cache 开销，架构实现可在 modeling_spark.py 中查看；
• 推理 + 工具调用：默认开启思考模式（thinking mode），并内置工具调用解析器，可对接 Codex、Claude Code 等 Agent 框架；
• 生态兼容：官方适配 vLLM、SGLang、llama.cpp、MLX，也可通过 Ollama、LM Studio 快速部署。

部署前准备：下载模型权重并配置路径

获取模型文件

本仓库即为模型权重（Hugging Face Transformers 格式），克隆下来即可获得全部权重与配置：

git clone https://gitcode.com/SparkLLM/Spark-X2.5-4B-FP8
export MODEL_PATH=/absolute/path/to/Spark-X2.5-4B-FP8

目录中除 5 个 *.safetensors 权重大文件外，还有几个部署时会被用到的关键文件：

文件	作用
config.json	模型结构：层数、注意力配置、FP8 量化方式
generation_config.json	官方推荐采样参数
chat_template.jinja	对话模板，控制思考模式开关
configuration_spark.py / modeling_spark.py	自定义模型定义（配合 --trust-remote-code 使用）

💡 显存参考：FP8 权重约 4~5 GB；若要拉满 100 万上下文，KV-Cache 会占用大量显存。显存紧张时把上下文长度调小即可（下文均有说明）。

方式一：SGLang 部署（NVIDIA GPU 最快路线）

SGLang 的官方镜像已针对 Spark-X2.5 运行时做了适配，是体验长上下文与工具调用最完整的路线。

第 1 步：拉取镜像

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

第 2 步：启动 OpenAI 兼容 API 服务

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

关键参数解读：

• --served-model-name spark2.5：对外暴露的模型名，客户端请求必须与之一致；
• --tool-call-parser spark25 / --reasoning-parser qwen3：分别启用 Spark 工具调用解析与思考（reasoning）内容解析；
• --context-length 1048576：100 万上下文；显存不足时改小，如 --context-length 32768；
• --chat-template：指定 chat_template.jinja，保证对话与思考行为与官方一致。

昇腾 NPU 用户可参考 README.md 中的 Ascend 专用命令（A2 / A3 分别使用不同镜像与设备挂载）。

第 3 步：发起第一次对话

curl -s http://localhost:30000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "spark2.5",
    "messages": [{"role": "user", "content": "安徽省的省会是哪里？"}],
    "max_tokens": 131072,
    "temperature": 1,
    "top_k": -1,
    "top_p": 0.95
  }'

返回 JSON 中出现回答即代表部署成功 🎉。因为接口与 OpenAI 完全兼容，你现有的 OpenAI SDK 代码只需把 base_url 和 model 换掉即可接入。

方式二：vLLM 部署（一条命令起服务）

vLLM 的官方 Docker 镜像开箱即用，命令更短，适合想快速验证的用户（完整示例见 README.md）：

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

• --trust-remote-code：加载仓库内自定义模型代码 modeling_spark.py 的必要参数；
• --enable-prefix-caching：前缀缓存对 Agent 多轮对话提速非常明显，建议保留；
• --served-model-name spark25：注意这里的名字与 SGLang 的 spark2.5 不同，客户端别写混。

调用示例：

curl -s http://127.0.0.1:30000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "spark25",
    "messages": [{"role": "user", "content": "用一句话解释什么是 KV-Cache"}],
    "temperature": 1.0,
    "top_k": -1,
    "top_p": 0.95
  }'

方式三：Ollama 部署（适合本地轻量运行）

Ollama 走 GGUF 量化路线，适合不想碰 Docker、只想 ollama run 直接聊天的场景。由于 Spark-X2.5 采用自定义混合注意力架构，需要构建支持 Spark 的 llama.cpp 分支版 Ollama，不能直接使用官方预编译版。

完整构建步骤见 README.md，流程为：编译 llama.cpp 的 Spark 分支 → 指定源码目录重新编译 Ollama。随后创建并运行模型：

# 终端 1：启动服务
printf 'FROM /absolute/path/to/your.gguf\n' > ./Modelfile.spark
./ollama serve

# 终端 2：创建模型并开聊
./ollama create Spark-X2.5-4B -f ./Modelfile.spark
./ollama run Spark-X2.5-4B

若你更习惯图形界面，LM Studio 路线同样适用：替换其内置 runtime 为 Spark 版 llama.cpp 构建产物后即可加载 GGUF 模型，步骤见 README.md。

推荐采样参数与思考模式设置

官方推荐采样参数记录在 generation_config.json 中，请求时建议保持一致：

参数	推荐值	说明
temperature	1.0	官方基准评测即在此值下完成
top_p	0.95	与 temperature 搭配使用
top_k	-1	表示不启用 top_k 截断
max_tokens	按需（如 131072）	4B 模型输出上限足够长

思考模式（thinking mode）默认开启：对话模板将 enable_thinking 默认设为 true（见 chat_template.jinja），模型会先输出推理过程再给出答案。对简单问答想省 token、降延迟时，可在请求中临时关闭：

"chat_template_kwargs": {"enable_thinking": false}

常见问题快速排查

1. 显存不足（OOM）：优先调小 --context-length（如 32768），或降低 SGLang 的 --mem-fraction-static / vLLM 的 --gpu-memory-utilization；
2. 请求返回 404 / model not found：客户端 model 字段与服务端 --served-model-name 不一致，检查是 spark2.5 还是 spark25；
3. 对话格式异常、思考内容混在正文里：确认启动时挂载并指定了 --chat-template .../chat_template.jinja；
4. 输出与预期差异大：检查采样参数是否与 generation_config.json 一致（temperature=1.0、top_p=0.95）；
5. vLLM 启动报加载模型失败：确认已加 --trust-remote-code，且模型目录包含 config.json、modeling_spark.py 等全部文件。

总结

路线	适合人群	特点
SGLang	生产 / 长上下文 / Agent 场景	工具调用与 reasoning 解析最完整
vLLM	快速验证 / OpenAI 兼容服务	命令最短，前缀缓存友好
Ollama	本地轻量聊天	图形生态友好，需 GGUF 与定制构建

三条路线任选其一，配合 MODEL_PATH 指向本仓库目录，10 分钟内即可与 Spark-X2.5-4B-FP8 开始对话。后续若希望继续进阶，可尝试用 LLaMA-Factory 对模型做微调（参考 README.md），或在 configuration_spark.py 中深入了解混合注意力的配置细节。