RF-DETR

Exact model and requirements

Artifact:

Roboflow / Official RF-DETR Nano COCO checkpoint, same generation through core 1.4.2 · checkpoint rfdetr/nano_coco/checkpoint_best_regular.pth

Publisher revision:

GCS generation 1753203874837584

Artifact digest:

md5-base64:+2UEzOf73Hg/ekaZHwdjnw==

Download size:

0.34 GiB

Memory requirement (unknown):

Unknown — No measured full-process peak for Nano, CPU dependencies, 384 image activations and serialization.

System RAM / disk:

Unknown / Unknown

Placement:

single device. One CPU host; no tensor or pipeline sharding. Complete detector and preprocessing on CPU; no accelerator or disk offload.

KV cache:

Non-autoregressive fixed-image detector; no text-generation K/V cache configured.

Workload:

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

Tokenizer:

Native 384 × 384 image, patch16, 2 × 2 windows; one class token per window and no registers · a9ec4776f54462c6b39ae56c1888430751a88634

Sampling / reasoning:

No text sampler. Fixed RGB geometry 384 × 384, native ToTensor/ImageNet normalization then square resize 384. Each of four windows contains 144 patches + one CLS = 145; full-attention layers concatenate 580 positions. threshold=0.5 keeps scores strictly greater than 0.5; num_select 300 and decoder queries 300 are different native counts. No chat/reasoning template, language tokenizer or tool calling. 580 is this configured image encoder representation, not a global family maximum or text budget. Preserve raw native boxes, including possible out-of-frame coordinates; clip only the overlay. Empty detections on synthetic geometry are valid transport output, not proof of quality.

Runtime prerequisites:

Ubuntu 24.04 x86_64; See prerequisites above.

Official artifact · License

Selected Nano checkpoint is expressly Apache 2.0 in the publisher OPEN_SOURCE_MODELS list; actual released core 1.4.2 LICENSE is Apache 2.0. Retain required license/notices and change/patent conditions. Plus models remain separately licensed and are not installed or selected. Earlier exact 1.4.0 package imports PML code and is not represented as unconditionally Apache; this guide uses the publisher-separated 1.4.2 core without altering enforcement or accepting any platform agreement. No legal clearance or rights to outside datasets are implied.

• 366,287,238 bytes is publisher GCS checkpoint size; trusted pickle may include optimizer/training metadata and is not a runtime memory estimate. No weight body downloaded.
• 32 GiB RAM, 40 GiB disk and four threads are chosen planning allocations, not measured fit or minima.

Install the runtime

1. 1. Install the exact released core CPU stack

   Install no Plus extras. Source metadata and private Transformer API locations support these documented choices; actual environment compatibility remains unexecuted. Other transitive/system dependencies resolve and must be recorded. Supervision 0.31.0 declares no OpenCV distribution; Roboflow requires headless. Select only opencv-python-headless 4.11.0.86 and verify no other cv2 distribution is installed. These packages share a namespace and must not coexist.

   CommandCopy command

   sudo apt-get update
   sudo apt-get install -y python3.12 python3.12-venv curl ca-certificates openssl
   mkdir -p "$HOME/rfdetr-nano/models"
   cd "$HOME/rfdetr-nano"
   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 'numpy==1.26.4' 'Pillow==11.1.0' 'transformers==4.51.3' 'peft==0.15.2' 'accelerate==1.6.0' 'huggingface_hub==0.33.1' 'safetensors==0.6.2' 'tokenizers==0.21.2' 'supervision==0.31.0' 'pydantic==2.11.2' 'scipy==1.15.2' 'matplotlib==3.10.1' 'opencv-python-headless==4.11.0.86' 'rf100vl==1.1.2' 'roboflow==1.7.1' 'pycocotools==2.0.11' 'tqdm==4.67.1'
   .venv/bin/python -m pip install 'https://files.pythonhosted.org/packages/d7/53/c4e2c4680e8c0a9a62521fd947559e67312c617f4df048d609c765f6338f/rfdetr-1.4.2-py3-none-any.whl#sha256=4afaf96bc75db321a26c06ef0fffb8380595b2ba4fcc218663d6d093047640f3'
   .venv/bin/python -m pip check
   .venv/bin/python -m pip freeze > resolved-environment.txt
   .venv/bin/python - <<'PYCORE'
   import importlib.util,importlib.metadata
   assert importlib.metadata.version('rfdetr')=='1.4.2'
   assert importlib.util.find_spec('rfdetr_plus') is None
   variants={'opencv-python','opencv-python-headless','opencv-contrib-python','opencv-contrib-python-headless'}
   installed={d.metadata['Name'].lower().replace('_','-') for d in importlib.metadata.distributions()}
   assert installed & variants == {'opencv-python-headless'}, 'Use exactly one OpenCV variant: headless'
   print('Exact core release, no Plus package installed; no model loaded.')
   PYCORE

   Expected result: Exact core 1.4.2 and CPU wheels installed by reader; pip check passes, resolved versions saved, and Plus package absent.

