optimum-habana 1.14.1

Optimum Habana is the interface between the Hugging Face Transformers and Diffusers libraries and Habana's Gaudi processor (HPU). It provides a set of tools enabling easy model loading, training and inference on single- and multi-HPU settings for different downstream tasks.

Optimum for Intel® Gaudi® Accelerators

Optimum for Intel Gaudi - a.k.a. optimum-habana - is the interface between the Transformers and Diffusers libraries and Intel Gaudi AI Accelerators (HPU). It provides a set of tools enabling easy model loading, training and inference on single- and multi-HPU settings for different downstream tasks. The list of officially validated models and tasks is available here. Users can try other of the thousands of Hugging Face models on Intel Gaudi accelerators and tasks with only few changes.

What are Intel Gaudi AI Accelerators (HPUs)?

HPUs offer fast model training and inference as well as a great price-performance ratio. Check out this blog post about BLOOM inference and this post benchmarking Intel Gaudi 2 and NVIDIA A100 GPUs for BridgeTower training for concrete examples.

Gaudi Setup

Please refer to the Intel Gaudi AI Accelerator official installation guide.

Tests should be run in a Docker container based on Intel Gaudi Docker images.

The current version has been validated for SynapseAI 1.18.

Install the library and get example scripts

Option 1: Use the latest stable release

To install the latest stable release of this package

pip install --upgrade-strategy eager optimum[habana]

The --upgrade-strategy eager option is needed to ensure optimum-habana is upgraded to the latest stable release.

To use the example associated with the latest stable release, run:

git clone https://github.com/huggingface/optimum-habana
cd optimum-habana && git checkout v1.14.0

with v1.14.0 the version number of this release.

Option 2: Use the latest main branch under development

Optimum for Intel Gaudi is a fast-moving project, and you may want to install it from source and get the latest scripts :

pip install git+https://github.com/huggingface/optimum-habana.git
git clone https://github.com/huggingface/optimum-habana

Option 3: Use the transformers_future branch to have the latest changes from Transformers

The transformers_future branch is regularly updated with the latest changes from the main branches of Optimum Habana and Transformers. This enables you to try out new Transformers features that have not been merged into the main branch yet.

[!WARNING] The transformers_future branch may have some regressions or bugs and may be less stable than the main branch.

pip install git+https://github.com/huggingface/optimum-habana.git@transformers_future
git clone -b transformers_future https://github.com/huggingface/optimum-habana

Install dependencies

To use DeepSpeed on HPUs, you also need to run the following command:

pip install git+https://github.com/HabanaAI/DeepSpeed.git@1.18.0

To install the requirements for every example:

cd <example-folder>
pip install -r requirements.txt

How to use it?

Quick Start

Optimum for Intel Gaudi was designed with one goal in mind: to make training and inference straightforward for Transformers and Diffusers users, while fully leveraging the power of Intel Gaudi AI Accelerators.

Transformers Interface

There are two main classes one needs to know:

• GaudiTrainer: the trainer class that takes care of compiling and distributing the model to run on HPUs, and performing training and evaluation.
• GaudiConfig: the class that enables to configure Habana Mixed Precision and to decide whether optimized operators and optimizers should be used or not.

The GaudiTrainer is very similar to the Transformers Trainer, and adapting a script using the Trainer to make it work with Intel Gaudi accelerators will mostly consist in simply swapping the Trainer class for the GaudiTrainer one. That's how most of the example scripts were adapted from their original counterparts.

Here is an example:

- from transformers import Trainer, TrainingArguments
+ from optimum.habana import GaudiConfig, GaudiTrainer, GaudiTrainingArguments

