---

name: search-retrieval description: "Guides CLIP-as-service search flows with CLIPEncoder plus AnnLite indexing, querying, dimensions, sharding, and retrieval troubleshooting." disable-model-invocation: true metadata: disco-role: operating license: NOASSERTION

Search and Retrieval

Use this sub-skill when the user wants CLIP-as-service to index a corpus and search across text/image embeddings, usually with a Jina Flow containing CLIPEncoder followed by AnnLiteIndexer.

Trigger examples

• "Build text-to-image search with CLIP-as-service."
• "Write search_flow.yml for CLIPEncoder + AnnLiteIndexer."
• "What should n_dim be for ViT-L-14?"
• "Why does /search return incomplete results in a sharded Flow?"
• "Use Client.index and Client.search after starting a search server."

Read first

• references/workflows.md for single-node and sharded CLIP Search setup, indexing, querying, and cross-modal examples.
• references/configuration.md for Flow YAML fields, AnnLite parameters, n_dim, workspace, sharding, and polling.
• references/troubleshooting.md for missing AnnLite, endpoint, dimension, workspace, empty result, and sharding failures.
• scripts/search-flow.yml for a self-contained starter template.
• scripts/check_search_config.py for static validation without starting a model or indexer.

Boundary routing

• Use server-runtime to select CLIP model/runtime, install optional backends, tune replicas/protocol/TLS/monitoring, or start the encoder service.
• Use client-api for detailed clip_client.Client input/output behavior, callbacks, async methods, authentication, and connectivity errors.
• Use this sub-skill only for retrieval/index-specific configuration and operation.

Minimal search architecture

A search Flow has two stages:

1. CLIPEncoder converts incoming text/image documents into embeddings.
2. AnnLiteIndexer stores and retrieves vectors with a dimension matching the selected CLIP model.

The client does not call encode() explicitly before indexing; Client.index() sends documents through the Flow and the encoder fills embeddings before the indexer stores them.

Minimal client use after server startup

from clip_client import Client
from docarray import Document

client = Client("grpc://127.0.0.1:61000")
client.index([
    Document(id="caption-1", text="a photo of a red car"),
    Document(id="caption-2", text="a photo of a blue bicycle"),
])

results = client.search(["red vehicle"], limit=2)
for match in results[0].matches:
    print(match.id, match.scores)

Critical decisions

• Set AnnLite n_dim to the chosen CLIP model output dimension. Default ViT-B-32::openai uses 512.
• Keep a stable workspace for persistent indexes. Changing model dimension or incompatible indexer configuration requires rebuilding.
• For sharded indexes, use ANY polling for /index so each document is indexed once; use ALL for /search so queries reach all shards.
• Search flows need the clip-server[search] extra or an environment with AnnLite installed.

Safe validation sequence

python sub-skills/search-retrieval/scripts/check_search_config.py sub-skills/search-retrieval/scripts/search-flow.yml --model-name ViT-B-32::openai

Then start a service only after the user approves model downloads and long-running server processes.