Skip to content

siglip2-toolkit

Local-first toolkit around Google's SigLIP 2 models: text and image embeddings, zero-shot and fine-tuned classification, incremental corpus export, and retrieval math.

Get started Quickstart

PyPI Python License: MIT

What it is

  • A library around SigLIP 2 that produces L2-normalised float32 embeddings for text and images.
  • A CLI (siglip2) for embedding, exporting a corpus, inspecting exports, classification and model-cache management.
  • An optional REST server (FastAPI) with the same behaviour as the library.
  • A set of retrieval primitives: similarity ranking, RRF fusion, similarity-drop filtering and serialisable metadata filters.
  • A portable, versioned export format (JSONL or pickle) with an embedding-space manifest.

What it is not

  • It is not a vector database: it does not store or index vectors for you. It produces embeddings and portable exports; use any store you like.
  • It does not download images or run a web UI.
  • It only uses the network for siglip2 models download (and, for the optional server, nothing beyond serving local requests).

Highlights

  • Own model cache, independent from HuggingFace's cache.
  • Three interfaces over one implementation: library, CLI, REST.
  • Incremental exports with resumable runs.
  • Embedding-space guard: exports from different models are never mixed.
  • CPU, CUDA and Apple MPS support (device: auto).
  • Portable exports with ids, vectors, metadata and an optional embedding-space manifest.
  • MIT licensed, co-developed by GIA-UH and Syalia S.R.L.

Install in one line

pip install "siglip2-toolkit[server]"

or with uv:

uv add "siglip2-toolkit[server]"

See Installation for source checkouts, CPU-only torch and offline installs.

30-second example

siglip2 models download google/siglip2-base-patch16-naflex
siglip2 models use google/siglip2-base-patch16-naflex

from siglip2_toolkit import Embedder, models

resolved = models.resolve_model("google/siglip2-base-patch16-naflex")
embedder = Embedder(
    model=resolved.path,
    model_id=resolved.identifier,
    device="auto",
)
vectors = embedder.embed_texts([
    "a wedding at sunset",
    "a dog on the beach",
])
print(vectors.shape)  # (2, dimensions)

Documentation map

If you want to… Read
Go from zero to search Tutorial
Run the examples Examples
Install it, including offline Installation
Embed, export, inspect and classify in minutes Quickstart
Manage models and the cache Models
Use the Python API in depth Library guide
Use the command line CLI
Call the REST service REST API
Understand the export file Export format
Copy a recipe (search, RRF, filters) Recipes
Fix a problem Troubleshooting · FAQ · Glossary
Contribute or build docs Development

Status

This is the 0.0.x preview. The public API and the export format may still change before 1.0; pin the version you depend on (siglip2-toolkit==0.0.3). See the changelog.

License

MIT — see LICENSE.