Ulabase

AI

AI Keys

Add the AI providers your service calls to compute vectors and rerank results, each with your own key and default models, checked before they are saved.

An AI provider, such as Voyage AI, Cohere or OpenAI, runs the models that turn a text into a vector and that rerank search results. Under AI → AI Keys you add the providers your service may call, each with your key and its default models. You also choose which provider embeds and which one reranks, unless a collection names its own.

Every other page of the AI group runs on what you set here. An auto-embedding rule names one of these providers, and $vectorize in a search and the rerank block of an aggregation call them.

What you get:

  • You pay your provider directly. The providers bill the calls to your account. Ulabase adds nothing.

  • Keys checked before they are saved. A wrong key is found here, before any rule uses it.

  • One default for the whole service. A rule that names no model uses the default chosen here.

A rule in Auto Embeddings that names no model embeds with the default chosen here. If such rules exist and you change the default, or the default provider’s model, the page warns you before saving. Keep writes the current model on those rules, so their vectors stay searchable. Change anyway moves them to the new model, and you embed the documents again from Auto Embeddings.

Before you start

Get a key from a provider:

  • Voyage AI, the default: models made for retrieval, and a contextual variant that embeds the chunks of a document aware of each other.

  • Any provider that answers OpenAI’s /v1/embeddings: OpenAI, OpenRouter, Together AI, or your own base URL.

Then click Enable in the page header; the badge says whether the feature is on. Disable stops the service from calling the providers and keeps the keys.

Providers

A provider is a key and its default models. Add the ones you have a key for:

  • Voyage AI, once: a default embedding model, among voyage-4, voyage-4-large, voyage-4-lite, voyage-code-4, voyage-finance-2, voyage-law-2 and voyage-context-4 (contextual embeddings: every chunk of a document aware of the others), with the vector’s length where the model allows a choice (1024, or 256, 512, 2048; 1024 alone for the finance and law models); and a reranking model, rerank-3, rerank-3-lite, rerank-2.5 or rerank-2.5-lite, or none.

  • OpenAI-compatible, as many as you like, one per URL: OpenAI, with text-embedding-3-small or text-embedding-3-large (1536 or 3072 by default, shorter on request); OpenRouter, Together AI, or any other provider answering /v1/embeddings, with its base URL and the model’s name as the provider calls it, the vector’s length read from the verification. Each is known by its host: openai-openrouter-ai, openai-api-acme-com.

  • Cohere, once: a default embedding model, embed-v4.0 (1536, or 256, 512, 1024), embed-multilingual-v3.0 or embed-english-v3.0 (1024), and a reranking model, rerank-v3.5, or none. Its embeddings answer at Cohere’s OpenAI-compatible endpoint, https://api.cohere.ai/compatibility/v1, with the same key.

Verify calls the provider: it embeds one word with the embedding model and reranks one document with the reranking model. The result appears under each field, such as «Voyage embeds with voyage-4, 1024 dimensions» or «Voyage reranks with rerank-3», or the provider’s full error message. Save stays disabled until every model has answered, and any change to the form needs a new verification, so a key that does not work never reaches the service.

The list shows every saved provider, with «key set» and its models. Keys are never shown again. Edit opens the form with the key masked; leave it masked to keep the stored key. Remove deletes the provider and its key.

The light beside each provider

A provider can stop answering after it was verified, when the key expires or the account runs out of credit. On a write, the document is then stored without its vector, and the response gives the reason in _warnings. On a search, the aggregation fails with the reason. The list shows what each provider answered last as a light: green when the last call went through, red with the provider’s message and the time when it failed, grey before any call.

Once a day, the owners of the service get one email listing the providers that failed since the last one, with the reason. A webhook on the collection sees the same _warnings in the response, for your own handling. To find the documents left without a vector: Auto Embeddings counts them under each rule and embeds them again on request, and GET /<collection>?filter={"embedding":{"$exists":false}} finds them anywhere. Send it as the service’s root, which may write its own query.

Defaults

Under the list you choose which provider embeds by default, among those with an embedding model, and which one reranks by default, among those with a reranking model, or none. They apply to every collection that names nothing of its own. Every saved provider is available to every collection. In its vectorSearch metadata, a collection names Voyage by RESTHeart’s provider name, and an OpenAI-compatible provider, Cohere included, by its base-url, with a model of its own.

