Enable Knowledge

Document files go to an S3-compatible bucket. Passages and vectors stay in Chat's Postgres database, so pgvector must be installed there (see Install Chat). From v0.4.2, the same bucket also holds the files people attach to chats and the images models generate; see Where files are kept.

Set it up

1. 1

   Create a bucket

   Any S3-compatible store works: AWS S3, Cloudflare R2, MinIO, Garage. Create an access key that can read, write and delete objects in that bucket only.

2. 2

   Serve an embedding model

   Register an embedding model in the gateway and make sure Chat's tenant may use it. The default is qwen3-embedding-8b; any embedding model works. Chat stores 1,024 dimensions: it keeps the first 1,024 of a longer vector and renormalizes them, which suits models trained to be truncated, such as Qwen3-Embedding, and pads a shorter one with zeros, which doesn't change its distances.

   Most embedding models expect a prefix before searches and before passages. From v0.4.4, Chat knows the prefixes for common models and uses them on its own; for any other model, set them (see Choose the embedding model).

3. 3

   Configure Chat

   OBLETH_CHAT_S3_ENDPOINT=https://<account>.r2.cloudflarestorage.com
   OBLETH_CHAT_S3_BUCKET=obleth-chat
   OBLETH_CHAT_S3_ACCESS_KEY_ID=…
   OBLETH_CHAT_S3_SECRET_ACCESS_KEY=…
   OBLETH_CHAT_EMBEDDING_MODEL=qwen3-embedding-8b
   

   Restart Chat. Library appears in the sidebar for everyone, with Saved, Collections and Generated, and answers get a Save button. Without these settings Library is hidden.

Where files are kept

With a bucket configured (v0.4.2 and later), Chat stores these files there:

Without a bucket, attachments and generated images are kept in Postgres. Turning the bucket on later needs no other step: a background worker moves existing files into it one at a time, and files stay readable throughout. Each replica logs moving files kept in Postgres into object storage when it starts moving them.

Attachments and generated images are served through Chat, never through a link to the bucket, so people's browsers don't need to reach the bucket to open them. Deleting a file, a chat or an account deletes the stored files shortly afterwards. An upload whose chat or file was never saved is deleted after 15 minutes.

VACUUM FULL attachments, generated_images;

Settings

Choose the embedding model

From v0.4.3, an administrator chooses the embedding model and its prefixes in Settings › Administration › System › Knowledge search. The list shows the embedding models the gateway offers. OBLETH_CHAT_EMBEDDING_MODEL sets the default model.

Each prefix comes from the first of these that is set (v0.4.4 and later):

1. The administrator's choice in Settings.
2. OBLETH_CHAT_EMBEDDING_QUERY_PREFIX or OBLETH_CHAT_EMBEDDING_DOCUMENT_PREFIX, while the default model is in use. They never carry over to another model.
3. The model's own prefixes, for the models in the table below.

Any other model gets no prefix. Choosing a model in Settings fills in its prefixes, so check them against the model's documentation only when it isn't in the table.

The same happens when the defaults change in the environment and no administrator has chosen otherwise. In v0.4.2, which has no setting in the app, change the environment variables and upload the documents again.