Seclai

Seclai

Sign inStart for free

Embedding Models

View as Markdown

Embedding Models

What are Embeddings?

Content in your knowledge bases is automatically converted into vector embeddings - numerical representations that capture semantic meaning. When you search, your query is also embedded, and similar content is found by comparing vector distances using cosine similarity.

Supported Models

Seclai supports embedding models from OpenAI, Google Vertex AI, and AWS Bedrock — with configurable dimensions, multilingual options, and multimodal support. See the Models page for the full, up-to-date catalog with dimensions, credits, and language support.

Choosing a Model

When selecting an embedding model, consider:

  • Dimensions: Higher dimensions can capture more nuance but increase storage and compute costs
  • Language support: Some models like multilingual-embedding-002 are optimized for multiple languages
  • Input modalities: Only some embedders can index images, audio or video — and the same choice decides whether a knowledge base can be searched with a file rather than a sentence. See Indexing images and video below
  • Provider: Choose based on your existing cloud infrastructure and API preferences
  • Performance: Different models have different speed vs. quality tradeoffs

Discovering Models Programmatically

The catalog is available over the API, so you never have to hard-code a model name. Every entry reports the model_type to pass as embedding_model when creating a source, the dimensions it supports, its credit rate, and — the field that decides whether it can index anything but text — supported_input_media.

  • API-key REST: GET /models/embedders. Add ?supports_input_media=image to list only embedders that can index images.
  • MCP: the list_embedding_models tool, with the same optional supports_input_media filter.

Both surfaces also return default_model_type and default_dimension — what a source uses when you omit embedding_model — plus storage and file-processing credit rates. An embedder with no published credit rate is omitted from both, so everything listed can actually be used.

Each entry's dimensions lists the sizes that embedder supports. Sending a dimensions value that is not in that list produces a source that cannot be indexed, so clients on API version 2026-08-21 or later have such a request rejected with the allowed values; older clients keep the previous behaviour until they opt in. Rerankers have a matching catalog — GET /models/rerankers and the list_reranker_models MCP tool — carrying each reranker's credits_per_action and which one is the default.

Indexing Images and Video

A source's media_types setting asks Seclai to embed images or video from your content as multi-modal chunks — but only the kinds the source's embedder can index are honored. Unsupported kinds are dropped when the source is saved, leaving an embedder_warning and a source that accepts image uploads without indexing anything useful from them.

Check supported_input_media before you choose. A text-only embedder reports it as null; a multi-modal one lists the kinds it accepts, for example ["text", "image"]. To index a knowledge base of images, list the image-capable embedders first and create the source with one of them:

curl -H "X-API-Key: $SECLAI_API_KEY" \
  "https://api.seclai.com/models/embedders?supports_input_media=image"

Changing the embedder on an existing source means re-indexing its content — see Migrating Existing Custom Index Sources.

The same capability decides what you can search with

supported_input_media governs both halves of a multi-modal knowledge base: which media get indexed, and which media can be used as a query. On a capable embedder, an agent's retrieval step can take an uploaded file as the query itself — send a phone photo and get back the page it matches — because the file and the indexed chunks are embedded by the same model into the same vector space.

The kinds a model declares are the kinds it can be searched with. Today Amazon Nova 2 Multimodal declares ["text", "image", "video", "audio", "pdf"] and Cohere Embed v4 declares ["text", "image"]; query the endpoint above rather than trusting that list to stay current.

A query whose type the embedder does not declare is not embedded as media. Retrieval falls back to the file's extracted text — a PDF's text layer, an audio or video transcript — and says so in the run's trace; a raw photo, which has no text counterpart, fails the step with a message naming the embedder instead. So an image-only embedder answers photo queries and not voice-memo queries, and the failure is visible either way rather than silently returning poor matches.

Configurable Dimensions

Many models support multiple dimension sizes. Lower dimensions reduce:

  • Storage costs
  • Query latency
  • Indexing time

