Knowledge

You upload files into collections. The gateway splits each document into chunks and embeds them with the collection's embedding model. For a model that has the Knowledge boon and at least one attached collection, it embeds the user's question, finds the best-scoring chunks, and places them ahead of the conversation. Retrieval runs from an in-process index inside the gateway; the request path never queries Postgres.

Turn it on

1. 1

   Create a collection

   Open Knowledge and choose New collection. Give it a name, an optional description and the Embedding model. Names are unique. Register an embedding model on the Models page first if you have none.

2. 2

   Upload documents

   On the collection's page (/knowledge/<name>), upload files under Documents. Each moves from Queued to Indexing to Indexed, or to Failed with the error shown; failures are listed first.

3. 3

   Attach it to a model

   Under Used by, pick a chat model and choose Attach. Attaching grants that model the Knowledge boon. You can also switch Knowledge on under a model's Boons and pick its collections there.

4. 4

   Turn retrieval on

   On the Knowledge page, choose Turn retrieval on, or open the Retrieval settings tab and switch Retrieval on. Pick a profile and save.

5. 5

   Try a search

   On the collection's page, type a question under Try a search. It shows the chunks that match, their scores, and which would be handed to the model under the current settings.

A request where it helps

curl http://localhost/v1/chat/completions \
  -H "Authorization: Bearer $OBLETH_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "glm-5-3",
    "messages": [{"role": "user", "content": "How many credits can a student transfer in?"}]
  }'

When passages were added, the response carries x-obleth-boons: knowledge.

What the model sees

The passages arrive in a <knowledge> block with a short instruction to use them only when they are relevant. It is appended to the system message, or becomes one; for a model flagged as not supporting system messages, it is put at the start of the latest user message.

The query is the last Question from user messages, newest first, cut to 2,000 characters. It is captured before compression and the block is added after compression and after the tenant's input guardrails, so the query is the user's own words and the passages reach the model unchanged. A follow-up turn in the tool loop carries the same block.

Retrieval settings

These live on Knowledge › Retrieval settings and apply to every model. A profile sets the first four:

Through the Management API, send only what you want to change; an omitted field, a 0, or a min_score outside 0 to 1 keeps the stored value:

curl -X PUT http://localhost:9180/api/v1/settings/knowledge \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": true, "top_k": 5, "min_score": 0.35, "max_context_tokens": 1500 }'

Each collection also has Chunk size (chunk_tokens, default 400) and Overlap (chunk_overlap_tokens, default 50, less than the chunk size) under its Settings. Existing chunks keep the old sizes until you Reindex.