G-star

This repository contains the complete G-star text-to-image generation model, its matching visual tokenizer, its SR2x refiner, and the inference code. Download the full repository, install the dependencies, and run inference locally. No training dataset or internal job platform is required.

Components

Location	Component
Repository root	Qwen3-8B generation backbone, visual embedding bridge and DSpark image head
tokenizer/	Matching g16 visual tokenizer, with 16 codebooks of 16,384 entries and 32x downsampling
refiner/	Matching g16 SR2x refiner, including its own visual encoder, codebooks, DiT and VAE
gstar/	G-star model implementation and generation pipeline
inference_config.json	Generation settings for this checkpoint
MANIFEST.json	Weight-file SHA-256 checksums and component metadata

The standalone tokenizer is extracted from the tokenizer embedded in the paired refiner. Tensor values, dtypes and shapes are preserved, so both components share the same learned codebooks. Use this paired tokenizer and refiner with the generation checkpoint in this repository.

Download and install

The model was verified with Python 3.12, PyTorch 2.6.0 / CUDA 12.4, Transformers 4.57.0 and FlashAttention 2.7.4.post1 on NVIDIA H100 80 GB GPUs. Each inference worker uses one GPU.

python -m pip install 'huggingface_hub>=0.36,<1'
python - <<'PY'
from huggingface_hub import snapshot_download
snapshot_download(repo_id='DAGroup-PKU/G-star', local_dir='./G-star')
PY

cd G-star
python -m pip install --upgrade pip wheel packaging ninja
python -m pip install torch==2.6.0 torchvision==0.21.0 torchaudio==2.6.0
python -m pip install --no-build-isolation -r requirements.txt \
  'flash-attn==2.7.4.post1' 'diffusers==0.38.0' 'accelerate==1.12.0'

Keep all downloaded configuration, text-tokenizer, Python implementation and weight-shard files. PyTorch and FlashAttention must match the machine's CUDA runtime and GPU.

Generate an image

Run from the downloaded G-star directory:

CUDA_VISIBLE_DEVICES=0 USE_TF=0 TOKENIZERS_PARALLELISM=false \
OMNI_DISABLE_WAVELET_COLOR_FIX=1 python -m gstar.infer \
  --task t2i --model . --visual-tokenizer ./refiner \
  --prompt-mode pretrain \
  --prompt 'A golden retriever lying on a wooden floor, looking up at its owner, warm morning sunlight, realistic photography.' \
  --height 1024 --width 1024 --cfg 2.4 \
  --top-k 4096 --top-p 0.75 --temperature 0.7 --seed 20260915 \
  --output outputs/generated_2048.png

This checkpoint uses the pretrain prompt format, without SFT role tokens. The LLM generates a 32 x 32 grid of g16 codes corresponding to a 1024 x 1024 image; the refiner produces a native 2048 x 2048 image. Its default refinement settings are 52 steps and seed 0. The command disables optional wavelet color correction to match the verified generation configuration.

For a 1024 output, resize with Lanczos:

python - <<'PY'
from PIL import Image
with Image.open('outputs/generated_2048.png') as image:
    image.resize((1024, 1024), Image.Resampling.LANCZOS).save('outputs/generated_1024.png')
PY

Prompts are used as supplied; pass rewritten text explicitly when using an external prompt-rewrite system. Fine details can contain generation errors, and identical seeds do not guarantee identical images across hardware.

Load individual components

import torch
from transformers import AutoModel, AutoModelForCausalLM, AutoTokenizer

text_tokenizer = AutoTokenizer.from_pretrained('./G-star')
llm = AutoModelForCausalLM.from_pretrained(
    './G-star', trust_remote_code=True, torch_dtype=torch.bfloat16,
)
visual_tokenizer = AutoModel.from_pretrained(
    './G-star/tokenizer', trust_remote_code=True, torch_dtype=torch.bfloat16,
)
refiner = AutoModel.from_pretrained(
    './G-star/refiner', trust_remote_code=True, torch_dtype=torch.bfloat16,
)

For generation, use gstar.infer as shown above; it supplies the image-size prefixes, newline handling, CFG branches and DSpark sampling. Tokenizer encode/decode uses CUDA BF16 autocast. The unified refiner manages its own autocast internally.

Validation and licenses

The source generation configuration was verified on four rewritten benchmark prompts, with complete image-code grids and finite SR2x outputs. The public CLI was also run with real weights. Validation of the sanitized release is recorded in VALIDATION.json.

Operational paths, experiment names and training metadata are omitted from the release. Original trained model tensors and required serialization keys are preserved. Original G-star code is MIT-licensed; upstream source attributions and license headers are retained.