Segment Anything Model

Exact model and requirements

Artifact:

Meta / facebookresearch / Original Segment Anything SAM ViT-B checkpoint · checkpoint sam_vit_b_01ec64.pth

Publisher revision:

Mr6xCf5BiIKu1NZw1QSZGz_F0TN9.TFi

Artifact digest:

Publisher HEAD exposes opaque multipart ETag dd6e14655a594ad8d2c1f256ccf6076e-45, not a full MD5 or SHA256. No weight body was downloaded or authoritative full body digest found.

Download size:

0.35 GiB

Memory requirement (unknown):

Unknown — No measured full-process peak for this exact CPU float32 model, image activation/decoder state and dependencies.

System RAM / disk:

Unknown / Unknown

Placement:

single device. One CPU host, one sequence and no tensor/pipeline sharding. Whole model and image/prompt handling on CPU; no device or disk offload.

KV cache:

Image segmentation has no autoregressive text K/V cache. Native image predictor state resets after each fixed request.

Workload:

4,096 token context; 4,096 input tokens; Not applicable; concurrency 1; batch 1; cache cold; repetitions Unknown.

Tokenizer:

Native image encoder 1024-pixel padded square, patch size 16, grid 64 × 64; no text tokenizer · dca509fe793f601edb92606367a655c15ac00fdf

Sampling / reasoning:

No generation sampler. Exactly one original 224 × 224 RGB fixture, one positive XY point [64,112] with label 1, multimask_output=False and return_logits=False. Native ResizeLongestSide uses PIL bilinear resizing; native normalization precedes padding to the 1024 square. This square fixture has no nonzero padding region. 4,096 is the configured single-image spatial embedding count. Local 14 × 14 attention windows may pad their partitioned grid; global attention uses the 64 × 64 grid. Prompt embeddings, learned mask/IoU tokens and upsampled decoder features are separate. No native global token maximum, text context allowance or point-count maximum is inferred.

Runtime prerequisites:

Ubuntu 24.04 x86_64; See prerequisites above.

Official artifact · License

Upstream README explicitly licenses the model under Apache License 2.0; the actual license is archived. Retain applicable license, copyright and NOTICE material; follow change-notice and patent conditions. This guide grants no trademark endorsement or legal clearance. The image fixture is original author geometry; no upstream demonstration media or datasets are included.

• 375,042,383 bytes is exact official HEAD Content-Length for the selected object version, not runtime RAM or an independently verified body hash.
• 32 GiB RAM, 40 GiB disk and four threads are chosen planning allocations; activation, decoder, packages and OS overhead remain unmeasured.

Install the runtime

1. 1. Create the pinned native CPU environment

   Native README requires Python>=3.8, torch>=1.7 and torchvision>=0.8 and recommends CUDA. This separately documented CPU configuration selects matching official CPU wheels. Native setup declares no dependencies; install the complete eager Python path explicitly. Optional automatic-mask region cleanup imports OpenCV only when invoked and is not used here. No all-extra, training, export or web demo package is selected.

   CommandCopy command

   set -e
   sudo apt-get update
   sudo apt-get install -y python3.12 python3.12-venv git curl ca-certificates openssl
   mkdir -p "$HOME/sam1-image/models"
   cd "$HOME/sam1-image"
   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==2.2.3' 'Pillow==11.1.0'
   git clone https://github.com/facebookresearch/segment-anything.git native-sam1
   git -C native-sam1 checkout --detach dca509fe793f601edb92606367a655c15ac00fdf
   .venv/bin/python -m pip install -e ./native-sam1
   .venv/bin/python -m pip check
   .venv/bin/python -m pip freeze > resolved-environment.txt

   Expected result: Pinned checkout and CPU wheels resolve, pip check passes and environment resolution is saved. No executed compatibility, speed or fit claim.

Download the model