Download the model

1. 1. Retrieve and verify the immutable publisher object

   Generation 1753203874837584 pins this exact GCS object. Size 366287238 and base64MD5 are publisher metadata; CRC32C O3yZfg== is recorded separately. No checkpoint body or SHA256 was obtained by the author. Verification must finish before any trusted pickle load.

   CommandCopy command

   cd "$HOME/rfdetr-nano"
   curl --fail --location --output models/nano.pth 'https://storage.googleapis.com/download/storage/v1/b/rfdetr/o/nano_coco%2Fcheckpoint_best_regular.pth?generation=1753203874837584&alt=media'
   .venv/bin/python - <<'PYWEIGHT'
   import pathlib,hashlib,base64
   p=pathlib.Path('models/nano.pth')
   assert p.stat().st_size==366287238
   h=hashlib.md5(usedforsecurity=False)
   with p.open('rb') as f:
    for b in iter(lambda:f.read(1048576),b''):h.update(b)
   assert base64.b64encode(h.digest()).decode()=='+2UEzOf73Hg/ekaZHwdjnw=='
   print('Publisher generation-selected checkpoint size and MD5 match; not a SHA-256 or collision-resistant guarantee.')
   PYWEIGHT

   Expected result: Exact size/MD5 checks pass. Stop on HTTP error, missing generation or mismatch; never fall back to a mutable logical-name download.

Configure

1. 1. Preserve a private service key

   Create only if absent; never print/share the local service key. Restore an empty/invalid existing key explicitly.

   CommandCopy command

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

   Expected result: Existing nonempty private key preserved; wrapper requires 64 lowercase hexadecimal characters.

