Skip to content
Omnio-js
Esc
↑↓navigate↵open⌘Jpreview
On this page

Manage embeddings

Control embedding generation and reindex existing objects after changing the model.

When embeddings are generated

putObject generates an embedding from the description when all of these are true:

  • no embedding was provided;
  • embed is not false;
  • a description is present.
const saved = await omnio.putObject({
  key: "notes/a.txt",
  data: bytes,
  contentType: "text/plain",
  description: "Text that should be searchable",
});

The generated embedding records the model name, dimensions, and source. embeddingSource.kind is "description".

Disable generation

await omnio.putObject({
  key: "notes/b.txt",
  data: bytes,
  contentType: "text/plain",
  description: "An embedding will be created later",
  embed: false,
});

The description is saved, but no embedding is created. Create one later with reindexObject.

await omnio.reindexObject("notes/b.txt");

Provide a precomputed vector

await omnio.putObject({
  key: "vectors/a",
  data: bytes,
  contentType: "application/octet-stream",
  embedding: new Float32Array([0.1, 0.2, 0.3]),
});

Change a description

updateObjectMetadata does not rebuild the embedding. Update the description and then call reindexObject.

await omnio.updateObjectMetadata({
  key: "notes/a.txt",
  description: "A new description",
});

await omnio.reindexObject("notes/a.txt");

If there is no description, reindexObject changes nothing and returns the current object.

Change the model

open() marks objects whose saved embedding model or dimensions differ from the current embedder.info. It targets active objects that have a description and a recorded embedding model.

It then reindexes them in the background.

// Previously indexed with model A.
const omnio = new Omnio({
  entity,
  index,
  embedder: new Gemma2Embedder({ dims: 256 }),
});

await omnio.open();

Until reindexing finishes, those objects are excluded from vector search. headObject and listObjects still return their latest metadata.

open() does not wait for reindexing. Search results may take time to become complete.

Reindex manually

const reindexed = await omnio.reindexObject("photos/sunset.jpg");

reindexObject embeds the description with the current embedder and updates embedding, embeddingDims, embeddingModel, embeddingSource, and updatedAt. A missing key returns null.

Use a custom embedder

Implement IEmbedder and set the dimensions, model name, and modalities in info.

import type { IEmbedder } from "@omniojs/core";

class MyEmbedder implements IEmbedder {
  readonly info = {
    dims: 384,
    name: "my-model-v1",
    modalities: ["text"],
    normalized: true,
    multilingual: false,
  };

  async embed(c: IEmbedder.EmbedContext) {
    // Convert the input to a 384-dimensional Float32Array.
  }

  async embedMany(c: IEmbedder.EmbedManyContext) {
    return Promise.all(c.inputs.map((input) => this.#embedInput(input, c.signal)));
  }

  async embedText(c: IEmbedder.EmbedTextContext) {
    return this.#embedInput({ kind: "text", text: c.text }, c.signal);
  }

  supports(c: IEmbedder.SupportsContext) {
    return c.modality === "text";
  }

  async #embedInput(input: IEmbedder.EmbedContext["input"], signal: AbortSignal) {
    signal.throwIfAborted();
    // Implement the real embedding call here.
    return new Float32Array(this.info.dims);
  }
}

Changing info.name treats existing embeddings as belonging to another model, and they are reindexed on the next open(). The same applies to info.dims.

Next steps

Was this page helpful?