DINOv3

Exact model and requirements

Artifact:

timm (maintainer derivative of Meta DINOv3) / vit_small_patch16_dinov3.lvd1689m; explicit representative derivative · checkpoint timm/vit_small_patch16_dinov3.lvd1689m

Publisher revision:

3bf4720a82ec2066db88137180ff1f83a675cef0

Artifact digest:

sha256:2a1ec16ae28ffa07bc0ead0241ee7df9fc26451fe6f9f839b7b3afa0a906b040

Download size:

0.08 GiB

Memory requirement (unknown):

Unknown — No measured full-process peak for this derivative, CPU runtime, image preprocessing or feature serialization.

System RAM / disk:

Unknown / Unknown

Placement:

single device. One CPU host; no model sharding. Whole model and preprocessing on CPU; no GPU or disk offload.

KV cache:

Non-autoregressive image feature encoder; no text-generation K/V cache configured.

Workload:

201 token context; 201 input tokens; Not applicable; concurrency 1; batch 1; cache unknown; repetitions Unknown.

Tokenizer:

Configured image patch embedding: 224 × 224 RGB, patch16, class1/register4; no text tokenizer · 0df212b369a5385b16dfe513d5143a7311ea1ddc

Sampling / reasoning:

No generation sampler. Author geometry fixture only; torchvision0.21 Resize shorter edge 224 bicubic, CenterCrop 224, ToTensor and channel normalization mean 0.485/0.456/0.406 and std 0.229/0.224/0.225. Published derivative default 256 is explicitly overridden. Sequence 201 is a configured per-image vision sequence, not text context or global maximum. No chat, reasoning, labels, generation template or tool calling. Explicit global_pool=token selects class pooling rather than derivative default average pooling. Return class[1,384] and patch[1,196,384] with per-vector L2 normalization; omit four registers. Cosine comparison is mathematical feature similarity, not calibrated semantic or classification truth.

Runtime prerequisites:

Ubuntu 24.04 x86_64; See prerequisites above.

Official artifact · License

Actual DINOv3 License, updated August 19, 2025, applies to the derivative; timm code Apache-2.0 does not replace model terms. Reader must independently review the agreement and confirm authority and intended use before downloading or running. Conditional worldwide, nontransferable royalty-free grant; retain agreement on distribution and applicable notices/acknowledgment; comply with privacy, law, trade controls and specified use restrictions, including military/ITAR and nuclear-related restrictions; no reverse engineering except as allowed by applicable law, and termination conditions apply. No legal clearance or terms acceptance is performed here. Public ungated availability is not a waiver of terms.

• Maintainer exact architecture and preprocessing config · 0 GiB · revision 3bf4720a82ec2066db88137180ff1f83a675cef0

• 86,362,376 bytes is maintainer LFS metadata for the selected safetensors artifact; no weight body was downloaded or independently hashed here.
• 32 GiB RAM, 40 GiB disk and four threads are planning allocations. Dependencies, OS, activations, tensor copies and numerical feature response add overhead; fit and performance are unknown.

Install the runtime

1. 1. Create the documented CPU research environment

   Use a dedicated directory and official hashed CPU wheels plus the exact timm release. No CUDA driver is needed. Other direct package versions are pinned; transitive packages and Ubuntu package revisions resolve at install. Save the environment and stop on dependency errors.

   CommandCopy command

   sudo apt-get update
   sudo apt-get install -y python3.12 python3.12-venv curl ca-certificates openssl
   mkdir -p "$HOME/dinov3-features/models"
   cd "$HOME/dinov3-features"
   python3.12 -m venv .venv
   .venv/bin/python -m pip install 'https://download.pytorch.org/whl/cpu/torch-2.6.0%2Bcpu-cp312-cp312-linux_x86_64.whl#sha256=59e78aa0c690f70734e42670036d6b541930b8eabbaa18d94e090abf14cc4d91' 'https://download-r2.pytorch.org/whl/cpu/torchvision-0.21.0%2Bcpu-cp312-cp312-linux_x86_64.whl#sha256=d6874431e678ba107b60a83f255c33f3755f06bad587b1b919aa514ec325dcd8'
   .venv/bin/python -m pip install 'https://files.pythonhosted.org/packages/f5/85/b897716d0fa016af23b11e6526f5ef76d2013e8bc36b9c7ce15d9200e456/timm-1.0.30-py3-none-any.whl#sha256=c8e27adf6801a2fdfb570dbbdd171f2f084756eefc673df8cfaab06bd14864f3' 'Pillow==11.1.0' 'safetensors==0.5.3' 'huggingface_hub==0.34.4'
   .venv/bin/python -m pip check
   .venv/bin/python -m pip freeze > resolved-environment.txt

   Expected result: Official CPU artifacts and timm resolve, pip check succeeds, and resolved versions are saved. This documented procedure has not been installed or model-executed by the author.

Download the model

