<!---
Copyright 2024 The HuggingFace Team. All rights reserved.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->

# 🤗 Optimum TPU

Optimum TPU provides all the necessary machinery to leverage and optimize AI workloads running on [Google Cloud TPU devices](https://cloud.google.com/tpu/docs).

The API provides the overall same user-experience as Hugging Face transformers with the minimum amount of changes required to target performance for inference and training.

## Installation

Optimum TPU is meant to reduce as much as possible the friction in order to leverage Google Cloud TPU accelerators.
As such, we provide a pip installable package to make sure everyone can get easily started.

### Run Cloud TPU with pip
```bash
pip install optimum-tpu -f https://storage.googleapis.com/libtpu-releases/index.html
```

### Run Cloud TPU within Docker container

### PyTorch
```bash
export TPUVM_IMAGE_URL=us-central1-docker.pkg.dev/tpu-pytorch-releases/docker/xla
export TPUVM_IMAGE_VERSION=8f1dcd5b03f993e4da5c20d17c77aff6a5f22d5455f8eb042d2e4b16ac460526
docker pull
docker run -ti --rm --privileged --network=host ${TPUVM_IMAGE_URL}@sha256:${TPUVM_IMAGE_VERSION} bash
```

From there you can install optimum-tpu through the pip instructions mentioned above.


<div class="mt-10">
    <div class="w-full flex flex-col space-y-4 md:space-y-0 md:grid md:grid-cols-2 md:gap-y-4 md:gap-x-5">
        <a class="!no-underline border dark:border-gray-700 p-5 rounded-lg shadow hover:shadow-lg" href="./tutorials/overview">
            <div class="w-full text-center bg-gradient-to-br from-blue-400 to-blue-500 rounded-lg py-1.5 font-semibold mb-5 text-white text-lg leading-relaxed">
                Tutorials
            </div>
            <p class="text-gray-700">
              Learn the basics and become familiar with deploying transformers on Google TPUs.
              Start here if you are using 🤗 Optimum-TPU for the first time!
            </p>
        </a>
        <a
            class="!no-underline border dark:border-gray-700 p-5 rounded-lg shadow hover:shadow-lg"
            href="./howto/overview"
        >
            <div class="w-full text-center bg-gradient-to-br from-indigo-400 to-indigo-500 rounded-lg py-1.5 font-semibold mb-5 text-white text-lg leading-relaxed">
                How-to guides
            </div>
            <p class="text-gray-700">
              Practical guides to help you achieve a specific goal. Take a look at these guides to learn how to use 🤗 Optimum-TPU
              to solve real-world problems.
            </p>
        </a>
    </div>
</div>