README.md

---
license: other
tags:
- pathology
- medical
- vision
- transformers
base_model: owkin/phikon-v2
pipeline_tag: image-feature-extraction
extra_gated_prompt: >-
  - This model and associated code are released under Waiv custom license and
  may only be used for non-commercial, academic research purposes with proper
  attribution.

  - Any commercial use, sale, or other monetization of the phaet model and its
  derivatives, which include models trained on outputs from the phaet model or
  datasets created from the phaet model, is prohibited and requires prior
  approval.

  - Please note that the primary email used to sign up for your Hugging Face
  account must match your institutional email to receive approval. By
  downloading the model, you attest that all information (affiliation, research
  use) is correct and up-to-date. Downloading the model requires prior
  registration on Hugging Face and agreeing to the terms of use. By downloading
  this model, you agree not to distribute, publish or reproduce a copy of the
  model. If another user within your organization wishes to use the phaet model,
  they must register as an individual user and agree to comply with the terms of
  use. Users may not attempt to re-identify the deidentified data used to
  develop the underlying model.

  - This model is provided "as-is" without warranties of any kind, express or
  implied. This model has not been reviewed, certified, or approved by any
  regulatory body, including but not limited to the FDA (U.S.), EMA (Europe),
  MHRA (UK), or other medical device authorities. Any application of this model
  in healthcare or biomedical settings must comply with relevant regulatory
  requirements and undergo independent validation. Users assume full
  responsibility for how they use this model and any resulting consequences. The
  authors, contributors, and distributors disclaim any liability for damages,
  direct or indirect, resulting from model use. Users are responsible for
  ensuring compliance with data protection regulations (e.g., GDPR, HIPAA) when
  using it in research that involves patient data.

  - We require users to fill in their ORCID ID, which can be created at
  https://orcid.org/register.

  - If you are a commercial entity, please contact us at
  fm-license@wearewaiv.com to discuss licensing options.
extra_gated_fields:
  Full name (first and last): text
  Current affiliation (no abbreviations): text
  Country you work in (for the downloads world map): text
  Type of Affiliation:
    type: select
    options:
    - Industry
    - Higher Education
    - Pharmaceutical
    - Medical Devices
    - Biotechnology
    - Research
    - Hospital & Healthcare
    - Other
  ORCID: text
  Current and official institutional email (this must match your primary email in your Hugging Face account, @gmail/@hotmail/@qq email domains will be denied): text
  Main use-case:
    type: select
    options:
    - Models benchmarking on various tasks
    - Biomarker Discovery
    - Diagnostics
    - Pathology workflows acceleration (cell & tissue segmentation etc)
    - Other
  I agree to all terms outlined above: checkbox
  I agree not to distribute the model, if another user within your organization wishes to use the phaet model, they must register as an individual user: checkbox
  I agree to use this model for non-commercial, academic purposes only: checkbox
  I'm happy for Waiv to email me with news, product updates, and helpful content. No spam, unsubscribe any time. You can check our privacy policy at https://wearewaiv.com/policies/privacy-policy:
    type: select
    options:
    - 'No'
    - 'Yes'
---

# Say hi to Phaet, the robustified version of Phikon-v2, by Waiv


Waiv, formerly Owkin Dx, builds AI-powered digital pathology to catalyze precision medicine in oncology.
This organization hosts pathology foundation models and research artifacts we share with the community for benchmarking and research use.
On July 29th, 2026, we released:
- Phaet — a robustified version of Phikon-v2
- Mascaret — a robustified version of Midnight-12k

Both come from a model-agnostic fine-tuning recipe that makes pathology foundation models invariant to acquisition factors like scanner and lab, improving robustness and downstream performance together. The names follow a wave theme drawn from the Waiv brand — a mascaret is a tidal bore, a wave that carries its shape forward.