1. 1. Verify the exact maintainer derivative

   After your own license review, download only this pinned derivative and config. The expected hash/size comes from maintainer metadata, not an author weight download. Native gated weights are not substituted or retrieved.

   CommandCopy command

   cd "$HOME/dinov3-features"
   curl --fail --location --output models/model.safetensors 'https://huggingface.co/timm/vit_small_patch16_dinov3.lvd1689m/resolve/3bf4720a82ec2066db88137180ff1f83a675cef0/model.safetensors'
   curl --fail --location --output models/config.json 'https://huggingface.co/timm/vit_small_patch16_dinov3.lvd1689m/resolve/3bf4720a82ec2066db88137180ff1f83a675cef0/config.json'
   curl --fail --location --output DINOv3-LICENSE.md 'https://huggingface.co/timm/vit_small_patch16_dinov3.lvd1689m/resolve/3bf4720a82ec2066db88137180ff1f83a675cef0/LICENSE.md'
   sha256sum --check <<'SHA256'
   2a1ec16ae28ffa07bc0ead0241ee7df9fc26451fe6f9f839b7b3afa0a906b040  models/model.safetensors
   8eb1eeb3a94a3faddfcdd9ae693607a9cd9c8b91c34381578f7f0a48ce454eef  models/config.json
   25d122eb8f5b880fd23c736fb6ea8018ee45c12237e00b8a86d14c653904999e  DINOv3-LICENSE.md
   SHA256

   Expected result: All three hashes report OK. Stop on any mismatch. Exact checkpoint identity is preserved; no claim of native Meta byte or numerical equivalence.

Configure

1. 1. Create a stable private service key

   Create the key only when absent. Do not print or share it; this is a local service key, not a provider credential.

   CommandCopy command

   cd "$HOME/dinov3-features"
   umask 077
   if [ ! -e .api-key ]; then openssl rand -hex 32 > .api-key; fi
   chmod 600 .api-key
   test -s .api-key || { echo "Restore empty service key before continuing"; exit 1; }

   Expected result: Existing nonempty key is preserved. Server validates exactly 64 lowercase hexadecimal characters.

