Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
79 changes: 76 additions & 3 deletions .github/workflows/extras.yml
Original file line number Diff line number Diff line change
Expand Up @@ -57,6 +57,79 @@ jobs:
wasm/main.js
retention-days: 14

# Placeholder for future tier-2 jobs: a llama.cpp-style http server example
# or the examples/ tree. Add jobs here with continue-on-error: true so they
# stay advisory.
# dinov2-server (tools/server/, DINOV2_BUILD_SERVER): build it, download
# the small GGUF (same pattern as the build.yml contract job, minus the
# hf CLI: a plain /resolve/ curl works for public repos), then curl
# /health and POST assets/tench.jpg to /v1/embeddings.
server:
continue-on-error: true
runs-on: ubuntu-latest
timeout-minutes: 20
steps:
- uses: actions/checkout@v4
with:
submodules: recursive

- name: Install ninja
run: |
sudo apt-get update
sudo apt-get install -y ninja-build

- name: Build dinov2-server
run: |
cmake -B build-server -G Ninja -DCMAKE_BUILD_TYPE=Release \
-DDINOV2_BUILD_SERVER=ON -DDINOV2_BUILD_TESTS=OFF
cmake --build build-server --target dinov2-server -j"$(nproc)"

- name: Download small GGUF
run: |
mkdir -p models/dinov2-small
curl -L -o models/dinov2-small/model.gguf \
https://huggingface.co/dinov2-cpp-core/dinov2-small-gguf/resolve/main/model.gguf

- name: Smoke test endpoints
run: |
./build-server/bin/dinov2-server \
-m models/dinov2-small/model.gguf --port 18080 --threads 2 &
SRV=$!
trap 'kill $SRV 2>/dev/null || true' EXIT
for _ in $(seq 1 60); do
curl -sf http://127.0.0.1:18080/health && break
sleep 1
done
curl -sf http://127.0.0.1:18080/v1/models | jq -e '.hidden_size == 384'
curl -sf -F image=@assets/tench.jpg \
http://127.0.0.1:18080/v1/embeddings \
| jq -e '(.cls | length) == 384 and (.grid.h * .grid.w == .n_patches)'
B64=$(base64 -w0 assets/tench.jpg)
curl -sf -X POST http://127.0.0.1:18080/v1/embeddings \
-H 'Content-Type: application/json' \
-d "{\"image\":\"$B64\",\"l2_normalize\":true}" \
| jq -e '(.cls | length) == 384'

# examples/: syntax checks only. These are copy-paste examples for users,
# not wired gates; the job just keeps them from rotting.
examples:
continue-on-error: true
runs-on: ubuntu-latest
timeout-minutes: 10
steps:
- uses: actions/checkout@v4

- name: Check dedup.py syntax
run: python3 -m py_compile examples/dedup/dedup.py

- name: Check example workflow YAML parses
run: |
sudo apt-get update && sudo apt-get install -y python3-yaml
python3 -c "
import yaml
doc = yaml.safe_load(open('examples/ci-visual-regression/visual-regression.yml'))
assert 'jobs' in doc and 'compare' in doc['jobs'], 'missing compare job'
print('example workflow parses')
"