- training_args = TrainingArguments(
+ training_args = GaudiTrainingArguments(
  # training arguments...
+ use_habana=True,
+ use_lazy_mode=True,  # whether to use lazy or eager mode
+ gaudi_config_name=path_to_gaudi_config,
)

# A lot of code here

# Initialize our Trainer
- trainer = Trainer(
+ trainer = GaudiTrainer(
    model=model,
    args=training_args,  # Original training arguments.
    train_dataset=train_dataset if training_args.do_train else None,
    eval_dataset=eval_dataset if training_args.do_eval else None,
    compute_metrics=compute_metrics,
    tokenizer=tokenizer,
    data_collator=data_collator,
)

where gaudi_config_name is the name of a model from the Hub (Intel Gaudi configurations are stored in model repositories) or a path to a local Intel Gaudi configuration file (you can see here how to write your own).

Diffusers Interface

You can generate images from prompts using Stable Diffusion on Intel Gaudi using the GaudiStableDiffusionPipeline class and the [GaudiDDIMScheduler] which have been both optimized for HPUs. Here is how to use them and the differences with the Diffusers library:

- from diffusers import DDIMScheduler, StableDiffusionPipeline
+ from optimum.habana.diffusers import GaudiDDIMScheduler, GaudiStableDiffusionPipeline


model_name = "CompVis/stable-diffusion-v1-4"

- scheduler = DDIMScheduler.from_pretrained(model_name, subfolder="scheduler")
+ scheduler = GaudiDDIMScheduler.from_pretrained(model_name, subfolder="scheduler")

- pipeline = StableDiffusionPipeline.from_pretrained(
+ pipeline = GaudiStableDiffusionPipeline.from_pretrained(
    model_name,
    scheduler=scheduler,
+   use_habana=True,
+   use_hpu_graphs=True,
+   gaudi_config="Habana/stable-diffusion",
)

outputs = generator(
    ["An image of a squirrel in Picasso style"],
    num_images_per_prompt=16,
+   batch_size=4,
)

Documentation

Check out the documentation of Optimum for Intel Gaudi for more advanced usage.

Validated Models

The following model architectures, tasks and device distributions have been validated for Optimum for Intel Gaudi:

In the tables below, :heavy_check_mark: means single-card, multi-card and DeepSpeed have all been validated.

• Transformers:

Architecture	Training	Inference	Tasks
BERT	:heavy_check_mark:	:heavy_check_mark:	text classification question answering language modeling text feature extraction
RoBERTa	:heavy_check_mark:	:heavy_check_mark:	question answering language modeling
ALBERT	:heavy_check_mark:	:heavy_check_mark:	question answering language modeling
DistilBERT	:heavy_check_mark:	:heavy_check_mark:	question answering language modeling
GPT2	:heavy_check_mark:	:heavy_check_mark:	language modeling text generation
BLOOM(Z)		DeepSpeed	text generation
StarCoder / StarCoder2	:heavy_check_mark:	Single card	language modeling text generation
GPT-J	DeepSpeed	Single card DeepSpeed	language modeling text generation
GPT-Neo		Single card	text generation
GPT-NeoX	DeepSpeed	DeepSpeed	language modeling text generation
OPT		DeepSpeed	text generation
Llama 2 / CodeLlama / Llama 3 / Llama Guard / Granite	:heavy_check_mark:	:heavy_check_mark:	language modeling text generation question answering text classification (Llama Guard)
StableLM		Single card	text generation
Falcon	LoRA	:heavy_check_mark:	language modeling text generation
CodeGen		Single card	text generation
MPT		Single card	text generation
Mistral		Single card	text generation
Phi	:heavy_check_mark:	Single card	language modeling text generation
Mixtral		Single card	text generation
Persimmon		Single card	text generation
Qwen2	Single card	Single card	language modeling text generation
Qwen2-MoE		Single card	text generation
Gemma	:heavy_check_mark:	Single card	language modeling text generation
T5 / Flan T5	:heavy_check_mark:	:heavy_check_mark:	summarization translation question answering
BART		Single card	summarization translation question answering
ViT	:heavy_check_mark:	:heavy_check_mark:	image classification
Swin	:heavy_check_mark:	:heavy_check_mark:	image classification
Wav2Vec2	:heavy_check_mark:	:heavy_check_mark:	audio classification speech recognition
Whisper	:heavy_check_mark:	:heavy_check_mark:	speech recognition
SpeechT5		Single card	text to speech
CLIP	:heavy_check_mark:	:heavy_check_mark:	contrastive image-text training
BridgeTower	:heavy_check_mark:	:heavy_check_mark:	contrastive image-text training
ESMFold		Single card	protein folding
Blip		Single card	visual question answering image to text
OWLViT		Single card	zero shot object detection
ClipSeg		Single card	object segmentation
Llava / Llava-next		Single card	image to text
Segment Anything Model		Single card	object segmentation
VideoMAE		Single card	Video classification
TableTransformer		Single card	table object detection
DETR		Single card	object detection

• Diffusers:

Architecture	Training	Inference	Tasks
Stable Diffusion	textual inversion ControlNet	Single card	text-to-image generation
Stable Diffusion XL	fine-tuning	Single card	text-to-image generation
Stable Diffusion Depth2img		Single card	depth-to-image generation
LDM3D		Single card	text-to-image generation
Text to Video		Single card	text-to-video generation

• PyTorch Image Models/TIMM:

Architecture	Training	Inference	Tasks
FastViT		Single card	image classification

• TRL:

Architecture	Training	Inference	Tasks
Llama 2	:heavy_check_mark:		DPO Pipeline
Llama 2	:heavy_check_mark:		PPO Pipeline
Stable Diffusion	:heavy_check_mark:		DDPO Pipeline

Other models and tasks supported by the Transformers and Diffusers libraries may also work. You can refer to this section for using them with Optimum for Intel Gaudi. In addition, this page explains how to modify any example from the Transformers library to make it work with Optimum for Intel Gaudi.

If you find any issues while using those, please open an issue or a pull request.

After training your model, feel free to submit it to the Intel leaderboard which is designed to evaluate, score, and rank open-source LLMs that have been pre-trained or fine-tuned on Intel Hardwares. Models submitted to the leaderboard will be evaluated on the Intel Developer Cloud. The evaluation platform consists of Gaudi Accelerators and Xeon CPUs running benchmarks from the Eleuther AI Language Model Evaluation Harness.

Development

Check the contributor guide for instructions.