2. 2. Create the reader-authored research harness

   This is original supporting code, not a publisher-native HTTP API. It accepts only the fixed fixture name, runs serially and binds loopback. Shape/digest/finite checks reject unexpected model results. The generated RGB geometry fixture is original author content; no external image is fetched.

   CommandCopy command

   cd "$HOME/dinov3-features"
   cat > dinov3_features.py <<'PYSERVER'
   """Reader-authored educational fixed-input DINOv3 derivative harness; not publisher server."""
   import hashlib
   import hmac
   import json
   import math
   import pathlib
   from http.server import BaseHTTPRequestHandler, HTTPServer
   
   ROOT = pathlib.Path(__file__).resolve().parent
   PORT = 8994
   MODEL_SHA = '2a1ec16ae28ffa07bc0ead0241ee7df9fc26451fe6f9f839b7b3afa0a906b040'
   
   
   def normalize(vector):
       if len(vector) != 384 or any(type(x) not in (int, float) or not math.isfinite(x) for x in vector):
           raise ValueError('invalid_feature')
       norm = math.sqrt(sum(x*x for x in vector))
       if not math.isfinite(norm) or norm <= 0:
           raise ValueError('invalid_norm')
       return [x/norm for x in vector]
   
   
   def make_encoder():
       # Imported only for the real reader-run model path; boundary tests inject a fake.
       import torch
       import timm
       from PIL import Image, ImageDraw
       from torchvision.transforms import Compose, Resize, CenterCrop, ToTensor, Normalize, InterpolationMode
       torch.set_num_threads(4)
       artifact = ROOT / 'models/model.safetensors'
       if hashlib.sha256(artifact.read_bytes()).hexdigest() != MODEL_SHA:
           raise RuntimeError('checkpoint_hash_mismatch')
       model = timm.create_model('vit_small_patch16_dinov3', pretrained=False,
                                num_classes=0, global_pool='token', img_size=224)
       from safetensors.torch import load_file
       model.load_state_dict(load_file(str(artifact), device='cpu'), strict=True)
       model = model.float().cpu().eval()
       transform = Compose([Resize(224, interpolation=InterpolationMode.BICUBIC), CenterCrop(224),
                            ToTensor(), Normalize([0.485, 0.456, 0.406], [0.229, 0.224, 0.225])])
       # Original author-drawn geometry; no third-party image, uploads, paths or URLs.
       image = Image.new('RGB', (224, 224), (240, 240, 240))
       draw = ImageDraw.Draw(image)
       draw.rectangle((24, 24, 104, 200), fill=(220, 40, 40))
       draw.ellipse((120, 64, 208, 152), fill=(30, 90, 220))
       image.save(ROOT / 'fixture.png')
       tensor = transform(image).unsqueeze(0)
       if list(tensor.shape) != [1, 3, 224, 224]:
           raise RuntimeError('input_shape')
   
       def encode():
           with torch.inference_mode():
               features = model.forward_features(tensor)
               if list(features.shape) != [1, 201, 384]:
                   raise RuntimeError('feature_shape')
               pooled = model.forward_head(features, pre_logits=True)
               if list(pooled.shape) != [1, 384]:
                   raise RuntimeError('pooled_shape')
               # token pooling selects class token; four registers are deliberately omitted.
               return pooled[0].tolist(), features[0, 5:, :].tolist()
       return encode
   
   
   def create_server(encoder, key, port=PORT):
       if not isinstance(key, str) or len(key) != 64 or any(c not in '0123456789abcdef' for c in key):
           raise ValueError('key_format')
   
       class Handler(BaseHTTPRequestHandler):
           def setup(self):
               super().setup()
               self.connection.settimeout(5)
   
           def log_message(self, *_):
               pass  # Do not log Bearer keys or request bodies.
   
           def reply(self, status, obj):
               data = json.dumps(obj, allow_nan=False, separators=(',', ':')).encode()
               self.send_response(status)
               self.send_header('Content-Type', 'application/json')
               self.send_header('Content-Length', str(len(data)))
               self.send_header('Connection', 'close')
               self.end_headers()
               self.wfile.write(data)
               self.close_connection = True
   
           def authorized(self):
               values = self.headers.get_all('Authorization', [])
               return len(values) == 1 and hmac.compare_digest(values[0].encode(), ('Bearer ' + key).encode())
   
           def do_GET(self):
               if not self.authorized():
                   return self.reply(401, {'error': 'unauthorized'})
               if self.path != '/health':
                   return self.reply(404, {'error': 'not_found'})
               return self.reply(200, {'ready': True, 'configured_vision_sequence_tokens': 201,
                                       'generated_text_tokens': None})
   
           def do_POST(self):
               if not self.authorized():
                   return self.reply(401, {'error': 'unauthorized'})
               if self.path != '/v1/image-features':
                   return self.reply(404, {'error': 'not_found'})
               if self.headers.get('Transfer-Encoding') is not None:
                   return self.reply(400, {'error': 'transfer_encoding_unsupported'})
               lengths = self.headers.get_all('Content-Length', [])
               if len(lengths) != 1:
                   return self.reply(411, {'error': 'content_length_required'})
               raw = lengths[0]
               if not raw or len(raw) > 4 or any(c not in '0123456789' for c in raw):
                   return self.reply(413, {'error': 'invalid_or_excessive_length'})
               n = int(raw)
               if n < 1 or n > 256:
                   return self.reply(413, {'error': 'body_limit'})
               if self.headers.get_content_type() != 'application/json':
                   return self.reply(415, {'error': 'json_required'})
               try:
                   body = self.rfile.read(n)
               except (TimeoutError, OSError):
                   return self.reply(408, {'error': 'body_timeout'})
               if len(body) != n:
                   return self.reply(400, {'error': 'incomplete_body'})
               try:
                   def unique(pairs):
                       obj = {}
                       for k, v in pairs:
                           if k in obj:
                               raise ValueError('duplicate_key')
                           obj[k] = v
                       return obj
                   request = json.loads(body.decode('utf-8'), object_pairs_hook=unique,
                                        parse_constant=lambda _: (_ for _ in ()).throw(ValueError('constant')))
               except (ValueError, UnicodeError, RecursionError):
                   return self.reply(400, {'error': 'invalid_json'})
               if type(request) is not dict or request != {'fixture': 'author-geometry-v1'}:
                   return self.reply(400, {'error': 'fixed_fixture_required'})
               try:
                   cls, patches = encoder()
                   cls = normalize(cls)
                   if len(patches) != 196:
                       raise ValueError('patch_shape')
                   patches = [normalize(row) for row in patches]
                   result = {'fixture': 'author-geometry-v1', 'image_shape': [1, 3, 224, 224],
                             'configured_vision_sequence_tokens': 201, 'class_shape': [1, 384],
                             'patch_shape': [1, 196, 384], 'class_embedding': cls, 'patch_embeddings': patches,
                             'normalization': 'per_vector_l2', 'pooling': 'class_token',
                             'register_tokens_omitted': 4, 'generated_text_tokens': None,
                             'classification': False}
               except Exception:
                   return self.reply(500, {'error': 'encoder_or_feature_failure'})
               return self.reply(200, result)
   
       return HTTPServer(('127.0.0.1', port), Handler)
   
   
   if __name__ == '__main__':
       secret = (ROOT / '.api-key').read_text().strip()
       encoder = make_encoder()
       with create_server(encoder, secret) as server:
           server.serve_forever()
   PYSERVER
   .venv/bin/python -m py_compile dinov3_features.py
   sha256sum --check <<'SHA256'
   8ed86175e4fc05efb7d6c8b36cdf32c45fda006cf6e83c91b7f19d060ce87e7a  dinov3_features.py
   SHA256

   Expected result: Supporting script syntax and exact hash verify without model loading.

Start the model

1. 1. Start the private fixed-image feature experiment

   Run in a foreground terminal. Load the verified safetensors into the exact unquantized timm architecture, strictly check keys and use CPU float32 with four threads. No automatic hub model download occurs: pretrained=False and local safetensors load are explicit.

   CommandCopy command

   cd "$HOME/dinov3-features"
   .venv/bin/python dinov3_features.py

   Expected result: After an unexecuted source-supported load, the server binds 127.0.0.1:8994. Stop on key, dependency, hash or shape errors; do not relax strict checks.

Verify the setup

