# AI use cases for Halo (whitecircle/halo) Repo: [whitecircle/halo](https://github.com/whitecircle/halo) | Use cases: 5 | Page: https://dedupedai.com/use-cases/whitecircle-halo/ Halo is an open-source framework from White Circle for training large language and multimodal models with pre-training, SFT, preference optimization, and multi-turn RL on Hugging Face models. This file holds every use case of this repo. Each one starts with a "## " heading and ends with its URL. - Fine-tune a Hugging Face LLM with LoRA on one GPU: https://dedupedai.com/use-cases/whitecircle-halo/lora-sft-single-gpu/ - Train a mixture-of-experts model across 8 GPUs: https://dedupedai.com/use-cases/whitecircle-halo/moe-expert-parallel-sft/ - Run multi-turn RL against vLLM or SGLang rollouts: https://dedupedai.com/use-cases/whitecircle-halo/async-rl-with-environments/ - Quantize a trained checkpoint to NVFP4: https://dedupedai.com/use-cases/whitecircle-halo/quantize-checkpoint-nvfp4/ - Let a coding agent set up and launch training jobs: https://dedupedai.com/use-cases/whitecircle-halo/agent-driven-training-setup/ ## How to fine-tune a Hugging Face LLM with LoRA on one GPU with Halo Repo: [whitecircle/halo](https://github.com/whitecircle/halo) | Difficulty: Intermediate | Time: 1 hour | Basis: From the README Run a LoRA SFT job on a Qwen3 model with one command from a ready YAML config. **Who it is for:** An ML engineer who wants to adapt an open Hugging Face model to a chat or instruction dataset and has a single GPU. **The problem:** Setting up a training stack with the right CUDA, attention kernels, and config format takes time before any training starts. **The outcome:** A LoRA fine-tuned checkpoint that still loads with from_pretrained. ### Steps 1. Pull the image that matches your GPU: `docker pull public.ecr.aws/whitecircle/halo:hopper` for H100/H200 or `docker pull public.ecr.aws/whitecircle/halo:blackwell` for B200/B300. 2. Start a container from that image with GPU access and open a shell in the repo. (inferred, check the README) 3. Print the command without running it: `halo launch sft examples/sft/qwen3/qwen3-4b-ultrachat-lora.yaml --dry-run`. (inferred, check the README) 4. Run the job: `halo launch sft examples/sft/qwen3/qwen3-4b-ultrachat-lora.yaml`. 5. Load the saved checkpoint with from_pretrained to confirm it is a standard Hugging Face model. ### Prompt to paste into your agent ```text In the whitecircle/halo repo, run `halo launch sft ` inside the Halo Docker image on one GPU, using examples/sft/qwen3/qwen3-4b-ultrachat-lora.yaml as the default. Expected output: a LoRA checkpoint written by the run. Verify first with `--dry-run` that the printed command matches the config path you chose. ``` ### Caveat The README describes the Docker images and the commands but does not list the exact GPU memory each example needs, so check the model size against your card before starting. Disclaimer: Third-party repos we don't own or vouch for. AI-generated use cases can be wrong: review everything and run at your own risk. Full text: https://dedupedai.com/disclaimer/ URL: https://dedupedai.com/use-cases/whitecircle-halo/lora-sft-single-gpu/ ## How to train a mixture-of-experts model across 8 GPUs with Halo Repo: [whitecircle/halo](https://github.com/whitecircle/halo) | Difficulty: Advanced | Time: 2 hours | Basis: From the README Use Expert Parallelism on a MoE model to spread experts over 8 GPUs with one launch command. **Who it is for:** A researcher or platform engineer training a MoE model such as Qwen3.5-35B-A3B who needs more throughput than a single GPU gives. **The problem:** Mixture-of-experts models are too large or slow to train on one GPU, and writing distributed expert code by hand is error-prone. **The outcome:** An SFT run that shards experts across 8 GPUs and writes a checkpoint that can be merged and exported. ### Steps 1. Pull the Blackwell or Hopper image as described in the installation section, for example `docker pull public.ecr.aws/whitecircle/halo:hopper`. 2. Preview the 8-GPU launch: `halo launch sft examples/sft/qwen3_5/qwen3.5-35b-a3b-ultrachat-ep.yaml -n 8 --dry-run`. (inferred, check the README) 3. Run the job with expert parallelism set to 8: `halo launch sft examples/sft/qwen3_5/qwen3.5-35b-a3b-ultrachat-ep.yaml -n 8 --expert_parallel_size=8`. (inferred, check the README) 4. If the run saves expert shards, merge them with `halo run merge-ep-shards --input_dir --output_dir `. (inferred, check the README) ### Prompt to paste into your agent ```text In the whitecircle/halo repo, launch the MoE SFT example with `halo launch sft -n 8 --expert_parallel_size=8` inside the Halo image on an 8-GPU node. Expected output: a completed run with expert shards in the output directory. Verify with `--dry-run` that the EP setting appears in the printed command before the real run. ``` ### Caveat The README says EP combines only with CP, TP, or ETP and other pairings are rejected at config time, so keep the parallelism flags to those combinations. Disclaimer: Third-party repos we don't own or vouch for. AI-generated use cases can be wrong: review everything and run at your own risk. Full text: https://dedupedai.com/disclaimer/ URL: https://dedupedai.com/use-cases/whitecircle-halo/moe-expert-parallel-sft/ ## How to run multi-turn RL against vLLM or SGLang rollouts with Halo Repo: [whitecircle/halo](https://github.com/whitecircle/halo) | Difficulty: Advanced | Time: 3 hours | Basis: From the README Train a policy with asynchronous GRPO where Ray actors roll out environments on vLLM or SGLang. **Who it is for:** A team building an RL post-training loop for a model that needs multi-turn interaction with verifiable environments. **The problem:** Keeping rollout generation and gradient updates in sync across inference servers and a trainer is hard to build from scratch. **The outcome:** An async GRPO run that pushes updated weights to the rollout servers and logs training progress. ### Steps 1. Pull the training image and the matching inference image, for example `docker pull public.ecr.aws/whitecircle/halo:hopper` and the vLLM image `public.ecr.aws/whitecircle/halo:vllm-0.26.0`. 2. Read the design of the async loop in human-docs/training-methods/async-grpo-environments.md. 3. List the available methods and tools: `halo launch --list` and `halo run --list`. 4. Launch the environment GRPO method named in the list with its YAML config: `halo launch environmental-grpo --dry-run`, then run it without --dry-run. (inferred, check the README) ### Prompt to paste into your agent ```text In the whitecircle/halo repo, read human-docs/training-methods/async-grpo-environments.md and then launch the environmental-grpo method with inside the Halo image. Expected output: a running async GRPO job that reports rollouts and weight syncs. Verify with `halo launch --list` that environmental-grpo is available before launching. ``` ### Caveat The README names the environmental-grpo method but does not show its config file, so you must write or pick a YAML config before the launch command will work. Disclaimer: Third-party repos we don't own or vouch for. AI-generated use cases can be wrong: review everything and run at your own risk. Full text: https://dedupedai.com/disclaimer/ URL: https://dedupedai.com/use-cases/whitecircle-halo/async-rl-with-environments/ ## How to quantize a trained checkpoint to NVFP4 with Halo Repo: [whitecircle/halo](https://github.com/whitecircle/halo) | Difficulty: Intermediate | Time: 1 hour | Basis: From the README Convert a saved checkpoint to a low-precision NVFP4 format with one Halo run command. **Who it is for:** An engineer preparing a trained model for cheaper inference who has a checkpoint directory from a Halo run. **The problem:** Low-precision formats need a conversion step that is easy to get wrong when done by hand. **The outcome:** A quantized NVFP4 checkpoint written to a new output directory. ### Steps 1. Start the Halo image with your checkpoint directory mounted (inferred: standard docker run with a volume). 2. List the available tools: `halo run --list`. 3. Run the quantization: `halo run quantize-to-lowp --input_dir --output_dir --format nvfp4`. (inferred, check the README) 4. Load the output with the standard loader for your inference server to confirm it is readable. ### Prompt to paste into your agent ```text In the whitecircle/halo repo, run `halo run quantize-to-lowp` with --input_dir and --output_dir and --format nvfp4 inside the Halo image. Expected output: a quantized checkpoint in the output directory. Verify that the input and output paths are different directories before running. ``` ### Caveat The README gives the NVFP4 flag but does not state which inference engines accept the quantized output, so test it in your serving stack first. Disclaimer: Third-party repos we don't own or vouch for. AI-generated use cases can be wrong: review everything and run at your own risk. Full text: https://dedupedai.com/disclaimer/ URL: https://dedupedai.com/use-cases/whitecircle-halo/quantize-checkpoint-nvfp4/ ## How to let a coding agent set up and launch training jobs with Halo Repo: [whitecircle/halo](https://github.com/whitecircle/halo) | Difficulty: Intermediate | Time: 1 hour | Basis: From the README Point Claude Code or Codex at the repo skills to choose parallelism and launch a Halo run. **Who it is for:** A developer who wants a coding agent to handle the config, parallelism choice, and launch steps for a training job. **The problem:** Choosing parallelism settings and debugging distributed runs takes experience that many teams do not have on hand. **The outcome:** An agent-run training job with parallelism settings chosen from the repo skills and a log of the launch. ### Steps 1. Pull the training image: `docker pull public.ecr.aws/whitecircle/halo:hopper` or the blackwell tag. 2. If you want the agent CLI inside the image, build locally with the build argument `--build-arg INSTALL_CLAUDE_CODE=1` as described in the coding agents section. (inferred, check the README) 3. Open the skills folder in the repo: see skills/ for the launch, parallelism, debug, and rl-setup skills. 4. Ask the agent to follow the parallelism skill and then run `halo launch sft -n 8 --dry-run` before the real launch. (inferred, check the README) ### Prompt to paste into your agent ```text In the whitecircle/halo repo, use the skills/parallelism and skills/launch guides to choose settings for and then run `halo launch sft` with --dry-run inside the Halo image. Expected output: a printed launch command with the chosen parallelism flags. Verify that the flags match one of the allowed EP, CP, TP, or ETP combinations before any real run. ``` ### Caveat The README says the skills are discoverable by Claude Code and Codex, but it does not say how the agents authenticate or which model they use. Disclaimer: Third-party repos we don't own or vouch for. AI-generated use cases can be wrong: review everything and run at your own risk. Full text: https://dedupedai.com/disclaimer/ URL: https://dedupedai.com/use-cases/whitecircle-halo/agent-driven-training-setup/