Model card

be8cc71 verified 8 days ago

7.13 kB

---
license: apache-2.0
library_name: cortiq
base_model: ostris/primal_vae
base_model_relation: quantized
tags:
  - cmf
  - cortiq
  - vae
  - autoencoder
  - latent-diffusion
  - vulkan
  - metal
language:
  - en
  - ru
  - zh
---
# Primal VAE — CMF

[Ostris Primal VAE](https://huggingface.co/ostris/primal_vae) — a deterministic
convolutional autoencoder that compresses an image 2× spatially into 1 or 2
channels whose values are already unit normal (no scaling or shift factor;
patchify by 4 for the 16- or 32-channel 8× layout of the Flux.1 / Flux.2 VAEs) —
packaged as single [CMF](https://github.com/infosave2007/cmf) files. They run
with `cortiq`, a Rust inference engine with no Python and no ML framework: the
whole encode or decode runs on the GPU (Vulkan/DX12 on NVIDIA, AMD and Intel,
Metal on Apple silicon) in one submission, or on the CPU.

[English](#quick-start) · [Русский](#документация-на-русском) · [中文](#中文说明)

## Quick start

```bash
cargo install cortiq-cli
hf download infosave/primal_vae-cmf primal_vae_2x2.cmf --local-dir .
cortiq vae --model primal_vae_2x2.cmf --mode roundtrip --input photo.png --output recon.png
```

Use cortiq 0.8.51 or later; prebuilt binaries for Linux, macOS and Windows
are on the [releases page](https://github.com/infosave2007/cmf/releases). Image
sides must be multiples of 16.

## Files

| file | latent | patch 4 = | size | PSNR on the card's three images |
|---|---|---|---:|---|
| `primal_vae_2x2.cmf` | 2 channels at 2× | 32 ch at 8× (Flux.2 layout) | 160,948,224 B (161 MB) | 37.5 / 27.1 / 27.4 dB |
| `primal_vae_2x1.cmf` | 1 channel at 2× | 16 ch at 8× (Flux.1 layout) | 160,944,128 B (161 MB) | 32.1 / 22.1 / 21.3 dB |

Both are the same 80 M-parameter network with 16-bit kernels (biases and norm
weights exact). Against the original float32 model in PyTorch on the same
images, the reconstructions have the same PSNR to 0.01 dB and the latents differ
by at most 0.14 % of their range.

## Usage

```bash
cortiq vae --model primal_vae_2x2.cmf --mode encode --input photo.png --output latent.npy   # [1, 2, H/2, W/2]
cortiq vae --model primal_vae_2x2.cmf --mode decode --input latent.npy --output image.png
cortiq vae --model primal_vae_2x2.cmf --mode roundtrip --input photo.png --output recon.png  # prints the PSNR
```

The latent is a float32 `.npy` of shape `[1, C, H/2, W/2]`, ~N(0, 1) per image
and channel — feed it to a diffusion model as it is, or patchify by 4
(`pixel_unshuffle`) for the 8× token grid. `decode` accepts `[1, C, h, w]` or
`[C, h, w]`; the image size is the latent's ×2. `CMF_GPU=0` forces the CPU.

## Performance

cortiq 0.8.51, `cortiq vae` (weights loaded once, the GPU run is one submission):

| device | 512×512 encode / decode | 1024×1024 encode / decode |
|---|---:|---:|
| NVIDIA A40 (Vulkan) | 0.20 s / 0.08 s | 0.40 s / 0.29 s |
| Apple M4 (Metal) | 0.34 s / 0.32 s | 1.27 s / 1.23 s |
| CPU (A40 host) | 3.9 s / 3.6 s | 13.3 s / 12.6 s |

## Verify

```bash
sha256sum -c primal_vae_2x2.cmf.sha256
```

```
2e81d119d8985bab6ed03f707992d44c0ce23e5e12d096766160adc6d5b4dc8d  primal_vae_2x2.cmf
979db68b6902aba6906d442f2034b0b8846e9e08f848f85c1d5cd065b5157eb9  primal_vae_2x1.cmf
```

## Reproduce

```bash
hf download ostris/primal_vae --local-dir primal_vae
cortiq convert --model primal_vae/primal_vae_2x2.safetensors --output primal_vae_2x2.cmf
cortiq convert --model primal_vae/primal_vae_2x1.safetensors --output primal_vae_2x1.cmf
```

## License

Apache-2.0, as the original release; the weights were converted to CMF by cortiq.

---

## Документация на русском

[Primal VAE от Ostris](https://huggingface.co/ostris/primal_vae) — детерминированный
свёрточный автоэнкодер: сжимает изображение в 2 раза по сторонам до 1 или 2
каналов, распределённых как N(0, 1) (без scaling/shift; patchify 4 даёт
16- или 32-канальную раскладку 8× VAE Flux.1 / Flux.2). Здесь он упакован в
одиночные файлы [CMF](https://github.com/infosave2007/cmf) для `cortiq` —
движка на Rust без Python: кодирование и декодирование целиком идут на GPU
(Vulkan/DX12, Metal) одной отправкой, либо на CPU.

```bash
cargo install cortiq-cli
hf download infosave/primal_vae-cmf primal_vae_2x2.cmf --local-dir .
cortiq vae --model primal_vae_2x2.cmf --mode roundtrip --input photo.png --output recon.png
```

Нужен cortiq 0.8.51 или новее. Стороны картинки кратны 16.

| файл | латент | размер | PSNR на трёх картинках карточки |
|---|---|---:|---|
| `primal_vae_2x2.cmf` | 2 канала, 2× | 160,948,224 B (161 MB) | 37,5 / 27,1 / 27,4 дБ |
| `primal_vae_2x1.cmf` | 1 канал, 2× | 160,944,128 B (161 MB) | 32,1 / 22,1 / 21,3 дБ |

Ядра свёрток 16-битные, смещения и веса норм точные; против исходной модели
float32 в PyTorch PSNR совпадает до 0,01 дБ, латенты отличаются не более чем
на 0,14 % диапазона. `--mode encode` пишет латент `[1, C, H/2, W/2]` в `.npy`,
`--mode decode` собирает картинку обратно, `roundtrip` печатает PSNR.

Скорость (cortiq 0.8.51): кодирование / декодирование 1024×1024 — 0.40 / 0.29 с
на NVIDIA A40 (Vulkan), 1.27 / 1.23 с на Apple M4 (Metal), около 13 с на CPU.

---

## 中文说明

[Ostris Primal VAE](https://huggingface.co/ostris/primal_vae) 是一个确定性卷积自编码器：
把图像在空间上压缩 2 倍，得到 1 或 2 个通道、本身即服从 N(0, 1) 的潜变量（无需
scaling/shift；按 4 做 patchify 即得到 Flux.1 / Flux.2 VAE 的 16 / 32 通道 8× 布局）。
这里打包为单个 [CMF](https://github.com/infosave2007/cmf) 文件，由 Rust 推理引擎
`cortiq` 运行（无 Python）：整个编码或解码在 GPU 上一次提交完成（Vulkan/DX12、Metal），
也可在 CPU 上运行。

```bash
cargo install cortiq-cli
hf download infosave/primal_vae-cmf primal_vae_2x2.cmf --local-dir .
cortiq vae --model primal_vae_2x2.cmf --mode roundtrip --input photo.png --output recon.png
```

需要 cortiq 0.8.51 或更高版本，图像边长须为 16 的倍数。

| 文件 | 潜变量 | 大小 | 卡片三张图的 PSNR |
|---|---|---:|---|
| `primal_vae_2x2.cmf` | 2 通道，2× | 160,948,224 B (161 MB) | 37.5 / 27.1 / 27.4 dB |
| `primal_vae_2x1.cmf` | 1 通道，2× | 160,944,128 B (161 MB) | 32.1 / 22.1 / 21.3 dB |

卷积核为 16 位，偏置与归一化权重保持精确；与 PyTorch 中的原始 float32 模型相比，
PSNR 相差不超过 0.01 dB，潜变量差异不超过其范围的 0.14%。

速度（cortiq 0.8.51）：1024×1024 编码 / 解码在 NVIDIA A40（Vulkan）上为 0.40 / 0.29 s，
在 Apple M4（Metal）上为 1.27 / 1.23 s，CPU 约 13 s。

	---
	license: apache-2.0
	library_name: cortiq
	base_model: ostris/primal_vae
	base_model_relation: quantized
	tags:
	- cmf
	- cortiq
	- vae
	- autoencoder
	- latent-diffusion
	- vulkan
	- metal
	language:
	- en
	- ru
	- zh
	---

	# Primal VAE — CMF

	[Ostris Primal VAE](https://huggingface.co/ostris/primal_vae) — a deterministic
	convolutional autoencoder that compresses an image 2× spatially into 1 or 2
	channels whose values are already unit normal (no scaling or shift factor;
	patchify by 4 for the 16- or 32-channel 8× layout of the Flux.1 / Flux.2 VAEs) —
	packaged as single [CMF](https://github.com/infosave2007/cmf) files. They run
	with `cortiq`, a Rust inference engine with no Python and no ML framework: the
	whole encode or decode runs on the GPU (Vulkan/DX12 on NVIDIA, AMD and Intel,
	Metal on Apple silicon) in one submission, or on the CPU.

	[English](#quick-start) · [Русский](#документация-на-русском) · [中文](#中文说明)

	## Quick start

	```bash
	cargo install cortiq-cli
	hf download infosave/primal_vae-cmf primal_vae_2x2.cmf --local-dir .
	cortiq vae --model primal_vae_2x2.cmf --mode roundtrip --input photo.png --output recon.png
	```

	Use cortiq 0.8.51 or later; prebuilt binaries for Linux, macOS and Windows
	are on the [releases page](https://github.com/infosave2007/cmf/releases). Image
	sides must be multiples of 16.

	## Files

	\| file \| latent \| patch 4 = \| size \| PSNR on the card's three images \|
	\|---\|---\|---\|---:\|---\|
	\| `primal_vae_2x2.cmf` \| 2 channels at 2× \| 32 ch at 8× (Flux.2 layout) \| 160,948,224 B (161 MB) \| 37.5 / 27.1 / 27.4 dB \|
	\| `primal_vae_2x1.cmf` \| 1 channel at 2× \| 16 ch at 8× (Flux.1 layout) \| 160,944,128 B (161 MB) \| 32.1 / 22.1 / 21.3 dB \|

	Both are the same 80 M-parameter network with 16-bit kernels (biases and norm
	weights exact). Against the original float32 model in PyTorch on the same
	images, the reconstructions have the same PSNR to 0.01 dB and the latents differ
	by at most 0.14 % of their range.

	## Usage

	```bash
	cortiq vae --model primal_vae_2x2.cmf --mode encode --input photo.png --output latent.npy # [1, 2, H/2, W/2]
	cortiq vae --model primal_vae_2x2.cmf --mode decode --input latent.npy --output image.png
	cortiq vae --model primal_vae_2x2.cmf --mode roundtrip --input photo.png --output recon.png # prints the PSNR
	```

	The latent is a float32 `.npy` of shape `[1, C, H/2, W/2]`, ~N(0, 1) per image
	and channel — feed it to a diffusion model as it is, or patchify by 4
	(`pixel_unshuffle`) for the 8× token grid. `decode` accepts `[1, C, h, w]` or
	`[C, h, w]`; the image size is the latent's ×2. `CMF_GPU=0` forces the CPU.

	## Performance

	cortiq 0.8.51, `cortiq vae` (weights loaded once, the GPU run is one submission):

	\| device \| 512×512 encode / decode \| 1024×1024 encode / decode \|
	\|---\|---:\|---:\|
	\| NVIDIA A40 (Vulkan) \| 0.20 s / 0.08 s \| 0.40 s / 0.29 s \|
	\| Apple M4 (Metal) \| 0.34 s / 0.32 s \| 1.27 s / 1.23 s \|
	\| CPU (A40 host) \| 3.9 s / 3.6 s \| 13.3 s / 12.6 s \|

	## Verify

	```bash
	sha256sum -c primal_vae_2x2.cmf.sha256
	```

	```
	2e81d119d8985bab6ed03f707992d44c0ce23e5e12d096766160adc6d5b4dc8d primal_vae_2x2.cmf
	979db68b6902aba6906d442f2034b0b8846e9e08f848f85c1d5cd065b5157eb9 primal_vae_2x1.cmf
	```

	## Reproduce

	```bash
	hf download ostris/primal_vae --local-dir primal_vae
	cortiq convert --model primal_vae/primal_vae_2x2.safetensors --output primal_vae_2x2.cmf
	cortiq convert --model primal_vae/primal_vae_2x1.safetensors --output primal_vae_2x1.cmf
	```

	## License

	Apache-2.0, as the original release; the weights were converted to CMF by cortiq.

	---

	## Документация на русском

	[Primal VAE от Ostris](https://huggingface.co/ostris/primal_vae) — детерминированный
	свёрточный автоэнкодер: сжимает изображение в 2 раза по сторонам до 1 или 2
	каналов, распределённых как N(0, 1) (без scaling/shift; patchify 4 даёт
	16- или 32-канальную раскладку 8× VAE Flux.1 / Flux.2). Здесь он упакован в
	одиночные файлы [CMF](https://github.com/infosave2007/cmf) для `cortiq` —
	движка на Rust без Python: кодирование и декодирование целиком идут на GPU
	(Vulkan/DX12, Metal) одной отправкой, либо на CPU.

	```bash
	cargo install cortiq-cli
	hf download infosave/primal_vae-cmf primal_vae_2x2.cmf --local-dir .
	cortiq vae --model primal_vae_2x2.cmf --mode roundtrip --input photo.png --output recon.png
	```

	Нужен cortiq 0.8.51 или новее. Стороны картинки кратны 16.

	\| файл \| латент \| размер \| PSNR на трёх картинках карточки \|
	\|---\|---\|---:\|---\|
	\| `primal_vae_2x2.cmf` \| 2 канала, 2× \| 160,948,224 B (161 MB) \| 37,5 / 27,1 / 27,4 дБ \|
	\| `primal_vae_2x1.cmf` \| 1 канал, 2× \| 160,944,128 B (161 MB) \| 32,1 / 22,1 / 21,3 дБ \|

	Ядра свёрток 16-битные, смещения и веса норм точные; против исходной модели
	float32 в PyTorch PSNR совпадает до 0,01 дБ, латенты отличаются не более чем
	на 0,14 % диапазона. `--mode encode` пишет латент `[1, C, H/2, W/2]` в `.npy`,
	`--mode decode` собирает картинку обратно, `roundtrip` печатает PSNR.

	Скорость (cortiq 0.8.51): кодирование / декодирование 1024×1024 — 0.40 / 0.29 с
	на NVIDIA A40 (Vulkan), 1.27 / 1.23 с на Apple M4 (Metal), около 13 с на CPU.

	---

	## 中文说明

	[Ostris Primal VAE](https://huggingface.co/ostris/primal_vae) 是一个确定性卷积自编码器：
	把图像在空间上压缩 2 倍，得到 1 或 2 个通道、本身即服从 N(0, 1) 的潜变量（无需
	scaling/shift；按 4 做 patchify 即得到 Flux.1 / Flux.2 VAE 的 16 / 32 通道 8× 布局）。
	这里打包为单个 [CMF](https://github.com/infosave2007/cmf) 文件，由 Rust 推理引擎
	`cortiq` 运行（无 Python）：整个编码或解码在 GPU 上一次提交完成（Vulkan/DX12、Metal），
	也可在 CPU 上运行。

	```bash
	cargo install cortiq-cli
	hf download infosave/primal_vae-cmf primal_vae_2x2.cmf --local-dir .
	cortiq vae --model primal_vae_2x2.cmf --mode roundtrip --input photo.png --output recon.png
	```

	需要 cortiq 0.8.51 或更高版本，图像边长须为 16 的倍数。

	\| 文件 \| 潜变量 \| 大小 \| 卡片三张图的 PSNR \|
	\|---\|---\|---:\|---\|
	\| `primal_vae_2x2.cmf` \| 2 通道，2× \| 160,948,224 B (161 MB) \| 37.5 / 27.1 / 27.4 dB \|
	\| `primal_vae_2x1.cmf` \| 1 通道，2× \| 160,944,128 B (161 MB) \| 32.1 / 22.1 / 21.3 dB \|

	卷积核为 16 位，偏置与归一化权重保持精确；与 PyTorch 中的原始 float32 模型相比，
	PSNR 相差不超过 0.01 dB，潜变量差异不超过其范围的 0.14%。

	速度（cortiq 0.8.51）：1024×1024 编码 / 解码在 NVIDIA A40（Vulkan）上为 0.40 / 0.29 s，
	在 Apple M4（Metal）上为 1.27 / 1.23 s，CPU 约 13 s。