🔥 新闻

• 2025年9月：RLRF被NeurIPS 2025接收，
  • 我们对StarVector的后续工作RLRF已被NeurIPS 2025接收！请查看论文[链接]
• 2025年3月：StarVector被CVPR 2025接收，
  • StarVector已被CVPR 2025接收！请查看论文[链接]
  • 更多信息请访问我们的网站[链接]
  • StarVector模型现已在HuggingFace上线！[链接] [链接]
  • SVGBench和SVG-Stack数据集现已在HuggingFace Datasets上线！[链接] [链接]

🚀 简介

StarVector是一个用于可缩放矢量图形（SVG）生成的多模态视觉-语言模型。它可以用于执行图像到SVG和文本到SVG的生成任务。我们将图像生成问题建模为代码生成任务，充分利用多模态VLM的强大能力。

摘要：可缩放矢量图形（SVG）因其可缩放性和多功能性，在现代图像渲染中至关重要。以往的SVG生成方法主要集中在基于曲线的矢量化上，缺乏语义理解，常常产生伪影，并且难以处理除路径曲线之外的SVG图元。为了解决这些问题，我们提出了StarVector，一个用于SVG生成的多模态大型语言模型。它通过理解图像语义并使用SVG图元来实现紧凑、精确的输出，从而完成图像矢量化。与传统方法不同，StarVector直接在SVG代码空间中工作，利用视觉理解来准确应用SVG图元。为了训练StarVector，我们创建了SVG-Stack，一个包含200万样本的多样化数据集，能够实现跨矢量化任务的泛化，并精确使用椭圆、多边形和文本等图元。我们还解决了SVG评估中的挑战，表明基于像素的指标如MSE无法捕捉矢量图形的独特特性。为此，我们引入了SVG-Bench，一个涵盖10个数据集和3项任务的基准测试：图像到SVG、文本到SVG生成以及图表生成。借助这一设置，StarVector实现了最先进的性能，生成了更加紧凑且语义丰富的SVG。

多模态架构

StarVector采用多模态架构来处理图像和文本。在进行图像到SVG转换（即图像矢量化）时，图像会被投影为视觉标记，然后生成SVG代码。而在进行文本到SVG转换时，模型仅接收文本指令（不提供图像），并生成全新的SVG。该LLM基于StarCoder，我们利用其编码技能来实现SVG生成。

📖 目录

• 💿 安装
• 🏎️ 快速入门 - 图像到SVG生成
• 🎨 模型
• 📊 数据集
• 🏋️‍♂️ 训练
• 🏆 SVG-Bench上的评估
• 🧩 演示
• 📚 引用
• 📝 许可证

安装

1. 克隆本仓库并进入star-vector文件夹

git clone https://github.com/joanrod/star-vector.git
cd star-vector

2. 安装软件包

conda create -n starvector python=3.11.3 -y
conda activate starvector
pip install --upgrade pip  # 启用PEP 660支持
pip install -e .

3. 安装额外的训练相关包

pip install -e ".[train]"

升级到最新代码库

git pull
pip install -e .

快速入门 - 图像转 SVG 生成

from PIL import Image
from starvector.model.starvector_arch import StarVectorForCausalLM
from starvector.data.util import process_and_rasterize_svg

model_name = "starvector/starvector-8b-im2svg"

starvector = StarVectorForCausalLM.from_pretrained(model_name)

starvector.cuda()
starvector.eval()

image_pil = Image.open('assets/examples/sample-0.png')
image = starvector.process_images([image_pil])[0].cuda()
batch = {"image": image}

raw_svg = starvector.generate_im2svg(batch, max_length=1000)[0]
svg, raster_image = process_and_rasterize_svg(raw_svg)

从 HuggingFace AutoModel 使用

from PIL import Image
from transformers import AutoModelForCausalLM, AutoTokenizer, AutoProcessor
from starvector.data.util import process_and_rasterize_svg
import torch

model_name = "starvector/starvector-8b-im2svg"