1. 1. Check the vision-sequence protocol and inspect features

   In a second terminal on the server, inspect fixture.png and authenticate health and the one fixed request. Missing key must return 401. The result must identify 201 configured vision tokens, RGB [1, 3, 224, 224], class [1, 384], patches [1, 196, 384], four omitted registers and no generated text. Exact values are unknown. The following local check verifies finite/unit vectors and shape, not model quality or semantics.

   CommandCopy command

   cd "$HOME/dinov3-features"
   DINO_KEY="$(cat .api-key)"
   curl --fail http://127.0.0.1:8994/health -H "Authorization: Bearer $DINO_KEY"
   curl --fail http://127.0.0.1:8994/v1/image-features -H "Authorization: Bearer $DINO_KEY" -H 'Content-Type: application/json' -d '{"fixture":"author-geometry-v1"}' -o features.json
   curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8994/health
   unset DINO_KEY
   .venv/bin/python - <<'PYVERIFY'
   import json, math
   d=json.load(open('features.json'))
   assert d['configured_vision_sequence_tokens']==201 and d['generated_text_tokens'] is None
   assert d['class_shape']==[1,384] and d['patch_shape']==[1,196,384]
   assert len(d['patch_embeddings'])==196
   for v in [d['class_embedding']]+d['patch_embeddings']:
    assert len(v)==384 and all(math.isfinite(x) for x in v)
    assert math.isclose(sum(x*x for x in v),1,rel_tol=1e-5,abs_tol=1e-5)
   print('Finite normalized feature shapes verified; no semantic quality claim.')
   PYVERIFY

   Expected result: Health ready; authorized fixed input returns documented numerical shapes. Unauthorized health 401. Finite/unit-vector checks pass only after actual reader execution; no observed feature values or accuracy are promised.

Performance evidence

No compatible measurement available. Documented support and estimated memory do not establish response speed.

Limits and troubleshooting

• This is one named maintainer derivative, not native Meta checkpoint bytes or complete frozen DINOv3 family coverage. Twelve native core backbones and later heads remain distinct research scope.
• The derivative card documents disabled zero QKV biases and float32 RoPE periods versus native persistent bfloat16 periods, with numerical differences. No native-output equivalence or sibling performance is inferred.
• 201 means one configured 224 × 224 vision sequence:196 patches + one class + four registers. It is not a text limit, generated-token allowance or global maximum. Published derivative default 256 gives 261 tokens; this guide deliberately configures 224. Generic finder context labels must be read with this stated native vision unit.
• The derivative default pool is average. This recipe explicitly uses global_pool=token for class features, omits four registers from patch output and normalizes each class/patch vector. Cosine similarity does not establish semantic labels, classification calibration or downstream task quality.
• The author-drawn rectangle/circle fixture supports shape and protocol checks only. Reader inspection and separate representative-data evaluation are needed for useful downstream quality. No external image rights are assumed.
• Actual DINOv3 custom license applies; public ungated access is not MIT/Apache licensing or a waiver. Reader must review applicable restrictions and authority before use; no terms accepted or legal clearance here.
• 32 GiB RAM, 40 GiB disk and four threads are planning allocations, not measured fit or minima. No latency, memory peak, speed or accuracy result is reported.
• No autoregressive K/V cache, chat template, text tokenizer, reasoning mode or generation sampler applies. Output tokens are not applicable; finite numerical features have explicit shapes.
• Reader-authored HTTPServer is an educational serial loopback harness with authentication, fixed request, bounded body and socket timeout. It has no inference deadline, public TLS, multiuser resilience or production suitability claim.
• CPU package stack is source-qualified only. Transitive/system dependency versions resolve during reader installation and must be recorded. Fake-encoder transport tests do not prove model/runtime compatibility, numerical outputs or quality.

Dependency, strict state-dictionary or hash failure

Stop and preserve logs and resolved-environment.txt. Restore exact timm release and derivative pin; do not disable strict loading or substitute native weights. Actual model compatibility is unexecuted.

Wrong shape or nonfinite feature result

Stop. Confirm explicit 224 preprocessing, class pooling and derivative architecture. Expect 201 unpooled tokens and 196 patch vectors; do not silently use published 256 default or reinterpret vision tokens as text.

401 or rejected request

Use matching 64-character lowercase hexadecimal private key and exact fixed fixture JSON. No URL, file path, prompt, labels or upload fields are supported.

Unexpected semantic interpretation or slow execution

Record observations without inventing accuracy or speed guarantees. Geometric fixture is not an in-domain evaluation. Inspect available memory and dependencies; allocation fit is unmeasured.

Stop the model

1. 1. Stop the research endpoint

   Press Ctrl+C in the server terminal and unset client keys. Confirm local port 8994 no longer serves.

   CommandCopy command

   unset DINO_KEY

   Expected result: Research process stops and loopback endpoint no longer responds.

Uninstall

1. 1. Remove dedicated research files

   Preserve desired results and license records first. Confirm this dedicated path before removing it; shared Ubuntu packages remain.

   CommandCopy command

   rm -r -- "$HOME/dinov3-features"

   Expected result: Dedicated checkpoint, generated fixture, results, environment, wrapper and private key removed.

Exact model and requirements

Artifact:

timm (maintainer derivative of Meta DINOv3) / vit_small_patch16_dinov3.lvd1689m; explicit representative derivative · checkpoint timm/vit_small_patch16_dinov3.lvd1689m

Publisher revision:

