Skip to content

Commit d272ed3

Browse files
authored
docs: marketing drafts and trust page (#22)
* docs(marketing): add HF model card template for dinov2-cpp-core GGUF repos * docs(marketing): add Show HN draft with verified numbers * docs(marketing): add launch blog post outline * docs: add trust and verification page * docs(marketing): add index and owner checklist
1 parent 2ca5a13 commit d272ed3

5 files changed

Lines changed: 464 additions & 0 deletions

File tree

‎docs/marketing/README.md‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
# Marketing drafts
2+
3+
Launch collateral for dinov2.cpp. Drafts only; nothing here is published
4+
yet. Every number in these files was verified against a repo artifact or a
5+
live HTTP check on 2026-09-23; re-verify before publishing if time passes.
6+
7+
## Contents
8+
9+
| File | Purpose |
10+
|:-----|:--------|
11+
| [hf-model-card-template.md](hf-model-card-template.md) | README/model-card template for the 8 `dinov2-cpp-core/*-gguf` HF repos (they ship only `model.gguf` + `.gitattributes` today, verified via the HF API). Includes a measured size lookup table. |
12+
| [show-hn-draft.md](show-hn-draft.md) | Show HN headline options and ~150-word body, restricted to verified numbers, with a source table. |
13+
| [blog-post-outline.md](blog-post-outline.md) | Full launch-post outline: hook, positioning, dedup-demo centerpiece, parity evidence, caveats draft, CTA. |
14+
15+
Related user-facing page (not marketing-internal): [../trust.md](../trust.md).
16+
17+
## Owner checklist (external steps, in rough order)
18+
19+
- [ ] **Upload the HF model cards.** Render `hf-model-card-template.md`
20+
once per repo (8 repos, lookup table at the bottom of the template) and
21+
upload as `README.md`. Needs an HF token with write access to
22+
`dinov2-cpp-core` (the `HF_TOKEN` secret already used by
23+
`convert-and-publish-gguf`; see `docs/hf-publishing.md`):
24+
`hf upload dinov2-cpp-core/<repo> README.md README.md --repo-type model`.
25+
The YAML frontmatter must be the first bytes of the file.
26+
- [ ] **Enable GitHub Pages** so the wasm demo (`wasm/index.html`) gets a
27+
live URL the Show HN and blog post can link to. Requires copying
28+
`dinov2-wasm.js` + `dinov2-wasm.wasm` plus a small GGUF next to the page
29+
per `docs/wasm.md`, or wiring CI to publish them.
30+
- [ ] **Set repo metadata**: GitHub topics (`ggml`, `gguf`, `dinov2`,
31+
`cpp`, `embeddings`, `vision-transformer`), the one-line description, and
32+
a social-preview image (Settings -> General -> Social preview;
33+
`assets/logo/logo-256.png` exists as a starting point).
34+
- [ ] **Post the Show HN** from `show-hn-draft.md` after Pages and the HF
35+
cards are live, so every link in the post resolves.
36+
- [ ] **Publish the blog post** from `blog-post-outline.md` (personal site
37+
first, then cross-posts).
38+
- [ ] **Testimonial permission**: if quoting a user or collaborator in any
39+
of the above, get explicit written permission first.
40+
41+
## Standing rules for this content
42+
43+
- No hype words, no invented numbers. If a number is not in
44+
`benchmark_results.txt`, `docs/parity/`, a release listing, or a live
45+
check, it does not go in.
46+
- The historical PyTorch comparison table is labeled historical; never
47+
present it as current evidence.
48+
- Backbone-only GGUFs are not published; do not imply they exist.
Lines changed: 142 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,142 @@
1+
# Launch blog post outline
2+
3+
Working title options:
4+
5+
- "dinov2.cpp: DINOv2 embeddings without the Python stack"
6+
- "Running DINOv2 like llama.cpp: one binary, GGUF weights, JSON out"
7+
8+
Positioning one-liner (use verbatim or near-verbatim):
9+
10+
> llama.cpp for vision encoders: DINOv2 on ggml, one binary, GGUF weights,
11+
> embeddings as JSON on stdout.
12+
13+
The analogy holds mechanically (ggml backend, GGUF format, single-binary
14+
CLI, prebuilt releases, HF-hosted weights). Do not overextend it into
15+
performance or maturity claims.
16+
17+
## 1. Hook
18+
19+
Draft:
20+
21+
> DINOv2 is the backbone under a lot of vision pipelines: retrieval,
22+
> dedup, clustering, dense features. Running it today means PyTorch,
23+
> transformers, and a few hundred MB of Python environment before you get
24+
> a single vector out. I wanted `model.gguf` plus one binary that prints
25+
> an embedding. dinov2.cpp is that: the DINOv2 encoder ported to C++ on
26+
> ggml, with prebuilt binaries for macOS, Linux, and Windows, and the
27+
> weights already converted on Hugging Face.
28+
29+
## 2. What it is
30+
31+
- C++20 port of DINOv2 (ViT-S/B/L/g, patch 14) on ggml. Vendored stb for
32+
image I/O, no other runtime dependencies (`ARCHITECTURE.md`).
33+
- One CLI (`dinov2-cli`) plus a C API (`include/dinov2.h`) for embedding.
34+
- Outputs: ImageNet top-k (`-c`), `cls`/`pooled`/patch embeddings as JSON
35+
(`--print-embeddings`), PCA feature map PNG (`-o`), bench mode
36+
(`--bench-json`).
37+
- GGUF weights for all 8 classifier checkpoints on
38+
`dinov2-cpp-core` HF, f16, published monthly by CI
39+
(`docs/hf-publishing.md`). Real sizes: 46.9 MB (small), 178.7 MB (base),
40+
616.5 MB (large), 2.29 GB (giant), measured via `x-linked-size` on
41+
2026-09-23.
42+
- Install story: download a ~1 MB release archive (mac 1,156,752 B,
43+
ubuntu x64 945,186 B, ubuntu arm64 895,818 B, win 1,120,200 B per
44+
`gh release view v0.4.0`), `hf download` a weight, run.
45+
46+
## 3. The demo (centerpiece): local photo dedup
47+
48+
`examples/dedup/dedup.py` is the proof that embeddings-as-JSON is a real
49+
interface, not a demo stub.
50+
51+
- Stdlib-only Python (~30 lines of logic): shells out to
52+
`dinov2-cli --print-embeddings`, takes `pooled`, pairwise cosine,
53+
single-linkage clustering, writes an HTML review page
54+
(`examples/dedup/README.md`).
55+
- Suggested narrative: point it at a real photo dump, show the HTML
56+
clusters, then show the three lines of code that matter (subprocess,
57+
cosine, union-find).
58+
- Talking point: threshold 0.99 catches re-encodes and resizes, 0.95
59+
catches same-scene shots. This is embedding-similarity behavior, tunable,
60+
not magic.
61+
- Honest limit to name in passing: pairwise comparison is O(n^2) in the
62+
example script; fine for a few thousand images, real indexes (FAISS,
63+
sqlite-vec) beyond that.
64+
- Secondary demo if Pages is enabled: the wasm build (~1 MB
65+
`dinov2-wasm.wasm`, 1,048,008 B locally) runs the encoder in-browser and
66+
shows CLS cosine plus a patch heatmap (`docs/wasm.md`).
67+
68+
## 4. Does it match the reference? (parity evidence)
69+
70+
- Nightly CI job (`.github/workflows/parity.yml`, cron `17 4 * * *`) runs
71+
`scripts/parity_check.py` against the HF reference for both small
72+
checkpoints; a drift fails the job.
73+
- Committed runs (`docs/parity/`): regular small CLS cosine 0.999911,
74+
pooled 0.999928; registers small CLS 0.999984, pooled 0.999984; patch
75+
mean cosine 0.9996/0.9998. Gates: cls/pooled >= 0.999, patches >= 0.99.
76+
- Classification matches too: same top-1 label ("tench"), probability diff
77+
0.000039 on the recorded run.
78+
- Frame it as: the numbers are published, the checker is in the repo, the
79+
gate runs nightly. Not "trust me".
80+
81+
## 5. Performance
82+
83+
- Committed evidence is narrow on purpose: ViT-S f16, CPU, ubuntu-latest,
84+
12 threads: 255.0 ms mean, stddev 9.1, 104 MB peak RSS
85+
(`benchmark_results.txt`, `docs/benchmarks.md`).
86+
- Historical i9-14900HX table exists (small 62 ms vs PyTorch 181 ms) but is
87+
labeled non-reproducible context. Mention it as history, not a claim.
88+
- wasm estimate is explicitly an estimate: ~4-10 s/image for ViT-S at 518
89+
px, single-threaded (`docs/wasm.md`).
90+
91+
## 6. Caveats (draft below)
92+
93+
## 7. How it works (optional technical section)
94+
95+
- ggml graph, Catmull-Rom resize, position-embedding interpolation for
96+
arbitrary grids, `--preprocess bounded|hf|crop518`, `--max-tokens` guard
97+
against quadratic attention memory on huge inputs.
98+
- Batch inference via repeated `-i` and `--batch`; per-image outputs
99+
identical to single runs.
100+
101+
## 8. CTA
102+
103+
- Try it: `hf download dinov2-cpp-core/dinov2-small-gguf --local-dir models`
104+
plus a release binary; three commands total.
105+
- File issues on parity gaps, missing formats, quantization results.
106+
- Star/watch if you want the backbone-only checkpoints and Windows ARM
107+
binaries when they land.
108+
109+
## Caveats section (suggested draft)
110+
111+
> What this is not, and where the edges are:
112+
>
113+
> - The committed benchmark is one row: ViT-S, f16, CPU, Ubuntu. There is
114+
> no GPU measurement, no quantization comparison, and no base/large/giant
115+
> row yet. The 3x-vs-PyTorch table in the docs is an older laptop
116+
> measurement kept as history, not CI evidence.
117+
> - Parity is recorded for the two small checkpoints on one image and one
118+
> environment. It is strong evidence, not a proof for every checkpoint,
119+
> image, and platform; the nightly job exists because drift is possible.
120+
> - Feature-mode preprocessing is not bit-identical to HF's
121+
> `AutoImageProcessor`: the CLI uses Catmull-Rom, HF uses antialiased
122+
> bicubic. Under `--preprocess hf` the measured residual on the test
123+
> image is CLS cosine ~0.996. Use the published GGUFs with the default
124+
> `bounded` recipe unless you specifically need token-for-token HF
125+
> comparison.
126+
> - `-fa` (flash attention) is documented as faster but less accurate; a
127+
> K/V padding bias was fixed in the audit pass, but avoid `-fa` when
128+
> comparing against HF outputs.
129+
> - Image decode is whatever stb_image supports (JPEG, PNG, BMP, TGA, GIF,
130+
> PSD, HDR, PNM). No WebP, HEIC, or AVIF.
131+
> - The C API is explicitly unstable for 0.4.x; the CLI JSONL schema is the
132+
> stable surface (`docs/stability.md`). The `.d2e` binary format is a
133+
> preview with no compatibility promise.
134+
> - Weights are the ImageNet classifier checkpoints only; backbone-only
135+
> DINOv2 GGUFs are supported by the code but not published yet.
136+
137+
## Distribution notes
138+
139+
- Cross-post targets: personal blog, Show HN (see show-hn-draft.md), maybe
140+
r/LocalLLaMA (fits the local-inference audience).
141+
- The parity and benchmarks pages are the credibility backbone; link them
142+
early, not just at the end.
Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
<!--
2+
Maintainer template, not a published file.
3+
4+
Backbone-only DINOv2 checkpoints (facebook/dinov2-{small,base,large,giant}
5+
without the imagenet1k-1-layer classifier head) are being converted and
6+
published separately; they are not in these repos yet. See
7+
docs/cli.md "Backbone-only checkpoints". Do not mention them in the card
8+
until the GGUFs actually exist on the hub.
9+
10+
How to use: fill in {{REPO}}, {{SOURCE}}, {{SIZE_BYTES}}, {{SIZE_HUMAN}},
11+
{{REGISTERS}}, {{HIDDEN}} from the lookup table at the bottom, then upload
12+
the result as README.md to the target repo. The YAML frontmatter must be
13+
the first bytes of the uploaded file (this comment block stays out).
14+
Upload command:
15+
16+
hf upload {{REPO}} README.md README.md --repo-type model
17+
18+
or via the hub web UI: Add file -> paste body.
19+
-->
20+
---
21+
license: apache-2.0
22+
tags:
23+
- gguf
24+
- dinov2
25+
- embeddings
26+
- image-feature-extraction
27+
---
28+
29+
# {{REPO}}
30+
31+
f16 GGUF conversion of [`{{SOURCE}}`](https://huggingface.co/{{SOURCE}}) for
32+
[dinov2.cpp](https://github.com/espetro/dinov2.cpp), a C++ port of Meta's
33+
DINOv2 vision encoder that runs on ggml. No Python or PyTorch needed at
34+
runtime.
35+
36+
- Format: GGUF, f16 weights
37+
- File: `model.gguf` ({{SIZE_HUMAN}}, {{SIZE_BYTES}} bytes)
38+
- Produced by `scripts/dinov2-to-gguf.py` and published by the
39+
`convert-and-publish-gguf` CI workflow (monthly + on demand)
40+
41+
## Install and run
42+
43+
```bash
44+
# 1. Download this weight
45+
hf download {{REPO}} --local-dir models
46+
# -> models/model.gguf
47+
48+
# 2. Get a dinov2-cli binary
49+
# prebuilt: https://github.com/espetro/dinov2.cpp/releases
50+
# or build: cmake --preset release && cmake --build --preset release
51+
52+
# 3. Run
53+
dinov2-cli -m models/model.gguf -i image.jpg -c # top-5 ImageNet labels
54+
dinov2-cli -m models/model.gguf -i image.jpg --print-embeddings # cls/pooled vectors as JSON
55+
dinov2-cli -m models/model.gguf -i image.jpg -o pca.png # PCA map of patch features
56+
```
57+
58+
## What this variant contains
59+
60+
- Backbone: ViT-{{VARIANT_LETTER}}/14 distilled DINOv2, hidden size {{HIDDEN}}
61+
- Register tokens: {{REGISTERS}}
62+
- ImageNet1k linear classifier head: included (`-c` works out of the box)
63+
- Outputs: `cls` embedding, `pooled` `[cls || mean(patches)]`, per-patch
64+
tokens with `--print-patch-tokens`
65+
66+
Register-token checkpoints reduce high-norm patch-token artifacts and give
67+
smoother dense feature maps in the settings studied in
68+
[Vision Transformers Need Registers](https://arxiv.org/abs/2309.16588).
69+
Prefer a `with-registers` repo for patch/dense feature work; prefer the
70+
plain repo for exact baseline reproduction or task-specific comparisons.
71+
72+
## Numerical parity
73+
74+
Embeddings from this GGUF are checked against the HF reference
75+
implementation by a nightly CI job and committed run reports. On the small
76+
checkpoints the recorded CLS cosine similarity is 0.9999+ and pooled cosine
77+
is 0.9999+ (gates: cls/pooled >= 0.999, patch mean >= 0.99). Full evidence,
78+
per-checkpoint provenance, and reproduction commands:
79+
[docs/parity/](https://github.com/espetro/dinov2.cpp/tree/main/docs/parity).
80+
81+
## Links
82+
83+
- Engine and CLI: https://github.com/espetro/dinov2.cpp
84+
- CLI reference: https://github.com/espetro/dinov2.cpp/blob/main/docs/cli.md
85+
- Publishing pipeline: https://github.com/espetro/dinov2.cpp/blob/main/docs/hf-publishing.md
86+
- Upstream model: https://huggingface.co/{{SOURCE}}
87+
88+
<!--
89+
Lookup table (measured 2026-09-23 via curl -sIL on /resolve/main/model.gguf,
90+
x-linked-size header). SIZE_HUMAN uses decimal GB/MB.
91+
92+
| REPO | SOURCE | SIZE_BYTES | SIZE_HUMAN | REGISTERS | HIDDEN | VARIANT_LETTER |
93+
|-----------------------------------------------------|------------------------------------------------------------|-------------|------------|-----------|--------|----------------|
94+
| dinov2-cpp-core/dinov2-small-gguf | facebook/dinov2-small-imagenet1k-1-layer | 46,901,760 | ~46.9 MB | 0 | 384 | S |
95+
| dinov2-cpp-core/dinov2-base-gguf | facebook/dinov2-base-imagenet1k-1-layer | 178,678,272 | ~178.7 MB | 0 | 768 | B |
96+
| dinov2-cpp-core/dinov2-large-gguf | facebook/dinov2-large-imagenet1k-1-layer | 616,453,984 | ~616.5 MB | 0 | 1024 | L |
97+
| dinov2-cpp-core/dinov2-giant-gguf | facebook/dinov2-giant-imagenet1k-1-layer | 2,285,418,624 | ~2.29 GB | 0 | 1536 | g |
98+
| dinov2-cpp-core/dinov2-with-registers-small-gguf | facebook/dinov2-with-registers-small-imagenet1k-1-layer | 46,907,968 | ~46.9 MB | 4 | 384 | S |
99+
| dinov2-cpp-core/dinov2-with-registers-base-gguf | facebook/dinov2-with-registers-base-imagenet1k-1-layer | 178,690,624 | ~178.7 MB | 4 | 768 | B |
100+
| dinov2-cpp-core/dinov2-with-registers-large-gguf | facebook/dinov2-with-registers-large-imagenet1k-1-layer | 616,470,432 | ~616.5 MB | 4 | 1024 | L |
101+
| dinov2-cpp-core/dinov2-with-registers-giant-gguf | facebook/dinov2-with-registers-giant-imagenet1k-1-layer | 2,285,443,296 | ~2.29 GB | 4 | 1536 | g |
102+
103+
Register count per the DINOv2 release is 4 for all with-registers sizes;
104+
confirm against the checkpoint config if a card claims it.
105+
-->

‎docs/marketing/show-hn-draft.md‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
# Show HN draft
2+
3+
Status: draft. Every number below is verified against a repo artifact or a
4+
live HTTP check (sources inline). Do not add numbers that are not in this
5+
file without re-verifying.
6+
7+
## Headline options
8+
9+
1. `Show HN: dinov2.cpp, DINOv2 vision embeddings from a single C++ binary, no Python`
10+
2. `Show HN: Run DINOv2 locally like llama.cpp: one binary, GGUF weights, JSON embeddings`
11+
3. `Show HN: DINOv2 image embeddings in C++ on ggml, with nightly parity checks against the HF reference`
12+
13+
Option 1 is the safest (self-describing). Option 2 trades on the llama.cpp
14+
analogy, which fits the mechanics (ggml, GGUF, single binary) but borrows a
15+
brand. Option 3 leads with the trust story; longer.
16+
17+
## Body (~150 words)
18+
19+
```text
20+
dinov2.cpp runs Meta's DINOv2 vision encoder in pure C++ on ggml. One
21+
binary, GGUF weights, JSON embeddings on stdout. No Python or PyTorch at
22+
runtime.
23+
24+
Numbers, all committed or reproducible: ViT-S f16 forward pass runs at a
25+
255 ms mean with 104 MB peak RSS on a GitHub ubuntu-latest runner
26+
(benchmark_results.txt, workflow run 35630688827). A nightly CI job gates
27+
embeddings against the Hugging Face reference; the committed runs show CLS
28+
cosine 0.9999+ on both small checkpoints (docs/parity/). Prebuilt CLI
29+
archives for macOS arm64, Linux x64/arm64, and Windows x64 are 0.9 to 1.2
30+
MB each, plus a SHA256SUMS.txt. The encoder also compiles to a ~1 MB wasm
31+
module for in-browser similarity demos.
32+
33+
Weights (47 MB ViT-S up to 2.3 GB giant) live on the dinov2-cpp-core HF
34+
profile. Repo: https://github.com/espetro/dinov2.cpp
35+
```
36+
37+
Word count: ~155. Trim "committed or reproducible" phrasing if needed.
38+
39+
## Links to include
40+
41+
- Repo: https://github.com/espetro/dinov2.cpp
42+
- Parity evidence: https://github.com/espetro/dinov2.cpp/tree/main/docs/parity
43+
- Benchmarks: https://github.com/espetro/dinov2.cpp/blob/main/docs/benchmarks.md
44+
- Demo: wasm demo lives in `wasm/index.html`; needs GitHub Pages enabled
45+
before it can be linked as a live URL (see README checklist)
46+
- Release post with prior benchmarks: https://alexlavaee.me/projects/dinov2cpp/
47+
48+
## Verified numbers used (with sources)
49+
50+
| Claim | Source |
51+
|:------|:-------|
52+
| 255.0 ms mean, 104 MB peak RSS, ViT-S f16 CPU, 12 threads, batch 1 | `benchmark_results.txt`, `docs/benchmarks.md`, run [35630688827](https://github.com/espetro/dinov2.cpp/actions/runs/35630688827) |
53+
| CLS cosine 0.999911 (regular), 0.999984 (registers) vs HF | `docs/parity/2026-09-21-small-regular.md`, `docs/parity/2026-09-21-small-registers.md`, rerun `2026-09-22-audit-hardening.md` |
54+
| Nightly parity gate | `.github/workflows/parity.yml` (cron `17 4 * * *`) |
55+
| Release asset sizes: mac 1,156,752 B; ubuntu x64 945,186 B; ubuntu arm64 895,818 B; win zip 1,120,200 B | `gh release view v0.4.0`, checked 2026-09-23 |
56+
| wasm module ~1 MB | `docs/wasm.md`; local `build-wasm/bin/dinov2-wasm.wasm` = 1,048,008 B |
57+
| GGUF sizes 46.9 MB to 2.29 GB | `curl -sIL` x-linked-size on the 8 `dinov2-cpp-core/*-gguf` repos, checked 2026-09-23 |
58+
59+
## Explicitly not claimed
60+
61+
- The "up to 3x faster than PyTorch" numbers in `docs/benchmarks.md` are a
62+
historical i9-14900HX measurement, not the committed CI evidence. Leave
63+
them out of the post or label them as historical.
64+
- No GPU, no quantization comparison, no base/large/giant benchmark rows:
65+
all unmeasured per `docs/benchmarks.md`.
66+
- No backbone-only GGUFs published yet (classifier checkpoints only).

0 commit comments

Comments
 (0)