starvector = AutoModelForCausalLM.from_pretrained(model_name, torch_dtype=torch.float16, trust_remote_code=True)
processor = starvector.model.processor
tokenizer = starvector.model.svg_transformer.tokenizer

starvector.cuda()
starvector.eval()

image_pil = Image.open('assets/examples/sample-18.png')

image = processor(image_pil, return_tensors="pt")['pixel_values'].cuda()
if not image.shape[0] == 1:
    image = image.squeeze(0)
batch = {"image": image}

raw_svg = starvector.generate_im2svg(batch, max_length=4000)[0]
svg, raster_image = process_and_rasterize_svg(raw_svg)

模型

我们提供了用于图像转 SVG 矢量化处理的 Hugging Face 🤗 模型检查点，分别适用于 💫 StarVector-8B 和 💫 StarVector-1B。以下是使用 DinoScore 指标在 SVG-Bench 上的评估结果。

方法	SVG-Stack	SVG-Fonts	SVG-Icons	SVG-Emoji	SVG-Diagrams
AutoTrace	0.942	0.954	0.946	0.975	0.874
Potrace	0.898	0.967	0.972	0.882	0.875
VTracer	0.954	0.964	0.940	0.981	0.882
Im2Vec	0.692	0.733	0.754	0.732	-
LIVE	0.934	0.956	0.959	0.969	0.870
DiffVG	0.810	0.821	0.952	0.814	0.822
GPT-4-V	0.852	0.842	0.848	0.850	-
💫 StarVector-1B (🤗 链接)	0.926	0.978	0.975	0.929	0.943
💫 StarVector-8B (🤗 链接)	0.966	0.982	0.984	0.981	0.959

注: StarVector 模型不适用于自然图像或插图，因为它们并未针对此类图像进行训练。这些模型在矢量化图标、标志、技术图表、图形和统计图方面表现出色。

数据集 - SVG-Bench

SVG-Bench 是一个用于评估 SVG 生成模型的基准测试。它包含 10 个数据集和 3 项任务：图像转 SVG、文本转 SVG 和图表转 SVG。

请参阅我们的 Huggingface 🤗 数据集合集

数据集	训练集	验证集	测试集	Token 长度	SVG 原语	注释
SVG-Stack (🤗 链接)	2.1M	108k	5.7k	1,822 ± 1,808	全部	字幕
SVG-Stack_sim (🤗 链接)	601k	30.1k	1.5k	2k ± 918	向量路径	-
SVG-Diagrams (🤗 链接)	-	-	472	3,486 ± 1,918	全部	-
SVG-Fonts (🤗 链接)	1.8M	91.5k	4.8k	2,121 ± 1,868	向量路径	字体字母
SVG-Fonts_sim (🤗 链接)	1.4M	71.7k	3.7k	1,722 ± 723	向量路径	字体字母
SVG-Emoji (🤗 链接)	8.7k	667	668	2,551 ± 1,805	全部	-
SVG-Emoji_sim (🤗 链接)	580	57	96	2,448 ± 1,026	向量路径	-
SVG-Icons (🤗 链接)	80.4k	6.2k	2.4k	2,449 ± 1,543	向量路径	-
SVG-Icons_sim (🤗 链接)	80,435	2,836	1,277	2,005 ± 824	向量路径	-
SVG-FIGR (🤗 链接)	270k	27k	3k	5,342 ± 2,345	向量路径	类别、标题

我们提供了关于我们训练和评估实验中所使用的数据集的统计数据概览。这些数据集均包含在 SVG-Bench 中。下标 sim 表示数据集的简化版本，这是某些基线方法所要求的。

训练

确认依赖项已安装

pip install -e ".[train]"

设置环境变量

我们建议设置以下环境变量：

  export HF_HOME=<您希望存储模型的文件夹路径>
  export HF_TOKEN=<您的 Hugging Face 令牌>
  export WANDB_API_KEY=<您的 WandB 令牌>
  export OUTPUT_DIR=<输出路径>

进入仓库根目录。

cd star-vector

图像转 SVG 预训练（阶段 1）