1. 1. Retrieve and check the exact publisher object version

   Reader-only weight retrieval. Pin the actual S3 version and verify version header, opaque multipart ETag and exact size. The ETag is not a full-body MD5/SHA; record a local body SHA for your own audit without claiming it matches a publisher digest. Stop on any mismatch. Use only this trusted official HTTPS object; safe tensor loading is defense in depth, not general untrusted-file clearance.

   CommandCopy command

   set -e
   cd "$HOME/sam1-image"
   curl --fail --location --dump-header checkpoint-headers.txt --output models/sam_vit_b_01ec64.pth 'https://dl.fbaipublicfiles.com/segment_anything/sam_vit_b_01ec64.pth?versionId=Mr6xCf5BiIKu1NZw1QSZGz_F0TN9.TFi'
   .venv/bin/python - <<'PYARTIFACT'
   import pathlib
   lines=pathlib.Path('checkpoint-headers.txt').read_text().splitlines()
   headers={k.strip().lower():v.strip() for line in lines if ':' in line for k,v in [line.split(':',1)]}
   assert headers['x-amz-version-id']=='Mr6xCf5BiIKu1NZw1QSZGz_F0TN9.TFi'
   assert headers['etag'].strip('"')=='dd6e14655a594ad8d2c1f256ccf6076e-45'
   assert pathlib.Path('models/sam_vit_b_01ec64.pth').stat().st_size==375042383
   PYARTIFACT
   sha256sum models/sam_vit_b_01ec64.pth > reader-downloaded-body.sha256
   sha256sum --check <<'SHASOURCE'
   c71d239df91726fc519c6eb72d318ec65820627232b2f796219e87dcf35d0ab4  native-sam1/LICENSE
   77bc4faf728118625ddd184dc4e6375bd1b5c636fc66fb429f9fc5276f331cc5  native-sam1/segment_anything/build_sam.py
   SHASOURCE

   Expected result: Official object version, opaque ETag, size and exact native source hashes match. Local body SHA is recorded; authoritative full-body digest remains unknown.

Configure

1. 1. Create a stable private service key

   Generate only when absent; preserve existing access. Do not print or share this local service key.

   CommandCopy command

   set -e
   cd "$HOME/sam1-image"
   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: Private existing key is preserved; server requires 64 lowercase hexadecimal characters.