- name: actionlint on the example workflow
run: |
bash <(curl -s https://raw.githubusercontent.com/rhysd/actionlint/main/scripts/download-actionlint.bash)
./actionlint -oneline examples/ci-visual-regression/visual-regression.yml
23 changes: 20 additions & 3 deletions ARCHITECTURE.md
Original file line number Diff line number Diff line change
Expand Up @@ -56,6 +56,13 @@ and scheduler synchronisation; all tensor plumbing lives behind
is on the library's public include path, so a bare `#include "dinov2.h"`
always resolves to the stable C API for embedders.

**Tier-2 surfaces** (`tools/server/`, `wasm/`, `examples/`) sit above this
graph: they may consume the public C header and in-repo internal headers
(`src/image.h`), but nothing tier-1 includes, links, or shells out to them.
They are off-by-default (`DINOV2_BUILD_WASM`, `DINOV2_BUILD_SERVER`) or not
part of the build at all, and their CI jobs are advisory only. See
[docs/tiers.md](docs/tiers.md).

## File-by-file index (role groups)

```mermaid
Expand All @@ -77,8 +84,9 @@ graph LR
Test["tests/test_image.cpp<br/>tests/test_dinov2.cpp<br/>tests/test_dinov2_c.cpp<br/>tests/test_cli.cpp"]
Tool["scripts/bench.sh<br/>scripts/dinov2-to-gguf.py<br/>scripts/publish-gguf.sh"]
Build["CMakeLists.txt<br/>CMakePresets.json<br/>src/stb_image.h<br/>src/stb_image_write.h<br/>src/doctest.h"]
CI[".github/workflows/release.yml<br/>.github/workflows/build.yml<br/>.github/workflows/convert-and-publish-gguf.yml"]
Doc["README.md<br/>CONTRIBUTING.md<br/>docs/cli.md<br/>docs/build.md<br/>docs/benchmarks.md<br/>docs/hf-publishing.md<br/>ARCHITECTURE.md<br/>CHANGELOG.md"]
Tier2["wasm/ (embind shim + demo)<br/>tools/server/ (dinov2-server)<br/>examples/ (dedup, ci-visual-regression)"]
CI[".github/workflows/release.yml<br/>.github/workflows/build.yml<br/>.github/workflows/extras.yml<br/>.github/workflows/convert-and-publish-gguf.yml"]
Doc["README.md<br/>CONTRIBUTING.md<br/>docs/cli.md<br/>docs/build.md<br/>docs/benchmarks.md<br/>docs/hf-publishing.md<br/>docs/stability.md + docs/tiers.md<br/>docs/wasm.md<br/>ARCHITECTURE.md<br/>CHANGELOG.md"]
Asset["assets/logo/<br/>assets/tench.jpg<br/>assets/logo.png"]
Sub["ggml/ (submodule)"]

Expand All @@ -87,6 +95,7 @@ graph LR
class CLI cli
class Test test
class Tool tool
class Tier2 tool
class Build build
class CI ci
class Doc doc
Expand All @@ -106,7 +115,10 @@ Abridged table:
| `tests/test_{image,dinov2,dinov2_c,cli}.cpp` | Test | doctest coverage + CLI black-box cases. |
| `scripts/{bench.sh,dinov2-to-gguf.py,publish-gguf.sh}` | Tool | Bench sweep + PyTorch→GGUF + HF upload. |
| `CMakeLists.txt`, `CMakePresets.json`, vendored stb/doctest | Build | CMake build + vendored single-file deps. |
| `.github/workflows/*` | CI | 3 workflows: release, build, convert-and-publish. |
| `wasm/` | Tier-2 | Emscripten embind shim over the C API + browser demo (`DINOV2_BUILD_WASM`). |
| `tools/server/` | Tier-2 | `dinov2-server` HTTP embeddings service over the C API + vendored cpp-httplib (`DINOV2_BUILD_SERVER`). |
| `examples/` | Tier-2 | Copy-paste examples: `dedup/` (near-duplicate finder), `ci-visual-regression/` (GitHub Action). |
| `.github/workflows/*` | CI | build, release, convert-and-publish, parity, bench, changelog, extras (tier-2 advisory jobs). |
| `README.md`, `CONTRIBUTING.md`, `docs/*`, `ARCHITECTURE.md`, `RELEASE_NOTES_*.md` | Doc | User + contributor-facing docs. |
| `assets/*` | Asset | Logo + default input image. |
| `ggml/` | Submodule | Vendored ggml at pinned SHA. |
Expand Down Expand Up @@ -160,6 +172,11 @@ themselves with `add_test(NAME …)`; `ctest --test-dir build` runs all four.
`dinov2-cli` itself is not a test (a real GGUF + image are only guaranteed
when `models/` is populated).

Two optional executables exist only when their tier-2 options are ON:
`dinov2-wasm` (`DINOV2_BUILD_WASM`, Emscripten toolchain) and
`dinov2-server` (`DINOV2_BUILD_SERVER`, vendored cpp-httplib). Neither is in
the default `all` graph unless requested.

## CLI surface

`dinov2-cli --help`:
Expand Down
7 changes: 7 additions & 0 deletions CMakeLists.txt
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,7 @@ option(DINOV2_BUILD_TESTS "Build doctest unit tests" ON)
option(DINOV2_BUILD_CLI "Build the dinov2-cli executable" ON)
option(DINOV2_BUILD_C_API "Build the pure C API (include/dinov2.h) into libdinov2" ON)
option(DINOV2_BUILD_WASM "Build the Emscripten/WebAssembly target in wasm/ (tier-2)" OFF)
option(DINOV2_BUILD_SERVER "Build the dinov2-server HTTP microservice in tools/server/ (tier-2)" OFF)

# deps
add_subdirectory(ggml)
Expand Down Expand Up @@ -131,3 +132,9 @@ if (DINOV2_BUILD_WASM)
endif ()
add_subdirectory(wasm)
endif ()

# server (tier-2): cpp-httplib microservice over the C API. Off by default,
# isolated in tools/server/; tier-1 targets never see it.
if (DINOV2_BUILD_SERVER)
add_subdirectory(tools/server)
endif ()
17 changes: 17 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -112,6 +112,22 @@ dino_model_free(m);

The API is unstable for the 0.4.x line; see [docs/stability.md](docs/stability.md).

## Tier-2 extras

Opt-in surfaces, off by default and not covered by the stability contract
([docs/tiers.md](docs/tiers.md)):

- **HTTP server**: `dinov2-server` is a single-binary embeddings
microservice over the C API (`-DDINOV2_BUILD_SERVER=ON`). POST an image to
`/v1/embeddings`, get `cls`/`pooled`/patch vectors back as JSON. See
[tools/server/README.md](tools/server/README.md).
- **wasm**: the encoder compiles to WebAssembly and runs in the browser;
see [docs/wasm.md](docs/wasm.md).
- **examples/**: `examples/dedup/` finds near-duplicate photos with the CLI
(stdlib-only Python, writes an HTML review page);
`examples/ci-visual-regression/` is a copy-paste GitHub Action that gates
screenshots by embedding cosine.

## Features

| Feature | Detail |
Expand Down Expand Up @@ -147,6 +163,7 @@ For patch and dense feature workflows, the register-token variants are the recom
- [docs/benchmarks.md](docs/benchmarks.md): benchmarks against PyTorch, how to run your own
- [docs/hf-publishing.md](docs/hf-publishing.md): how CI publishes GGUF weights to Hugging Face
- [docs/wasm.md](docs/wasm.md): Emscripten/WebAssembly build and browser demo
- [docs/stability.md](docs/stability.md) + [docs/tiers.md](docs/tiers.md): the compatibility contract and tier policy

## Why this fork

Expand Down
8 changes: 8 additions & 0 deletions docs/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -459,3 +459,11 @@ the HF image processor.
which is not valid JSON; this only happens on pathological inputs.
String escaping covers `"` and `\` only, which suffices for the bundled
ImageNet labels.

## See also

- [tools/server/README.md](../tools/server/README.md): `dinov2-server`
exposes the same embeddings over HTTP (tier-2, off by default).
- [examples/dedup/](../examples/dedup/): a stdlib-only script that consumes
this JSONL output to cluster near-duplicate images.
- [stability.md](stability.md): which parts of this contract are frozen.
67 changes: 49 additions & 18 deletions docs/stability.md
Original file line number Diff line number Diff line change
@@ -1,23 +1,54 @@
# Stability
# Stability contract

What is covered by compatibility guarantees, and what is not.
What consumers can rely on, and for how long. Surfaces are split into
**tier-1** (the shipped product; breaking changes follow semver and are
documented in release notes) and **tier-2** (opt-in previews and examples;
may change or disappear between any two commits). Tier definitions and the
promotion process live in [tiers.md](tiers.md).

## Stable
## Tier-1 surfaces

- The `dinov2-cli` command-line contract: flags, JSONL/JSON output keys and
order, human-readable top-k output, exit codes, and stderr messages. See
[cli.md](cli.md).
- The GGUF schema read by the loader: metadata keys and tensor names written
by `scripts/dinov2-to-gguf.py` and published on the `dinov2-cpp-core` HF
profile.
| Surface | What is covered | Policy |
|:--------|:----------------|:-------|
| `dinov2-cli` flags and output | Flag names/semantics, JSONL/JSON output keys and order, human-readable top-k format, exit codes, stderr messages ([cli.md](cli.md)) | Semver: breaking changes bump minor (0.x) or major and are called out in release notes |
| `--print-embeddings` JSONL schema | Record keys, types, field semantics, per-line ordering (`index` == line number) | Semver, same as the CLI. Additive keys are allowed in minor releases; removed/renamed/retyped keys are breaking |
| `libdinov2` build target | The `dinov2` CMake target name, `include/` as its only public interface dir, `BUILD_SHARED_LIBS` support | Semver |
| C API (`include/dinov2.h`) | `dino_*` functions, `dino_status`, params PODs, accessor borrow semantics | **Unstable for the 0.4.x line**: signatures and struct layouts may change between minor releases. Stabilizes at a later minor (announced in release notes). Pin a tag if you embed it |
| GGUF schema | Metadata keys and tensor names the loader reads, as written by `scripts/dinov2-to-gguf.py` | Stable: the loader keeps reading GGUFs produced by released converters |
| GGUF publishing | The `dinov2-cpp-core` HF profile, repo naming (`dinov2-*-gguf`), `model.gguf` filename | Best-effort stable: repos and file names are not renamed or deleted without a deprecation notice |

## Unstable
## Tier-2 surfaces

- The C API in `include/dinov2.h` (`libdinov2`): new in the 0.4.x line.
Function signatures, the `dino_status` enum, params struct layout, and
accessor semantics may change between minor releases. Pin a tag if you
embed it.
- The D2EMB binary preview written by `--embeddings-binary`: explicitly
unstable; the header carries a version field but no compatibility promise.
- The internal C++ header `src/dinov2-impl.h`: not installed, no
compatibility guarantees at all. It changes freely between commits.
Nothing below is a compatibility promise. These are off-by-default previews
and example code; pin a commit if you depend on one.

| Surface | Status |
|:--------|:-------|
| wasm target (`wasm/`, `DINOV2_BUILD_WASM`) | Preview. JS API shape, embind names and build flags may change |
| `dinov2-server` (`tools/server/`, `DINOV2_BUILD_SERVER`) | Preview. Endpoints and response shape may change; single-process, no SLA |
| `examples/` (dedup, ci-visual-regression) | Example code. Copy-paste supported, upstream compatibility not promised |
| `--embeddings-binary` (D2EMB) | Explicitly unstable preview: the header carries a version field but no compatibility promise, format may change at any commit |

## Internal surfaces (no guarantees)

- `src/dinov2-impl.h`: the internal C++ header shared by the engine, CLI, C
wrapper and tests. **Not installed.** Source-compat only within a commit;
it changes freely. Out-of-tree consumers should not include it.
- `src/image.h`: internal helpers. Same rule: usable in-repo (tier-2 code
may), not a public contract.
- Anything reachable only by patching the build (sanitizer flags, internal
ggml knobs) is unsupported.

## Deprecation mechanics

When a tier-1 surface must break:

1. The old behavior keeps working for at least one minor release where
technically feasible, with a deprecation warning on stderr.
2. The breaking change lands with a `BREAKING` note in the changelog and
release notes.
3. `DINO_DEPRECATED` marks doomed C API functions once the C API is stable;
while it is unstable (0.4.x) functions may simply change.

Tier-2 surfaces skip this process entirely; their preview status is the
warning.
59 changes: 59 additions & 0 deletions docs/tiers.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,59 @@
# Tiers

Every user-visible surface in this repo is either **tier-1** or **tier-2**.
The split exists so optional previews can ship early without putting the
engine, the CLI contract, or CI health at risk. Per-surface policies are in
[stability.md](stability.md); this page defines the tiers themselves.

## Tier-1: the product

- Ships in every release archive and is covered by the compatibility
contract.
- Built and tested by default: `cmake --preset debug` builds it, `ctest`
covers it, a red tier-1 job blocks merge.
- Currently: `libdinov2` (with the C API in `include/dinov2.h`),
`dinov2-cli` and its JSONL schema, the GGUF loader schema, the converter
(`scripts/dinov2-to-gguf.py`), and GGUF publishing to `dinov2-cpp-core`.

## Tier-2: opt-in previews and examples

Hard requirements, all enforced by construction:

- **Off by default.** A CMake option (`DINOV2_BUILD_WASM`,
`DINOV2_BUILD_SERVER`) or a directory nothing tier-1 references
(`examples/`). The default build must be bit-identical with or without the
tier-2 code present.
- **Isolated.** Tier-2 code may consume the public C API and in-repo
internal headers, but nothing tier-1 may include, link, or shell out to
tier-2 code. Dependencies point downward only; nothing flows back.
- **Non-blocking in CI.** Tier-2 jobs live in
`.github/workflows/extras.yml` with `continue-on-error: true`. Red is a
drift signal, never a merge gate.
- **No compatibility promise.** APIs, endpoints and output formats may
change or be deleted between any two commits. Pin a commit to depend on
one.

Currently tier-2: the wasm target (`wasm/`), `dinov2-server`
(`tools/server/`), everything under `examples/`, and the D2EMB binary
preview (`--embeddings-binary`).

## Promotion (tier-2 -> tier-1)

A surface graduates when all of these hold:

1. A declared owner and a doc page that commits to a contract
(endpoints/schema/API written down, not just implemented).
2. Real usage evidence: at least one downstream consumer or sustained
community use, tracked in an issue.
3. It moves into the default build or the release artifacts, and its CI job
loses `continue-on-error`.
4. A stability policy entry in [stability.md](stability.md) stating what is
frozen and the deprecation path.

## Demotion (tier-1 -> tier-2)

Rare and deliberate. Requires a deprecation notice in release notes and at
least one minor release where the surface still works behind a warning.
Demotion is for surfaces that are maintained but no longer part of the
contract (e.g. an experimental output mode that never found consumers), not
for code being deleted outright.
40 changes: 40 additions & 0 deletions examples/ci-visual-regression/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
# CI visual regression (example)

A copy-paste GitHub Action that uses release `dinov2-cli` builds as a visual
regression gate: screenshots from your PR are compared against committed
baselines by embedding cosine similarity instead of pixel diffs.

**This is an example, not a gate on this repo.** It is not referenced by any
workflow in `.github/workflows/`; copy `visual-regression.yml` into your own
project and adapt it.

## What it does

1. Resolves the latest dinov2.cpp release tag, downloads the Ubuntu x64
tarball and `SHA256SUMS.txt`, verifies the archive checksum.
2. Downloads the `dinov2-small` GGUF straight from Hugging Face
(`/resolve/` URL, no `hf` CLI needed).
3. Embeds every `baseline/*.png|jpg` and `screenshots/*.png|jpg` with
`--preprocess crop518 --batch 8 --print-embeddings`. `crop518` fixes all
inputs at 518x518 so grids always match; batching keeps it fast.
4. Compares `pooled` vectors pairwise by basename and fails when any pair
drops below `THRESHOLD` (default `0.98`).

## Why not pixel diffs

Font rendering, anti-aliasing and GPU rasterization jitter make pixel-exact
screenshot gates flaky. DINOv2 pooled features tolerate subpixel drift while
still firing on real layout and content changes. Tune `THRESHOLD` down
(e.g. `0.95`) if legit UI changes trip the gate.

## Assumed repo layout

```
your-repo/
baseline/ committed reference screenshots
screenshots/ written by your test harness on each run
.github/workflows/visual-regression.yml
```

Filenames must match between the two directories; the comparison joins on
`basename(image)`. New screenshots are reported but do not fail the build.
Loading
Loading