Instructions to use sensenova/SenseNova-Loop-9B-Preview with libraries, inference providers, notebooks, and local apps. Follow these links to get started.

Libraries

How to use sensenova/SenseNova-Loop-9B-Preview with Transformers:

# Use a pipeline as a high-level helper
from transformers import pipeline

pipe = pipeline("image-text-to-text", model="sensenova/SenseNova-Loop-9B-Preview", trust_remote_code=True)
messages = [
    {
        "role": "user",
        "content": [
            {"type": "image", "url": "https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/p-blog/candy.JPG"},
            {"type": "text", "text": "What animal is on the candy?"}
        ]
    },
]
pipe(text=messages)

# pip install -U transformers accelerate
# Load model directly
from transformers import AutoModelForCausalLM
model = AutoModelForCausalLM.from_pretrained("sensenova/SenseNova-Loop-9B-Preview", trust_remote_code=True, device_map="auto")

Notebooks
Google Colab
Kaggle
Local Apps Settings

vLLM

How to use sensenova/SenseNova-Loop-9B-Preview with vLLM:

Install from pip and serve model

# Install vLLM from pip:
pip install vllm
# Start the vLLM server:
vllm serve "sensenova/SenseNova-Loop-9B-Preview"
# Call the server using curl (OpenAI-compatible API):
curl -X POST "http://localhost:8000/v1/chat/completions" \
	-H "Content-Type: application/json" \
	--data '{
		"model": "sensenova/SenseNova-Loop-9B-Preview",
		"messages": [
			{
				"role": "user",
				"content": [
					{
						"type": "text",
						"text": "Describe this image in one sentence."
					},
					{
						"type": "image_url",
						"image_url": {
							"url": "https://cdn.britannica.com/61/93061-050-99147DCE/Statue-of-Liberty-Island-New-York-Bay.jpg"
						}
					}
				]
			}
		]
	}'

Use Docker

docker model run hf.co/sensenova/SenseNova-Loop-9B-Preview

SGLang

How to use sensenova/SenseNova-Loop-9B-Preview with SGLang:

Install from pip and serve model

# Install SGLang from pip:
pip install sglang
# Start the SGLang server:
python3 -m sglang.launch_server \
    --model-path "sensenova/SenseNova-Loop-9B-Preview" \
    --host 0.0.0.0 \
    --port 30000
# Call the server using curl (OpenAI-compatible API):
curl -X POST "http://localhost:30000/v1/chat/completions" \
	-H "Content-Type: application/json" \
	--data '{
		"model": "sensenova/SenseNova-Loop-9B-Preview",
		"messages": [
			{
				"role": "user",
				"content": [
					{
						"type": "text",
						"text": "Describe this image in one sentence."
					},
					{
						"type": "image_url",
						"image_url": {
							"url": "https://cdn.britannica.com/61/93061-050-99147DCE/Statue-of-Liberty-Island-New-York-Bay.jpg"
						}
					}
				]
			}
		]
	}'

Use Docker images

docker run --gpus all \
    --shm-size 32g \
    -p 30000:30000 \
    -v ~/.cache/huggingface:/root/.cache/huggingface \
    --env "HF_TOKEN=<secret>" \
    --ipc=host \
    lmsysorg/sglang:latest \
    python3 -m sglang.launch_server \
        --model-path "sensenova/SenseNova-Loop-9B-Preview" \
        --host 0.0.0.0 \
        --port 30000
# Call the server using curl (OpenAI-compatible API):
curl -X POST "http://localhost:30000/v1/chat/completions" \
	-H "Content-Type: application/json" \
	--data '{
		"model": "sensenova/SenseNova-Loop-9B-Preview",
		"messages": [
			{
				"role": "user",
				"content": [
					{
						"type": "text",
						"text": "Describe this image in one sentence."
					},
					{
						"type": "image_url",
						"image_url": {
							"url": "https://cdn.britannica.com/61/93061-050-99147DCE/Statue-of-Liberty-Island-New-York-Bay.jpg"
						}
					}
				]
			}
		]
	}'

Docker Model Runner
How to use sensenova/SenseNova-Loop-9B-Preview with Docker Model Runner:
```
docker model run hf.co/sensenova/SenseNova-Loop-9B-Preview
```

SenseNova-Loop-9B-Preview / README_CN.md

jklyuiozcx

docs: consolidate speculative decoding training instructions

9937e91 verified about 1 hour ago

preview code

Raw History Blame Contribute Delete

12.7 kB

metadata

license: apache-2.0
language:
  - en
  - zh
library_name: transformers
pipeline_tag: image-text-to-text
tags:
  - multimodal
  - text-generation
  - image-text-to-text
  - looped-transformer
  - mhc
  - custom_code

SenseNova-Loop-9B-Preview

English | 简体中文

