Using RAG

Guide · Users, developers and operators · Applies to 5.0.x

RAG lets Eldric answer from your own documents: you put documents into a knowledge base, and when you ask a question the chat finds the relevant passages and gives them to the model, which answers with citations you can click.

Knowledge bases

A knowledge base is a named collection of documents. Knowledge bases belong to your tenant: everyone in the tenant sees the same list, and no other tenant can read them.

• Create one: choose + New knowledge base in the knowledge-base menu at the top of the chat, or in the sidebar, and give it a name.
• Delete one: click × next to it in the sidebar and confirm. This removes its documents from search.
• Users with the viewer role can use knowledge bases but cannot create, fill or delete them.

Add documents

Drag and drop into the chat

Drag files onto the chat window. Two drop targets appear:

• 📎 Attach to message is always there. The file goes with this one message only. Nothing is added to a knowledge base.
• 📚 Add to "name" appears only while a knowledge base is switched on in the chat, and adds the file to the first active knowledge base. Drop here to make the document permanently searchable.

You can also drop a file directly onto a knowledge base in the sidebar. The chat shows Ingesting N files into … and then Indexed N file(s), or names the reason when a file fails.

Up to 10 files can be attached to one message.

Other ways in

• ⇪ Upload to KB (smart) in the knowledge-base menu opens a guided upload.
• The knowledge-base wizard builds a knowledge base from a web source. It starts by itself when you write, for example, create a knowledge base from https://… in the chat.
• The API, see below.

Which files work

Kind	What happens
Text: .txt, .md, .html, .json, .yaml, .csv, .sql and similar	Read in your browser, HTML stripped, then indexed. Text under 20 characters is refused.
PDF with a text layer	Text is extracted on the server and indexed, with page numbers kept for citations.
Office: .docx, .xlsx, .pptx, .odt, .ods, .odp	Text is extracted on the server and indexed.
Audio and video	Transcribed by the media module, where it runs, then indexed.
Scanned PDF (image only), encrypted PDF	Refused. There is no OCR. Use a PDF with a text layer.
Legacy .doc, .xls, .ppt	Refused. Save as the newer format first.

What happens on upload

1. Text is extracted from the file, as in the table above.
2. The text is split into passages of about 1,200 characters, each overlapping the next by 150 characters, so a sentence at a boundary is not lost.
3. Each passage is turned into an embedding, a numeric fingerprint of its meaning, by the cluster's embedding model. The default is bge-m3. Passages that mean similar things get similar fingerprints, which is what lets a question find a passage that uses different words.
4. The passages are stored with their fingerprints, per tenant and knowledge base, on your own servers. With the default settings the embedding model also runs on your own infrastructure; it only leaves it if an administrator points embedding_url at an external service.

A knowledge base is bound to the embedding model its first document was stored with. Documents embedded by a different model cannot be mixed in; the upload is refused with embedding_dimension_mismatch. To move a knowledge base to another model, delete it and add the documents again. If the embedding service cannot be reached, the upload fails with embedding_failed rather than storing passages that could never be found.

Ask with your documents

1. Open the knowledge-base menu at the top of the chat and switch RAG on.
2. Tick one or more knowledge bases (✓).
3. Ask your question as usual.

Before your message is sent, the chat searches each selected knowledge base (the status reads Searching N knowledge base(s)…). The search combines keyword matching with matching by meaning. The best passages, normally up to 4 per knowledge base and more for "list all" style questions, go to the model with your question and an instruction to cite them.

The answer marks its sources as [1], [2]. Click one to open the source, with the page for PDFs. A line N sources cited appears under the answer. If nothing relevant is found, the model answers without document context. That is a sign to rephrase with words from the document or to check which knowledge base is selected.

The selection is not tied to one conversation: the knowledge bases you tick stay selected when you start a new chat.

Change or remove a document

A stored document cannot be edited in place. To change one, delete it and add the new version. To remove everything, delete the knowledge base.

From the API

Add text to a knowledge base (the knowledge base is the namespace):

curl -X POST https://<your-eldric-host>/api/v1/vector/ingest \
  -H "X-API-Key: $ELDRIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tenant":"acme","namespace":"policies","text":"The text you want indexed...","source":"travel-policy.md"}'

Search it:

curl -X POST https://<your-eldric-host>/api/v1/vector/search \
  -H "X-API-Key: $ELDRIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tenant":"acme","namespace":"policies","query":"How much can I spend on a hotel?","top_k":5}'

A caller can only name its own tenant; another tenant is refused. Files larger than 4 MB go through the chunked upload endpoints (/api/v1/upload/init, /chunk, /finalize). See the API reference.

For administrators

• Embedding model: the data module's embedding_model setting (default bge-m3-q8_0) and embedding_url (default http://localhost:11434), in the admin console under the Vector group. ELDRIC_DATA_EMBEDDING_MODEL overrides it. Changing it affects new knowledge bases; existing ones keep the model they were built with.
• Licence: adding to and searching knowledge bases needs the rag feature in your licence.

Current limits

• Large files: from 5.0.173, PDF and Office files over 4 MB are indexed as a background job with progress, and Latin-1 and UTF-16 text is indexed too. In 5.0.172 and earlier, binary files over 4 MB were stored but not indexed. A single request over 128 MB answers 413; use the chunked upload. Scans without a text layer and .doc/.xls/.rtf are stored but not indexed, and the chat says so.
• The result-count and minimum-score values set for a group or project are stored but do not affect the search in the chat yet; it uses the fixed values described above.
• No OCR: scanned documents need a text layer first.

Troubleshooting

1. No citations: check that RAG is switched on and the right knowledge base is ticked.
2. A file never found in search: check whether the chat reported it as not indexed, and see Current limits.
3. Upload refused: read the reason in the message. Scanned and encrypted PDFs and legacy Office formats are refused, see Which files work.
4. 401 or 403: check your API key and that you are addressing your own tenant.
5. embedding_failed: the embedding service is not reachable. An administrator checks embedding_url.