2. 2. Create the fixed point-prompt harness

   Reader-authored serial loopback HTTPServer, not publisher deployment software. It instantiates the exact native vit_b registry architecture with checkpoint set to None, then uses torch.load with tensor-only loading on CPU: weights_only is True and map_location is cpu. State loading uses strict=True. This replaces the native builder’s implicit torch.load default without altering model architecture or checkpoint keys. A missing, unsafe or incompatible state dictionary stops loading.

   CommandCopy command

   set -e
   cd "$HOME/sam1-image"
   cat > sam1_image.py <<'PYSERVER'
   """Reader-authored educational fixed-input SAM1 ViT-B 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_BYTES = 375042383
   
   
   def validate_mask(result):
       mask, score, low_shape = result
       if type(score) not in (int, float) or not math.isfinite(score):
           raise ValueError('invalid_score')
       if low_shape != [1, 256, 256] or len(mask) != 224:
           raise ValueError('invalid_shape')
       flat = []
       for row in mask:
           if len(row) != 224 or any(type(v) is not bool for v in row):
               raise ValueError('invalid_mask')
           flat.extend(row)
       runs = []
       i = 0
       while i < len(flat):
           if not flat[i]:
               i += 1
               continue
           start = i
           while i < len(flat) and flat[i]:
               i += 1
           runs.append([start, i-start])
       return {'fixture': 'author-geometry-v1', 'image_shape': [224, 224, 3],
               'transformed_shape': [1, 3, 1024, 1024],
               'coarse_embedding_shape': [1, 256, 64, 64],
               'configured_coarse_vision_positions': 4096,
               'point_xy': [64, 112], 'point_label': 1,
               'mask_shape': [1, 224, 224], 'mask_true_runs': runs,
               'mask_area_pixels': sum(flat), 'estimated_iou': score,
               'low_resolution_logits_shape': low_shape,
               'generated_text_tokens': None, 'semantic_classification': False}
   
   
   def make_encoder():
       # Actual model imports occur only in the reader-run path, not fake boundary tests.
       import numpy as np
       import torch
       from PIL import Image, ImageDraw
       from segment_anything import sam_model_registry, SamPredictor
       torch.set_num_threads(4)
       artifact = ROOT / 'models/sam_vit_b_01ec64.pth'
       if artifact.stat().st_size != MODEL_BYTES:
           raise RuntimeError('checkpoint_size_mismatch')
       # Publisher gives opaque multipart ETag, not a full body hash. Reader must
       # retrieve the exact HTTPS S3 version and verify saved response headers first.
       # Record the downloaded body hash for their own audit, without inventing
       # publisher checksum equivalence or untrusted-pickle safety from a file size.
       model = sam_model_registry['vit_b'](checkpoint=None)
       state = torch.load(artifact, map_location='cpu', weights_only=True)
       model.load_state_dict(state, strict=True)
       model = model.float().cpu().eval()
       predictor = SamPredictor(model)
       # Original author geometry; no third-party input or mutable remote URL.
       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')
   
       def encode():
           # Set fresh predictor state for each fixed-image request; no video state shared.
           try:
               with torch.inference_mode():
                   predictor.set_image(np.asarray(image), image_format='RGB')
                   if list(predictor.get_image_embedding().shape) != [1, 256, 64, 64]:
                       raise RuntimeError('coarse_embedding_shape')
                   masks, scores, low = predictor.predict(
                       point_coords=np.array([[64, 112]], dtype=np.float32),
                       point_labels=np.array([1], dtype=np.int32),
                       multimask_output=False, return_logits=False)
                   if list(masks.shape) != [1, 224, 224] or list(scores.shape) != [1]:
                       raise RuntimeError('output_shape')
                   if list(low.shape) != [1, 256, 256] or not np.isfinite(low).all():
                       raise RuntimeError('low_logit_shape_or_finiteness')
                   return masks[0].astype(bool).tolist(), float(scores[0]), list(low.shape)
           finally:
               predictor.reset_image()
       return encode
   
   
   PYSERVER

   Expected result: Wrapper syntax and bytes verify without model loading.

3. 3. Complete and verify the private protocol

   Append the bounded fixed-input authenticated transport; no model code runs in this syntax check.

   CommandCopy command

   set -e
   cd "$HOME/sam1-image"
   cat >> sam1_image.py <<'PYSERVER'
   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_coarse_vision_positions': 4096,
                                       'generated_text_tokens': None})
   
           def do_POST(self):
               if not self.authorized():
                   return self.reply(401, {'error': 'unauthorized'})
               if self.path != '/v1/point-segment':
                   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_mask(encoder())
               except Exception:
                   return self.reply(500, {'error': 'predictor_or_mask_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 sam1_image.py
   sha256sum --check <<'SHA256'
   557af327a6c1c6a456ca30fb6627a6bdde9d7b856fea7bc032cc76984610b95b  sam1_image.py
   SHA256

   Expected result: Both exact code fragments form the source-bound wrapper; syntax and hash pass.

Start the model

1. 1. Start native CPU point segmentation

   Run from the dedicated workspace, outside the source checkout. The reader loader selects CPU float32, eval and inference_mode; predictor state resets after every request. Four threads are explicit, while full process fit/performance remain unknown.

   CommandCopy command

   set -e
   cd "$HOME/sam1-image"
   .venv/bin/python sam1_image.py

   Expected result: After actual reader-side model loading, service binds 127.0.0.1:8994. Stop on load or shape errors; no successful model execution has been claimed.

Verify the setup

1. 1. Validate mask shape and inspect spatial quality

   From a second terminal on the server, request the fixed geometry and inspect the resulting mask overlay. Validate exact shapes, finite estimated IoU and RLE bounds. The expected mask is only an image-dependent spatial result; no exact area, score or full-object boundary is promised. Missing authentication must return 401.

   CommandCopy command

   set -e
   cd "$HOME/sam1-image"
   SAM_KEY="$(cat .api-key)"
   curl --fail http://127.0.0.1:8994/health -H "Authorization: Bearer $SAM_KEY"
   curl --fail http://127.0.0.1:8994/v1/point-segment -H "Authorization: Bearer $SAM_KEY" -H 'Content-Type: application/json' -d '{"fixture":"author-geometry-v1"}' -o mask.json
   curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8994/health
   unset SAM_KEY
   .venv/bin/python - <<'PYVERIFY'
   import json,math
   from PIL import Image
   d=json.load(open('mask.json'))
   assert d['configured_coarse_vision_positions']==4096 and d['generated_text_tokens'] is None
   assert d['mask_shape']==[1,224,224] and d['low_resolution_logits_shape']==[1,256,256]
   assert math.isfinite(d['estimated_iou'])
   pixels=[0]*(224*224);previous=0
   for start,length in d['mask_true_runs']:
    assert type(start) is int and type(length) is int and start>=previous and length>0 and start+length<=len(pixels)
    pixels[start:start+length]=[255]*length;previous=start+length
   assert sum(x>0 for x in pixels)==d['mask_area_pixels']
   mask=Image.new('L',(224,224));mask.putdata(pixels);mask.save('mask.png')
   image=Image.open('fixture.png').convert('RGB');tint=Image.new('RGB',image.size,(0,255,0))
   image.paste(Image.blend(image,tint,0.4),(0,0),mask);image.save('overlay.png')
   print('Inspect overlay.png and clicked point [64,112]; no exact mask quality promised.')
   PYVERIFY

   Expected result: Authenticated health and fixed segmentation return structured JSON; unauthenticated health 401. After real execution, inspect overlay.png against the red rectangle and point. A finite but inaccurate mask is not a successful quality result.

Performance evidence

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

Limits and troubleshooting

• The original SAM1 ViT-B native registry, predictor and exact publisher object version are selected. ViT-L, ViT-H, automatic mask generation, batched images, box/multiple-point refinements, ONNX and other backends remain separately useful open scopes; this pair does not complete family coverage.
• 4,096 means the configured 64 × 64 spatial encoder positions for this fixed input. Local window padding, sparse prompt embeddings, learned mask/IoU tokens and decoder features are distinct. This is not text context, a global native maximum or a point-count cap.
• The publisher provides exact 375,042,383-byte metadata, S3 version and opaque multipart ETag. No authoritative native checkpoint body SHA was found; no weights were downloaded. Size/headers do not cryptographically verify a local body. Reader records a local body hash and trusts the pinned official HTTPS retrieval, not arbitrary files.
• Explicit safe state-dictionary loading with strict=True is reader-authored. It avoids reliance on changing torch.load defaults; weights_only=True reduces pickle exposure but does not certify untrusted artifacts. Native architecture remains unchanged; real loading/compatibility is unexecuted.
• CPU float32, 32 GiB RAM, 40 GiB disk and four threads are selected allocations. No measured peak, speed, latency, fit or mask quality is transferred from another model, GPU or checkpoint.
• The single positive point selects a mask; masks have no semantic class label and estimated IoU is not guaranteed ground-truth accuracy. Synthetic geometry is a bounded transport/spatial smoke experiment, not a segmentation benchmark.
• Private serial HTTPServer has bounded input, private key, loopback and socket timeout, but no inference deadline or production/multiuser service guarantee. No arbitrary uploads, points, paths or URLs are accepted.
• No text tokenizer, autoregressive K/V cache, reasoning template or generation sampler applies. Native encoder image state is reset for each request. Output tokens are N/A.
• Exact native eager imports include the automatic-mask module and torchvision NMS; optional OpenCV cleanup is a lazy import in an uncalled helper. No required dependency is removed. Package resolution is documented but uninstalled; mock tests exercise only protocol/security, not native model compatibility.

Checkpoint metadata or state-dictionary mismatch

Stop on version, ETag, size, safe-loader or strict-key errors. Restore the exact native object/source. Do not substitute Transformers-converted weights, relax strict=True or set weights_only=False to force a result.

Missing torchvision NMS or import error

Use the exact matching torch and torchvision CPU wheels and run pip check. The native top-level eager path imports automatic-mask helpers even though this recipe calls only the image predictor. Do not strip publisher imports or assume CUDA-only wheels work on this CPU host.

401 or rejected body

Use the preserved private 64-character lowercase-hex key and the exact fixed fixture object. Unknown fields, changed points, uploads, paths and URLs are rejected.

Empty, inaccurate or slow mask

Inspect fixture.png, point [64,112], native resize and overlay.png. Record actual model defects, memory errors or latency. No exact score, area, speed or full-object mask is guaranteed.

Stop the model

1. 1. Stop the research endpoint

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

   CommandCopy command

   unset SAM_KEY

   Expected result: Native process and endpoint stop; no active session state remains.

Uninstall

1. 1. Remove dedicated experiment files

   Preserve desired masks, environment and licensing/audit records first. Confirm this dedicated directory before deletion; shared Ubuntu packages remain.

   CommandCopy command

   rm -r -- "$HOME/sam1-image"

   Expected result: Dedicated checkpoint, native checkout, virtualenv, fixture/mask/overlay, wrapper and key are removed.

Exact model and requirements

Artifact:

Meta / facebookresearch / Original Segment Anything SAM ViT-B checkpoint · checkpoint sam_vit_b_01ec64.pth

Publisher revision:

Mr6xCf5BiIKu1NZw1QSZGz_F0TN9.TFi

Artifact digest:

Publisher HEAD exposes opaque multipart ETag dd6e14655a594ad8d2c1f256ccf6076e-45, not a full MD5 or SHA256. No weight body was downloaded or authoritative full body digest found.

Download size:

0.35 GiB

Memory requirement (unknown):

Unknown — No measured full-process peak for this exact CPU float32 model, image activation/decoder state and dependencies.

System RAM / disk:

Unknown / Unknown

Placement:

single device. One CPU host, one sequence and no tensor/pipeline sharding. Whole model and image/prompt handling on CPU; no device or disk offload.

KV cache:

Image segmentation has no autoregressive text K/V cache. Native image predictor state resets after each fixed request.

Workload:

4,096 token context; 4,096 input tokens; Not applicable; concurrency 1; batch 1; cache cold; repetitions Unknown.

Tokenizer:

Native image encoder 1024-pixel padded square, patch size 16, grid 64 × 64; no text tokenizer · dca509fe793f601edb92606367a655c15ac00fdf

Sampling / reasoning:

No generation sampler. Exactly one original 224 × 224 RGB fixture, one positive XY point [64,112] with label 1, multimask_output=False and return_logits=False. Native ResizeLongestSide uses PIL bilinear resizing; native normalization precedes padding to the 1024 square. This square fixture has no nonzero padding region. 4,096 is the configured single-image spatial embedding count. Local 14 × 14 attention windows may pad their partitioned grid; global attention uses the 64 × 64 grid. Prompt embeddings, learned mask/IoU tokens and upsampled decoder features are separate. No native global token maximum, text context allowance or point-count maximum is inferred.

Runtime prerequisites:

Ubuntu 24.04 x86_64; See prerequisites above.

Official artifact · License

Upstream README explicitly licenses the model under Apache License 2.0; the actual license is archived. Retain applicable license, copyright and NOTICE material; follow change-notice and patent conditions. This guide grants no trademark endorsement or legal clearance. The image fixture is original author geometry; no upstream demonstration media or datasets are included.

• 375,042,383 bytes is exact official HEAD Content-Length for the selected object version, not runtime RAM or an independently verified body hash.
• 32 GiB RAM, 40 GiB disk and four threads are chosen planning allocations; activation, decoder, packages and OS overhead remain unmeasured.

Install the runtime

1. 1. Create the pinned native CPU environment

   Native README requires Python>=3.8, torch>=1.7 and torchvision>=0.8 and recommends CUDA. This separately documented CPU configuration selects matching official CPU wheels. Native setup declares no dependencies; install the complete eager Python path explicitly. Optional automatic-mask region cleanup imports OpenCV only when invoked and is not used here. No all-extra, training, export or web demo package is selected.

   CommandCopy command

   set -e
   sudo apt-get update
   sudo apt-get install -y python3.12 python3.12-venv git curl ca-certificates openssl
   mkdir -p "$HOME/sam1-image/models"
   cd "$HOME/sam1-image"
   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==2.2.3' 'Pillow==11.1.0'
   git clone https://github.com/facebookresearch/segment-anything.git native-sam1
   git -C native-sam1 checkout --detach dca509fe793f601edb92606367a655c15ac00fdf
   .venv/bin/python -m pip install -e ./native-sam1
   .venv/bin/python -m pip check
   .venv/bin/python -m pip freeze > resolved-environment.txt

   Expected result: Pinned checkout and CPU wheels resolve, pip check passes and environment resolution is saved. No executed compatibility, speed or fit claim.

Download the model

1. 1. Retrieve and check the exact publisher object version

   Reader-only weight retrieval. Pin the actual S3 version and verify version header, opaque multipart ETag and exact size. The ETag is not a full-body MD5/SHA; record a local body SHA for your own audit without claiming it matches a publisher digest. Stop on any mismatch. Use only this trusted official HTTPS object; safe tensor loading is defense in depth, not general untrusted-file clearance.

   CommandCopy command

   set -e
   cd "$HOME/sam1-image"
   curl --fail --location --dump-header checkpoint-headers.txt --output models/sam_vit_b_01ec64.pth 'https://dl.fbaipublicfiles.com/segment_anything/sam_vit_b_01ec64.pth?versionId=Mr6xCf5BiIKu1NZw1QSZGz_F0TN9.TFi'
   .venv/bin/python - <<'PYARTIFACT'
   import pathlib
   lines=pathlib.Path('checkpoint-headers.txt').read_text().splitlines()
   headers={k.strip().lower():v.strip() for line in lines if ':' in line for k,v in [line.split(':',1)]}
   assert headers['x-amz-version-id']=='Mr6xCf5BiIKu1NZw1QSZGz_F0TN9.TFi'
   assert headers['etag'].strip('"')=='dd6e14655a594ad8d2c1f256ccf6076e-45'
   assert pathlib.Path('models/sam_vit_b_01ec64.pth').stat().st_size==375042383
   PYARTIFACT
   sha256sum models/sam_vit_b_01ec64.pth > reader-downloaded-body.sha256
   sha256sum --check <<'SHASOURCE'
   c71d239df91726fc519c6eb72d318ec65820627232b2f796219e87dcf35d0ab4  native-sam1/LICENSE
   77bc4faf728118625ddd184dc4e6375bd1b5c636fc66fb429f9fc5276f331cc5  native-sam1/segment_anything/build_sam.py
   SHASOURCE

   Expected result: Official object version, opaque ETag, size and exact native source hashes match. Local body SHA is recorded; authoritative full-body digest remains unknown.

Configure

1. 1. Create a stable private service key

   Generate only when absent; preserve existing access. Do not print or share this local service key.

   CommandCopy command

   set -e
   cd "$HOME/sam1-image"
   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: Private existing key is preserved; server requires 64 lowercase hexadecimal characters.

2. 2. Create the fixed point-prompt harness

   Reader-authored serial loopback HTTPServer, not publisher deployment software. It instantiates the exact native vit_b registry architecture with checkpoint set to None, then uses torch.load with tensor-only loading on CPU: weights_only is True and map_location is cpu. State loading uses strict=True. This replaces the native builder’s implicit torch.load default without altering model architecture or checkpoint keys. A missing, unsafe or incompatible state dictionary stops loading.

   CommandCopy command

   set -e
   cd "$HOME/sam1-image"
   cat > sam1_image.py <<'PYSERVER'
   """Reader-authored educational fixed-input SAM1 ViT-B 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_BYTES = 375042383
   
   
   def validate_mask(result):
       mask, score, low_shape = result
       if type(score) not in (int, float) or not math.isfinite(score):
           raise ValueError('invalid_score')
       if low_shape != [1, 256, 256] or len(mask) != 224:
           raise ValueError('invalid_shape')
       flat = []
       for row in mask:
           if len(row) != 224 or any(type(v) is not bool for v in row):
               raise ValueError('invalid_mask')
           flat.extend(row)
       runs = []
       i = 0
       while i < len(flat):
           if not flat[i]:
               i += 1
               continue
           start = i
           while i < len(flat) and flat[i]:
               i += 1
           runs.append([start, i-start])
       return {'fixture': 'author-geometry-v1', 'image_shape': [224, 224, 3],
               'transformed_shape': [1, 3, 1024, 1024],
               'coarse_embedding_shape': [1, 256, 64, 64],
               'configured_coarse_vision_positions': 4096,
               'point_xy': [64, 112], 'point_label': 1,
               'mask_shape': [1, 224, 224], 'mask_true_runs': runs,
               'mask_area_pixels': sum(flat), 'estimated_iou': score,
               'low_resolution_logits_shape': low_shape,
               'generated_text_tokens': None, 'semantic_classification': False}
   
   
   def make_encoder():
       # Actual model imports occur only in the reader-run path, not fake boundary tests.
       import numpy as np
       import torch
       from PIL import Image, ImageDraw
       from segment_anything import sam_model_registry, SamPredictor
       torch.set_num_threads(4)
       artifact = ROOT / 'models/sam_vit_b_01ec64.pth'
       if artifact.stat().st_size != MODEL_BYTES:
           raise RuntimeError('checkpoint_size_mismatch')
       # Publisher gives opaque multipart ETag, not a full body hash. Reader must
       # retrieve the exact HTTPS S3 version and verify saved response headers first.
       # Record the downloaded body hash for their own audit, without inventing
       # publisher checksum equivalence or untrusted-pickle safety from a file size.
       model = sam_model_registry['vit_b'](checkpoint=None)
       state = torch.load(artifact, map_location='cpu', weights_only=True)
       model.load_state_dict(state, strict=True)
       model = model.float().cpu().eval()
       predictor = SamPredictor(model)
       # Original author geometry; no third-party input or mutable remote URL.
       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')
   
       def encode():
           # Set fresh predictor state for each fixed-image request; no video state shared.
           try:
               with torch.inference_mode():
                   predictor.set_image(np.asarray(image), image_format='RGB')
                   if list(predictor.get_image_embedding().shape) != [1, 256, 64, 64]:
                       raise RuntimeError('coarse_embedding_shape')
                   masks, scores, low = predictor.predict(
                       point_coords=np.array([[64, 112]], dtype=np.float32),
                       point_labels=np.array([1], dtype=np.int32),
                       multimask_output=False, return_logits=False)
                   if list(masks.shape) != [1, 224, 224] or list(scores.shape) != [1]:
                       raise RuntimeError('output_shape')
                   if list(low.shape) != [1, 256, 256] or not np.isfinite(low).all():
                       raise RuntimeError('low_logit_shape_or_finiteness')
                   return masks[0].astype(bool).tolist(), float(scores[0]), list(low.shape)
           finally:
               predictor.reset_image()
       return encode
   
   
   PYSERVER

   Expected result: Wrapper syntax and bytes verify without model loading.

