Official Codebase of 3DCodeVerse
Environment setup (what was actually installed; reproduce on a new box)
Machine used: DGX (8×H100 80 GB, driver 570 / CUDA 12.8, 224 cores, 2 TB RAM), Ubuntu; only GPUs 0–3 were used.
$HOME was full, so everything lives under one workspace dir (WORKSPACE=/wekafs/ict/hx_624 in env.sh) — Anaconda, HF cache, models, tools, caches. Set WORKSPACE to your own path and keep the rest of env.sh as is.
0. Anaconda
wget https://repo.anaconda.com/archive/Anaconda3-2026.07-Linux-x86_64.sh
bash Anaconda3-2026.07-Linux-x86_64.sh -b -p $WORKSPACE/anaconda3
source $WORKSPACE/anaconda3/etc/profile.d/conda.sh
1. Three conda envs (all Python 3.12; pip freezes in env/)
Why three: LLaMA-Factory (training) and vLLM (inference) pin incompatible torch versions; the data/eval stack has its own deps (CadQuery, Playwright, trimesh).
lf — training (LLaMA-Factory, unpatched)
conda create -y -n lf python=3.12 && conda activate lf
pip install torch==2.8.0 torchvision --index-url https://download.pytorch.org/whl/cu128
git clone https://github.com/hiyouga/LLaMA-Factory.git $WORKSPACE/tools/LLaMA-Factory
cd $WORKSPACE/tools/LLaMA-Factory && git checkout c4e09c7 # 0.9.6.dev0, 2026-08-20 ("support GDN Ulysses cp")
pip install -e ".[torch,metrics,deepspeed]" # transformers 5.8.0, peft, trl, deepspeed 0.19.5
pip install flash-attn==2.8.3 --no-build-isolation # H100: FA2 (prebuilt wheel for torch 2.8/cu128 if available)
pip install flash-linear-attention==0.5.2 causal-conv1d==1.7.0 # Qwen3.5 Gated-DeltaNet kernels
pip install triton==3.7.1 # REQUIRED on Hopper: fla refuses the GDN backward with triton 3.4–3.7.0
Pins that matter (see env/requirements-lf.txt): torch 2.8.0+cu128 (LLaMA-Factory rejects torch 2.9.x with models that contain Conv3D — Qwen3.5's vision tower), transformers 5.8.0, flash_attn 2.8.3, flash-linear-attention 0.5.2, causal-conv1d 1.7.0, triton 3.7.1, deepspeed 0.19.5.
vllm — generation for every evaluation
conda create -y -n vllm python=3.12 && conda activate vllm
pip install vllm==0.27.1 # brings torch 2.13.0+cu129; runs on the 12.8 driver via CUDA minor-version compatibility
pip install flash-linear-attention==0.5.2 triton==3.7.1
Use with export VLLM_CACHE_ROOT=$WORKSPACE/cache/vllm (torch.compile cache; default is ~/.cache). Qwen3.5 needs limit_mm_per_prompt={"image":0,"video":0} and chat_template_kwargs={"enable_thinking": False} — thinking is turned off in ../eval/llm/generate.py.
llmft — data building, HF-side checks, executors, metrics
conda create -y -n llmft python=3.12 && conda activate llmft
pip install torch==2.9.1 --index-url https://download.pytorch.org/whl/cu128
pip install transformers==5.15.1 trl==1.10.0 peft==0.20.0 deepspeed==0.19.5 flash-attn==2.8.3 flash-linear-attention==0.5.2
pip install trimesh==5.0.0 numpy scipy pyarrow pandas pyyaml markdown pillow huggingface_hub
pip install cadquery==2.8.0 # CadQuery executor (OCP 7.8 / 6.0 wheels)
conda install -y -c conda-forge glslang # glslangValidator for the GLSL executor
pip install playwright==1.62.0 && PLAYWRIGHT_BROWSERS_PATH=$WORKSPACE/cache/ms-playwright playwright install chromium # three.js executor
pip uninstall -y torchaudio # a mismatched torchaudio breaks `import transformers`
(trl/peft here were only used for early hand-written trainer checks; all real training went through lf.)
2. External tools (called by absolute path from eval/)
| tool | how | path key |
|---|---|---|
| Blender 5.2.2 LTS (headless; executes generated bpy code, exports GLB) | wget https://download.blender.org/release/Blender5.2/blender-5.2.2-linux-x64.tar.xz && tar xf … -C $WORKSPACE/tools — then blender-5.2.2-linux-x64/5.0/python/bin/python3.11 -m pip install scipy: 15 of the 212 3DCodeBench reference scripts import scipy, and without it any model that writes the same idiom is scored as a failure (this cost the tuned 27B 8.1 points before we caught it) |
C3D_BLENDER / C3D_TOOLS (../eval/llm/config.py) |
| OpenSCAD (nightly AppImage, extracted so it runs without FUSE) | wget …/OpenSCAD-2026.08.19-x86_64.AppImage && ./OpenSCAD-*.AppImage --appimage-extract → squashfs-root/AppRun |
C3D_OPENSCAD / C3D_TOOLS (../eval/llm/config.py) |
| glslangValidator | conda-forge glslang (in llmft) |
C3D_GLSLANG (../eval/llm/config.py) |
| Chromium (Playwright) | see llmft above |
PLAYWRIGHT_BROWSERS_PATH |
| Models | hf download Qwen/Qwen3.5-9B --local-dir $WORKSPACE/models/Qwen3.5-9B (also used: Qwen3.5-4B, Qwen3-8B, Qwen2.5-Coder-7B-Instruct) |
model_name_or_path in configs/lf/*.yaml |
| Data | only metadata.parquet of each 3DCodeVerse subset (3dcodeverse/3dcodeverse-2m on the HF Hub) + the 3DCodeBench tarball; llamafactory/fetch_hf_files.py is more robust than hf download for many small files on a network FS |
llamafactory/build_md_max.py |
Secrets: env.sh sources $WORKSPACE/.secrets/hf.env (export HF_TOKEN=..., chmod 600). Never put tokens in configs or scripts.
3. Caches on a network filesystem (important for parallel runs)
TRITON_CACHE_DIRon a network FS races between concurrent trainings (atomic rename is not reliable) →scripts/lf_train.shgives every run a private copy on local disk (/tmp/<user>_triton/<run>).VLLM_CACHE_ROOT,HF_HOME,TORCH_EXTENSIONS_DIR,PIP_CACHE_DIRall point into$WORKSPACE/cache(env.sh).
4. Smoke tests
source env.sh # llmft
python - <<'PY'
import torch, transformers, trimesh, cadquery; print(torch.__version__, torch.cuda.is_available(), transformers.__version__)
PY
conda activate lf && python -c "import llamafactory, fla, flash_attn, triton; print(llamafactory.__version__, triton.__version__)"
conda activate vllm && python -c "import vllm; print(vllm.__version__)"
$WORKSPACE/tools/blender-5.2.2-linux-x64/blender -b --version | head -1
$WORKSPACE/tools/openscad/squashfs-root/AppRun --version
# 1-GPU LoRA dry run (tiny dataset), then merge, then a 5-prompt generation:
GPUS=0 scripts/lf_train.sh configs/lf/sft_9b_lora64_lr1e-4_len8k_hub-remote.yaml num_train_epochs=0.01