AI Keys

Get a key from a provider:

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.

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

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.

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.

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.

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.

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:

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.

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