我们为 StarVector-1B 和 StarVector-8B 提供了不同的训练方法。StarVector-1B 可以使用 Deepspeed 进行训练，而 StarVector-8B 则需要 FSDP。

StarVector-1B 训练

您可以使用以下命令，通过 Deepspeed 和 Accelerate 在 SVG-Stack 数据集上对 StarVector-1B 进行图像转 SVG 矢量化任务的预训练：

# StarVector-1B
accelerate launch --config_file configs/accelerate/deepspeed-8-gpu.yaml starvector/train/train.py config=configs/models/starvector-1b/im2svg-stack.yaml

StarVector-8B 训练

您可以使用以下命令，通过 FSDP 和 Accelerate 在 SVG-Stack 数据集上对 StarVector-8B 进行图像转 SVG 矢量化任务的预训练。我们还提供了 torchrun 命令，以支持多节点和多 GPU 的训练：

# StarVector-8B
torchrun \
  --nproc-per-node=8 \
  --nnodes=1 \
  starvector/train/train.py \
  config=configs/models/starvector-8b/im2svg-stack.yaml

微调 StarVector（阶段 2）

在对 StarVector 进行图像矢量化预训练之后，我们会对其在其他 SVG 任务上进行微调，例如文本转 SVG 以及 SVG-Bench 数据集。

文本转 SVG 微调

# StarVector-1B
accelerate launch --config_file configs/accelerate/deepspeed-8-gpu.yaml starvector/train/train.py config=configs/models/starvector-1b/text2svg-stack.yaml

SVG-Bench 微调

# StarVector-8B
torchrun \
  --nproc-per-node=8 \
  --nnodes=1 \
  starvector/train/train.py \
  config=configs/models/starvector-8b/svg-bench-stack.yaml

StarVector-1B

accelerate launch --config_file config/accelerate/deepspeed-8-gpu.yaml starvector/train/train.py config=configs/models/starvector-1b/text2svg-stack.yaml

StarVector-8B

torchrun
--nproc-per-node=8
--nnodes=1
starvector/train/train.py
config=configs/models/starvector-8b/text2svg-stack.yaml

#### SVG-Bench 微调