3bf4720a82ec2066db88137180ff1f83a675cef0

Artifact digest:

sha256:2a1ec16ae28ffa07bc0ead0241ee7df9fc26451fe6f9f839b7b3afa0a906b040

Download size:

0.08 GiB

Memory requirement (unknown):

Unknown — No measured full-process peak for this derivative, CPU runtime, image preprocessing or feature serialization.

System RAM / disk:

Unknown / Unknown

Placement:

single device. One CPU host; no model sharding. Whole model and preprocessing on CPU; no GPU or disk offload.

KV cache:

Non-autoregressive image feature encoder; no text-generation K/V cache configured.

Workload:

201 token context; 201 input tokens; Not applicable; concurrency 1; batch 1; cache unknown; repetitions Unknown.

Tokenizer:

Configured image patch embedding: 224 × 224 RGB, patch16, class1/register4; no text tokenizer · 0df212b369a5385b16dfe513d5143a7311ea1ddc

Sampling / reasoning:

No generation sampler. Author geometry fixture only; torchvision0.21 Resize shorter edge 224 bicubic, CenterCrop 224, ToTensor and channel normalization mean 0.485/0.456/0.406 and std 0.229/0.224/0.225. Published derivative default 256 is explicitly overridden. Sequence 201 is a configured per-image vision sequence, not text context or global maximum. No chat, reasoning, labels, generation template or tool calling. Explicit global_pool=token selects class pooling rather than derivative default average pooling. Return class[1,384] and patch[1,196,384] with per-vector L2 normalization; omit four registers. Cosine comparison is mathematical feature similarity, not calibrated semantic or classification truth.

Runtime prerequisites:

Ubuntu 24.04 x86_64; See prerequisites above.

Official artifact · License

Actual DINOv3 License, updated August 19, 2025, applies to the derivative; timm code Apache-2.0 does not replace model terms. Reader must independently review the agreement and confirm authority and intended use before downloading or running. Conditional worldwide, nontransferable royalty-free grant; retain agreement on distribution and applicable notices/acknowledgment; comply with privacy, law, trade controls and specified use restrictions, including military/ITAR and nuclear-related restrictions; no reverse engineering except as allowed by applicable law, and termination conditions apply. No legal clearance or terms acceptance is performed here. Public ungated availability is not a waiver of terms.

• Maintainer exact architecture and preprocessing config · 0 GiB · revision 3bf4720a82ec2066db88137180ff1f83a675cef0

• 86,362,376 bytes is maintainer LFS metadata for the selected safetensors artifact; no weight body was downloaded or independently hashed here.
• 32 GiB RAM, 40 GiB disk and four threads are planning allocations. Dependencies, OS, activations, tensor copies and numerical feature response add overhead; fit and performance are unknown.

Install the runtime

1. 1. Create the documented CPU research environment

   Use a dedicated directory and official hashed CPU wheels plus the exact timm release. No CUDA driver is needed. Other direct package versions are pinned; transitive packages and Ubuntu package revisions resolve at install. Save the environment and stop on dependency errors.

   CommandCopy command

   sudo apt-get update
   sudo apt-get install -y python3.12 python3.12-venv curl ca-certificates openssl
   mkdir -p "$HOME/dinov3-features/models"
   cd "$HOME/dinov3-features"
   python3.12 -m venv .venv
   .venv/bin/python -m pip install 'https://download.pytorch.org/whl/cpu/torch-2.6.0%2Bcpu-cp312-cp312-linux_x86_64.whl#sha256=59e78aa0c690f70734e42670036d6b541930b8eabbaa18d94e090abf14cc4d91' 'https://download-r2.pytorch.org/whl/cpu/torchvision-0.21.0%2Bcpu-cp312-cp312-linux_x86_64.whl#sha256=d6874431e678ba107b60a83f255c33f3755f06bad587b1b919aa514ec325dcd8'
   .venv/bin/python -m pip install 'https://files.pythonhosted.org/packages/f5/85/b897716d0fa016af23b11e6526f5ef76d2013e8bc36b9c7ce15d9200e456/timm-1.0.30-py3-none-any.whl#sha256=c8e27adf6801a2fdfb570dbbdd171f2f084756eefc673df8cfaab06bd14864f3' 'Pillow==11.1.0' 'safetensors==0.5.3' 'huggingface_hub==0.34.4'
   .venv/bin/python -m pip check
   .venv/bin/python -m pip freeze > resolved-environment.txt

   Expected result: Official CPU artifacts and timm resolve, pip check succeeds, and resolved versions are saved. This documented procedure has not been installed or model-executed by the author.

Download the model

