DeTikZify入门指南：从环境搭建到高级配置

一、环境搭建：快速上手DeTikZify

1.1 5分钟安装流程

DeTikZify提供两种安装方式，推荐使用源码安装以获得完整功能体验：

# 克隆项目仓库（国内用户推荐使用GitCode镜像）
git clone https://gitcode.com/gh_mirrors/de/DeTikZify

# 进入项目目录并安装（包含示例所需依赖）
cd DeTikZify && pip install -e .[examples]

💡 安装技巧：如果仅需使用DeTikZify v2模型，可简化为pip install -e .。如需兼容v1模型，添加[legacy]参数。

1.2 系统依赖配置

⚠️ 注意事项：除Python依赖外，需手动安装以下系统组件：

• TeX Live 2023（完整版本，用于TikZ编译）
• Ghostscript（PDF处理）
• Poppler（矢量图渲染）

Ubuntu/Debian用户可通过以下命令快速安装：

sudo apt-get install texlive-full ghostscript poppler-utils

1.3 验证安装完整性

安装完成后，运行示例脚本验证环境：

# 执行基础推理示例
python examples/infer.py

如无报错并生成fig.tex文件，说明环境配置成功。

二、核心功能：DeTikZify能力解析

2.1 项目目录功能速览

目录路径	功能价值
detikzify/	核心代码库，包含模型实现与推理逻辑
examples/	通过实战案例掌握核心API调用，覆盖训练/评估全流程
detikzify/webui/	可视化交互界面，适合快速测试模型效果
detikzify/model/	模型架构定义，含v1/v2版本及适配器实现
detikzify/train/	训练脚本集合，支持预训练与微调流程
detikzify/util/	工具函数库，提供图像处理、张量操作等基础能力

2.2 WebUI启动与问题解决

通过Web界面直观体验模型功能：

# 轻量模式启动（适合资源有限环境）
python -m detikzify.webui --light

⚙️ 常见问题处理：

• 端口占用：使用--port 8080指定其他端口（替换8080为可用端口）
• 启动缓慢：添加--disable-cuda-memory-check跳过内存检查（需确保显存充足）
• 界面空白：清除浏览器缓存或使用--debug模式查看错误日志

2.3 基础API调用示例

通过编程接口实现图像转TikZ代码：

from detikzify.model import load
from detikzify.infer import DetikzifyPipeline

# 加载模型（自动选择设备）
pipeline = DetikzifyPipeline(*load(
    model_name_or_path="nllg/detikzify-v2.5-8b",
    device_map="auto",
    torch_dtype="bfloat16"
))

# 图像转TikZ代码
fig = pipeline.sample(image="path/to/your/image.png")
if fig.is_rasterizable:
    fig.rasterize().save("output.png")  # 保存渲染结果
    fig.save("output.tex")             # 保存TikZ代码

💡 进阶技巧：使用MCTS算法优化生成结果：

# 运行10分钟MCTS搜索最优解
for score, fig in pipeline.simulate(image=image, timeout=600):
    print(f"Score: {score}, TikZ code length: {len(fig.code)}")

三、进阶配置：定制化与性能优化

3.1 配置优先级说明

DeTikZify按以下顺序读取配置（优先级从高到低）：

1. 环境变量：适合动态调整参数（如export DETIKZIFY_DEVICE=cuda:1）
2. .env文件：项目根目录创建，存储固定配置（如MODEL_PATH=./models）
3. 代码硬编码：作为默认值，不建议直接修改源码

3.2 模型选择与资源配置

根据硬件条件选择合适模型：

模型版本	显存需求	适用场景
detikzify-v2.5-8b	≥12GB	追求高精度输出
detikzify-v2-8b	≥10GB	平衡速度与精度
tikzero-plus-10b	≥16GB	文本引导生成

⚙️ 性能调优参数：

# 低显存模式配置示例
pipeline = DetikzifyPipeline(*load(
    model_name_or_path="nllg/detikzify-v2-8b",
    device_map="auto",          # 自动分配设备
    torch_dtype="float16",      # 使用半精度浮点
    load_in_4bit=True,          # 4位量化加载（需bitsandbytes库）
    max_memory={0: "8GiB"}      # 限制GPU内存使用
))

3.3 文本引导生成（TikZero）

通过文本描述生成科学图表：

# TikZero+文本引导生成示例
pipeline = DetikzifyPipeline(*load(
    model_name_or_path="nllg/tikzero-plus-10b",
    device_map="auto"
))
fig = pipeline.sample(text="A neural network with 3 layers and ReLU activation")
fig.save("network.tex")

⚠️ 注意事项：文本引导功能目前仅支持编程接口调用，需确保模型文件完整下载。

3.4 训练与微调配置

自定义训练流程（以适配器训练为例）：

# 启动适配器预训练
python detikzify/train/adapter/pretrain.py \
    --dataset_path ./data \
    --output_dir ./models/adapter \
    --per_device_train_batch_size 4 \
    --num_train_epochs 10

训练配置通过命令行参数或环境变量传递，关键参数包括：

• --learning_rate：学习率（默认2e-5）
• --weight_decay：权重衰减（默认0.01）
• --gradient_accumulation_steps：梯度累积（显存不足时增加）

四、扩展资源与社区支持

4.1 模型与数据集获取

所有预训练模型及数据集均托管于Hugging Face Hub：

• DeTikZify模型集合
• TikZero模型
• DaTikZ数据集

4.2 常见问题排查

• 编译错误：检查TeX Live安装完整性，特别是tikz宏包
• 显存溢出：降低批次大小或使用load_in_8bit=True加载模型
• 生成质量低：尝试MCTS优化（增加timeout参数值）或更新至最新模型

4.3 贡献与反馈

• 提交Issue：在项目GitHub页面提交bug报告或功能建议
• 贡献代码：通过Pull Request参与开发
• 社区讨论：加入项目Discord或GitHub Discussions交流使用经验

通过本指南，您已掌握DeTikZify的核心使用方法。如需深入了解模型原理，请参考项目论文及源码注释。祝您在科学图表自动化生成的旅程中取得成功！