159 lines
5.1 KiB
Markdown
159 lines
5.1 KiB
Markdown
# Anima
|
|
|
|
> Native single-file diffusion text-to-image
|
|
|
|
## Summary
|
|
|
|
- Vendor: circlestone-labs
|
|
- Model: [`circlestone-labs/Anima`](https://huggingface.co/circlestone-labs/Anima)
|
|
- Task: text2img
|
|
- Mode: Offline inference, Online serving (OpenAI-compatible API)
|
|
- Maintainer: Community
|
|
|
|
## When to use this recipe
|
|
|
|
Use this recipe to run Anima via vLLM-Omni's native `AnimaPipeline`. Anima is a
|
|
Cosmos-style diffusion transformer text-to-image model distributed as a
|
|
single-file transformer checkpoint, not as a normal Hugging Face model
|
|
directory.
|
|
|
|
The native path reads the Anima transformer checkpoint directly, converts
|
|
original Cosmos transformer keys when needed, and loads the Cosmos transformer
|
|
and text conditioner into native vLLM-Omni modules. Non-denoiser components
|
|
such as `text_encoder`, `tokenizer`, `t5_tokenizer`, `vae`, and optionally
|
|
`scheduler` must be supplied through a Diffusers-layout components directory.
|
|
|
|
Native Anima currently supports baseline single-GPU execution. Cache-DiT,
|
|
TeaCache, CPU offload, layer-wise offload, quantization, TP/SP, CFG parallel,
|
|
HSDP, and step execution are not supported by `AnimaPipeline` yet.
|
|
|
|
## References
|
|
|
|
- Offline example:
|
|
[`examples/offline_inference/text_to_image/README.md`](../../examples/offline_inference/text_to_image/README.md)
|
|
- Supported model entry:
|
|
[`docs/models/supported_models.md`](../../docs/models/supported_models.md)
|
|
- HuggingFace model page:
|
|
[circlestone-labs/Anima](https://huggingface.co/circlestone-labs/Anima)
|
|
- Diffusers-layout components:
|
|
[circlestone-labs/Anima-Base-v1.0-Diffusers](https://huggingface.co/circlestone-labs/Anima-Base-v1.0-Diffusers)
|
|
|
|
## Hardware Support
|
|
|
|
## ROCm
|
|
|
|
### 1x AMD MI300X
|
|
|
|
#### Environment
|
|
|
|
- OS: Ubuntu 22.04.5 LTS (x86_64)
|
|
- Python: 3.12.13
|
|
- Driver / runtime: ROCm 7.2.53211, HIP runtime 7.2.53211, MIOpen 3.5.1
|
|
- PyTorch: 2.10.0+git8514f05 built with ROCm 7.2.53211
|
|
- GPU: 1x AMD MI300X
|
|
- vLLM version: 0.23.0
|
|
- vLLM-Omni version or commit: 0.1.dev2002+g704724675.rocm
|
|
|
|
Recommended environment variables:
|
|
|
|
```bash
|
|
export VLLM_WORKER_MULTIPROC_METHOD=spawn
|
|
export VLLM_ROCM_USE_AITER=0
|
|
export PYTORCH_ROCM_ARCH=gfx942
|
|
export PYTORCH_NVML_BASED_CUDA_CHECK=1
|
|
```
|
|
|
|
#### Command - prepare assets
|
|
|
|
Download the official transformer checkpoint and the Diffusers-layout component
|
|
directory:
|
|
|
|
```bash
|
|
mkdir -p /path/to/models/anima-official
|
|
mkdir -p /path/to/models/anima-components
|
|
|
|
hf download circlestone-labs/Anima \
|
|
split_files/diffusion_models/anima-base-v1.0.safetensors \
|
|
--local-dir /path/to/models/anima-official
|
|
|
|
hf download circlestone-labs/Anima-Base-v1.0-Diffusers \
|
|
--local-dir /path/to/models/anima-components
|
|
|
|
export ANIMA_CHECKPOINT=/path/to/models/anima-official/split_files/diffusion_models/anima-base-v1.0.safetensors
|
|
export ANIMA_COMPONENTS=/path/to/models/anima-components
|
|
```
|
|
|
|
The `ANIMA_COMPONENTS` directory must be in Diffusers `from_pretrained()`
|
|
layout. Raw auxiliary files such as `qwen_3_06b_base.safetensors` and
|
|
`qwen_image_vae.safetensors` are converter inputs; they are not accepted
|
|
directly as `components_path`.
|
|
|
|
#### Command - text-to-image
|
|
|
|
```bash
|
|
python examples/offline_inference/text_to_image/text_to_image.py \
|
|
--model "$ANIMA_CHECKPOINT" \
|
|
--model-class-name AnimaPipeline \
|
|
--custom-pipeline-args "{\"components_path\":\"$ANIMA_COMPONENTS\"}" \
|
|
--prompt "A cinematic close-up of a glass teapot on a wooden table." \
|
|
--seed 42 \
|
|
--guidance-scale 4.0 \
|
|
--num-inference-steps 50 \
|
|
--height 1024 \
|
|
--width 1024 \
|
|
--output /tmp/anima_output.png
|
|
```
|
|
|
|
Use 1024x1024, 50 denoising steps, `max_sequence_length=512`, one image per
|
|
prompt, empty negative prompt, and CFG scale 4.0 when matching Anima's default
|
|
Diffusers settings.
|
|
|
|
#### Verification
|
|
|
|
Check that `/tmp/anima_output.png` exists and contains a generated image.
|
|
|
|
#### Notes
|
|
|
|
- Key flags: `--model-class-name AnimaPipeline` selects the native Anima path;
|
|
`--custom-pipeline-args` supplies `components_path`.
|
|
- Keep the default diffusion load format. No deploy config is required when a
|
|
local checkpoint and `--model-class-name AnimaPipeline` are provided.
|
|
- Start with `max-concurrency=1` for correctness and latency validation.
|
|
- Keep requests at the same resolution when comparing runs.
|
|
- Do not enable parallelism, cache acceleration, offload, or quantized
|
|
checkpoint flags for Anima until support is added to `AnimaPipeline`.
|
|
|
|
## Online Serving
|
|
|
|
Anima supports text-to-image generation through the OpenAI-compatible image
|
|
generation API.
|
|
|
|
### Launch
|
|
|
|
```bash
|
|
vllm serve "$ANIMA_CHECKPOINT" \
|
|
--omni \
|
|
--port 8099 \
|
|
--model-class-name AnimaPipeline \
|
|
--custom-pipeline-args "{\"components_path\":\"$ANIMA_COMPONENTS\"}"
|
|
```
|
|
|
|
### Send requests
|
|
|
|
```bash
|
|
curl http://localhost:8099/v1/images/generations \
|
|
-H "Content-Type: application/json" \
|
|
-d "{
|
|
\"model\": \"$ANIMA_CHECKPOINT\",
|
|
\"prompt\": \"A cinematic close-up of a glass teapot on a wooden table.\",
|
|
\"size\": \"1024x1024\",
|
|
\"num_inference_steps\": 50,
|
|
\"guidance_scale\": 4.0,
|
|
\"seed\": 42
|
|
}"
|
|
```
|
|
|
|
The same generation knobs used by other text-to-image recipes apply:
|
|
`num_inference_steps`, `seed`, `height` / `width` through `size`, and optional
|
|
negative prompting.
|