Instructions to use breezexian/UniPhysGen-1.7B-Object with libraries, inference providers, notebooks, and local apps. Follow these links to get started.

Libraries

How to use breezexian/UniPhysGen-1.7B-Object with Transformers:

# Use a pipeline as a high-level helper
from transformers import pipeline

pipe = pipeline("text-generation", model="breezexian/UniPhysGen-1.7B-Object")
messages = [
    {"role": "user", "content": "Who are you?"},
]
pipe(messages)

# Load model directly
from transformers import AutoModelForCausalLM
model = AutoModelForCausalLM.from_pretrained("breezexian/UniPhysGen-1.7B-Object", device_map="auto")

Notebooks
Google Colab
Kaggle
Local Apps Settings

vLLM

How to use breezexian/UniPhysGen-1.7B-Object with vLLM:

Install from pip and serve model

# Install vLLM from pip:
pip install vllm
# Start the vLLM server:
vllm serve "breezexian/UniPhysGen-1.7B-Object"
# Call the server using curl (OpenAI-compatible API):
curl -X POST "http://localhost:8000/v1/chat/completions" \
	-H "Content-Type: application/json" \
	--data '{
		"model": "breezexian/UniPhysGen-1.7B-Object",
		"messages": [
			{
				"role": "user",
				"content": "What is the capital of France?"
			}
		]
	}'

Use Docker

docker model run hf.co/breezexian/UniPhysGen-1.7B-Object

SGLang

How to use breezexian/UniPhysGen-1.7B-Object with SGLang:

Install from pip and serve model

# Install SGLang from pip:
pip install sglang
# Start the SGLang server:
python3 -m sglang.launch_server \
    --model-path "breezexian/UniPhysGen-1.7B-Object" \
    --host 0.0.0.0 \
    --port 30000
# Call the server using curl (OpenAI-compatible API):
curl -X POST "http://localhost:30000/v1/chat/completions" \
	-H "Content-Type: application/json" \
	--data '{
		"model": "breezexian/UniPhysGen-1.7B-Object",
		"messages": [
			{
				"role": "user",
				"content": "What is the capital of France?"
			}
		]
	}'

Use Docker images

docker run --gpus all \
    --shm-size 32g \
    -p 30000:30000 \
    -v ~/.cache/huggingface:/root/.cache/huggingface \
    --env "HF_TOKEN=<secret>" \
    --ipc=host \
    lmsysorg/sglang:latest \
    python3 -m sglang.launch_server \
        --model-path "breezexian/UniPhysGen-1.7B-Object" \
        --host 0.0.0.0 \
        --port 30000
# Call the server using curl (OpenAI-compatible API):
curl -X POST "http://localhost:30000/v1/chat/completions" \
	-H "Content-Type: application/json" \
	--data '{
		"model": "breezexian/UniPhysGen-1.7B-Object",
		"messages": [
			{
				"role": "user",
				"content": "What is the capital of France?"
			}
		]
	}'

Docker Model Runner
How to use breezexian/UniPhysGen-1.7B-Object with Docker Model Runner:
```
docker model run hf.co/breezexian/UniPhysGen-1.7B-Object
```

UniPhysGen-1.7B-Object

UniPhysGen-1.7B-Object is the object-level intrinsic physical grounding checkpoint from UniPhysGen. Given a full-object point cloud, it predicts object identity, category, dimensions, and mass. It does not require a target-part point cloud.

Model details

Item	Value
Internal task name	`object_level`
Required geometry	Object point cloud only
Training lineage	UniPhysGen-1.7B-Init → UniPhysGen-1.7B-Physics → object-level fine-tuning
Training data	spatialverse/UniPhys-40K
Evaluation data	spatialverse/UniPhys-Bench
Tested Transformers version	`4.51.0`
Source code	breezexian/UniPhysGen
Paper	arXiv:2607.13586

Inputs and outputs

The recommended point-cloud format is .npz with aligned arrays:

point   float32 [N, 3]
color   uint8   [N, 3]
normal  float32 [N, 3]

The structured prediction is:

{
  "object_name": "cabinet",
  "category": "Furniture/Cabinet",
  "volume": [80.0, 40.0, 120.0],
  "mass": 35.0
}

volume stores [length, width, height] in centimeters. mass is expressed in kilograms.

Installation

The model has been tested on Linux with Python 3.11, PyTorch 2.4.1, CUDA 12.4, and transformers==4.51.0.

Use transformers==4.51.0. This is the tested version and is pinned by the UniPhysGen project metadata.

git clone https://github.com/breezexian/UniPhysGen.git
cd UniPhysGen

conda create -n uniphysgen python=3.11 -y
conda activate uniphysgen
conda install -y -c nvidia/label/cuda-12.4.0 cuda-toolkit

python -m pip install torch==2.4.1 torchvision==0.19.1 torchaudio==2.4.1 --index-url https://download.pytorch.org/whl/cu124
python -m pip install -e ".[train]"
bash scripts/install_cuda_extensions.sh

For inference only, replace python -m pip install -e ".[train]" with python -m pip install -e ..

The model uses a custom Transformers architecture. Install UniPhysGen before loading the checkpoint; a generic transformers.pipeline is not supported.

Inference

CUDA_VISIBLE_DEVICES=0 python inference_batch_intrinsic_physics_object.py \
  --model_path breezexian/UniPhysGen-1.7B-Object \
  --object_pcd examples/object.npz \
  --output outputs/intrinsic_physics_object.json

For batch inference, pass a JSON list with --input_json. No --part_pcd argument is needed for this task.

Evaluation

python -m eval intrinsic_physics_object PREDICTIONS \
  --output intrinsic_physics_object_metrics.json

See Table 2 of the paper for the UniPhys-Bench results and the main project README for the complete evaluation protocol.

Intended use and limitations

This checkpoint is intended for research on object-level physical grounding and for proposing approximate object metadata for downstream simulation. Predicted dimensions and mass are estimates, not calibrated measurements.

Performance may degrade for incomplete scans, incorrect scale, sparse or noisy point clouds, unusual materials, composite objects, or categories outside the training distribution. Validate predictions before using them in robotics, safety-critical systems, or engineering workflows.

License

The model weights are released under the Creative Commons Attribution-NonCommercial 4.0 International license. Commercial use is not permitted under this license. The UniPhysGen source code is licensed separately under Apache-2.0. See the included license for Qwen3 and Sonata attribution.

Citation

@article{li2026uniphysgen,
  title   = {UniPhysGen: Unified Physical Grounding for Simulation-Ready 3D Assets},
  author  = {Li, Xian and Wei, Rong and Yang, Lujie and Huang, Haolin and Fang, Junyuan and Tang, Siliang and Xiao, Jun and Tang, Rui and Li, Juncheng},
  journal = {arXiv preprint arXiv:2607.13586},
  year    = {2026}
}