README.md

---

NexusAlign is a unified and extensible framework for aligning foundation models.

• 📦 Installation
• 🚀 Training
• 📊 Evaluation
• 📚 Citation

📦 Installation

Requirements: Python ≥3.10, PyTorch ≥2.5, and CUDA.

git clone https://github.com/junkunyuan/NexusAlign.git
cd NexusAlign
pip install -e .

🚀 Training

Launch training: use command nexus-align train.

Load huggingface datasets/models/pipelines from local: set common.data_and_model_dir.

Config options:

• ⌨️ CLI overrides: append key=value.
• 📄 Config file: --config / -c with a YAML file path.

# Example (single-node): 4 GPUs
nexus-align train \
  --nproc_per_node=4 \
  model=flux \
  log.exp_info=train-exp \
  common.data_and_model_dir=my_hf_cache

# Example (multi-node): 2 nodes, 8 GPUs per node
nexus-align train \
  --nnodes=2 \
  --nproc_per_node=8 \
  --node_rank=${NODE_RANK} \
  --master_addr=${MASTER_IP} \
  --master_port=29500 \
  -c my_train_config.yaml

📊 Evaluation

Launch evaluation: use command nexus-align eval.

Load huggingface datasets/models/pipelines from local: set common.data_and_model_dir.

Use a trained checkpoint: set model.eval.ckpt_path (e.g. checkpoints/model.pt).

Config options:

• ⌨️ CLI overrides: append key=value.
• 📄 Config file: --config / -c with a YAML file path.

# Example (single-node): 4 GPUs
nexus-align eval \
  --nproc_per_node=4 \
  model=flux \
  data=hpd_v2_benchmark \
  reward_model=hps_v2 \
  log.exp_info="eval-exp" \
  common.data_and_model_dir=my_hf_cache \
  model.eval.ckpt_path=checkpoints/exp_name/model.pt

# Example (multi-node): 2 nodes, 8 GPUs per node
nexus-align eval \
  --nnodes=2 \
  --nproc_per_node=8 \
  --node_rank=${NODE_RANK} \
  --master_addr=${MASTER_IP} \
  --master_port=29500 \
  -c my_eval_config.yaml

📚 Citation

@misc{nexus-align-2026,
  title = {NexusAlign: A Unified and Extensible Framework for Aligning Foundation Models},
  author = {Junkun Yuan, You Huang},
  year = {2026},
  url = {https://github.com/junkunyuan/NexusAlign}
}