📣 最新动态

[2026.10.30] 我们发布了 SenseNova-Loop-9B-Preview，一个面向长上下文与智能体工作流的循环多模态模型。

🚀 SenseNova-Loop-9B-Preview

🎬 效果展示（由商汤小浣熊创作）

动效设计

PPT 设计

数据分析

模型概述

SenseNova-Loop-9B-Preview 是一个面向长上下文和智能体工作流的多模态语言模型。模型接收文本和图像输入，生成文本输出，适用于结合文档理解、编程及外部工具交互的应用。

模型将循环解码器与双流流形约束超连接（mHC）相结合。一段连续的解码器层共享权重，依次执行两遍；循环模块中的可学习映射负责管理两条残差流之间的信息流动。通过这种设计，模型无需复制循环模块的参数，就能增加实际执行深度。

已有训练方案结合了长序列、多模态输入和带监督的任务轨迹，最长训练序列为 262,144 个 token。为更好地发挥模型性能，建议使用我们提供的部署环境与参数配置。

模型亮点

共享循环模块：24 个解码器层依次执行两遍，使 32 个独立层在一次前向传播中完成 56 次层计算。
双流 mHC：通过可学习映射，对循环模块中两条残差流的信息进行路由与融合。
混合注意力：解码器以四层为一个循环单元，交替使用线性注意力与全注意力。
长上下文多模态训练：已有训练方案涵盖文本、图像、代码和工具调用轨迹，序列长度最长为 256K token。

📊 核心评测

模型规格

项目	SenseNova-Loop-9B-Preview
架构	自回归多模态解码器；循环模块采用双流 mHC
参数规模	总共约 9B 参数，推理实际约 14.6B 参数
输入 / 输出	文本和图像 / 文本
独立解码器层数	32
循环层范围 / 执行次数	[4, 28) / 2 次，共享权重
解码器层执行次数	每次前向传播执行 56 次
mHC 残差流数量	2
训练上下文长度	最长 262,144 个 token
现有导出精度	主干为 BF16；mHC 路由参数为 FP32

模型架构

SenseNova-Loop-9B-Preview 以 32 层多模态解码器为基础，结合共享权重的循环计算、混合注意力与双流流形约束超连接（mHC）。下文将分别介绍这些组件如何拓展模型的计算路径，并组织模型内部的信息流动。

循环解码器

输入首先经过第 0–3 层，随后依次通过同一组第 4–27 层两次，最后由第 28–31 层和输出头生成模型输出。若用 B 表示循环模块、h 表示其输入，则循环计算可写为 **B(B(h))**。

推理时，模型每次前向传播完成 56 次解码器层计算，只需存储 32 层解码器权重。循环模块在两次执行中复用同一组权重，第二次执行以第一次的输出作为输入。

混合注意力

解码器交替使用线性注意力层与全注意力层。每四层为一组，依次包含三层线性注意力和一层全注意力。循环模块的边界与完整的四层组对齐，因此两次执行都保持相同的注意力排列。

双流 mHC

在循环模块中，mHC 使用两条残差流传递解码器层计算前后的信息。可学习映射决定各层如何读取残差流、混合流间信息，以及将层输出写入残差状态。流间混合映射采用 Sinkhorn 归一化进行约束；已有配置使用 20 次迭代。

循环层范围、执行次数和 mHC 路由参数共同构成模型检查点的执行配置。兼容的推理实现需要加载这些参数，并保持相同的计算顺序。

配置	数值
独立解码器层数 / 执行次数	32 / 56
循环层范围 / 执行次数	[4, 28) / 2
隐藏层维度	4,096
前馈网络维度	12,288
词表大小	248,320
全注意力头数 / KV 头数	16 / 4
mHC 残差流数量 / Sinkhorn 迭代次数	2 / 20

推理加速

SenseNova-Loop-9B-Preview 已支持 MTP 推理加速。Dspark 和 Dflash2 正在开发中，目前处于训练阶段。

方法	状态
MTP	已可用
Dspark	训练中
Dflash2	训练中

实际加速效果取决于任务负载、硬件和服务配置。

模型与资源

资源	状态
模型权重	Hugging Face 模型页面
Transformers 推理实现	发布详情待公布
技术报告	TBD

快速开始

使用 Transformers 从 Hugging Face 仓库或本地模型目录中加载模型及其自定义实现。下面的示例展示了如何在单张 GPU 上进行文本生成。

环境要求

已核对的推理环境使用 Transformers 5.18.0 和 PyTorch 2.11.0（CUDA 13.0）。模型目录需要包含配置、分词器、对话模板、模型代码，以及可访问的权重分片。

请先安装与 CUDA 环境兼容的 PyTorch 版本，再安装其余依赖：

python -m pip install "transformers==5.18.0" accelerate safetensors