While potentially trading off some semantic precision.

Migrating Existing Custom Index Sources

If you already have a custom index source and want to move it to a different embedding model or dimensions, use embedding migration.

Migration creates and indexes a shadow source, tracks progress, then switches the source connection when indexing completes. Once it does, the old index is released automatically — your storage does not stay at double size after a migration, and there is nothing to clean up by hand.

Your source stays usable throughout, and content that arrives while a migration runs is migrated too: the migration keeps catching up until nothing is left uncopied before it switches over. A source ingesting faster than the migration can copy is the one case this cannot resolve — the migration fails rather than switch over and leave that content behind, and retrying while the source is quieter (or pausing its polling for the duration) is the fix.

Channel support:

  • UI: Open a source, go to the Embeddings tab, start migration, and monitor progress.
  • User-authenticated REST: POST /sources/{source_connection_id}/embedding-migration, then poll GET /sources/{source_connection_id}/embedding-migration. Cancel with POST /sources/{source_connection_id}/embedding-migration/cancel.
  • API-key REST (/api/*): POST /api/sources/{source_connection_id}/embedding-migration, then poll GET /api/sources/{source_connection_id}/embedding-migration. Cancel with POST /api/sources/{source_connection_id}/embedding-migration/cancel.
  • MCP: Use the start_source_embedding_migration, get_source_embedding_migration and cancel_source_embedding_migration tools.

Migration is supported for custom_index sources and enforces model/dimension compatibility.

If a Migration Fails or Is Cancelled

Your source is never left in a half-migrated state. The switch-over is the very last step, so until it happens the source connection keeps serving its existing index — searches and agents are unaffected throughout, and a failed or cancelled migration leaves them exactly as they were.

The partially-built shadow index is discarded automatically. There is nothing to clean up and nothing to delete by hand, and you are not charged storage for it. Reclamation runs in the background and normally finishes within minutes. A very large index — hundreds of thousands of items — is cleared in stages and can take more than a day to finish, but it needs no attention from you while it does.

One timing note: a migration that has reached its final switch-over step can no longer be cancelled — that step either completes or does not, so there is no half-applied state to back out of. Cancel returns an error in that case, and the migration finishes normally.

Two things are worth knowing before you retry:

  • Starting again begins from scratch. A new migration re-copies and re-embeds every item. (A migration that is merely interrupted — a transient infrastructure problem mid-copy — picks up where it left off on its own; that is not something you need to restart.)
  • Work already done is still billed. Items embedded before the failure consumed credits, and cancelling does not refund them. Cancel early if you started a migration by mistake.

Check status and failure_message on the migration response to see why a migration ended. If it failed for a transient reason (for example a temporary indexing problem), simply starting it again is the right next step.

Reranking

After the initial similarity search using embeddings, you can optionally apply a reranking model to improve the relevance and quality of results. Reranking re-evaluates the retrieved content and reorders it based on deeper semantic understanding of the query.

How Reranking Works

The retrieval pipeline works in two stages:

  1. Initial Retrieval - Vector similarity search finds potentially relevant content quickly using cosine similarity
  2. Reranking (Optional) - A specialized model re-scores the top results for better relevance

Reranking models are more computationally expensive than embedding similarity, so they're applied only to the top candidates from the initial search.

Supported Reranking Models

Browse the current list on the Models page, or read it programmatically — GET /models/rerankers (API-key REST) and the list_reranker_models MCP tool return each reranker's model_type, its credits_per_action, and which one is the default when you omit reranker_model.

To turn reranking off, send "none" (or an empty string) as reranker_model rather than a value from that list.

When to Use Reranking

Consider enabling reranking when:

  • Precision is critical - You need the most relevant results at the top
  • Semantic nuance matters - Your queries require deep understanding of context
  • Large knowledge bases - More content means initial similarity may miss subtle relevance

Reranking is optional and can be configured per knowledge base. If not enabled, results are ranked solely by embedding similarity scores.