1. 1. Verify the exact maintainer derivative

   After your own license review, download only this pinned derivative and config. The expected hash/size comes from maintainer metadata, not an author weight download. Native gated weights are not substituted or retrieved.

   CommandCopy command

   cd "$HOME/dinov3-features"
   curl --fail --location --output models/model.safetensors 'https://huggingface.co/timm/vit_small_patch16_dinov3.lvd1689m/resolve/3bf4720a82ec2066db88137180ff1f83a675cef0/model.safetensors'
   curl --fail --location --output models/config.json 'https://huggingface.co/timm/vit_small_patch16_dinov3.lvd1689m/resolve/3bf4720a82ec2066db88137180ff1f83a675cef0/config.json'
   curl --fail --location --output DINOv3-LICENSE.md 'https://huggingface.co/timm/vit_small_patch16_dinov3.lvd1689m/resolve/3bf4720a82ec2066db88137180ff1f83a675cef0/LICENSE.md'
   sha256sum --check <<'SHA256'
   2a1ec16ae28ffa07bc0ead0241ee7df9fc26451fe6f9f839b7b3afa0a906b040  models/model.safetensors
   8eb1eeb3a94a3faddfcdd9ae693607a9cd9c8b91c34381578f7f0a48ce454eef  models/config.json
   25d122eb8f5b880fd23c736fb6ea8018ee45c12237e00b8a86d14c653904999e  DINOv3-LICENSE.md
   SHA256

   Expected result: All three hashes report OK. Stop on any mismatch. Exact checkpoint identity is preserved; no claim of native Meta byte or numerical equivalence.

Configure

1. 1. Create a stable private service key

   Create the key only when absent. Do not print or share it; this is a local service key, not a provider credential.

   CommandCopy command

   cd "$HOME/dinov3-features"
   umask 077
   if [ ! -e .api-key ]; then openssl rand -hex 32 > .api-key; fi
   chmod 600 .api-key
   test -s .api-key || { echo "Restore empty service key before continuing"; exit 1; }

   Expected result: Existing nonempty key is preserved. Server validates exactly 64 lowercase hexadecimal characters.