2. 2. Create the fixed detector harness

   Reader-authored supporting HTTP code, not publisher serving code. It verifies checkpoint size/MD5 before imports/load and denies outbound connect/DNS for imports/constructor/inference. The native absolute-file path avoids hosted-name redownload; native core handles absent Plus without entitlement bypass. Geometry fixture only; no NMS or accuracy claim.

   CommandCopy command

   cd "$HOME/rfdetr-nano"
   cat > rfdetr_detect.py <<'PYMODEL'
   """Reader-authored educational fixed-input RF-DETR Nano core1.4.2 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 = 8992
   
   
   def verify_checkpoint(path):
       import base64
       expected_md5 = '+2UEzOf73Hg/ekaZHwdjnw=='
       if path.stat().st_size != 366287238:
           raise RuntimeError('checkpoint_size_mismatch')
       digest = hashlib.md5(usedforsecurity=False)
       with path.open('rb') as stream:
           for block in iter(lambda: stream.read(1024*1024), b''):
               digest.update(block)
       if base64.b64encode(digest.digest()).decode() != expected_md5:
           raise RuntimeError('checkpoint_md5_mismatch')
   
   
   def validate_detections(values):
       if type(values) is not list or len(values) > 300:
           raise ValueError('detection_count')
       for row in values:
           if type(row) is not dict or set(row) != {'box_xyxy', 'class_id', 'confidence'}:
               raise ValueError('detection_schema')
           box, cls, score = row['box_xyxy'], row['class_id'], row['confidence']
           if type(box) is not list or len(box) != 4 or any(type(x) not in (int,float) or not math.isfinite(x) for x in box):
               raise ValueError('box_type')
           if not (box[0] <= box[2] and box[1] <= box[3]):
               raise ValueError('box_range')
           if type(cls) is not int or not 0 <= cls <= 90:
               raise ValueError('class_id')
           if type(score) not in (int,float) or not math.isfinite(score) or not 0.5 < score <= 1:
               raise ValueError('confidence')
       return {'fixture': 'author-geometry-v1', 'image_shape': [1,3,384,384],
               'configured_vision_positions': 580, 'windows_per_axis': 2,
               'patches_per_window': 144, 'class_tokens_per_window': 1,
               'decoder_queries': 300, 'threshold': 0.5, 'detections': values,
               'generated_text_tokens': None, 'quality_validated': False}
   
   
   def make_encoder():
       import sys
       import importlib.util
       artifact = (ROOT/'models/nano.pth').resolve()
       verify_checkpoint(artifact)  # Verify publisher size+MD5 BEFORE trusted pickle load.
       # Deny outbound connections for reader-run imports/constructor/inference.
       def offline(event, args):
           if event in ('socket.connect', 'socket.getaddrinfo', 'socket.gethostbyname', 'socket.gethostbyaddr'):
               raise OSError('outbound_network_disabled')
       sys.addaudithook(offline)
       if importlib.util.find_spec('rfdetr_plus') is not None:
           raise RuntimeError('use_clean_core_only_environment')
       import torch
       from PIL import Image, ImageDraw
       from rfdetr import RFDETRNano
       torch.set_num_threads(4)
       model = RFDETRNano(device='cpu', pretrain_weights=str(artifact))
       model.model.model.float().eval()
       cfg = model.model_config
       assert (cfg.resolution,cfg.patch_size,cfg.num_windows,cfg.dec_layers)==(384,16,2,2)
       assert (cfg.encoder,cfg.num_queries,cfg.num_select)==('dinov2_windowed_small',300,300)
       assert not model.model.model.training
       assert all(x.device.type=='cpu' and x.dtype==torch.float32 for x in model.model.model.parameters())
       # Original geometric smoke fixture; no semantic object detection is promised.
       image=Image.new('RGB',(384,384),(240,240,240));draw=ImageDraw.Draw(image)
       draw.rectangle((40,40,180,340),fill=(220,40,40));draw.ellipse((210,110,360,260),fill=(30,90,220))
       image.save(ROOT/'fixture.png')
       def encode():
           with torch.inference_mode():
               detections=model.predict(image,threshold=0.5)
           return [{'box_xyxy':[float(x) for x in box], 'class_id':int(cls), 'confidence':float(score)}
                   for box,cls,score in zip(detections.xyxy,detections.class_id,detections.confidence)]
       return encode
   
   PYMODEL

   Expected result: First complete supporting-code section written; append HTTP section before compiling or starting.

3. 3. Append the bounded HTTP protocol

   Append the second exact supporting-code section, then verify complete wrapper hash and syntax. Both sections are required.

   CommandCopy command

   cd "$HOME/rfdetr-nano"
   cat >> rfdetr_detect.py <<'PYHTTP'
   
   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_positions': 580,
                                       'generated_text_tokens': None})
   
           def do_POST(self):
               if not self.authorized():
                   return self.reply(401, {'error': 'unauthorized'})
               if self.path != '/v1/detect':
                   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:
                   result = validate_detections(encoder())
               except Exception:
                   return self.reply(500, {'error': 'detector_or_output_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()
   PYHTTP
   .venv/bin/python -m py_compile rfdetr_detect.py
   sha256sum --check <<'SHA256'
   24adeb287190241d06a392e23d70f184788511137ff199651ea4ae2557cfa066  rfdetr_detect.py
   SHA256

   Expected result: Complete wrapper hash and syntax verify without model imports.

Start the model

1. 1. Start the private CPU detector

   Foreground serial process; explicit CPU FP32 eval, no compile/LoRA/export/train/deploy. HF offline flags and audit hook prevent new network connections; fail rather than fetch a mutable auxiliary model. The hook is an author endpoint boundary, not a modification to publisher license code.

   CommandCopy command

   cd "$HOME/rfdetr-nano"
   HF_HUB_OFFLINE=1 TRANSFORMERS_OFFLINE=1 OMP_NUM_THREADS=4 MKL_NUM_THREADS=4 .venv/bin/python rfdetr_detect.py

   Expected result: After unexecuted source-supported load, bind 127.0.0.1:8992. Stop on offline dependency/import/config failures; do not weaken verification or enable fallback.

Verify the setup

1. 1. Inspect detection protocol and overlay

   Check authentication,580 configured positions and box/class/score schema. Inspect original fixture.png and overlay.png; no object class/count is promised for geometry. Class IDs follow native COCO-trained output, not a shape-specific taxonomy. Raw boxes can extend outside image boundaries; clipping affects display only.

   CommandCopy command

   cd "$HOME/rfdetr-nano"
   RF_KEY="$(cat .api-key)"
   curl --fail http://127.0.0.1:8992/health -H "Authorization: Bearer $RF_KEY"
   curl --fail http://127.0.0.1:8992/v1/detect -H "Authorization: Bearer $RF_KEY" -H 'Content-Type: application/json' -d '{"fixture":"author-geometry-v1"}' -o detections.json
   curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8992/health
   unset RF_KEY
   .venv/bin/python - <<'PYVERIFY'
   import json,math
   from PIL import Image,ImageDraw
   x=json.load(open('detections.json'))
   assert x['configured_vision_positions']==580 and x['decoder_queries']==300
   assert x['generated_text_tokens'] is None and x['threshold']==0.5
   assert x['image_shape']==[1,3,384,384] and len(x['detections'])<=300
   image=Image.open('fixture.png').convert('RGB');draw=ImageDraw.Draw(image)
   for d in x['detections']:
    b=d['box_xyxy'];s=d['confidence'];c=d['class_id']
    assert len(b)==4 and all(math.isfinite(v) for v in b) and b[0]<=b[2] and b[1]<=b[3]
    assert math.isfinite(s) and 0.5<s<=1 and type(c) is int and 0<=c<=90
    # Preserve native raw coordinates in JSON; clip only the display overlay.
    b=[min(383,max(0,v)) for v in b]
    draw.rectangle(b,outline=(0,170,0),width=2);draw.text((b[0],b[1]),str(c)+' '+format(s,'.3f'),fill=(0,0,0))
   image.save('overlay.png')
   print('Inspect fixture/overlay and raw JSON. Empty geometry detections are allowed; no exact count, class or score is promised.')
   PYVERIFY

   Expected result: Authorized fixed request yields finite ordered boxes, integer class IDs and confidence > 0.5, up to 300 entries; zero entries is allowed. Unauthorized health 401. Overlay is a research inspection aid, not detection accuracy proof.

Performance evidence

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

Limits and troubleshooting

• The frozen family version 1.4 does not force the unsafe/unqualified 1.4.0 package path. This recipe explicitly names publisher-released Apache core 1.4.2 for the exact same Nano checkpoint. 1.4.0 imported PML runtime remains held; no license checks stripped, plan assumed free or agreement accepted.
• 580 is configured encoder positions: 384 / 16 = 24 patches per axis; four 12 × 12 windows each repeat one CLS =>4×145. Register tokens: 0. This is not 577, 300 decoder queries, text context or a global family maximum.
• Nano is an object detector; no segmentation masks, language generation or autoregressive K/V cache. Native thresholding selects scores>0.5 from up to 300 ranked entries; no additional NMS or calibrated confidence claim.
• Original colored geometry is a reproducible protocol fixture, not a COCO benchmark. Empty or unexpected detections are possible. Inspect native class IDs, boxes and confidence without inventing expected labels/counts or quality.
• Native raw boxes are not clamped to image bounds. Wrapper requires finite ordered coordinates and valid score/class ranges; visualization alone clips to image rectangle. Do not silently treat clipping as native model output.
• Publisher objectgeneration/size/MD5/CRC metadata identify exact bytes for retrieval but do not provide SHA256 or modern collision resistance. Native trusted pickle weights_only=False can execute code and state_dict loading uses strict=False; only the pinned publisher object is accepted by the wrapper.
• The complete native constructor uses an absolute existing file and nonpretrained DINO backbone under Nano patch 16. Core absent-Plus shim returns an empty optional registry. Source-qualified offline behavior is unexecuted; outbound audit denial fails rather than allowing surprise downloads.
• 32 GiB RAM, 40 GiB disk and four threads are allocations, not measured requirements. Serialized checkpoint size includes potential training state; no fit, speed, memory peak or accuracy is known.
• This original HTTPServer is serial, loopback-only and authenticated with fixed input/body limits/socket timeout; no inference deadline, public TLS or production resilience is claimed. Client timeout does not cancel model work.
• Exact direct version choices are sourced; transitive/system package resolutions remain reader-recorded. Fake-detector boundary tests and syntax checks do not prove actual target environment/model compatibility. Other sizes, segmentation/GPU/other backends remain open family scope.

Checkpoint mismatch or pickle trust concern

Stop before loading. Check exact generation-selected publisher URL, size and base64MD5. Never use an arbitrary checkpoint or claim MD5 is a cryptographic SHA256 guarantee.

Plus import or outbound-network failure

Use a clean dedicated core 1.4.2 environment without rfdetr_plus and exact local absolute weights. Do not strip publisher checks, accept a plan or allow mutable downloads. Preserve errors; documented compatibility is unexecuted.

No detections or unexpected boxes

Geometry may produce zero detections. Inspect raw JSON and clipped display overlay, threshold 0.5 and native class IDs. Do not lower threshold silently or invent expected quality.

401, package error or memory failure

Use matching private key and exact fixture JSON. Stop on dependency or resource errors; inspect saved versions. Allocation does not establish fit or latency.

Stop the model

1. 1. Stop the fixed detector

   Press Ctrl+C in foreground; unset client keys. Confirm local loopback port no longer serves.

   CommandCopy command

   unset RF_KEY

   Expected result: Process stops and loopback endpoint no longer responds.

Uninstall

1. 1. Remove dedicated experiment files

   Preserve wanted results/notices first and confirm the exact dedicated directory. Shared Ubuntu packages remain.

   CommandCopy command

   rm -r -- "$HOME/rfdetr-nano"

   Expected result: Dedicated weights, environment, wrapper, fixtures, results and private key removed.

Exact model and requirements

Artifact:

Roboflow / Official RF-DETR Nano COCO checkpoint, same generation through core 1.4.2 · checkpoint rfdetr/nano_coco/checkpoint_best_regular.pth

Publisher revision:

GCS generation 1753203874837584

Artifact digest:

md5-base64:+2UEzOf73Hg/ekaZHwdjnw==

Download size:

0.34 GiB

Memory requirement (unknown):

Unknown — No measured full-process peak for Nano, CPU dependencies, 384 image activations and serialization.

System RAM / disk:

Unknown / Unknown

Placement:

single device. One CPU host; no tensor or pipeline sharding. Complete detector and preprocessing on CPU; no accelerator or disk offload.

KV cache:

Non-autoregressive fixed-image detector; no text-generation K/V cache configured.

Workload:

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

Tokenizer:

Native 384 × 384 image, patch16, 2 × 2 windows; one class token per window and no registers · a9ec4776f54462c6b39ae56c1888430751a88634

Sampling / reasoning:

No text sampler. Fixed RGB geometry 384 × 384, native ToTensor/ImageNet normalization then square resize 384. Each of four windows contains 144 patches + one CLS = 145; full-attention layers concatenate 580 positions. threshold=0.5 keeps scores strictly greater than 0.5; num_select 300 and decoder queries 300 are different native counts. No chat/reasoning template, language tokenizer or tool calling. 580 is this configured image encoder representation, not a global family maximum or text budget. Preserve raw native boxes, including possible out-of-frame coordinates; clip only the overlay. Empty detections on synthetic geometry are valid transport output, not proof of quality.

Runtime prerequisites:

Ubuntu 24.04 x86_64; See prerequisites above.

Official artifact · License

Selected Nano checkpoint is expressly Apache 2.0 in the publisher OPEN_SOURCE_MODELS list; actual released core 1.4.2 LICENSE is Apache 2.0. Retain required license/notices and change/patent conditions. Plus models remain separately licensed and are not installed or selected. Earlier exact 1.4.0 package imports PML code and is not represented as unconditionally Apache; this guide uses the publisher-separated 1.4.2 core without altering enforcement or accepting any platform agreement. No legal clearance or rights to outside datasets are implied.

• 366,287,238 bytes is publisher GCS checkpoint size; trusted pickle may include optimizer/training metadata and is not a runtime memory estimate. No weight body downloaded.
• 32 GiB RAM, 40 GiB disk and four threads are chosen planning allocations, not measured fit or minima.

Install the runtime

1. 1. Install the exact released core CPU stack

   Install no Plus extras. Source metadata and private Transformer API locations support these documented choices; actual environment compatibility remains unexecuted. Other transitive/system dependencies resolve and must be recorded. Supervision 0.31.0 declares no OpenCV distribution; Roboflow requires headless. Select only opencv-python-headless 4.11.0.86 and verify no other cv2 distribution is installed. These packages share a namespace and must not coexist.

   CommandCopy command

   sudo apt-get update
   sudo apt-get install -y python3.12 python3.12-venv curl ca-certificates openssl
   mkdir -p "$HOME/rfdetr-nano/models"
   cd "$HOME/rfdetr-nano"
   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 'numpy==1.26.4' 'Pillow==11.1.0' 'transformers==4.51.3' 'peft==0.15.2' 'accelerate==1.6.0' 'huggingface_hub==0.33.1' 'safetensors==0.6.2' 'tokenizers==0.21.2' 'supervision==0.31.0' 'pydantic==2.11.2' 'scipy==1.15.2' 'matplotlib==3.10.1' 'opencv-python-headless==4.11.0.86' 'rf100vl==1.1.2' 'roboflow==1.7.1' 'pycocotools==2.0.11' 'tqdm==4.67.1'
   .venv/bin/python -m pip install 'https://files.pythonhosted.org/packages/d7/53/c4e2c4680e8c0a9a62521fd947559e67312c617f4df048d609c765f6338f/rfdetr-1.4.2-py3-none-any.whl#sha256=4afaf96bc75db321a26c06ef0fffb8380595b2ba4fcc218663d6d093047640f3'
   .venv/bin/python -m pip check
   .venv/bin/python -m pip freeze > resolved-environment.txt
   .venv/bin/python - <<'PYCORE'
   import importlib.util,importlib.metadata
   assert importlib.metadata.version('rfdetr')=='1.4.2'
   assert importlib.util.find_spec('rfdetr_plus') is None
   variants={'opencv-python','opencv-python-headless','opencv-contrib-python','opencv-contrib-python-headless'}
   installed={d.metadata['Name'].lower().replace('_','-') for d in importlib.metadata.distributions()}
   assert installed & variants == {'opencv-python-headless'}, 'Use exactly one OpenCV variant: headless'
   print('Exact core release, no Plus package installed; no model loaded.')
   PYCORE

   Expected result: Exact core 1.4.2 and CPU wheels installed by reader; pip check passes, resolved versions saved, and Plus package absent.

Download the model

1. 1. Retrieve and verify the immutable publisher object

   Generation 1753203874837584 pins this exact GCS object. Size 366287238 and base64MD5 are publisher metadata; CRC32C O3yZfg== is recorded separately. No checkpoint body or SHA256 was obtained by the author. Verification must finish before any trusted pickle load.

   CommandCopy command

   cd "$HOME/rfdetr-nano"
   curl --fail --location --output models/nano.pth 'https://storage.googleapis.com/download/storage/v1/b/rfdetr/o/nano_coco%2Fcheckpoint_best_regular.pth?generation=1753203874837584&alt=media'
   .venv/bin/python - <<'PYWEIGHT'
   import pathlib,hashlib,base64
   p=pathlib.Path('models/nano.pth')
   assert p.stat().st_size==366287238
   h=hashlib.md5(usedforsecurity=False)
   with p.open('rb') as f:
    for b in iter(lambda:f.read(1048576),b''):h.update(b)
   assert base64.b64encode(h.digest()).decode()=='+2UEzOf73Hg/ekaZHwdjnw=='
   print('Publisher generation-selected checkpoint size and MD5 match; not a SHA-256 or collision-resistant guarantee.')
   PYWEIGHT

   Expected result: Exact size/MD5 checks pass. Stop on HTTP error, missing generation or mismatch; never fall back to a mutable logical-name download.

Configure

1. 1. Preserve a private service key

   Create only if absent; never print/share the local service key. Restore an empty/invalid existing key explicitly.

   CommandCopy command

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

   Expected result: Existing nonempty private key preserved; wrapper requires 64 lowercase hexadecimal characters.

2. 2. Create the fixed detector harness

   Reader-authored supporting HTTP code, not publisher serving code. It verifies checkpoint size/MD5 before imports/load and denies outbound connect/DNS for imports/constructor/inference. The native absolute-file path avoids hosted-name redownload; native core handles absent Plus without entitlement bypass. Geometry fixture only; no NMS or accuracy claim.

   CommandCopy command

   cd "$HOME/rfdetr-nano"
   cat > rfdetr_detect.py <<'PYMODEL'
   """Reader-authored educational fixed-input RF-DETR Nano core1.4.2 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 = 8992
   
   
   def verify_checkpoint(path):
       import base64
       expected_md5 = '+2UEzOf73Hg/ekaZHwdjnw=='
       if path.stat().st_size != 366287238:
           raise RuntimeError('checkpoint_size_mismatch')
       digest = hashlib.md5(usedforsecurity=False)
       with path.open('rb') as stream:
           for block in iter(lambda: stream.read(1024*1024), b''):
               digest.update(block)
       if base64.b64encode(digest.digest()).decode() != expected_md5:
           raise RuntimeError('checkpoint_md5_mismatch')
   
   
   def validate_detections(values):
       if type(values) is not list or len(values) > 300:
           raise ValueError('detection_count')
       for row in values:
           if type(row) is not dict or set(row) != {'box_xyxy', 'class_id', 'confidence'}:
               raise ValueError('detection_schema')
           box, cls, score = row['box_xyxy'], row['class_id'], row['confidence']
           if type(box) is not list or len(box) != 4 or any(type(x) not in (int,float) or not math.isfinite(x) for x in box):
               raise ValueError('box_type')
           if not (box[0] <= box[2] and box[1] <= box[3]):
               raise ValueError('box_range')
           if type(cls) is not int or not 0 <= cls <= 90:
               raise ValueError('class_id')
           if type(score) not in (int,float) or not math.isfinite(score) or not 0.5 < score <= 1:
               raise ValueError('confidence')
       return {'fixture': 'author-geometry-v1', 'image_shape': [1,3,384,384],
               'configured_vision_positions': 580, 'windows_per_axis': 2,
               'patches_per_window': 144, 'class_tokens_per_window': 1,
               'decoder_queries': 300, 'threshold': 0.5, 'detections': values,
               'generated_text_tokens': None, 'quality_validated': False}
   
   
   def make_encoder():
       import sys
       import importlib.util
       artifact = (ROOT/'models/nano.pth').resolve()
       verify_checkpoint(artifact)  # Verify publisher size+MD5 BEFORE trusted pickle load.
       # Deny outbound connections for reader-run imports/constructor/inference.
       def offline(event, args):
           if event in ('socket.connect', 'socket.getaddrinfo', 'socket.gethostbyname', 'socket.gethostbyaddr'):
               raise OSError('outbound_network_disabled')
       sys.addaudithook(offline)
       if importlib.util.find_spec('rfdetr_plus') is not None:
           raise RuntimeError('use_clean_core_only_environment')
       import torch
       from PIL import Image, ImageDraw
       from rfdetr import RFDETRNano
       torch.set_num_threads(4)
       model = RFDETRNano(device='cpu', pretrain_weights=str(artifact))
       model.model.model.float().eval()
       cfg = model.model_config
       assert (cfg.resolution,cfg.patch_size,cfg.num_windows,cfg.dec_layers)==(384,16,2,2)
       assert (cfg.encoder,cfg.num_queries,cfg.num_select)==('dinov2_windowed_small',300,300)
       assert not model.model.model.training
       assert all(x.device.type=='cpu' and x.dtype==torch.float32 for x in model.model.model.parameters())
       # Original geometric smoke fixture; no semantic object detection is promised.
       image=Image.new('RGB',(384,384),(240,240,240));draw=ImageDraw.Draw(image)
       draw.rectangle((40,40,180,340),fill=(220,40,40));draw.ellipse((210,110,360,260),fill=(30,90,220))
       image.save(ROOT/'fixture.png')
       def encode():
           with torch.inference_mode():
               detections=model.predict(image,threshold=0.5)
           return [{'box_xyxy':[float(x) for x in box], 'class_id':int(cls), 'confidence':float(score)}
                   for box,cls,score in zip(detections.xyxy,detections.class_id,detections.confidence)]
       return encode
   
   PYMODEL

   Expected result: First complete supporting-code section written; append HTTP section before compiling or starting.

