Knowledge Management¶
Overview¶
The Knowledge Management system in iPassion AI Portal uses Retrieval-Augmented Generation (RAG) to let AI find and reference relevant chunks from your uploaded documents on demand. Rather than stuffing entire files into every prompt, the system indexes documents into searchable vectors and retrieves only the most relevant passages when a user asks a question. This makes it ideal for large document sets where full-context injection would exceed model limits.
How It Works¶
1. Upload documents to a Knowledge Base
2. An extraction engine parses the content (PDF, spreadsheet, code, etc.)
3. Text is chunked and converted to vector embeddings
4. Embeddings are stored in a vector database
5. User asks a question
6. Hybrid search (keyword + semantic) retrieves the most relevant chunks
7. Cross-encoder reranking scores and orders the results
8. Top chunks are injected into the prompt alongside the question
9. AI generates a grounded, citation-backed response
Creating a Knowledge Base¶
Steps¶
- Navigate to Workspace > Knowledge
- Click + Create
- Fill in:
- Name: e.g., "Customer Service Handbook"
- Description: Describe what the Knowledge Base contains
- Click Create
- Upload files into the newly created Knowledge Base
- Attach the Knowledge Base to one or more models/agents so they can reference it
Document Management¶
Uploading Documents¶
Open a Knowledge Base and upload files by clicking the upload button or dragging and dropping files directly into the interface. The system supports a wide range of formats:
| Category | Formats |
|---|---|
| Documents | PDF (text-based and scanned/OCR), DOCX, DOC, PPTX, PPT |
| Spreadsheets | XLSX, XLS, CSV |
| Text & Markup | TXT, MD (Markdown), HTML, HTM, XML |
| Data | JSON, YAML |
| Code | Python, JavaScript, TypeScript, and other source files |
Files can be renamed in place directly within the Knowledge Base interface.
Directory Structure¶
Knowledge Bases support nested directories for organizing large document collections:
- Create subdirectories to group related files
- Drag-and-drop files and folders to reorganize
- Breadcrumb navigation at the top shows your current location in the hierarchy
- Navigate up and down through the folder tree as you would in a file manager
Extraction Engines¶
iPassion AI Portal supports 8 document extraction engines for converting uploaded files into indexable text:
| Engine | Best For |
|---|---|
| Tika (default) | General-purpose extraction for most document types |
| Docling | High-quality document structure preservation |
| Azure Document Intelligence | Enterprise OCR with layout understanding |
| Mistral OCR | Fast optical character recognition |
| Datalab Marker | PDF-to-markdown with table and figure extraction |
| MinerU | Academic and research paper parsing |
| PaddleOCR | Multilingual OCR including Thai script |
| Custom Loaders | User-defined extraction pipelines for specialized formats |
Administrators can configure the active extraction engine in Admin Panel > Settings > Documents.
Search and Retrieval¶
Hybrid Search¶
The system combines two search strategies for maximum accuracy:
- BM25 Keyword Search: Traditional term-frequency matching that excels at finding exact phrases and specific terminology
- Vector Semantic Search: Embedding-based similarity that understands meaning and finds conceptually related content even when exact words differ
Results from both strategies are fused together, then passed through a cross-encoder reranker that scores each candidate passage for relevance to the query. This produces significantly better results than either method alone.
Supported Vector Databases¶
iPassion AI Portal supports 13 vector database backends:
| Database | Notes |
|---|---|
| ChromaDB | Officially maintained, lightweight option |
| PGVector | Officially maintained, PostgreSQL extension |
| Qdrant | High-performance vector search engine |
| Milvus | Scalable distributed vector database |
| OpenSearch | AWS-compatible search and analytics |
| Elasticsearch | Full-text and vector search combined |
| Pinecone | Managed cloud vector database |
| Weaviate | AI-native vector database |
| FAISS | Facebook AI Similarity Search |
| LanceDB | Embedded vector database |
| Chroma (remote) | Hosted ChromaDB instances |
| pgvecto.rs | Rust-based PostgreSQL vector extension |
| Tidb | Distributed SQL with vector capabilities |
The default deployment uses PGVector integrated with the system's PostgreSQL database.
Two Retrieval Modes¶
When attaching a Knowledge Base to a model or agent, you can choose between two retrieval modes:
| Mode | Behavior | Best For |
|---|---|---|
| Focused (default) | RAG-based retrieval — only the most relevant chunks are injected into the prompt | Large document sets, general Q&A |
| Full Context | Injects the entire content of all attached documents into the prompt | Small reference documents where complete context is needed |
Agentic Knowledge Tools¶
When native function calling is enabled, the AI can autonomously decide how to search your Knowledge Base using five specialized tools:
| Tool | Purpose |
|---|---|
query_knowledge_files |
Semantic/RAG search — finds passages by meaning |
grep_knowledge_files |
Exact text and regex search — finds specific strings, patterns, or code |
search_knowledge_files |
Search by filename — locates files by name within the Knowledge Base |
view_file |
Read file content with pagination — lets the AI read through a file page by page |
list_knowledge |
List attached Knowledge Bases and their files — provides an overview of available content |
With these tools, the AI can chain searches together: first listing available files, then searching by filename, then reading specific sections — behaving more like a research assistant than a simple retrieval system.
Using Knowledge in Conversations¶
Method 1: Type # in the Message Input¶
- In the chat message input, type #
- A dropdown appears listing available Knowledge Bases
- Select one or more Knowledge Bases
- Type your question
- The AI searches the selected Knowledge Bases before responding
Method 2: Via AI Agent¶
AI Agents with a bound Knowledge Base automatically reference it in every conversation. Users simply select the agent and start chatting.
Method 3: Via Custom Model¶
Custom Models with a bound Knowledge Base reference it whenever that model is selected for a conversation.
Directory Syncing¶
The Sync Directory feature mirrors a local server folder into a Knowledge Base:
- Point a Knowledge Base at a directory path on the server
- The system uses SHA-256 hashing to detect which files have changed, been added, or removed
- Only modified files are re-processed on sync, saving time and compute
- Useful for keeping Knowledge Bases in sync with shared drives, document management systems, or automated pipelines
API Access¶
Knowledge Bases can be managed programmatically through the REST API:
- File upload: Upload documents to a Knowledge Base via API
- Directory operations: Create, rename, move, and delete directories
- Sync workflow: Trigger directory sync programmatically
- Export: Download an entire Knowledge Base as a ZIP archive
- CRUD operations: Create, read, update, and delete Knowledge Bases and their contents
This enables integration with external document pipelines, CI/CD workflows, and automated content management systems.
Access Permissions¶
| Permission Level | Description |
|---|---|
| Owner | The user who created the Knowledge Base; full control |
| Group-based | Assign specific user groups that can access and use the Knowledge Base |
| Private | Only the owner can see and use it |
Administrators can manage group assignments to control which departments or teams have access to specific Knowledge Bases.
Managing Knowledge Bases¶
Adding Documents¶
Open a Knowledge Base and upload additional files at any time. New files are automatically processed and indexed.
Updating Documents¶
Delete the outdated document and upload the new version. The system re-embeds the updated content automatically. Alternatively, use Directory Sync to keep content current with an external source.
Deleting Documents¶
Open a Knowledge Base, select the document to remove, and click Delete. The associated vectors are removed from the database.
Storage Capacity¶
- The system provides a minimum of 400 GB initial storage for document uploads and vector data
- Storage can be expanded as needed without impacting system performance
Reference
For more technical details, see the Open WebUI — Knowledge (Workspace) documentation.