2. 2. Create the reader-authored research harness

   This is original supporting code, not a publisher-native HTTP API. It accepts only the fixed fixture name, runs serially and binds loopback. Shape/digest/finite checks reject unexpected model results. The generated RGB geometry fixture is original author content; no external image is fetched.

   CommandCopy command

   cd "$HOME/dinov3-features"
   cat > dinov3_features.py <<'PYSERVER'
   """Reader-authored educational fixed-input DINOv3 derivative harness; not publisher server."""
   import hashlib
   import hmac
   import json
   import math
   import pathlib
   from http.server import BaseHTTPRequestHandler, HTTPServer
   
   ROOT = pathlib.Path(__file__).resolve().parent
   PORT = 8994
   MODEL_SHA = '2a1ec16ae28ffa07bc0ead0241ee7df9fc26451fe6f9f839b7b3afa0a906b040'
   
   
   def normalize(vector):
       if len(vector) != 384 or any(type(x) not in (int, float) or not math.isfinite(x) for x in vector):
           raise ValueError('invalid_feature')
       norm = math.sqrt(sum(x*x for x in vector))
       if not math.isfinite(norm) or norm <= 0:
           raise ValueError('invalid_norm')
       return [x/norm for x in vector]
   
   
   def make_encoder():
       # Imported only for the real reader-run model path; boundary tests inject a fake.
       import torch
       import timm
       from PIL import Image, ImageDraw
       from torchvision.transforms import Compose, Resize, CenterCrop, ToTensor, Normalize, InterpolationMode
       torch.set_num_threads(4)
       artifact = ROOT / 'models/model.safetensors'
       if hashlib.sha256(artifact.read_bytes()).hexdigest() != MODEL_SHA:
           raise RuntimeError('checkpoint_hash_mismatch')
       model = timm.create_model('vit_small_patch16_dinov3', pretrained=False,
                                num_classes=0, global_pool='token', img_size=224)
       from safetensors.torch import load_file
       model.load_state_dict(load_file(str(artifact), device='cpu'), strict=True)
       model = model.float().cpu().eval()
       transform = Compose([Resize(224, interpolation=InterpolationMode.BICUBIC), CenterCrop(224),
                            ToTensor(), Normalize([0.485, 0.456, 0.406], [0.229, 0.224, 0.225])])
       # Original author-drawn geometry; no third-party image, uploads, paths or URLs.
       image = Image.new('RGB', (224, 224), (240, 240, 240))
       draw = ImageDraw.Draw(image)
       draw.rectangle((24, 24, 104, 200), fill=(220, 40, 40))
       draw.ellipse((120, 64, 208, 152), fill=(30, 90, 220))
       image.save(ROOT / 'fixture.png')
       tensor = transform(image).unsqueeze(0)
       if list(tensor.shape) != [1, 3, 224, 224]:
           raise RuntimeError('input_shape')
   
       def encode():
           with torch.inference_mode():
               features = model.forward_features(tensor)
               if list(features.shape) != [1, 201, 384]:
                   raise RuntimeError('feature_shape')
               pooled = model.forward_head(features, pre_logits=True)
               if list(pooled.shape) != [1, 384]:
                   raise RuntimeError('pooled_shape')
               # token pooling selects class token; four registers are deliberately omitted.
               return pooled[0].tolist(), features[0, 5:, :].tolist()
       return encode
   
   
   def create_server(encoder, key, port=PORT):
       if not isinstance(key, str) or len(key) != 64 or any(c not in '0123456789abcdef' for c in key):
           raise ValueError('key_format')
   
       class Handler(BaseHTTPRequestHandler):
           def setup(self):
               super().setup()
               self.connection.settimeout(5)
   
           def log_message(self, *_):
               pass  # Do not log Bearer keys or request bodies.
   
           def reply(self, status, obj):
               data = json.dumps(obj, allow_nan=False, separators=(',', ':')).encode()
               self.send_response(status)
               self.send_header('Content-Type', 'application/json')
               self.send_header('Content-Length', str(len(data)))
               self.send_header('Connection', 'close')
               self.end_headers()
               self.wfile.write(data)
               self.close_connection = True
   
           def authorized(self):
               values = self.headers.get_all('Authorization', [])
               return len(values) == 1 and hmac.compare_digest(values[0].encode(), ('Bearer ' + key).encode())
   
           def do_GET(self):
               if not self.authorized():
                   return self.reply(401, {'error': 'unauthorized'})
               if self.path != '/health':
                   return self.reply(404, {'error': 'not_found'})
               return self.reply(200, {'ready': True, 'configured_vision_sequence_tokens': 201,
                                       'generated_text_tokens': None})
   
           def do_POST(self):
               if not self.authorized():
                   return self.reply(401, {'error': 'unauthorized'})
               if self.path != '/v1/image-features':
                   return self.reply(404, {'error': 'not_found'})
               if self.headers.get('Transfer-Encoding') is not None:
                   return self.reply(400, {'error': 'transfer_encoding_unsupported'})
               lengths = self.headers.get_all('Content-Length', [])
               if len(lengths) != 1:
                   return self.reply(411, {'error': 'content_length_required'})
               raw = lengths[0]
               if not raw or len(raw) > 4 or any(c not in '0123456789' for c in raw):
                   return self.reply(413, {'error': 'invalid_or_excessive_length'})
               n = int(raw)
               if n < 1 or n > 256:
                   return self.reply(413, {'error': 'body_limit'})
               if self.headers.get_content_type() != 'application/json':
                   return self.reply(415, {'error': 'json_required'})
               try:
                   body = self.rfile.read(n)
               except (TimeoutError, OSError):
                   return self.reply(408, {'error': 'body_timeout'})
               if len(body) != n:
                   return self.reply(400, {'error': 'incomplete_body'})
               try:
                   def unique(pairs):
                       obj = {}
                       for k, v in pairs:
                           if k in obj:
                               raise ValueError('duplicate_key')
                           obj[k] = v
                       return obj
                   request = json.loads(body.decode('utf-8'), object_pairs_hook=unique,
                                        parse_constant=lambda _: (_ for _ in ()).throw(ValueError('constant')))
               except (ValueError, UnicodeError, RecursionError):
                   return self.reply(400, {'error': 'invalid_json'})
               if type(request) is not dict or request != {'fixture': 'author-geometry-v1'}:
                   return self.reply(400, {'error': 'fixed_fixture_required'})
               try:
                   cls, patches = encoder()
                   cls = normalize(cls)
                   if len(patches) != 196:
                       raise ValueError('patch_shape')
                   patches = [normalize(row) for row in patches]
                   result = {'fixture': 'author-geometry-v1', 'image_shape': [1, 3, 224, 224],
                             'configured_vision_sequence_tokens': 201, 'class_shape': [1, 384],
                             'patch_shape': [1, 196, 384], 'class_embedding': cls, 'patch_embeddings': patches,
                             'normalization': 'per_vector_l2', 'pooling': 'class_token',
                             'register_tokens_omitted': 4, 'generated_text_tokens': None,
                             'classification': False}
               except Exception:
                   return self.reply(500, {'error': 'encoder_or_feature_failure'})
               return self.reply(200, result)
   
       return HTTPServer(('127.0.0.1', port), Handler)
   
   
   if __name__ == '__main__':
       secret = (ROOT / '.api-key').read_text().strip()
       encoder = make_encoder()
       with create_server(encoder, secret) as server:
           server.serve_forever()
   PYSERVER
   .venv/bin/python -m py_compile dinov3_features.py
   sha256sum --check <<'SHA256'
   8ed86175e4fc05efb7d6c8b36cdf32c45fda006cf6e83c91b7f19d060ce87e7a  dinov3_features.py
   SHA256

   Expected result: Supporting script syntax and exact hash verify without model loading.

Start the model

1. 1. Start the private fixed-image feature experiment

   Run in a foreground terminal. Load the verified safetensors into the exact unquantized timm architecture, strictly check keys and use CPU float32 with four threads. No automatic hub model download occurs: pretrained=False and local safetensors load are explicit.

   CommandCopy command

   cd "$HOME/dinov3-features"
   .venv/bin/python dinov3_features.py

   Expected result: After an unexecuted source-supported load, the server binds 127.0.0.1:8994. Stop on key, dependency, hash or shape errors; do not relax strict checks.

Verify the setup