Learn more:
- Preprint: [Robustifying pathology foundation models via fine-tuning](https://arxiv.org/abs/2607.22861)
- Blog: [Meet Phaet and Mascaret: two pathology foundation models build to generalize across labs](https://wearewaiv.com/blog/meet-phaet-and-mascaret-two-pathology-foundation-models-built-to-generalize-across-labs)
- Website: [wearewaiv.com](https://wearewaiv.com)

![Graphical abstract](https://huggingface.co/wearewaiv/phaet/resolve/main/assets/graphical_abstract.gif)


## Usage

End-to-end example: load the model, load an image, extract features.

```python
import torch
import torchvision.transforms as T
from huggingface_hub import hf_hub_download
from PIL import Image
from transformers import AutoModel

REPO = "wearewaiv/phaet"

# Load the fine-tuned encoder
model = AutoModel.from_pretrained(REPO, trust_remote_code=True)
model.eval()

# Build the preprocessing transform from the model config
# (pixel_mean / pixel_std are stored in the config, so this stays correct)
transform = T.Compose([
    T.Resize(224),        # shorter side -> 224, aspect ratio preserved
    T.CenterCrop(224),    # ... then crop, so the result really is 224x224
    T.ToTensor(),
    T.Normalize(mean=model.config.pixel_mean, std=model.config.pixel_std),
])

# Load the example image shipped with this repository
image = Image.open(hf_hub_download(REPO, "assets/image.jpg")).convert("RGB")

# Preprocess -> (B, 3, 224, 224)
pixel_values = transform(image).unsqueeze(0)

# L2-normalised CLS embedding — the recommended feature vector
features = model.encode(pixel_values)       # (1, 1024); encode() is already no-grad
print(features.shape)

# Full token sequence when patch-level features are needed
with torch.inference_mode():
    out = model(pixel_values=pixel_values)
out.last_hidden_state                       # (1, 197, 1024) — CLS at index 0
out.pooler_output                           # (1, 1024)      — L2-normalised CLS (== features)
```

`trust_remote_code=True` makes `transformers` fetch this repository's
`modeling_finetuned_encoder.py`, and it prints a warning every time a new version of that
file is downloaded. Pass an explicit `revision` to pin the code you reviewed and silence it:

```python
model = AutoModel.from_pretrained(REPO, trust_remote_code=True, revision="<commit-sha>")
```

## Preprocessing

`pixel_mean` and `pixel_std` are stored in the config, so you never need to hardcode them:

```python
model.config.pixel_mean  # [0.485, 0.456, 0.406]
model.config.pixel_std   # [0.229, 0.224, 0.225]
```

## Environment

We recommend an isolated environment — `trust_remote_code` models are sensitive to the
`transformers` version, and mixing them into a large existing environment tends to surface
version conflicts:

```bash
uv venv --python 3.11 ~/venvs/waiv
source ~/venvs/waiv/bin/activate
uv pip install torch torchvision "transformers>=5.14,<6" "safetensors>=0.8.0" \
    huggingface-hub pillow
```

The snippet above is verified end-to-end on this combination:

| Package           | Version    |
| ----------------- | ---------- |
| Python            | 3.11       |
| `torch`           | 2.5.1+cu124 |
| `torchvision`     | 0.20.1+cu124 |
| `transformers`    | 5.14.1     |
| `safetensors`     | 0.8.0      |
| `huggingface_hub` | 1.25.1     |

Notes:

- `transformers` 5.x requires `safetensors >= 0.8.0`. An older `safetensors` pinned by some
  other dependency makes `import transformers` fail outright with an `ImportError` — this is the
  most common setup problem we see.
- `timm` is not needed for this model. It is imported lazily, and only for checkpoints that
  use the `timm` loader; this one uses the `hf_transformers` loader (DINOv2).
- CPU is fine for a handful of images. For batches, `model.to("cuda")` and move
  `pixel_values` to the same device.

## Acknowledgments

**Computing resources.** This work was granted access to the High-Performance Computing (HPC) resources of IDRIS under the allocation 2026-A0201012519 made by GENCI. Fine-tuning experiments were performed using the EuroHPC supercomputer MareNostrum 5, hosted by the Barcelona Supercomputing Center (BSC). We gratefully acknowledge EuroHPC and BSC for providing access to these resources under the EHPC-AIF-2026PG01-102 allocation.

**Data access.** The results presented here are in part based upon data generated by the TCGA Research Network: https://www.cancer.gov/tcga.

## License

This model is licensed under Waiv non-commercial license, available in this repository.

### Example image attribution

`assets/image.jpg`, used by the snippet above, is not covered by the Waiv license — it keeps
its own terms and is included solely as a runnable example input.

- Title: *Breast DCIS histopathology (1)* — histopathologic image of ductal carcinoma in situ
  (DCIS) of the breast, haematoxylin-eosin stain
- Author: KGH
- Source: [Wikimedia Commons](https://commons.wikimedia.org/wiki/File:Breast_DCIS_histopathology_(1).jpg)
- License: dual-licensed by the author — [CC BY-SA 3.0 Unported](https://creativecommons.org/licenses/by-sa/3.0/)
  or the [GNU Free Documentation License v1.2 or later](https://www.gnu.org/licenses/old-licenses/fdl-1.2.html);
  you may use either
- Changes: reproduced unmodified

<!-- ACCESS_MAP:START -->
## Where our users are

![World map of access-request origins](https://huggingface.co/wearewaiv/phaet/resolve/main/assets/access_worldmap.png?v=2026-08-03)

*Access-request origins (accepted) as of 2026-08-03. 2 located across 2 countries; 1 of unknown origin. Top: Germany (1), United States (1).*

<sub>Inferred from requesters' institutional email domains — Hugging Face does not expose per-download geolocation. For this gated model, granted requesters are the population able to download it.</sub>
<!-- ACCESS_MAP:END -->