AI Keys

Get a key from a provider:

Then Install the feature from the page header. The badge says whether it is enabled; Disable stops the service from calling the provider without forgetting the keys, Uninstall forgets them.

A provider is a key and the models it serves by default. 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. Each verdict is written under its field, «Voyage embeds with voyage-4, 1024 dimensions», «Voyage reranks with rerank-2.5», or the provider’s refusal in its own words, whole. Save stays disabled until every model the provider is saved with has answered, and any change to the form asks for a new verification, so a key that does not work never reaches the service.

The list shows every provider saved, with «key set» and its models. Keys are never shown again; Edit opens the form with the key masked, and leaving it masked keeps the one stored. Remove forgets the provider and its key.

A provider can stop answering after it was verified: the key expires, the account runs out of credit. When that happens on a write, the document is stored without its vector and the response carries the reason in _warnings; on a search, the aggregation fails with it. The service records what each provider answered last, and the list shows it as a light: green when the last call went through, red with the provider’s words 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 it receives, for your own handling. The documents left without a vector are those where the field is missing: 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, two choices: 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 provider saved is available to every collection: a collection names Voyage by RESTHeart’s provider name, and an OpenAI-compatible one, Cohere included, by its base-url, with a model of its own, in its vectorSearch metadata.

The vectors of a field and those of the questions searched against it must come from the same model. The default provider’s model is what a collection gets when its rule names nothing; 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 those collections as they are. Rules are written under Auto Embeddings, which also warns when a change of model means dropping the vectors already stored.

Under the providers, the page lists every object of the service built on these keys, each with a link to the page that owns it: the auto-embedding rules, the aggregations that search by vector, the vector indexes. Empty at first, 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 same block is a section of the form, with the query variable and topK as fields, and the Semantic search preset fills it in.

The provider bills every embedding, one per document written and one per question, and every reranking call, to your account. RESTHeart Cloud adds nothing.