Semantic search

Semantic search lets you find files by describing what you're looking for in natural language, rather than by exact tag names. It works by comparing embedding vectors: a mathematical representation of the "meaning" of a file's content.

How it works

An embedding model converts each file into a vector (a list of numbers that encodes meaning).
Your search query is converted into a vector using the same model.
Files whose vectors are closest to the query vector are returned as results.

tessera supports two modalities:

Modality	Model type	Covers
Vision	Image/vision embedding (e.g. `nomic-embed-vision`)	Images, videos (via sprite sheet), comic archives (cover image)
Text	Text embedding (e.g. `nomic-embed-text`)	Text files, Markdown, EPUBs, ZIP entry listings

Setup

1. Run an embedding server

You need an OpenAI-compatible embedding endpoint. Infinity is recommended:

pip install infinity-emb[all]

# Start a vision + text server
infinity_emb v2 \
  --model-id nomic-ai/nomic-embed-vision-v1.5 \
  --model-id nomic-ai/nomic-embed-text-v1.5 \
  --port 7997

Or use Ollama with a compatible model:

ollama pull nomic-embed-text
ollama serve

2. Configure the endpoints in tessera-web

Open Settings → Embeddings and fill in:

Field	Example value
Text endpoint	`http://localhost:7997`
Text model	`nomic-ai/nomic-embed-text-v1.5`
Vision endpoint	`http://localhost:7997`
Vision model	`nomic-ai/nomic-embed-vision-v1.5`

If your server hosts both models at the same URL, set both endpoints to the same value.

3. Index your files

In Settings → Embeddings, click Index all files. A progress bar shows how many files have been processed. You can cancel and resume at any time — already-indexed files are skipped automatically.

Supported file types:

Type	How it's embedded
Images (jpg, png, webp, …)	Thumbnail sent to vision model
Videos (mp4, mkv, avi, …)	Sprite sheet (contact sheet of frames) sent to vision model
Comic archives (cbz, cbr)	Cover image sent to vision model
Text files (txt, md, rst)	File content (up to 8 KB) sent to text model
EPUBs	Extracted text sent to text model
ZIP archives	Entry listing sent to text model

Using semantic search

In the search bar, type ~ followed by your query. Quote a multi-word semantic phrase when combining it with structured criteria:

~ sunset over the ocean
~ a person playing guitar on stage
~ invoice from 2023
~ technical documentation about networking
~"sunset over the ocean" and type:image
~"invoice from 2023" and dir:Documents/

The semantic term ranks the candidates selected by the rest of the expression. It can therefore be combined with and, but not placed under or, not, or a subject group. A badge appears in the search bar to confirm semantic ranking.

Results are sorted by similarity (most similar first). The score shown is cosine similarity — closer to 1.0 means more similar.

Finding similar files

In the detail panel (right side), click Find similar to search for files visually or textually similar to the file you are viewing. This uses the stored embedding vector rather than a text query.

Tips

A semantic phrase does not implicitly mean tags: ~ jazz piano ranks by similar content. Add an explicit tag criterion when both are required.
For best results with images and videos, use a dedicated vision model (nomic-embed-vision, CLIP variants).
For text documents, use a text model (nomic-embed-text, BGE, E5, etc.).
The quality of results depends heavily on the model. Larger models generally give better results at the cost of speed.
Indexing is one-time — only new or updated files need to be re-indexed.

Tessera