Skip to content

OpenRAG is a comprehensive, single package Retrieval-Augmented Generation platform built on Langflow, Docling, and Opensearch.

Python

reduce chunk size troubleshooting (#1461)

April I. Murphy634f3afee512
diff --git a/docs/docs/core-components/ingestion-configure.mdx b/docs/docs/core-components/ingestion-configure.mdx
index 64951f36f..8f7252e6e 100644
--- a/docs/docs/core-components/ingestion-configure.mdx
+++ b/docs/docs/core-components/ingestion-configure.mdx
@@ -87,13 +87,34 @@ This is because the agent cannot access the model to generate a query embedding
You can edit the following settings on the OpenRAG <Icon name="Settings2" aria-hidden="true"/> **Settings** page in the **Knowledge Ingest** section:
-* **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 size**: Set the average 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.
+
+ :::warning
+ The **Chunk size** must be less than the maximum token length supported by your embedding model.
+ To determine this value, see the documentation for your embedding model or provider.
+
+ Because **Chunk size** is an average, actual chunks can be larger or smaller than the specified value.
+ To account for variations in chunking and ensure that no chunks exceed the model's limits, **Chunk size** must _not_ be equal to the model's maximum token length.
+
+ If ingestion fails with errors like `ContextLengthExceeded` and `reduce the length of the input`, this indicates that some chunks exceed the model's maximum token length.
+ Decrease the **Chunk size**, and then retry ingestion.
+ Repeat this process until you find a value that works consistently for your documents and embedding model.
+ :::
* **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 with the default **Chunk size** of 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.
+
+ 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 with the default **Chunk size** of 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.
## Configure table parsing
diff --git a/docs/docs/get-started/tui.mdx b/docs/docs/get-started/tui.mdx
index 72a559690..0cc3ee205 100644
--- a/docs/docs/get-started/tui.mdx
+++ b/docs/docs/get-started/tui.mdx
@@ -21,7 +21,7 @@ If you installed OpenRAG with `uvx`, start a terminal session with `uvx openrag`
### Start a GUI terminal session
-:::important
+:::info
The GUI terminal (TUI) is required to access certain controls like **Factory Reset**, **GPU/CPU mode**, and **Upgrade**.
:::
diff --git a/docs/docs/support/troubleshoot.mdx b/docs/docs/support/troubleshoot.mdx
index 94c2ce680..f1df75a5c 100644
--- a/docs/docs/support/troubleshoot.mdx
+++ b/docs/docs/support/troubleshoot.mdx
@@ -162,6 +162,8 @@ The following issues can occur during document ingestion or as a result of subop
If an ingestion task fails, try the following:
* Make sure you ingest only [supported file types](/ingestion#supported-file-types).
+* Make sure the [ingestion settings](/ingestion-configure) are appropriate for your embedding model.
+For example, the **Chunk size** cannot exceed the maximum token length supported by your embedding model.
* Split very large files into smaller files.
* Remove unusual or complex embedded content, such as videos or animations. Although Docling can replace some non-text content with placeholders during ingestion, some embedded content might cause errors.
* Make sure your Podman/Docker VM has [sufficient memory](/support/troubleshoot#container-out-of-memory-errors) and temporary storage for the ingestion tasks.