--- title: Embed, compare and rerank description: "Dense vectors, similarity matrices and cross-encoder reranking from the command line and over HTTP: the retrieval building blocks." --- Retrieval systems stand on three operations: turn inputs into dense vectors, compare vectors, and rerank candidates against a query with a model that reads both together. Modelverse's embedding and reranking families provide all three as commands, and the same models serve them over HTTP. ## Compare texts Any text-embedding family provides `similar`: the positional texts embed in one batch, and the payload names the inputs by index and prints their cosine matrix: ```bash clikart-cli Qwen/Qwen3-Embedding-0.6B-GGUF:Q8_0 similar \ "How do I reset my password?" \ "Password reset instructions" \ "Quarterly revenue rose 4 percent" ``` ```text [0] How do I reset my password? [1] Password reset instructions [2] Quarterly revenue rose 4 percent scores (cosine; 1 = identical direction): [0] [1] [2] [0] 1.0000 0.7265 0.2591 [1] 0.7265 1.0000 0.3705 [2] 0.2591 0.3705 1.0000 ``` `--top-k N` switches the rendering to a per-input ranking (the nearest N others per row), the form you want when the list is long; `--json` emits the same result as a document for scripts. ## Compare images, or texts against images A dual-tower family (CLIP, SigLIP) embeds texts and images into one space, so `similar` grows two more forms: with `--image` attachments the matrix is texts against images, and with only images it is images against images: ```bash clikart-cli google/siglip-base-patch16-224 similar \ "a photo of a cat" "a photo of a dog" --image pet1.jpg --image pet2.jpg ``` For the raw vectors, `embed` takes images and prints a summary row per input (vector width, L2 norm, a quantized-vector signature, and each row's cosine against the first), with `--output PREFIX` writing `PREFIX.csv` (one row per image, the full vector as columns) and `PREFIX.json` (run configuration, summary and vectors) for whatever indexes them next: ```bash clikart-cli google/siglip-base-patch16-224 embed catalog/*.jpg --output catalog_vectors ``` ## Rerank documents against a query Embedding similarity is a coarse first pass; a reranker is a cross-encoder that reads the query and each document together and scores actual relevance. The reranking families provide `rerank`, with every document scored through one packed forward: ```bash clikart-cli Qwen/Qwen3-Reranker-0.6B rerank \ "how to reset a password" \ "Password reset instructions" \ "Changing your username" \ "Quarterly revenue rose 4 percent" ``` ```text 0.9231 [0] Password reset instructions 0.4106 [1] Changing your username 0.0312 [2] Quarterly revenue rose 4 percent ``` `--instruction` prepends the task instruction the checkpoint was trained with, when your use differs from the default retrieval phrasing. The everyday pipeline is both stages in order: `similar --top-k` over the corpus to shortlist, `rerank` over the shortlist to decide. ## Over HTTP The same models serve the retrieval routes ([the full route table](serve-openai-compatible.md)): ```bash clikart-cli Qwen/Qwen3-Embedding-0.6B-GGUF:Q8_0 serve --port 8000 ``` ```bash curl -s http://127.0.0.1:8000/v1/embeddings \ -H "Content-Type: application/json" \ -d '{"input": ["How do I reset my password?", "Password reset instructions"]}' ``` `POST /v1/embeddings` answers in the OpenAI shape, so `client.embeddings.create(...)` works against the base URL unchanged; `POST /v1/similarity` returns the cosine matrix directly, saving the round trip through raw vectors when the comparison is all you need. Embedding models are small ([Model requirements](../model-requirements.md) carries the figures), and the GGUF quantization selector on the source works here exactly as in [Run a specific GGUF quantization](run-a-gguf-quantization.md).