154 lines
No EOL
12 KiB
Text
154 lines
No EOL
12 KiB
Text
---
|
|
title: Configure knowledge
|
|
slug: /knowledge
|
|
---
|
|
|
|
import Icon from "@site/src/components/icon/icon";
|
|
import PartialOpenSearchAuthMode from '@site/docs/_partial-opensearch-auth-mode.mdx';
|
|
|
|
OpenRAG includes a built-in [OpenSearch](https://docs.opensearch.org/latest/) instance that serves as the underlying datastore for your _knowledge_ (documents).
|
|
This specialized database is used to store and retrieve your documents and the associated vector data (embeddings).
|
|
|
|
The documents in your OpenSearch knowledge base provide specialized context in addition to the general knowledge available to the language model that you select when you [install OpenRAG](/install-options) or [edit a flow](/agents).
|
|
|
|
You can [upload documents](/ingestion) from a variety of sources to populate your knowledge base with unique content, such as your own company documents, research papers, or websites.
|
|
Documents are processed through OpenRAG's knowledge ingestion flows with Docling.
|
|
|
|
Then, the [OpenRAG **Chat**](/chat) can run [similarity searches](https://www.ibm.com/think/topics/vector-search) against your OpenSearch database to retrieve relevant information and generate context-aware responses.
|
|
|
|
You can configure how documents are ingested and how the **Chat** interacts with your knowledge base.
|
|
|
|
## Browse knowledge {#browse-knowledge}
|
|
|
|
The **Knowledge** page lists the documents OpenRAG has ingested into your OpenSearch database, specifically in an [OpenSearch index](https://docs.opensearch.org/latest/getting-started/intro/#index) named `documents`.
|
|
|
|
To explore the raw contents of your knowledge base, click <Icon name="Library" aria-hidden="true"/> **Knowledge** to get a list of all ingested documents.
|
|
Click a document to view the chunks produced from splitting the document during ingestion.
|
|
|
|
### Default documents {#default-documents}
|
|
|
|
By default, OpenRAG includes some initial documents about OpenRAG.
|
|
These documents are ingested automatically during the [application onboarding process](/install#application-onboarding).
|
|
|
|
You can use these documents to ask OpenRAG about itself, and to test the [**Chat**](/chat) feature before uploading your own documents.
|
|
|
|
If you [delete](#delete-knowledge) these documents, you won't be able to ask OpenRAG about itself and it's own functionality.
|
|
It is recommended that you keep these documents, and use [filters](/knowledge-filters) to separate them from your other knowledge.
|
|
|
|
## OpenSearch authentication and document access {#auth}
|
|
|
|
When you [install OpenRAG](/install-options), you provide the initial configuration values for your OpenRAG services, including authentication credentials for OpenSearch and OAuth connectors.
|
|
This configuration determines how OpenRAG authenticates with your deployment's OpenSearch instance, and it controls user access to documents in your knowledge base:
|
|
|
|
<PartialOpenSearchAuthMode />
|
|
|
|
## OpenSearch indexes
|
|
|
|
An [OpenSearch index](https://docs.opensearch.org/latest/getting-started/intro/#index) is a collection of documents in an OpenSearch database.
|
|
|
|
By default, all documents you upload to your OpenRAG knowledge base are stored in an index named `documents`.
|
|
|
|
It is possible to change the index name by [editing the ingestion flow](/agents#inspect-and-modify-flows).
|
|
However, this can impact dependent processes, such as the [filters](/knowledge-filters) and [**Chat**](/chat) flow, that reference the `documents` index by default.
|
|
Make sure you edit other flows as needed to ensure all processes use the same index name.
|
|
|
|
If you encounter errors or unexpected behavior after changing the index name, you can [revert the flows to their original configuration](/agents#revert-a-built-in-flow-to-its-original-configuration), or [delete knowledge](/knowledge#delete-knowledge) to clear the existing documents from your knowledge base.
|
|
|
|
## Knowledge ingestion settings {#knowledge-ingestion-settings}
|
|
|
|
:::warning
|
|
Knowledge ingestion settings apply to documents you upload after making the changes.
|
|
Documents uploaded before changing these settings aren't reprocessed.
|
|
:::
|
|
|
|
After changing knowledge ingestion settings, you must determine if you need to reupload any documents to be consistent with the new settings.
|
|
|
|
It isn't always necessary to reupload documents after changing knowledge ingestion settings.
|
|
For example, it is typical to upload some documents with OCR enabled and others without OCR enabled.
|
|
|
|
If needed, you can use [filters](/knowledge-filters) to separate documents that you uploaded with different settings, such as different embedding models.
|
|
|
|
### Set the embedding model and dimensions {#set-the-embedding-model-and-dimensions}
|
|
|
|
When you [install OpenRAG](/install-options), you select at least one embedding model during the [application onboarding process](/install#application-onboarding).
|
|
OpenRAG automatically detects and configures the appropriate vector dimensions for your selected embedding model, ensuring optimal search performance and compatibility.
|
|
|
|
In the OpenRAG repository, you can find the complete list of supported models in [`models_service.py`](https://github.com/langflow-ai/openrag/blob/main/src/services/models_service.py) and the corresponding vector dimensions in [`settings.py`](https://github.com/langflow-ai/openrag/blob/main/src/config/settings.py).
|
|
|
|
During the application onboarding process, you can select from the supported models.
|
|
The default embedding dimension is `1536`, and the default model is the OpenAI `text-embedding-3-small`.
|
|
|
|
If you want to use an unsupported model, you must manually set the model in your [OpenRAG `.env` file](/reference/configuration).
|
|
If you use an unsupported embedding model that doesn't have defined dimensions in `settings.py`, then OpenRAG falls back to the default dimensions (1536) and logs a warning. OpenRAG's OpenSearch instance and flows continue to work, but [similarity search](https://www.ibm.com/think/topics/vector-search) quality can be affected if the actual model dimensions aren't 1536.
|
|
|
|
To change the embedding model after onboarding, it is recommended that you modify the embedding model setting in the OpenRAG **Settings** page or in your [OpenRAG `.env` file](/reference/configuration).
|
|
This will automatically update all relevant [OpenRAG flows](/agents) to use the new embedding model configuration.
|
|
|
|
### Set Docling parameters
|
|
|
|
OpenRAG uses [Docling](https://docling-project.github.io/docling/) for document ingestion because it supports many file formats, processes tables and images well, and performs efficiently.
|
|
|
|
When you [upload documents](/ingestion), Docling processes the files, splits them into chunks, and stores them as separate, structured documents in your OpenSearch knowledge base.
|
|
|
|
You can use either Docling Serve or OpenRAG's built-in Docling ingestion pipeline to process documents.
|
|
|
|
* **Docling Serve ingestion**: By default, OpenRAG uses [Docling Serve](https://github.com/docling-project/docling-serve).
|
|
This means that OpenRAG starts a `docling serve` process on your local machine and runs Docling ingestion through an API service.
|
|
|
|
* **Built-in Docling ingestion**: If you want to use OpenRAG's built-in Docling ingestion pipeline instead of the separate Docling Serve service, set `DISABLE_INGEST_WITH_LANGFLOW=true` in your [OpenRAG environment variables](/reference/configuration#document-processing-settings).
|
|
|
|
The built-in pipeline uses the Docling processor directly instead of through the Docling Serve API.
|
|
|
|
For the underlying functionality, see [`processors.py`](https://github.com/langflow-ai/openrag/blob/main/src/models/processors.py#L58) in the OpenRAG repository.
|
|
|
|
To modify the Docling ingestion and embedding parameters, click <Icon name="Settings2" aria-hidden="true"/> **Settings** in the OpenRAG user interface.
|
|
|
|
:::tip
|
|
OpenRAG warns you if `docling serve` isn't running.
|
|
For information about starting and stopping OpenRAG native services, like Docling, see [Manage OpenRAG services](/manage-services).
|
|
:::
|
|
|
|
* **Embedding model**: Select the model to use to generate vector embeddings for your documents.
|
|
|
|
This is initially set during installation.
|
|
The recommended way to change this setting is in the OpenRAG **Settings** or your [OpenRAG `.env` file](/reference/configuration).
|
|
This will automatically update all relevant [OpenRAG flows](/agents) to use the new embedding model configuration.
|
|
|
|
If you uploaded documents prior to changing the embedding model, you can [create filters](/knowledge-filters) to separate documents embedded with different models, or you can reupload all documents to regenerate embeddings with the new model.
|
|
If you want to use multiple embeddings models, similarity search (in the **Chat**) can take longer as it searching each model's embeddings separately.
|
|
|
|
* **Chunk size**: Set the number of characters for each text chunk when breaking down a file.
|
|
Larger chunks yield more context per chunk, but can include irrelevant information. Smaller chunks yield more precise semantic search, but can lack context.
|
|
The default value is 1000 characters, which is usually a good balance between context and precision.
|
|
|
|
* **Chunk overlap**: Set the number of characters to overlap over chunk boundaries.
|
|
Use larger overlap values for documents where context is most important. Use smaller overlap values for simpler documents or when optimization is most important.
|
|
The default value is 200 characters, which represents an overlap of 20 percent if the **Chunk size** is 1000. This is suitable for general use. For faster processing, decrease the overlap to approximately 10 percent. For more complex documents where you need to preserve context across chunks, increase it to approximately 40 percent.
|
|
|
|
* **Table Structure**: Enables Docling's [`DocumentConverter`](https://docling-project.github.io/docling/reference/document_converter/) tool for parsing tables. Instead of treating tables as plain text, tables are output as structured table data with preserved relationships and metadata. This option is enabled by default.
|
|
|
|
* **OCR**: Enables Optical Character Recognition (OCR) processing when extracting text from images and ingesting scanned documents. This setting is best suited for processing text-based documents faster with Docling's [`DocumentConverter`](https://docling-project.github.io/docling/reference/document_converter/). Images are ignored and not processed.
|
|
|
|
This option is disabled by default. Enabling OCR can slow ingestion performance.
|
|
|
|
If OpenRAG detects that the local machine is running on macOS, OpenRAG uses the [ocrmac](https://www.piwheels.org/project/ocrmac/) OCR engine. Other platforms use [easyocr](https://www.jaided.ai/easyocr/).
|
|
|
|
* **Picture descriptions**: Only applicable if **OCR** is enabled. Adds image descriptions generated by the [`SmolVLM-256M-Instruct`](https://huggingface.co/HuggingFaceTB/SmolVLM-Instruct) model. Enabling picture descriptions can slow ingestion performance.
|
|
|
|
### Set the local documents path {#set-the-local-documents-path}
|
|
|
|
The default path for local uploads is the `./openrag-documents` subdirectory in your OpenRAG installation directory. This is mounted to the `/app/openrag-documents/` directory inside the OpenRAG container. Files added to the host or container directory are visible in both locations.
|
|
|
|
To change this location, modify the **Documents Paths** variable in either the [**Advanced Setup** menu](/install#setup) or in your [OpenRAG `.env` file](/reference/configuration).
|
|
|
|
## Delete knowledge {#delete-knowledge}
|
|
|
|
To clear your entire knowledge base, delete the contents of the `./opensearch-data` folder in your OpenRAG installation directory.
|
|
This is a destructive operation that cannot be undone.
|
|
|
|
## See also
|
|
|
|
* [Ingest knowledge](/ingestion)
|
|
* [Filter knowledge](/knowledge-filters)
|
|
* [Chat with knowledge](/chat)
|
|
* [Inspect and modify flows](/agents#inspect-and-modify-flows) |