3. 3. Complete and verify the private protocol

   Append the bounded fixed-input authenticated transport; no model code runs in this syntax check.

   CommandCopy command

   set -e
   cd "$HOME/sam1-image"
   cat >> sam1_image.py <<'PYSERVER'
   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_coarse_vision_positions': 4096,
                                       'generated_text_tokens': None})
   
           def do_POST(self):
               if not self.authorized():
                   return self.reply(401, {'error': 'unauthorized'})
               if self.path != '/v1/point-segment':
                   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_mask(encoder())
               except Exception:
                   return self.reply(500, {'error': 'predictor_or_mask_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 sam1_image.py
   sha256sum --check <<'SHA256'
   557af327a6c1c6a456ca30fb6627a6bdde9d7b856fea7bc032cc76984610b95b  sam1_image.py
   SHA256

   Expected result: Both exact code fragments form the source-bound wrapper; syntax and hash pass.

Start the model

1. 1. Start native CPU point segmentation

   Run from the dedicated workspace, outside the source checkout. The reader loader selects CPU float32, eval and inference_mode; predictor state resets after every request. Four threads are explicit, while full process fit/performance remain unknown.

   CommandCopy command

   set -e
   cd "$HOME/sam1-image"
   .venv/bin/python sam1_image.py

   Expected result: After actual reader-side model loading, service binds 127.0.0.1:8994. Stop on load or shape errors; no successful model execution has been claimed.

Verify the setup

1. 1. Validate mask shape and inspect spatial quality

   From a second terminal on the server, request the fixed geometry and inspect the resulting mask overlay. Validate exact shapes, finite estimated IoU and RLE bounds. The expected mask is only an image-dependent spatial result; no exact area, score or full-object boundary is promised. Missing authentication must return 401.

   CommandCopy command

   set -e
   cd "$HOME/sam1-image"
   SAM_KEY="$(cat .api-key)"
   curl --fail http://127.0.0.1:8994/health -H "Authorization: Bearer $SAM_KEY"
   curl --fail http://127.0.0.1:8994/v1/point-segment -H "Authorization: Bearer $SAM_KEY" -H 'Content-Type: application/json' -d '{"fixture":"author-geometry-v1"}' -o mask.json
   curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8994/health
   unset SAM_KEY
   .venv/bin/python - <<'PYVERIFY'
   import json,math
   from PIL import Image
   d=json.load(open('mask.json'))
   assert d['configured_coarse_vision_positions']==4096 and d['generated_text_tokens'] is None
   assert d['mask_shape']==[1,224,224] and d['low_resolution_logits_shape']==[1,256,256]
   assert math.isfinite(d['estimated_iou'])
   pixels=[0]*(224*224);previous=0
   for start,length in d['mask_true_runs']:
    assert type(start) is int and type(length) is int and start>=previous and length>0 and start+length<=len(pixels)
    pixels[start:start+length]=[255]*length;previous=start+length
   assert sum(x>0 for x in pixels)==d['mask_area_pixels']
   mask=Image.new('L',(224,224));mask.putdata(pixels);mask.save('mask.png')
   image=Image.open('fixture.png').convert('RGB');tint=Image.new('RGB',image.size,(0,255,0))
   image.paste(Image.blend(image,tint,0.4),(0,0),mask);image.save('overlay.png')
   print('Inspect overlay.png and clicked point [64,112]; no exact mask quality promised.')
   PYVERIFY

   Expected result: Authenticated health and fixed segmentation return structured JSON; unauthenticated health 401. After real execution, inspect overlay.png against the red rectangle and point. A finite but inaccurate mask is not a successful quality result.

Performance evidence

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

Limits and troubleshooting

• The original SAM1 ViT-B native registry, predictor and exact publisher object version are selected. ViT-L, ViT-H, automatic mask generation, batched images, box/multiple-point refinements, ONNX and other backends remain separately useful open scopes; this pair does not complete family coverage.
• 4,096 means the configured 64 × 64 spatial encoder positions for this fixed input. Local window padding, sparse prompt embeddings, learned mask/IoU tokens and decoder features are distinct. This is not text context, a global native maximum or a point-count cap.
• The publisher provides exact 375,042,383-byte metadata, S3 version and opaque multipart ETag. No authoritative native checkpoint body SHA was found; no weights were downloaded. Size/headers do not cryptographically verify a local body. Reader records a local body hash and trusts the pinned official HTTPS retrieval, not arbitrary files.
• Explicit safe state-dictionary loading with strict=True is reader-authored. It avoids reliance on changing torch.load defaults; weights_only=True reduces pickle exposure but does not certify untrusted artifacts. Native architecture remains unchanged; real loading/compatibility is unexecuted.
• CPU float32, 32 GiB RAM, 40 GiB disk and four threads are selected allocations. No measured peak, speed, latency, fit or mask quality is transferred from another model, GPU or checkpoint.
• The single positive point selects a mask; masks have no semantic class label and estimated IoU is not guaranteed ground-truth accuracy. Synthetic geometry is a bounded transport/spatial smoke experiment, not a segmentation benchmark.
• Private serial HTTPServer has bounded input, private key, loopback and socket timeout, but no inference deadline or production/multiuser service guarantee. No arbitrary uploads, points, paths or URLs are accepted.
• No text tokenizer, autoregressive K/V cache, reasoning template or generation sampler applies. Native encoder image state is reset for each request. Output tokens are N/A.
• Exact native eager imports include the automatic-mask module and torchvision NMS; optional OpenCV cleanup is a lazy import in an uncalled helper. No required dependency is removed. Package resolution is documented but uninstalled; mock tests exercise only protocol/security, not native model compatibility.

Checkpoint metadata or state-dictionary mismatch

Stop on version, ETag, size, safe-loader or strict-key errors. Restore the exact native object/source. Do not substitute Transformers-converted weights, relax strict=True or set weights_only=False to force a result.

Missing torchvision NMS or import error

Use the exact matching torch and torchvision CPU wheels and run pip check. The native top-level eager path imports automatic-mask helpers even though this recipe calls only the image predictor. Do not strip publisher imports or assume CUDA-only wheels work on this CPU host.

401 or rejected body

Use the preserved private 64-character lowercase-hex key and the exact fixed fixture object. Unknown fields, changed points, uploads, paths and URLs are rejected.

Empty, inaccurate or slow mask

Inspect fixture.png, point [64,112], native resize and overlay.png. Record actual model defects, memory errors or latency. No exact score, area, speed or full-object mask is guaranteed.

Stop the model

1. 1. Stop the research endpoint

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

   CommandCopy command

   unset SAM_KEY

   Expected result: Native process and endpoint stop; no active session state remains.

Uninstall

1. 1. Remove dedicated experiment files

   Preserve desired masks, environment and licensing/audit records first. Confirm this dedicated directory before deletion; shared Ubuntu packages remain.

   CommandCopy command

   rm -r -- "$HOME/sam1-image"

   Expected result: Dedicated checkpoint, native checkout, virtualenv, fixture/mask/overlay, wrapper and key are 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.