OpenWebUI - Upload files versus Knowledge collection
When you create or edit a model in OpenWebUI, you can attach documents in two ways: Upload Files and Select Knowledge. Both options make external information available to the AI, but they work very differently under the surface. Choosing the wrong method can lead to errors, degraded responses, or conversations that fail entirely.
This guide explains how each method works, when to use which, and how to create a Knowledge Collection step by step.
How Upload Files Works
The Upload Files option attaches one or more documents directly to your model. When a user starts a conversation with that model, the full content of every attached file is injected into the context window alongside the conversation itself.
This means the AI receives the complete text of every uploaded file with every single message, regardless of whether the content is relevant to the question being asked.
Why this creates problems
Every AI model has a finite context window, measured in tokens. A token is roughly three quarters of a word. When the combined size of your uploaded files, the system prompt, and the conversation history exceeds the model's context window, one of two things happens:
The request fails with an error, and the user receives no response at all.
Older parts of the conversation are silently dropped to make room, causing the AI to lose track of what was discussed earlier.
A single PDF of 30 pages can easily consume 15,000 to 20,000 tokens. Attach three or four documents of that size and you may have already filled the entire context window before the user has typed a single message.
When Upload Files is appropriate
Upload Files is suitable only for small, highly relevant reference documents that should always be available in full. Examples include a short style guide, a one page set of formatting rules, or a brief glossary. If the document is longer than a few pages, or if you plan to attach more than one or two files, use a Knowledge Collection instead.
How Knowledge Collections Work
The Select Knowledge option connects your model to a Knowledge Collection. Rather than injecting all content into every message, Knowledge Collections use a technique called Retrieval Augmented Generation, commonly known as RAG.
When a user asks a question, the system searches the Knowledge Collection for the most relevant passages and injects only those passages into the context. The rest of the collection stays in the background, ready to be searched but not consuming any tokens.
This means you can attach hundreds of documents to a single Knowledge Collection without ever risking a context window overflow. The AI only retrieves what it needs for each specific question.
Key differences at a glance
How content reaches the AI
Full text injected into every message
Only relevant passages retrieved per question
Token usage
High and fixed, regardless of the question
Low and variable, scales with relevance
Risk of context overflow
High with larger or multiple documents
Low, even with large document sets
Best for
Short reference documents (1 to 3 pages)
Larger documents, multiple files, knowledge bases
Search capability
None; the AI reads everything linearly
Semantic search across all documents
Practical recommendation
As a general rule, default to Knowledge Collections. Use Upload Files only when you have a short document that must be available in its entirety for every interaction, such as a system prompt supplement or a compliance checklist of a few hundred words.
Creating a Knowledge Collection
Follow the steps below to create a Knowledge Collection, populate it with documents, and attach it to a model.
Step 1: Navigate to the Knowledge section
Open the sidebar and click Workspace. From the top navigation within the Workspace, select Knowledge.
Step 2: Create a new Knowledge Collection
Click the + button (or + New Knowledge) in the top right corner of the Knowledge overview.
Step 3: Name and describe the collection
Enter a clear, descriptive name for your collection. Use a name that reflects its contents or purpose, for example "Product Documentation Q2 2025" or "HR Policies". Add a brief description so that other users (and the AI) understand what the collection contains.
Click Create Knowledge to confirm.
Step 4: Upload documents to the collection
Once the collection is created, you are taken to the collection detail page. Click the + icon next to the search bar on the right side to upload files. You can upload individual files or entire directories.
Supported formats include PDF, Word documents, spreadsheets, plain text, HTML, and code files.
Wait for the processing indicator to complete before proceeding. Each uploaded file is automatically chunked and indexed for semantic search. You can click on any file to preview its contents.
Step 5: Verify the uploaded content
After uploading, confirm that your documents appear in the file list and that their content has been processed. You can click on individual files to inspect the extracted text. If a file appears empty or incorrectly parsed, remove it and re-upload in a different format (for example, convert a scanned PDF to a text based PDF first).
Step 6: Attach the collection to a model
Navigate to Workspace and select Models. Find the model you want to enhance with your Knowledge Collection and click the three dot menu, then select Edit.
Scroll down to the Knowledge section of the model configuration. Click Select Knowledge and choose the collection you just created from the list.
Save your changes.
Step 7: Test the setup
Start a new chat using the model you just configured. Ask a question that can only be answered using the content in your Knowledge Collection. The AI should retrieve relevant passages and provide an answer grounded in your documents.
If the AI does not reference your documents, verify that:
The Knowledge Collection is correctly attached to the model in the model settings.
The documents have finished processing (check for a processing indicator in the collection).
Your question is specific enough to trigger a relevant retrieval.
Referencing Knowledge Collections in Chat
You do not need to attach a Knowledge Collection to a model to use it. Any user can reference a Knowledge Collection directly in chat by typing # in the message input field. This brings up a list of available collections. Select one, and the AI will search that collection when answering your question.
This is useful for ad hoc queries where you want to consult a specific set of documents without permanently binding them to a model configuration.
Summary
Use Upload Files sparingly and only for short documents that must be present in full for every interaction. For everything else, create a Knowledge Collection and attach it to your model using Select Knowledge. Knowledge Collections scale to large document sets without risking context window errors, and they produce more focused responses because the AI retrieves only the passages that matter for each question.
Last updated
Was this helpful?