> For the complete documentation index, see [llms.txt](https://docs.roboflow.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.roboflow.com/models/supported-models/foundad.md).

# FoundAD

Train FoundAD anomaly detection models on normal images in Roboflow and run them through the Serverless Cloud API

FoundAD finds defects without needing pictures of them. It learns what a normal part looks like from normal images only, then flags any image that departs from it. It pairs a frozen DINOv3 encoder with a small predictor trained to rebuild the features of normal images. Image patches the predictor can't rebuild are anomalous. Each prediction returns a "normal" or "anomalous" verdict, a raw anomaly score, and a heatmap of where the image differs. The encoder is a ViT-B, so FoundAD runs best on a GPU. Its inference time is the same at any training set size.

<figure><img src="https://3448603185-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fcmo9mhfIjYrvFFy1U7dk%2Fuploads%2Fgit-blob-683f809344207112fede594158241aa65f00edf6%2Ffoundad-egg-anomaly-heatmap.webp?alt=media" alt="FoundAD results on a normal egg, a cracked egg, and a stained egg: the normal egg is framed in green, the cracked and stained eggs are framed in red with a heatmap on each defect"><figcaption><p>A FoundAD model trained on normal eggs passes the clean egg and flags the cracked and stained eggs. The heatmap marks where each image is above the anomaly threshold, from green at the edge to red at the strongest point.</p></figcaption></figure>

Try [PatchCore](/models/supported-models/patchcore.md) if you need fast scoring on a CPU and 224×224 images show your defects. FoundAD is more accurate, especially with only a few normal images. See [Choosing an anomaly detection model](/models/supported-tasks/anomaly-detection.md#choosing-an-anomaly-detection-model) to compare the two.

## Train FoundAD

{% stepper %}
{% step %}

### Label normal and anomalous images

Create an Anomaly Detection [Project](https://docs.roboflow.com/datasets/create-and-upload/create-a-project), upload images, and label each one "normal" or "anomalous". Most of your images should be normal. The model trains on normal images only. Anomalous images set the decision threshold and measure accuracy, so they go to the valid and test splits only.
{% endstep %}

{% step %}

### Generate a version

Use only the auto-orient and "Stretch to" resize preprocessing steps, and no augmentation. The image size must be square, from 32 to 1024 pixels, and divisible by 16. FoundAD defaults to 512×512.
{% endstep %}

{% step %}

### Start a training

[Train a model](/models/train/train-a-model.md) and pick FoundAD. Training takes longer than PatchCore, up to hours on large datasets. When training finishes, Roboflow reports precision, recall, and F1 on the test set, using the threshold it saved during training.
{% endstep %}
{% endstepper %}

## FoundAD API

{% stepper %}
{% step %}

### Get your API Key

Find your key on the [Roboflow API settings page](https://app.roboflow.com/settings/api) and make it available to your shell:

```bash
export ROBOFLOW_API_KEY="your-key-here"
```

{% endstep %}

{% step %}

### Install the dependencies

Install the [Inference SDK](https://docs.roboflow.com/deployment/self-hosted/self-hosted):

```bash
pip install -U inference-sdk
```

{% endstep %}

{% step %}

### Run the model

Call your trained model by its ID (see [Versions, Trainings, and Models](/models/versions-trainings-and-models.md)).

```python
import os
from inference_sdk import InferenceHTTPClient, InferenceConfiguration

client = InferenceHTTPClient(
    api_url="https://serverless.roboflow.com",
    api_key=os.environ["ROBOFLOW_API_KEY"],
).configure(InferenceConfiguration(api_key_transport="header", include_anomaly_map=True))

# Replace "your-project/1" with your model ID.
result = client.infer("my-image.jpg", model_id="your-project/1")

print(result["top"])  # "normal" or "anomalous"
print(result["anomaly_score"], result["anomaly_threshold"])
heatmap = result["anomaly_map"]  # NumPy array, larger values are more anomalous
```

{% endstep %}
{% endstepper %}

The response has these fields:

* `top`: the verdict, "normal" or "anomalous".
* `anomaly_score`: the raw score. Larger means more anomalous. The score has no fixed range.
* `anomaly_threshold`: the score at which an image becomes anomalous, saved during training.
* `confidence` and `predictions`: the confidence of the verdict, and of each class. The "anomalous" confidence grows with the score and is exactly 0.5 at the threshold, so it is not a defect probability.
* `anomaly_map`: the heatmap, returned only when you set `include_anomaly_map=True`. It is a square array at the model's input size, so stretch it to your image's width and height to overlay it.

{% hint style="info" %}
Set `api_url` to match your deployment target:

* `https://serverless.roboflow.com` for the Serverless Cloud API.
* `http://localhost:9001` for a local [Inference](https://docs.roboflow.com/deployment/self-hosted/self-hosted) server, version 1.7.4 or later.
* Your [Dedicated Deployment](https://docs.roboflow.com/deployment/roboflow-cloud/dedicated-deployments) URL for a private endpoint.
  {% endhint %}

## Use FoundAD in a Workflow

Add the [Anomaly Detection Model](https://docs.roboflow.com/workflows/blocks/blocks/run-a-model/anomaly-detection-model) block to a [Workflow](https://docs.roboflow.com/workflows) to score images, then connect its `anomaly_map` output to the [Anomaly Heatmap Visualization](https://docs.roboflow.com/workflows/blocks/blocks/visualize-predictions/anomaly-heatmap-visualization) block to draw the heatmap. Self-hosted Workflows need Inference 1.8.2 or later for these blocks. Change the block's `confidence` to trade missed defects for false alarms without retraining: lower it to flag more images as anomalous.

## License

FoundAD follows [ymxlzgy/FoundAD](https://github.com/ymxlzgy/FoundAD) and is licensed under MIT. Its DINOv3 encoder weights are covered by the [DINOv3 license](https://github.com/facebookresearch/dinov3?tab=License-1-ov-file). See [Model Licenses](/models/model-licenses.md#other-models).