HiVG快速上手教程：5分钟安装部署，生成你的第一张SVG矢量图

HiVG 是一款开源的分层 SVG 分词与生成模型（Hierarchical SVG Tokenization），它能把文字描述变成 SVG 矢量图，也能把任意位图转换成干净、可编辑的 SVG。本文是一份面向新手的 HiVG 快速上手教程：只需 5 分钟完成安装部署，就能生成你的第一张 SVG 矢量图。

为什么选择 HiVG？

在动手之前，先看看 HiVG 相比其他 SVG 生成工具的独特优势：

HiVG 的核心创新在于层级式 SVG 分词：先把原始 SVG 拆成原子 token，再通过 BPE 学习出更高层的结构化 segment token，从而大幅缩短模型输出序列。整个分词实现位于 hivg_tokenizer/ 目录，训练细节可参考 docs/segment_training.md。

一键安装步骤：5 分钟完成部署

1. 准备工作

HiVG 基于 PyTorch 生态，环境要求很简单：

• Python ≥ 3.9（支持 3.9 ~ 3.12）
• 建议 GPU 环境（如使用 vLLM 后端可进一步提升推理速度）
• 依赖声明见 requirements.txt，核心依赖为torch、transformers、cairosvg、pillow

2. 克隆仓库并安装

打开终端，执行以下命令（仓库地址可从 HiVG 项目主页获取）：

# 克隆 HiVG 仓库 git clone <HiVG 仓库地址> cd HiVG # 以可编辑模式安装，自动带上全部依赖 pip install -e .

安装包定义在 setup.py 中，执行pip install -e .后，hivg_infer、hivg_tokenizer、hivg_metric三个模块即可直接使用。

3. 获取模型权重

安装完成后，需要下载 HiVG 模型权重。目前开源的模型如下：

从 HuggingFace 下载HiVG-3B-Base权重到本地，记下目录路径（后文记为/path/to/model）。

生成你的第一张 SVG 矢量图

HiVG 提供命令行（CLI）和 Python API 两种方式，新手推荐直接用命令行。入口实现在 hivg_infer/cli.py，推理流水线见 hivg_infer/pipeline.py。

方式一：命令行 Text-to-SVG（文字生图）

用一句文字描述即可生成矢量图，无需写任何代码：

python -m hivg_infer.cli --model_path /path/to/model \ --prompt "A minimalist black phone icon with an outline style"

生成的 SVG 代码会直接打印到终端，例如仓库自带的 AI 芯片图标就是典型的矢量生成效果：

方式二：命令行 Image-to-SVG（图片转矢量）

把任意位图（PNG/JPG）转成可编辑的 SVG。仓库的 assets/cases/ 目录提供了示例图片，可以直接拿来试：

# 单张图片转 SVG python -m hivg_infer.cli --model_path /path/to/model \ --image assets/cases/w2.png # 批量处理整个数据集 python -m hivg_infer.cli --model_path /path/to/model \ --dataset test.json --output_dir ./outputs

仓库示例图就是这类 logo 风格的图片，转换后会得到结构清晰的矢量图形：

方式三：交互式模式（边聊边画）

最接近"对话式"体验的用法，在终端里持续输入文字描述：

python -m hivg_infer.cli --model_path /path/to/model --interactive

方式四：Python API（集成到自己的工作流）

如果想在自己的项目中调用 HiVG，几行代码即可：

from hivg_infer import HiSVGInferencePipeline pipeline = HiSVGInferencePipeline( model_path="/path/to/model", coord_range=234, temperature=0.7, top_p=0.9, max_new_tokens=4096, ) # 图片转 SVG result = pipeline.img2svg("assets/cases/w2.png") # 文字转 SVG result = pipeline.text2svg("A flat-style briefcase with a plus symbol") if result["success"]: with open("output.svg", "w") as f: f.write(result["svg"])

常用生成参数速查

不同参数会影响生成效果，以下是 hivg_infer/cli.py 支持的常用参数：

💡 小技巧：想要更稳定的输出可降低temperature；想要更丰富的变化则适当调高。

进阶：评估你的生成质量

批量生成后，可以用hivg_metric模块自动打分（实现见 hivg_metric/eval.py）：

# 批量推理（支持 vLLM 后端加速） python -m hivg_metric.eval \ --model_path /path/to/model \ --dataset test.json --infer_backend vllm \ --batch_size 32 --save_name results.jsonl # 计算指标：成功率、CLIP 分数、PickScore 等 python -m hivg_metric.compute_metrics \ --input results.jsonl --task_type text2svg \ --metrics basic,clip,preference --output metrics.json # 生成可交互的 HTML 对比报告 python -m hivg_metric.visualize \ --input results.jsonl --output report.html

常见问题（FAQ）

Q：没有 GPU 能跑吗？A：建议配备 GPU。可尝试--torch_dtype float16或减小max_new_tokens降低显存占用。

Q：生成失败（success 为 False）怎么办？A：检查model_path是否指向有效权重目录，并确认transformers版本 ≥ 4.40。

Q：如何用自己数据训练 segment token？A：参考官方分词训练指南 docs/segment_training.md，分词器配置在 hivg_tokenizer/configs/ 下（如 config_224.yaml）。

写在最后

到这里，你已完成 HiVG 的快速上手：从克隆安装到生成第一张 SVG 矢量图，整个过程不到 5 分钟。接下来可以试试：

1. 用--interactive交互式模式画你自己的图标
2. 调整temperature/top_p观察风格变化
3. 用 hivg_metric/ 给批量结果自动打分

祝你在矢量生成之旅中玩得开心！🚀