```bash
# StarVector-1B
accelerate launch --config_file config/accelerate/deepspeed-8-gpu.yaml starvector/train/train.py config=configs/models/starvector-1b/im2svg-{fonts,icons,emoji}.yaml

# StarVector-8B
torchrun \
  --nproc-per-node=8 \
  --nnodes=1 \
  starvector/train/train.py \
  config=configs/models/starvector-8b/im2svg-{fonts,icons,emoji}.yaml

我们还在 scripts/train/* 中提供了 Shell 脚本。

在 SVG 基准上的验证（⭐ SVG-Bench）

我们在 ⭐ SVG-Bench 基准上对 StarVector 进行了验证。我们提供了一个 SVGValidator 类，允许您使用 1) HuggingFace 生成后端 或 2) VLLM 后端 来运行 StarVector。后者由于采用了分页注意力机制，速度显著更快。

HuggingFace 生成后端

我们先从 StarVector-1B 和 StarVector-8B 在 SVG-Stack 上的评估开始，使用 HuggingFace 生成后端（StarVectorHFAPIValidator）。要覆盖输入参数，您可以按照 YAML 文件的结构添加 CLI 参数。

# StarVector-1B 在 SVG-Stack 上，使用 HuggingFace 后端
python starvector/validation/validate.py \
config=configs/generation/hf/starvector-1b/im2svg.yaml \
dataset.dataset_name=starvector/svg-stack

# StarVector-8B 在 SVG-Stack 上，使用原生 HuggingFace 生成 API
python starvector/validation/validate.py \
config=configs/generation/hf/starvector-8b/im2svg.yaml \
dataset.dataset_name=starvector/svg-stack

vLLM 后端

要使用 vLLM 后端（StarVectorVLLMAPIValidator），请先安装我们基于 VLLM 的 StarVector 分支，这里。

git clone https://github.com/starvector/vllm.git
cd vllm
pip install -e .

然后，使用 vllm 配置文件启动（它使用 StarVectorVLLMValidator）：

# StarVector-1B
python starvector/validation/validate.py \
config=configs/generation/vllm/starvector-1b/im2svg.yaml \
dataset.dataset_name=starvector/svg-stack

# StarVector-8B
python starvector/validation/validate.py \
config=configs/generation/vllm/starvector-8b/im2svg.yaml \
dataset.dataset_name=starvector/svg-stack

我们在 scripts/eval/* 中提供了评估脚本。

StarVector 演示

演示提供了两种将图像转换为 SVG 代码的方式：

1. HuggingFace 生成功能
2. VLLM（推荐）——提供更快的生成速度

选项 1：使用 Gradio Web UI 的 HuggingFace 生成

我们提供了一个 Gradio Web UI，供您体验我们的模型。

启动控制器

python -m starvector.serve.controller --host 0.0.0.0 --port 10000

启动 Gradio Web 服务器。

python -m starvector.serve.gradio_web_server --controller http://localhost:10000 --model-list-mode reload --port 7000

现在您已经启动了 Gradio 网页界面。您可以打开屏幕上显示的 URL 来访问该界面。您可能会注意到模型列表中还没有任何模型。不用担心，因为我们还没有启动任何模型工作进程。当您启动一个模型工作进程时，模型列表会自动更新。

启动模型工作进程

这是实际在 GPU 上执行推理的 工作进程。每个工作进程负责 --model-path 中指定的单个模型。

python -m starvector.serve.model_worker --host 0.0.0.0 --controller http://localhost:10000 --port 40000 --worker http://localhost:40000 --model-path joanrodai/starvector-1.4b

等待进程完成模型加载，并看到“Uvicorn 正在运行…”的消息。此时刷新您的 Gradio 网页界面，您就会在模型列表中看到刚刚启动的模型。

您可以根据需要启动任意数量的工作进程，并在同一 Gradio 界面中比较不同的模型检查点。请确保 --controller 保持一致，而将 --port 和 --worker 分别设置为不同的端口号以区分各个工作进程。

vllm serve starvector/starvector-8b-im2svg --chat-template configs/chat-template.jinja --trust-remote-code --port 8001 --max-model-len 16000

python -m starvector.serve.model_worker --host 0.0.0.0 --controller http://localhost:10000 --port <不同于40000，比如40001> --worker http://localhost:<相应地更改，即40001> --model-path <ckpt2>

选项 2：启动 VLLM

0. 请记住克隆 starvector/vllm 分支（其中包含针对 StarVector 的修改）。

git clone https://github.com/starvector/vllm.git
cd vllm
pip install -e .

1. 调用以下命令来启动 VLLM 端点：

vllm serve starvector/starvector-1b-im2svg --chat-template configs/chat-template.jinja --trust-remote-code --port 8000 --max-model-len 8192

2. 创建 VLLM 演示：

python -m starvector.serve.vllm_api_gradio.controller --host 0.0.0.0 --port 10000
python -m starvector.serve.vllm_api_gradio.gradio_web_server --controller http://localhost:10000 --model-list-mode reload --port 7000
python -m starvector.serve.vllm_api_gradio.model_worker --host 0.0.0.0 --controller http://localhost:10000 --port 40000 --worker http://localhost:40000 --model-name starvector/starvector-1b-im2svg --vllm-base-url http://localhost:8000

3. 通过 VLLM 提供更多模型并调用新的模型工作进程来添加更多模型：

vllm serve starvector/starvector-8b-im2svg --chat-template configs/chat-template.jinja --trust-remote-code --port 8001 --max-model-len 16384

python -m starvector.serve.vllm_api_gradio.model_worker --host 0.0.0.0 --controller http://localhost:10000 --port 40001 --worker http://localhost:40001 --model-name starvector/starvector-8b-im2svg --vllm-base-url http://localhost:8001

引用

@misc{rodriguez2024starvector,
      title={StarVector: 从图像和文本生成可缩放矢量图形代码}, 
      author={Juan A. Rodriguez 和 Abhay Puri、Shubham Agarwal、Issam H. Laradji、Pau Rodriguez、Sai Rajeswar、David Vazquez、Christopher Pal 和 Marco Pedersoli},
      year={2024},
      eprint={2312.11556},
      archivePrefix={arXiv},
      primaryClass={cs.CV},
      url={https://arxiv.org/abs/2312.11556}, 
}

许可证

本项目采用 Apache License, Version 2.0 许可证——详情请参阅 LICENSE 文件。

StarVector 快速上手指南

StarVector 是一个多模态视觉 - 语言模型，专为生成可缩放矢量图形（SVG）代码而设计。它支持从图像生成 SVG（Image-to-SVG）和从文本生成 SVG（Text-to-SVG），将图像生成任务转化为代码生成任务。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统: Linux 或 macOS (Windows 用户建议使用 WSL2)
• Python 版本: 3.11.3 (推荐严格匹配以避免依赖冲突)
• 包管理器: Conda (推荐) 或 Pip
• GPU: 推荐使用 NVIDIA GPU 并安装对应的 CUDA 驱动（用于加速推理和训练）
• 前置依赖: Git

安装步骤

1. 克隆项目代码

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

git clone https://github.com/joanrod/star-vector.git
cd star-vector

2. 创建并激活虚拟环境

使用 Conda 创建名为 starvector 的独立环境：

conda create -n starvector python=3.11.3 -y
conda activate starvector

3. 安装核心依赖

升级 pip 以支持最新安装标准，并安装项目核心包：

pip install --upgrade pip
pip install -e .

提示：如果您计划进行模型训练，请额外运行以下命令安装训练依赖：

pip install -e ".[train]"

4. 更新代码（可选）

如果需要获取最新代码库：

git pull
pip install -e .

基本使用：图像转 SVG (Image2SVG)

以下是最简单的使用示例，展示如何加载预训练模型并将图片转换为 SVG 代码。本示例使用 Hugging Face AutoModel 接口，兼容性更好。

Python 代码示例

from PIL import Image
from transformers import AutoModelForCausalLM, AutoTokenizer, AutoProcessor
from starvector.data.util import process_and_rasterize_svg
import torch

# 1. 指定模型名称 (提供 1B 和 8B 两个版本)
model_name = "starvector/starvector-8b-im2svg"

# 2. 加载模型 (使用 float16 节省显存)
starvector = AutoModelForCausalLM.from_pretrained(
    model_name, 
    torch_dtype=torch.float16, 
    trust_remote_code=True
)

# 获取处理器和分词器
processor = starvector.model.processor
tokenizer = starvector.model.svg_transformer.tokenizer

# 3. 将模型移至 GPU 并设置为评估模式
starvector.cuda()
starvector.eval()

# 4. 加载输入图像
# 请确保 'assets/examples/sample-18.png' 替换为您本地的图片路径
image_pil = Image.open('assets/examples/sample-18.png')

# 5. 预处理图像
image = processor(image_pil, return_tensors="pt")['pixel_values'].cuda()
if not image.shape[0] == 1:
    image = image.squeeze(0)
    
batch = {"image": image}

# 6. 生成 SVG 代码
# max_length 控制生成代码的最大长度，可根据图像复杂度调整
raw_svg = starvector.generate_im2svg(batch, max_length=4000)[0]

# 7. 后处理：整理 SVG 格式并生成对应的栅格化预览图
svg_code, raster_image = process_and_rasterize_svg(raw_svg)

# 打印生成的 SVG 代码前 200 个字符
print(svg_code[:200]) 

注意事项

• 适用场景: StarVector 擅长处理图标、Logo、技术图表、图形和图表等矢量风格图像。不适用于自然风景照片或复杂插画。
• 模型选择:
  • starvector-8b-im2svg: 性能更强，适合高精度需求（需较大显存）。
  • starvector-1b-im2svg: 速度更快，显存占用更低，适合资源受限环境。
• 网络加速: 加载模型时默认连接 Hugging Face。国内用户若下载缓慢，可配置 HF_ENDPOINT 环境变量使用镜像源：

  export HF_ENDPOINT=https://hf-mirror.com