Skip to content
Beef Docs

Round Models

Round Service Models

Section titled “Round Service Models”

Round model binaries are not checked into the repository. They are downloaded during Docker builds or at runtime through EnsureModelFile, which treats missing files, tiny files, and Git LFS pointer stubs as invalid and downloads the canonical artifact.

Model Cache

Section titled “Model Cache”

Round reads models from MODEL_CACHE_DIR, which defaults to /opt/models in the service. Mount persistent storage there when runtime downloads need to survive container restarts.

Docker downloads RetinaFace and LVFace into /opt/models/. Text embedding artifacts are downloaded on first use unless override URLs are configured.

Models

Section titled “Models”

RetinaFace (Face Detection)

Section titled “RetinaFace (Face Detection)”
  • Path: retinaface/retinaface_mv1_0.25.onnx
  • Source: https://round-models.sexty.dev/retinaface/retinaface_mv1_0.25.onnx
  • Override: ROUND_RETINAFACE_URL
  • Architecture: RetinaFace MobileNet V1 0.25
  • Input: 640x480x3 (HxWxC), BGR format
  • Output: Bounding boxes, confidence scores, and landmarks
  • Preprocessing: Mean subtraction [104, 117, 123]

LVFace-B_Glint360K (Face Embeddings)

Section titled “LVFace-B_Glint360K (Face Embeddings)”
  • Path: lvface/LVFace-B_Glint360K.onnx
  • Source: https://round-models.sexty.dev/lvface/LVFace-B_Glint360K.onnx
  • Override: ROUND_LVFACE_URL
  • Input: 112x112 aligned face image produced after RetinaFace detection
  • Output: 512-dimensional face embedding

BAAI/bge-small-en-v1.5 (Text Embeddings)

Section titled “BAAI/bge-small-en-v1.5 (Text Embeddings)”
  • Path: bge-small-en-v1.5/model.onnx and bge-small-en-v1.5/tokenizer.json
  • Source: HuggingFace BAAI/bge-small-en-v1.5
  • Revision: 5c38ec7c405ec4b44b94cc5a9bb96e735b38267a
  • Model SHA-256: 828e1496d7fabb79cfa4dcd84fa38625c0d3d21da474a00f08db0f559940cf35
  • Tokenizer SHA-256: d241a60d5e8f04cc1b2b3e9ef7a4921b27bf526d9f6050ab90f9267a1f9e5c66
  • Overrides: ROUND_EMBEDDINGS_MODEL_URL, ROUND_EMBEDDINGS_TOKENIZER_URL
  • Input: text, truncated to the model token limit
  • Output: a 384-dimensional L2-normalized embedding
  • Semantic-search option: {"pooling":"cls"} selects the CLS token
  • Semantic-search contract version: 2.0.0
  • Compatibility behavior: requests without a pooling option use legacy mean pooling and report contract 1.0.0

The default and override downloads must match the checked-in SHA-256 values. An override can mirror the pinned artifacts, but it cannot silently replace the model or tokenizer. Change the revision, hashes, and model contract version together when upgrading either artifact.

BGE uses asymmetric retrieval. Callers add Represent this sentence for searching relevant passages: to search queries. They do not add that instruction to stored media-example descriptions. Sirloin’s semantic workers request CLS pooling for stored documents. Search keeps requesting legacy mean pooling until its separate read-cutover flag is enabled. Other callers can omit the option until they migrate both sides of their retrieval contract.

Deployment

Section titled “Deployment”

Model artifacts should be provided by the configured download sources or by a pre-populated MODEL_CACHE_DIR. Do not reintroduce large ONNX binaries into git.

Local Verification

Section titled “Local Verification”
  • cd apps/round && make build
  • cd apps/round && make run-tests
  • cd apps/round && make lint