embeddings.md

Embeddings

OmniGraph can turn query text into a vector for nearest($document.embedding, $text). Use the same provider and model that produced the stored document vectors; vectors from different models are not comparable.

Generated vectors are finite, nonzero, and L2-normalized before use. The target Vector(N) property determines their required dimension.

Providers

Provider Configuration
openai-compatible Default. Uses an OpenAI-compatible /embeddings endpoint; defaults to OpenRouter.
openai Uses OpenAI directly.
gemini Uses Google's embedding API.
mock Deterministic local vectors for tests and development.

For direct or embedded use, configure the provider with environment variables:

Variable Meaning
OMNIGRAPH_EMBED_PROVIDER openai-compatible, openai, gemini, or mock
OMNIGRAPH_EMBED_BASE_URL Override the provider endpoint
OMNIGRAPH_EMBED_MODEL Override the model id
OPENROUTER_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY Provider credential
OMNIGRAPH_EMBED_DEADLINE_MS Total call deadline; default 60,000 ms
OMNIGRAPH_EMBED_TIMEOUT_MS Per-request timeout; default 30,000 ms
OMNIGRAPH_EMBED_RETRY_ATTEMPTS Maximum attempts; default 4
OMNIGRAPH_EMBED_RETRY_BACKOFF_MS Initial retry backoff; default 200 ms
OMNIGRAPH_EMBEDDINGS_MOCK Force the mock provider

The default OpenRouter model is openai/text-embedding-3-large. The direct OpenAI default is text-embedding-3-large; Gemini defaults to gemini-embedding-2.

Outbound requests

Apart from its storage, embedding is the only outbound request the server makes: it happens when a query's nearest takes text rather than a vector, and goes to the provider endpoint with that provider's key. Stored vectors are never re-embedded by the server, and loads do not call a provider. To run with no outbound requests at all, bind no embedding_provider and leave OPENROUTER_API_KEY, OPENAI_API_KEY and GEMINI_API_KEY unset in the server's environment, along with OMNIGRAPH_EMBED_PROVIDER: a text nearest then fails, and every other query is unaffected. Pass vectors as nearest parameters instead. The mock provider also makes no request, but its vectors are not real embeddings.

Cluster configuration

Cluster-served graphs select a named provider in cluster.yaml:

providers:
  embedding:
    default:
      kind: openai-compatible
      base_url: https://openrouter.ai/api/v1
      model: openai/text-embedding-3-large
      api_key: ${OPENROUTER_API_KEY}

graphs:
  knowledge:
    schema: knowledge.pg
    embedding_provider: default

Inline API keys are rejected. ${ENV_VAR} references are resolved when the server starts, not when the cluster configuration is planned or applied.

Schema annotation

Associate a vector with its source text:

node Document {
  slug: String @key
  body: String
  embedding: Vector(1536) @embed("body", model="openai/text-embedding-3-large") @index
}

The vector is the embedding of the record's body value exactly as stored, and a text nearest($d.embedding, $q) embeds $q exactly as given. Neither side adds a type name, a field label or any other template, and neither trims whitespace, so a record whose body equals the query text embeds the same input. The one difference a provider can see is the retrieval role: Gemini receives RETRIEVAL_DOCUMENT for stored text and RETRIEVAL_QUERY for a query, and the other providers receive identical requests. Vectors you compute yourself must embed the source value the same way to be comparable with text queries.

When model is recorded, a text nearest query is rejected unless the active provider resolves to exactly that model id. Changing the recorded source or model is not an in-place schema migration; rebuild or re-embed the data instead.

@embed does not populate the property during a load, even with an embedding provider configured. Supplied vectors are preserved, omitted nullable vectors remain null, and missing required vectors refuse the load. Supply vectors in input data or prepare seed files with the offline command.

Successful HTTP and CLI JSON load results include embedding_generation: "unsupported" means the load touched a node type with an @embed property; null means it did not. This describes the load capability, including when every vector was supplied. Human CLI output prints the corresponding guidance.

Offline file pipeline

omnigraph embed reads and writes JSONL files; it does not mutate a graph.

omnigraph embed --input raw.jsonl --output embedded.jsonl --spec embeddings.json

The spec names, for each node type, the vector property to fill and the one property whose value it embeds:

{
  "dimension": 1536,
  "types": {
    "Document": { "target": "embedding", "fields": ["body"] }
  }
}

fields must name exactly one property, the source the target's @embed declares; a spec that lists none or several is refused. The command does not read the schema, so keep target, fields, and dimension equal to the @embed declaration and its Vector(N). The source's string value is embedded unchanged, as described under Schema annotation. A processed record whose source is absent, null, or blank gets no vector: whatever its target held, including a null or an empty list, is removed and counted as cleaned. A source value that is not a string is refused.

By default it fills missing vectors. Use --reembed-all to replace selected vectors or --clean to remove them. --type and --select restrict the records processed. A seed manifest can be supplied with --seed instead of separate input, output, and spec paths; its embeddings entry takes the same shape as the spec.