Knowledge Bases

Ground model answers in your own documents, with citations back to the source.

A Knowledge Base is a collection of your own documents that Hyperstack AI Studio indexes so models can search it while answering. Attach one to a conversation in the Text Playground and the model draws on passages from your files, citing each source it used. This page covers creating a Knowledge Base, keeping its documents current, and using it in a conversation.

You can also manage Knowledge Bases programmatically. See the Knowledge Bases API for creating them, uploading and indexing files, and tracking indexing from your own code.

How Knowledge Bases Work

Uploading a document does not make it available to a model straight away. Each document is indexed first, and only then can the Knowledge Base be used in a conversation.

Two things happen in sequence:

1. Indexing. Each document you upload is split into chunks, passages small enough for a model to work with, and each chunk is converted into a searchable form using an embedding model. This runs in the background, so you can leave the page while it works.
2. Retrieval. When you send a message with a Knowledge Base selected, AI Studio searches those chunks and passes the closest matches to the model alongside your prompt.

A Knowledge Base belongs to the user who creates it, so the ones you create are visible only to you.

Knowledge Base statuses

Every Knowledge Base carries a status that tells you whether it is ready to use. Statuses update on their own while you have the page open, with no refresh needed.

Status	What it means
Processing	At least one document is still being indexed. The Knowledge Base cannot be selected in the Text Playground yet.
Active	Indexing has finished and the Knowledge Base is ready to use.
Failed	Indexing finished without a single document succeeding.
Deleting	The Knowledge Base is being removed. It disappears from the list once cleanup completes.

Documents carry their own status, shown in the table on the Knowledge Base detail page. A document moves from Pending to Processing and then to Ready. Because each document is indexed independently, one failure does not take the rest with it.

Supported documents

Knowledge Bases accept plain text (.txt) and Markdown (.md) files, up to 2 MB each. Anything else is rejected as you add it, so an unsupported file in a larger selection does not block the rest of the batch.

Create a Knowledge Base

Creating a Knowledge Base takes two steps: naming it, then choosing which documents go in it.

1. Open the Knowledge Bases page

   Navigate to the Knowledge Bases page in Hyperstack AI Studio and select New Knowledge Base.

   

2. Name the Knowledge Base

   Enter a name of up to 100 characters, unique among your Knowledge Bases. You can add a description of up to 500 characters to record what the collection holds, which is worth doing once you have more than a few. AI Studio derives an ID from the name as you type, shown beneath the field.

   Select Continue.

3. Add documents

   Drop your .txt and .md files onto the upload area or select it to browse. Each file you add is listed with its size before anything is uploaded, so you can check the batch first.

   Select Create knowledge base. Indexing begins immediately and you are returned to the Knowledge Bases page.

   Creating an Empty Knowledge Base

   You do not have to add documents now. Select Finish to create the Knowledge Base empty and upload to it later from its detail page, which is useful when you want the collection in place before its content is ready.

The new Knowledge Base appears in the list as Processing, and switches to Active once every document has been indexed.

Manage Your Knowledge Bases

The Knowledge Bases page lists every Knowledge Base you have created. Each entry shows its name and description, how many documents and chunks it holds, its total size, when it was last updated, and its current status, which is enough to tell at a glance which collection you want without opening it.

Selecting an entry opens its detail page. Alongside the document table, a Details panel gives you the Knowledge Base ID, the embedding model used to index it, the document and chunk counts, total storage, and the creation date.

Review the documents in a Knowledge Base

The documents table lists every file with its name, size, chunk count, upload date, and status. Use Filter documents to narrow the table by filename when a collection has grown large.

Add documents to an existing Knowledge Base

Select Upload File on the detail page and choose your files, with the same formats and size limit that apply at creation. Progress is shown per file, and the new documents begin indexing as soon as they arrive. The Knowledge Base returns to Processing until they finish.

Cancel indexing

While documents are indexing, the detail page shows a Cancel Ingestion button.

Cancelling stops the documents that have not finished and discards any chunks already written for them. Documents that completed beforehand keep their chunks and stay searchable. What you are left with depends on how far indexing got: the Knowledge Base stays Active if at least one document completed, and ends up Failed if none did.

Remove a document

Select the delete action on a document's row and confirm. Its chunks are removed with it, so that content stops appearing in retrieval.

Documents that are still processing or already being deleted cannot be removed. Wait for indexing to finish, or cancel it first, then delete the document.

Delete a Knowledge Base

Select Delete on the detail page and confirm.

The Knowledge Base shows as Deleting while its documents and indexed chunks are cleaned up, then disappears from the list.

Deletion Is Permanent

Deleting a Knowledge Base permanently removes it, its uploaded files, and everything indexed from them. Conversations that used it keep their existing messages, but they are detached from it, and later messages in those conversations are answered without retrieval. To use the same content again, create a new Knowledge Base and upload the files.

Use a Knowledge Base in the Text Playground

Attaching a Knowledge Base to a conversation grounds the model's answers in your documents for that conversation only.

1. Select a Knowledge Base

   In the Text Playground settings, open the RAG Context dropdown and choose a Knowledge Base. Only Active ones are listed, since a Knowledge Base still indexing has nothing complete to search. The most recently updated appear first.

   Conversations start with no Knowledge Base attached. To detach the one you selected, click the x icon at the top right of the RAG Context panel.

2. Send your message

   Enter your prompt and send it as usual. AI Studio searches the Knowledge Base for chunks related to your message and passes the closest matches to the model along with your prompt.

3. Check the sources

   The reply carries numbered citation markers. Hover over one to see the document the passage came from, an excerpt of the passage itself, and a relevance score showing how closely it matched.

   

Your choice stays with the conversation, so leaving the Text Playground and returning, or reopening the conversation from History, restores it. If none of your documents are relevant to a message, the model still answers from its own knowledge.

Billing for Grounded Responses

Retrieved passages are sent to the model as part of your request, so a grounded message uses more input tokens than the same message without a Knowledge Base. Inference is billed per input and output token as usual. You can track usage under Billing.