One model per collection, one default

The vectors of a field and the vectors of the questions searched against it must come from the same model. A collection whose rule names no model uses the default provider’s model. A rule may name its own provider and model, so /legal can use voyage-law-2 and /src voyage-code-4 with one key. $vectorize follows the collection, so a question is embedded with the model of the vectors it is searched against. Changing a default leaves collections with their own model as they are. You write rules under Auto Embeddings, which also warns when a new model means dropping the vectors already stored.

Where AI is used

Under the providers, the page lists everything in the service that uses these keys, each with a link to its page: the auto-embedding rules, the aggregations that search by vector, the vector indexes. At first the list is empty, with a link to Auto Embeddings to start.

A rerank block beside the stages of an aggregation hands its results to the reranking model, which reorders them by how well each answers the question:

{ "uri": "search", "type": "pipeline",
  "stages": [ { "$vectorSearch": { "...": "..." } }, { "$set": { "text": "$description" } } ],
  "rerank": { "query": { "$var": "q" }, "topK": 5 } }

query is the text to judge by, usually the same $var that vectorizes the question. topK is how many results to keep, all of them when omitted. The model reads each result’s text field, or the whole document when there is none, so add a $set stage that copies the field to judge by into text. The block names no model: the service uses the reranking model saved here. On the Aggregations page the block is a section of the form, with the query variable and topK as fields, and the Semantic search preset fills it in.

Do it from the command line

You can keep your AI providers in git and apply them with ulabase setup. The steps below install the ai feature, add Voyage AI with its key, and make it the default for embeddings and reranking.

Each provider has an id, such as voyage, cohere or openai-<host>. embedding and rerank say which provider is the default.

import { defineSetup, step, fromEnv, isRedacted } from '@ulabase/cli';

// Voyage AI: the embedding model, the size of the vectors and the rerank model; the key is added below, from the environment
const voyage = { vendor: 'voyage', model: 'voyage-4', dimensions: 1024, 'rerank-model': 'rerank-3' };

export default defineSetup('AI', [
  // step 1: install the ai feature, if it is not installed yet
  step('ai feature installed', {
    check: ({ admin, srvId }) => admin.isFeatureInstalled(srvId, 'ai'),
    apply: ({ admin, srvId }) => admin.installFeature(srvId, 'ai'),
  }),

  // step 2: save Voyage AI with its key, unless it is already saved and the key works
  step('Voyage AI key saved and answering', {
    async check({ admin, srvId }) {
      const c = await admin.getFeatureConfig(srvId, 'ai');
      // the server never returns a saved key: it sends '••••••••' in its place, so isRedacted() means a key is saved
      const p = (c.providers as any)?.voyage;
      if (p?.model !== voyage.model || !isRedacted(p['api-key'])) return false;
      // ask the server to test the saved key with Voyage AI, as the Verify button of the console does
      const res = await admin.fetch(`/plugins-mgmt/${srvId}/ai/verify`, {
        method: 'POST',
        body: JSON.stringify({ providers: { voyage: p } }),
      });
      const v = (await res.json()).providers.voyage;
      return v.embedding?.valid === true && v.rerank?.valid !== false;
    },
    async apply({ admin, srvId }) {
      // read the configuration first, so the other providers stay as they are
      const current = await admin.getFeatureConfig(srvId, 'ai');
      await admin.updateFeatureConfig(srvId, 'ai', {
        ...current,
        providers: {
          ...(current.providers as object),
          voyage: { ...voyage, 'api-key': fromEnv('VOYAGE_API_KEY') },
        },
        // Voyage becomes the default for embeddings and for reranking
        embedding: { provider: 'voyage' },
        rerank: { provider: 'voyage' },
      });
    },
  }),
]);

For an OpenAI-compatible provider, set vendor: 'openai' and its base-url. To turn reranking off, set rerank: { provider: 'none' }.

Saving does not test the key. The check does: it calls the same Verify as the console, which tries the stored key with the provider.

What it costs

Your provider bills every embedding, one per document written and one per question, and every reranking call, to your account. Ulabase adds nothing.