> ## Documentation Index
> Fetch the complete documentation index at: https://docs.r3al.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# QAT pipeline

> Quantization-aware training for any vision model, via the R3AL platform.

QAT is the second paradigm in the R3AL.AI SDK. Where PTQ needs no training, QAT **fine-tunes** your model with quantization simulated in the loop, then quantizes it. The training runs on R3AL GPU infrastructure; the SDK uploads your model and images, streams progress, and downloads the result. A QAT job consumes one plan run.

## When to use it

```text theme={null}
PTQ accuracy acceptable?         → use PTQ (ptq_dynamic / ptq_static)
Low bit-width (3-4 bit) needed?  → QAT recovers accuracy PTQ can't
Have representative images?      → QAT
```

## Run it

```python theme={null}
import r3alai.platform as platform
from r3alai.quant import QuantConfig, Quantizer

platform.login("r3l_live_...")   # or set R3AL_API_KEY

config = QuantConfig(mode="qat", qat_wbit=8, qat_abit=8)
result = Quantizer(config).train_qat(
    "model.onnx",
    calibration_data=["/data/img1.jpg", "/data/img2.jpg"],
    output_dir="./qat_out",
    epochs=3,
)
print(result.path)
```

## What happens on the platform

<Steps>
  <Step title="Upload">
    The SDK uploads your model (exporting to ONNX locally first if you passed a checkpoint) and your calibration images.
  </Step>

  <Step title="Fine-tune with quantization in the loop">
    R3AL's engine trains on GPU with lower precision simulated during the forward pass, and automatically protects accuracy-sensitive layers.
  </Step>

  <Step title="Download the bundle">
    The engine exports a standard quantized ONNX model plus `r3alai_manifest.json`, downloaded into your `output_dir`.
  </Step>
</Steps>

## Key options

| Field                   | Default   | Description                                                |
| ----------------------- | --------- | ---------------------------------------------------------- |
| `model`                 | required  | Path to `.onnx` (or a checkpoint for local export)         |
| `calibration_data`      | required  | Training / calibration images                              |
| `epochs`                | `1`       | Training epochs (`1` = smoke test)                         |
| `qat_wbit` / `qat_abit` | `8` / `8` | Weight / activation bit widths (3-8), set on `QuantConfig` |
| `qat_calib_batches`     | `16`      | Batches for activation calibration, set on `QuantConfig`   |
| `learning_rate`         | `1e-4`    | Optimizer learning rate, passed to `train_qat()`           |

See [QAT explained](/concepts/qat) for a detailed breakdown of `qat_wbit` and `qat_abit`.

## Monitoring and results

`train_qat()` blocks and prints live progress; you can also follow the job on the platform's **Jobs** page. When it finishes, the deliverable is downloaded and `result.path` points at the bundle:

```text theme={null}
qat_out/
├── model_qat.quantized.onnx
└── r3alai_manifest.json
```

<Warning>
  `epochs=1` is a smoke test, not a converged model. Use representative images from your deployment domain and more epochs for production runs.
</Warning>

## Next steps

<CardGroup cols={2}>
  <Card title="QAT explained" icon="dumbbell" href="/concepts/qat">
    Deep dive on wbit, abit, and epochs.
  </Card>

  <Card title="Calibration" icon="images" href="/concepts/calibration">
    Building a representative image set for QAT.
  </Card>
</CardGroup>