DOCSEARCHbyAlgolia
Submit Docs

HunyuanImage-3.0 Documentation

repository·main·Indexed 25 days ago

https://github.com/tencent-hunyuan/hunyuanimage-3.0

A high-performance, large-scale multimodal image generation model utilizing a Mixture of Experts (MoE) architecture. It supports text-to-image and image-to-image tasks across three variants: the standard HunyuanImage-3.0, HunyuanImage-3.0-Instruct for reasoning and prompt enhancement, and HunyuanImage-3.0-Instruct-Distil for efficient deployment. Features include CoT thinking, multi-image fusion, and integration with Transformers, Gradio, and vLLM.

Tokens
18.1K
Snippets
17
Records
101
Agent score
85%

What's inside HunyuanImage-3.0

  1. Overview of HunyuanImage-3.0

    main

    HunyuanImage-3.0 is a native multimodal model that unifies multimodal understanding and generation within an autoregressive framework. It provides high-performance Text-to-Image (T2I) and Image-to-Image (I2I) capabilities, comparable to or exceeding leading closed-source models.

    Key Features

    • Unified Multimodal Architecture: Uses an autoregressive framework instead of standard DiT to achieve deep integration of semantic understanding and image generation.
    • Large-scale MoE Model: The largest open-source image generation Mixture-of-Experts (MoE) model, featuring 64 experts and 80 billion total parameters (with 13 billion parameters activated per token).
    • High-Quality Generation: Optimized for semantic accuracy and visual expressiveness, producing photorealistic and artistically detailed images.
    • Intelligent Reasoning: Capable of deep image understanding and world knowledge reasoning. It can automatically expand brief prompts with contextually relevant details to improve visual output.

  2. Features of HunyuanImage-3.0-Instruct

    main

    The HunyuanImage-3.0-Instruct model provides advanced intelligent image generation and editing capabilities:

    • CoT Think (Intelligent Visual Understanding and Reasoning): Performs structured thinking to analyze input images and prompts, expanding user intent into comprehensive instructions for better generation/editing.
    • Prompt Self-Rewrite: Automatically enhances sparse or vague prompts into detailed, professional-grade descriptions.
    • Text-to-Image (T2I): High-quality image generation with strong prompt adherence.
    • Image-to-Image (TI2I): Supports adding/removing elements, modifying styles, and background replacement while preserving key visual elements.
    • Multi-Image Fusion: Combines up to 3 reference images to create coherent composite images.

  3. Capabilities of HunyuanImage-3.0-Instruct

    main

    HunyuanImage-3.0-Instruct is a specialized model designed for intelligent image generation and editing. Its core capabilities include:

    • CoT Think (Chain-of-Thought Reasoning): Performs structured visual reasoning to decompose complex user intents and editing tasks into detailed visual components (subject, composition, lighting, color, and style).
    • Prompt Auto-Rewriting: Automatically enhances sparse or vague prompts into professional, detailed descriptions.
    • Text-to-Image (T2I): Generates high-quality images with high prompt adherence and photorealism.
    • Image-to-Image (TI2I): Supports creative editing such as adding/removing objects, modifying styles, and seamless background replacement while preserving key visual elements.
    • Multi-Image Fusion: Combines up to 3 reference images to create a coherent synthetic image containing elements from all sources.

  4. Launch the Gradio Interactive Web Interface

    main

    You can launch an interactive web interface for text-to-image generation using Gradio.

    1. Install Gradio: pip install gradio>=4.21.0.
    2. Configure environment variables:
      • MODEL_ID: Path to your model.
      • GPUS: (Optional) Comma-separated list of GPU IDs (e.g., 0,1,2,3).
      • HOST: (Optional) Host address (default 0.0.0.0).
      • PORT: (Optional) Port number (default 443).
    3. Run the application using sh run_app.sh. You can also pass optimizations like --moe-impl flashinfer --attn-impl flash_attention_2 to the script.
    # 1. Install Gradio
pip install gradio>=4.21.0

# 2. Configure Environment
export MODEL_ID="path/to/your/model"
export GPUS="0,1,2,3"
export HOST="0.0.0.0"
export PORT="443"

# 3. Launch
sh run_app.sh

# With Performance Optimizations
sh run_app.sh --moe-impl flashinfer --attn-impl flash_attention_2

  5. Optimize inference with FlashInfer

    main

    To achieve up to 3x inference acceleration via optimized MoE (Mixture of Experts) inference, install flashinfer-python.

    Warning: The first inference run with FlashInfer may be slow (approximately 10 minutes) as it needs to compile kernels. Subsequent runs on the same machine will be significantly faster.

  6. Run HunyuanImage-3.0-Instruct-Distil with fewer steps

    main

    For faster generation, use the HunyuanImage-3.0-Instruct-Distil model. It is recommended to set --diff-infer-steps 8 while keeping all other recommended parameters unchanged.

    # Download HunyuanImage-3.0-Instruct-Distil from HuggingFace
hf download tencent/HunyuanImage-3.0-Instruct-Distil --local-dir ./HunyuanImage-3-Instruct-Distil

# Run demo with 8 sampling steps
export MODEL_PATH="./HunyuanImage-3-Instruct-Distil"
bash run_demo_instruct_distil.sh

  7. Quick Start: Launch Hunyuan Image3 Server and Generate Images

    main

    To use the Hunyuan Image3 API service with a vLLM backend, follow these two steps:

    1. Launch the Server: Run the provided shell script pointing to your model path. The server will start at http://localhost:8000.
    2. Generate Images: Use the openai_client.py script to send prompts to the running server.

    Basic Usage Example:

    # 1. Launch Server
