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

Libraries

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

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

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

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

Notebooks
Google Colab
Kaggle
Local Apps Settings

vLLM

How to use breezexian/UniPhysGen-1.7B-Physics 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-Physics"
# 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-Physics",
		"messages": [
			{
				"role": "user",
				"content": "What is the capital of France?"
			}
		]
	}'

Use Docker

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

SGLang

How to use breezexian/UniPhysGen-1.7B-Physics 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-Physics" \
    --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-Physics",
		"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-Physics" \
        --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-Physics",
		"messages": [
			{
				"role": "user",
				"content": "What is the capital of France?"
			}
		]
	}'

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

UniPhysGen-1.7B-Physics

UniPhysGen-1.7B-Physics is the physical semantic alignment checkpoint of UniPhysGen, with direct support for part-level intrinsic physical grounding. It combines the Qwen3-1.7B language backbone with the Sonata point-cloud encoder and a lightweight MLP projector.

Given a full-object point cloud and a target-part point cloud, it predicts structured part identity, semantic descriptions, and intrinsic physical properties. During alignment pretraining, this supervision connects local part geometry and global object context with functional semantics, articulation behavior, and intrinsic physical properties, establishing a shared physical grounding representation.

The checkpoint therefore serves both as a part-level physics predictor and as the shared initialization for downstream task-specific fine-tuning of UniPhysGen-1.7B-Kinematics, UniPhysGen-1.7B-Structure, and UniPhysGen-1.7B-Object. See Section 4.1 and Appendices B.1 and C of the paper for the alignment objective and training stages.

Model details

Item	Value
Checkpoint role	Physical semantic alignment; part-level physics inference; downstream fine-tuning initialization
Internal task name	`physics`
Required geometry	Object point cloud + target-part point cloud
Training lineage	UniPhysGen-1.7B-Init → physical semantic alignment pretraining → this checkpoint
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]

Object and part point clouds are normalized together by the inference pipeline. The structured result contains:

part_identity: part name and motion type;
semantic_description: basic, functional, movement, and grasp descriptions;
physical_properties: material, density, Young's modulus, hardness, Poisson's ratio, friction, graspability, and affordance.

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_part.py \
  --model_path breezexian/UniPhysGen-1.7B-Physics \
  --object_pcd examples/object.npz \
  --part_pcd examples/part.npz \
  --output outputs/intrinsic_physics_part.json

The entry point also accepts a JSON list through --input_json. See the main project README for the batch schema, path resolution rules, and output record format. The final prediction is stored in result, while raw_response keeps the direct generated text.

Evaluation

Evaluate predictions using the UniPhysGen evaluator:

python -m eval intrinsic_physics_part PREDICTIONS \
  --output intrinsic_physics_part_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 physical grounding of 3D object parts, initialization of downstream grounding models, and producing candidate simulation parameters that are subsequently validated. It is not a physics simulator, and its estimates should not be treated as measured material properties.

Performance may degrade for incomplete scans, sparse or noisy point clouds, unseen materials, ambiguous part decompositions, unusual scales, or objects far outside the training distribution. Validate predictions before using them in robotics, safety-critical systems, or real-world 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}
}