3. 3. Append the bounded HTTP protocol

   Append the second exact supporting-code section, then verify complete wrapper hash and syntax. Both sections are required.

   CommandCopy command

   cd "$HOME/rfdetr-nano"
   cat >> rfdetr_detect.py <<'PYHTTP'
   
   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_positions': 580,
                                       'generated_text_tokens': None})
   
           def do_POST(self):
               if not self.authorized():
                   return self.reply(401, {'error': 'unauthorized'})
               if self.path != '/v1/detect':
                   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:
                   result = validate_detections(encoder())
               except Exception:
                   return self.reply(500, {'error': 'detector_or_output_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()
   PYHTTP
   .venv/bin/python -m py_compile rfdetr_detect.py
   sha256sum --check <<'SHA256'
   24adeb287190241d06a392e23d70f184788511137ff199651ea4ae2557cfa066  rfdetr_detect.py
   SHA256

   Expected result: Complete wrapper hash and syntax verify without model imports.

Start the model

1. 1. Start the private CPU detector

   Foreground serial process; explicit CPU FP32 eval, no compile/LoRA/export/train/deploy. HF offline flags and audit hook prevent new network connections; fail rather than fetch a mutable auxiliary model. The hook is an author endpoint boundary, not a modification to publisher license code.

   CommandCopy command

   cd "$HOME/rfdetr-nano"
   HF_HUB_OFFLINE=1 TRANSFORMERS_OFFLINE=1 OMP_NUM_THREADS=4 MKL_NUM_THREADS=4 .venv/bin/python rfdetr_detect.py

   Expected result: After unexecuted source-supported load, bind 127.0.0.1:8992. Stop on offline dependency/import/config failures; do not weaken verification or enable fallback.

Verify the setup

1. 1. Inspect detection protocol and overlay

   Check authentication,580 configured positions and box/class/score schema. Inspect original fixture.png and overlay.png; no object class/count is promised for geometry. Class IDs follow native COCO-trained output, not a shape-specific taxonomy. Raw boxes can extend outside image boundaries; clipping affects display only.

   CommandCopy command

   cd "$HOME/rfdetr-nano"
   RF_KEY="$(cat .api-key)"
   curl --fail http://127.0.0.1:8992/health -H "Authorization: Bearer $RF_KEY"
   curl --fail http://127.0.0.1:8992/v1/detect -H "Authorization: Bearer $RF_KEY" -H 'Content-Type: application/json' -d '{"fixture":"author-geometry-v1"}' -o detections.json
   curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8992/health
   unset RF_KEY
   .venv/bin/python - <<'PYVERIFY'
   import json,math
   from PIL import Image,ImageDraw
   x=json.load(open('detections.json'))
   assert x['configured_vision_positions']==580 and x['decoder_queries']==300
   assert x['generated_text_tokens'] is None and x['threshold']==0.5
   assert x['image_shape']==[1,3,384,384] and len(x['detections'])<=300
   image=Image.open('fixture.png').convert('RGB');draw=ImageDraw.Draw(image)
   for d in x['detections']:
    b=d['box_xyxy'];s=d['confidence'];c=d['class_id']
    assert len(b)==4 and all(math.isfinite(v) for v in b) and b[0]<=b[2] and b[1]<=b[3]
    assert math.isfinite(s) and 0.5<s<=1 and type(c) is int and 0<=c<=90
    # Preserve native raw coordinates in JSON; clip only the display overlay.
    b=[min(383,max(0,v)) for v in b]
    draw.rectangle(b,outline=(0,170,0),width=2);draw.text((b[0],b[1]),str(c)+' '+format(s,'.3f'),fill=(0,0,0))
   image.save('overlay.png')
   print('Inspect fixture/overlay and raw JSON. Empty geometry detections are allowed; no exact count, class or score is promised.')
   PYVERIFY

   Expected result: Authorized fixed request yields finite ordered boxes, integer class IDs and confidence > 0.5, up to 300 entries; zero entries is allowed. Unauthorized health 401. Overlay is a research inspection aid, not detection accuracy proof.

Performance evidence

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

Limits and troubleshooting

• The frozen family version 1.4 does not force the unsafe/unqualified 1.4.0 package path. This recipe explicitly names publisher-released Apache core 1.4.2 for the exact same Nano checkpoint. 1.4.0 imported PML runtime remains held; no license checks stripped, plan assumed free or agreement accepted.
• 580 is configured encoder positions: 384 / 16 = 24 patches per axis; four 12 × 12 windows each repeat one CLS =>4×145. Register tokens: 0. This is not 577, 300 decoder queries, text context or a global family maximum.
• Nano is an object detector; no segmentation masks, language generation or autoregressive K/V cache. Native thresholding selects scores>0.5 from up to 300 ranked entries; no additional NMS or calibrated confidence claim.
• Original colored geometry is a reproducible protocol fixture, not a COCO benchmark. Empty or unexpected detections are possible. Inspect native class IDs, boxes and confidence without inventing expected labels/counts or quality.
• Native raw boxes are not clamped to image bounds. Wrapper requires finite ordered coordinates and valid score/class ranges; visualization alone clips to image rectangle. Do not silently treat clipping as native model output.
• Publisher objectgeneration/size/MD5/CRC metadata identify exact bytes for retrieval but do not provide SHA256 or modern collision resistance. Native trusted pickle weights_only=False can execute code and state_dict loading uses strict=False; only the pinned publisher object is accepted by the wrapper.
• The complete native constructor uses an absolute existing file and nonpretrained DINO backbone under Nano patch 16. Core absent-Plus shim returns an empty optional registry. Source-qualified offline behavior is unexecuted; outbound audit denial fails rather than allowing surprise downloads.
• 32 GiB RAM, 40 GiB disk and four threads are allocations, not measured requirements. Serialized checkpoint size includes potential training state; no fit, speed, memory peak or accuracy is known.
• This original HTTPServer is serial, loopback-only and authenticated with fixed input/body limits/socket timeout; no inference deadline, public TLS or production resilience is claimed. Client timeout does not cancel model work.
• Exact direct version choices are sourced; transitive/system package resolutions remain reader-recorded. Fake-detector boundary tests and syntax checks do not prove actual target environment/model compatibility. Other sizes, segmentation/GPU/other backends remain open family scope.

Checkpoint mismatch or pickle trust concern

Stop before loading. Check exact generation-selected publisher URL, size and base64MD5. Never use an arbitrary checkpoint or claim MD5 is a cryptographic SHA256 guarantee.

Plus import or outbound-network failure

Use a clean dedicated core 1.4.2 environment without rfdetr_plus and exact local absolute weights. Do not strip publisher checks, accept a plan or allow mutable downloads. Preserve errors; documented compatibility is unexecuted.

No detections or unexpected boxes

Geometry may produce zero detections. Inspect raw JSON and clipped display overlay, threshold 0.5 and native class IDs. Do not lower threshold silently or invent expected quality.

401, package error or memory failure

Use matching private key and exact fixture JSON. Stop on dependency or resource errors; inspect saved versions. Allocation does not establish fit or latency.

Stop the model

1. 1. Stop the fixed detector

   Press Ctrl+C in foreground; unset client keys. Close SSH tunnel; stopping Python does not stop VM billing.

   CommandCopy command

   unset RF_KEY

   Expected result: Process stops and loopback endpoint no longer responds.

Uninstall

1. 1. Remove dedicated experiment files

   Preserve wanted results/notices first and confirm the exact dedicated directory. Shared Ubuntu packages remain.

   CommandCopy command

   rm -r -- "$HOME/rfdetr-nano"

   Expected result: Dedicated weights, environment, wrapper, fixtures, results 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.