1. 1. Check the vision-sequence protocol and inspect features

   In a second terminal on the server, inspect fixture.png and authenticate health and the one fixed request. Missing key must return 401. The result must identify 201 configured vision tokens, RGB [1, 3, 224, 224], class [1, 384], patches [1, 196, 384], four omitted registers and no generated text. Exact values are unknown. The following local check verifies finite/unit vectors and shape, not model quality or semantics.

   CommandCopy command

   cd "$HOME/dinov3-features"
   DINO_KEY="$(cat .api-key)"
   curl --fail http://127.0.0.1:8994/health -H "Authorization: Bearer $DINO_KEY"
   curl --fail http://127.0.0.1:8994/v1/image-features -H "Authorization: Bearer $DINO_KEY" -H 'Content-Type: application/json' -d '{"fixture":"author-geometry-v1"}' -o features.json
   curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8994/health
   unset DINO_KEY
   .venv/bin/python - <<'PYVERIFY'
   import json, math
   d=json.load(open('features.json'))
   assert d['configured_vision_sequence_tokens']==201 and d['generated_text_tokens'] is None
   assert d['class_shape']==[1,384] and d['patch_shape']==[1,196,384]
   assert len(d['patch_embeddings'])==196
   for v in [d['class_embedding']]+d['patch_embeddings']:
    assert len(v)==384 and all(math.isfinite(x) for x in v)
    assert math.isclose(sum(x*x for x in v),1,rel_tol=1e-5,abs_tol=1e-5)
   print('Finite normalized feature shapes verified; no semantic quality claim.')
   PYVERIFY

   Expected result: Health ready; authorized fixed input returns documented numerical shapes. Unauthorized health 401. Finite/unit-vector checks pass only after actual reader execution; no observed feature values or accuracy are promised.

Performance evidence

No compatible measurement available. Documented support and estimated memory do not establish response speed.

Limits and troubleshooting

• This is one named maintainer derivative, not native Meta checkpoint bytes or complete frozen DINOv3 family coverage. Twelve native core backbones and later heads remain distinct research scope.
• The derivative card documents disabled zero QKV biases and float32 RoPE periods versus native persistent bfloat16 periods, with numerical differences. No native-output equivalence or sibling performance is inferred.
• 201 means one configured 224 × 224 vision sequence:196 patches + one class + four registers. It is not a text limit, generated-token allowance or global maximum. Published derivative default 256 gives 261 tokens; this guide deliberately configures 224. Generic finder context labels must be read with this stated native vision unit.
• The derivative default pool is average. This recipe explicitly uses global_pool=token for class features, omits four registers from patch output and normalizes each class/patch vector. Cosine similarity does not establish semantic labels, classification calibration or downstream task quality.
• The author-drawn rectangle/circle fixture supports shape and protocol checks only. Reader inspection and separate representative-data evaluation are needed for useful downstream quality. No external image rights are assumed.
• Actual DINOv3 custom license applies; public ungated access is not MIT/Apache licensing or a waiver. Reader must review applicable restrictions and authority before use; no terms accepted or legal clearance here.
• 32 GiB RAM, 40 GiB disk and four threads are planning allocations, not measured fit or minima. No latency, memory peak, speed or accuracy result is reported.
• No autoregressive K/V cache, chat template, text tokenizer, reasoning mode or generation sampler applies. Output tokens are not applicable; finite numerical features have explicit shapes.
• Reader-authored HTTPServer is an educational serial loopback harness with authentication, fixed request, bounded body and socket timeout. It has no inference deadline, public TLS, multiuser resilience or production suitability claim.
• CPU package stack is source-qualified only. Transitive/system dependency versions resolve during reader installation and must be recorded. Fake-encoder transport tests do not prove model/runtime compatibility, numerical outputs or quality.

Dependency, strict state-dictionary or hash failure

Stop and preserve logs and resolved-environment.txt. Restore exact timm release and derivative pin; do not disable strict loading or substitute native weights. Actual model compatibility is unexecuted.

Wrong shape or nonfinite feature result

Stop. Confirm explicit 224 preprocessing, class pooling and derivative architecture. Expect 201 unpooled tokens and 196 patch vectors; do not silently use published 256 default or reinterpret vision tokens as text.

401 or rejected request

Use matching 64-character lowercase hexadecimal private key and exact fixed fixture JSON. No URL, file path, prompt, labels or upload fields are supported.

Unexpected semantic interpretation or slow execution

Record observations without inventing accuracy or speed guarantees. Geometric fixture is not an in-domain evaluation. Inspect available memory and dependencies; allocation fit is unmeasured.

Stop the model

1. 1. Stop the research endpoint

   Press Ctrl+C in the server terminal and unset client keys. Close any SSH tunnel; stopping Python alone does not stop VM billing.

   CommandCopy command

   unset DINO_KEY

   Expected result: Research process stops and loopback endpoint no longer responds.

Uninstall

1. 1. Remove dedicated research files

   Preserve desired results and license records first. Confirm this dedicated path before removing it; shared Ubuntu packages remain.

   CommandCopy command

   rm -r -- "$HOME/dinov3-features"

   Expected result: Dedicated checkpoint, generated fixture, results, environment, wrapper and private key removed.

Shut down cloud resources

1. 1. End cloud billing resources

   In EC2 us-east-1, stop for later reuse or terminate this exact VM. Review Delete on termination for its root volume. Delete unwanted detached EBS volumes, snapshots and reserved/Elastic/public IP resources. Stopped VM storage and retained resources may still bill. Check Bills/Cost Explorer later for final usage.

   Expected result: Exact instance is stopped/terminated as intended; no unwanted attached/retained billed resources remain. Instance compute stops only after its lifecycle transition, not when the Python service stops.