使用 Transformers 生成文本

将 model_id 设置为 Hugging Face 仓库 ID 或本地模型目录，然后运行：

import torch
from transformers import AutoModelForCausalLM, AutoTokenizer

model_id = "sensenova/SenseNova-Loop-9B-Preview"
device = "cuda:0"

tokenizer = AutoTokenizer.from_pretrained(model_id, trust_remote_code=True)
model = AutoModelForCausalLM.from_pretrained(
    model_id,
    trust_remote_code=True,
    dtype=torch.bfloat16,
    device_map={"": device},
).eval()

messages = [{"role": "user", "content": "13 乘以 7 等于多少？只回答数字。"}]
prompt = tokenizer.apply_chat_template(
    messages,
    tokenize=False,
    add_generation_prompt=True,
    enable_thinking=False,
)
inputs = tokenizer(prompt, return_tensors="pt").to(device)

with torch.inference_mode():
    outputs = model.generate(
        **inputs,
        max_new_tokens=256,
        do_sample=False,
        use_cache=True,
    )

response = tokenizer.decode(
    outputs[0, inputs.input_ids.shape[1]:],
    skip_special_tokens=True,
)
print(response)

示例采用贪心解码，最多生成 256 个新 token。将 enable_thinking=True 可开启思考模式，修改 device 可选择其他 GPU。

trust_remote_code=True 用于加载 SenseNova Loop 的自定义模型实现。

训练

主模型训练

在配置好的训练环境中，可使用以下命令在单机 8 卡上对 SenseNova-Loop-9B-Preview 进行采用 mHC 的微调：

git clone https://github.com/OpenSenseNova/torchtitan.git
cd torchtitan
MODEL_PATH=/path/to/SenseNova-Loop-9B-Preview DATASET=/path/to/train.jsonl \
  bash examples/train/SenseNova-Loop-9B-Preview/mhc2_loop2_titan.sh

请将 /path/to/train.jsonl 替换为你的 SFT 数据集路径。配置选项、DPO 和 MTP 训练方法请参见训练指南。

推测解码训练

如需在单机 8 卡上为 SenseNova-Loop-9B-Preview 训练 DSpark 或 DFlash2 draft model，请使用 SenseSpec 仓库提供的训练脚本。

首先，克隆仓库并进入项目目录：

git clone https://github.com/OpenSenseNova/SenseSpec.git
cd SenseSpec

DSpark 训练

运行以下命令训练 DSpark draft model：

bash examples/SenseNova-Loop-9B-Preview-dspark/run.sh

DFlash2 训练

运行以下命令训练 DFlash2 draft model：

bash examples/SenseNova-Loop-9B-Preview-dflash2/run.sh

部署

LightLLM

以下为四卡 GPU 部署示例，请将本地模型路径替换为实际路径：

docker pull ghcr.io/modeltc/lightllm:main

docker run --rm --gpus all --ipc=host -p 8000:8000 \
  -v /path/to/SenseNova-Loop-9B-Preview:/model \
  -e LOADWORKER=4 -e LIGHTLLM_TRITON_AUTOTUNE_LEVEL=1 \
  ghcr.io/modeltc/lightllm:main \
  python -m lightllm.server.api_server \
    --model_dir /model --model_name SenseNova-Loop-9B-Preview \
    --tp 4 --host 0.0.0.0 --port 8000

请求示例：

curl http://localhost:8000/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{"model": "SenseNova-Loop-9B-Preview", "messages": [{"role": "user", "content": "Hello!"}], "max_tokens": 128}'

SGLang

请使用包含 SenseNova Loop 实现的 SGLang PR #47281 对应版本，并将下方模型路径替换为本地 checkpoint 目录：

git clone https://github.com/sgl-project/sglang.git
cd sglang
git fetch origin pull/47281/head
git checkout -b sensenova-loop FETCH_HEAD
python -m pip install -e ./python

sglang serve --model-path /path/to/SenseNova-Loop-9B-Preview

vLLM

请使用包含 SenseNova Loop 实现的 vLLM PR #64832 对应版本进行推理：

git clone https://github.com/vllm-project/vllm.git
cd vllm
git fetch origin pull/64832/head
git checkout -b sensenova-loop FETCH_HEAD
python -m pip install -e .

vllm serve sensenova/SenseNova-Loop-9B-Preview \
  --served-model-name sensenova_loop \
  --tensor-parallel-size 4 \
  --dtype bfloat16

许可证与引用

许可证：Apache License 2.0。
引用：

@misc{sensenova2026loop,
  title        = {{SenseNova-Loop-9B-Preview}},
  author       = {{SenseNova}},
  year         = {2026},
  howpublished = {Hugging Face model repository},
  url          = {https://huggingface.co/sensenova/SenseNova-Loop-9B-Preview}
}