sh vllm_infer/run_vllm_server.sh /path/to/model

# 2. Generate Image
python openai_client.py --prompt "your image description"
    # 1. Launch Server
sh vllm_infer/run_vllm_server.sh /path/to/model

# 2. Generate Image
python openai_client.py --prompt "your image description"

  8. Run HunyuanImage-3.0 (Text-to-Image) via CLI

    main

    Run the pure text-to-image model using the run_image_gen.py script.

    Prompt Enhancement (PE): For optimal results, it is recommended to use prompt rewriting. You can enable this by setting --rewrite 1. If you wish to use the built-in enhancement, you must provide DEEPSEEK_KEY_ID and DEEPSEEK_KEY_SECRET environment variables.

    Example (Without PE):

    export MODEL_PATH="./HunyuanImage-3"
python3 run_image_gen.py \
    --model-id $MODEL_PATH \
    --verbose 1 \
    --prompt "A brown and white dog is running on the grass" \
    --bot-task image \
    --image-size "1024x1024" \
    --save ./image.png \
    --moe-impl flashinfer

    Example (With PE):

    export DEEPSEEK_KEY_ID="your_deepseek_key_id"
export DEEPSEEK_KEY_SECRET="your_deepseek_key_secret"
export MODEL_PATH="./HunyuanImage-3"
python3 run_image_gen.py \
    --model-id $MODEL_PATH \
    --verbose 1 \
    --prompt "A brown and white dog is running on the grass" \
    --bot-task image \
    --image-size "1024x1024" \
    --save ./image.png \
    --moe-impl flashinfer \
    --rewrite 1

  9. Install HunyuanImage-3.0 dependencies

    main

    To set up the environment for HunyuanImage-3.0, ensure you are using Python 3.12+ and CUDA 12.8. Follow these steps in order:

    1. Install PyTorch with CUDA 12.8 support.
    2. Install tencentcloud-sdk-python for Prompt Enhancement (PE). Note: PE is only required for HunyuanImage-3.0, not for HunyuanImage-3.0-Instruct.
    3. Install remaining dependencies from requirements.txt.

    Optimization: For up to 3x faster inference, install flashinfer-python==0.5.0.

    Important Notes:

    • The PyTorch CUDA version must match your system's CUDA version.
    • GCC version >= 9 is recommended for compiling FlashAttention and FlashInfer.
    • When using FlashInfer, the first inference may take approximately 10 minutes due to kernel compilation.
    # 1. First install PyTorch (CUDA 12.8 Version)
pip install torch==2.8.0 torchvision==0.23.0 torchaudio==2.8.0 --index-url https://download.pytorch.org/whl/cu128

# 2. Install tencentcloud-sdk for Prompt Enhancement (PE) only for HunyuanImage-3.0 not HunyuanImage-3.0-Instruct
pip install -i https://mirrors.tencent.com/pypi/simple/ --upgrade tencentcloud-sdk-python

# 3. Then install other dependencies
pip install -r requirements.txt

# For up to 3x faster inference
pip install flashinfer-python==0.5.0

  10. Use system prompts for automatic prompt enhancement (PE)

    main

    The repository includes two system prompts in the PE folder designed to leverage DeepSeek for automatic prompt enhancement. Note that these prompts are written in Chinese to optimize performance with DeepSeek, but can be translated to English for English-oriented models.

    • system_prompt_universal: Converts photographic or artistic prompts into highly detailed descriptions.
    • system_prompt_text_rendering: Converts UI, poster, or text-rendering prompts into detailed descriptions suitable for the model.

    To implement the universal enhancement workflow, you can use the Yuanqi workflow.

  11. Run HunyuanImage-3.0-Instruct via CLI

    main

    You can run the HunyuanImage-3.0-Instruct model locally using the provided shell scripts.

    1. Clone the repository and enter the directory.
    2. Download the model weights from HuggingFace to a local directory (ensure the directory name has no dots).
    3. Set the MODEL_PATH environment variable and execute run_demo_instruct.sh.

    For faster sampling, you can use the HunyuanImage-3.0-Instruct-Distil model with --diff-infer-steps 8.

    # Clone and setup
git clone https://github.com/Tencent-Hunyuan/HunyuanImage-3.0.git
cd HunyuanImage-3.0/

# Download weights
hf download tencent/HunyuanImage-3.0-Instruct --local-dir ./HunyuanImage-3-Instruct

# Run demo
export MODEL_PATH="./HunyuanImage-3-Instruct"
bash run_demo_instruct.sh

  12. Set up Hunyuan Image3 using Docker (Recommended)

    main

    The easiest way to deploy the service is using the provided Dockerfile located at docker/hyimage3_vllm.Dockerfile. This method handles the complex dependencies and vLLM requirements automatically.

    1. Build the image: Use the -f flag to specify the Dockerfile.
    2. Run the container: Ensure you pass --gpus all, map port 8000, and bind-mount your local model directory to the /model target inside the container.
    # Build the Docker image
docker build -t hunyuan_image3_vllm -f docker/hyimage3_vllm.Dockerfile

# Run the Docker container
docker run --gpus all -it -p 8000:8000 hunyuan_image3_vllm \
    --mount type=bind,source=/path/to/model,target=/model \
    sh HunyuanImage-3.0/vllm_infer/run_vllm_server.sh /model