When working with Knowledge Bases there are several aspects you must take into account so that the knowledge base responses are correct.
RAG optimization with documents does not depend only on the language model: it starts much earlier, in how the documents that make up your knowledge base are prepared, cleaned, and indexed. In this article we review the key factors that determine the quality of answers in a RAG system and how to configure them correctly in Athento.
Supported document formats
Only the following formats can be indexed: PDF, DOCX, TXT, HTML, EML, PNG. Documents in other formats must be converted before being ingested.
Content extraction — OCR matters
The system tries to extract text in this order for PDFs:
- Previously extracted text (for example, from an OCR function value executed earlier)
- Full OCR through the platform’s OCR pipeline
- Raw text extraction
This means that the scanned PDFs or those with many images and no embedded text layer will only produce useful results if OCR has already been run on them. A scanned PDF that has never gone through OCR will return empty or illegible content to the knowledge base, which will lead to poor or null answers. Make sure to run OCR on scanned documents before adding them to a knowledge base.
PNG files also depend on OCR: an image without an OCR result will not contribute anything.
The text extraction operation is not necessary for native PDFs. The system extracts the text automatically at the time of indexing. Where you do need to intervene is in:
- Scanned PDFs / image-only PDFs → OCR must be run first; otherwise, step 3 returns illegible or empty text
- PNGs → same, OCR is mandatory
- DOCX files → textract can also handle them as an alternative, but if a conversion to PDF operation has already been run, that result takes priority
How much text is actually sent to the AI
There is a limit of 5,000 characters of content per document when building the prompt sent to the LLM (configurable, but 5,000 is the default value). In addition, the embedding generation step limits the text to 6,000 characters.
This means that the very long documents are truncated. If the most relevant information is buried in the last pages of a document (for example, page 20 of a 40-page contract), it may not be captured. For long documents, consider:
- Using the chunk extraction operation (see below)
- Splitting large documents into logical sub-documents
- Ensuring that key information appears at the beginning of the document
The text sent to the AI also includes the file name, metadata field values, and lifecycle status, not just the body content. Files with good names and complete metadata fields improve retrieval accuracy.
Chunking — optional but recommended for long documents
There is an optional operation called op_extract_relevant_file_chunks that can be configured by document type. It splits the document into word-based chunks and selects the most representative ones according to a keyword score.
Key parameters:
- chunk-size: Number of words per chunk (default: 300 words)
- num-top-chunks: How many chunks to keep (default: 2)
- keywords: Keywords that guide which chunks are considered more relevant
When the knowledge base has the “use chunks” option enabled, it retrieves these pre-extracted chunks instead of the full document content.
Recommendations:
- Chunking is very beneficial for long documents (contracts, manuals, reports)
- Chunks should be configured as a document operation and executed before generating embeddings
- Choosing relevant domain keywords improves the quality of chunk selection
- Without chunking, the 5,000-character limit means that only the beginning of long documents is used.
The top_n parameter — balance between speed and quality
The top_n parameter controls how many documents are retrieved from the vector index for each question. The default value is 5.
Retrieval itself (vector search) is fast regardless of top_n. The real cost of a high top_n is that more document content is concatenated into the prompt sent to the LLM, which increases latency and token usage.
Recommendation: Start with the default value of 5. If answers omit information that you know is in the knowledge base, increase top_n. If response time or cost is a concern, reduce it. The optimal value depends on how homogeneous the document collection is: a knowledge base with very similar documents benefits more from a high top_n than one with very diverse content.
Document metadata improves retrieval
The embedding text includes values from metadata fields configured as “source metadata” in the knowledge base. This means that a document with rich and accurate metadata (for example, document type, subject, author, department) will be easier to find than one with empty metadata.
Recommendation: Define which types of metadata are semantically most significant and make sure they are filled in before indexing.
Cleaning documents before indexing
The system does not perform automatic text cleaning beyond extraction. Documents with:
- OCR errors (illegible characters, incorrect word splitting)
- Repeated headers/footers on each page (repetitive legal text, page numbers)
- Tables in PDF format (often extracted as illegible strings)
- Multiple languages mixed in the same file
…will produce lower-quality embeddings and, therefore, worse retrieval.
Recommendation: Review and clean documents, especially if they come from scans or legacy systems. Plain, well-structured text is extracted with higher quality.
Re-indexing after changes to documents
The system uses a SHA hash per document to detect changes. Embeddings are only regenerated when the document content has changed and the --update-existing flag is used in the management command. Documents that have been corrected or re-processed with OCR will not be re-indexed automatically: this must be explicitly enabled.
Recommendation: After any mass document update or OCR correction campaign, rerun embedding generation with --update-existing to ensure that the index reflects the current state of the documents.
The embedding model affects quality and language support
The system supports multiple embedding models. For multilingual document collections (especially in Spanish), models such as intfloat/multilingual-e5-large or embed-multilingual-v3.0 will outperform English-only models such as all-MiniLM-L6-v2.p
Useful operations for RAG optimization with documents
Athento includes specific operations that you can configure by document type to improve indexing quality and, thereby, the accuracy of your RAG system’s answers.
Entity extraction from a PDF
Name in the platform: Extract entities from a PDF
This operation uses spaCy’s xx_ent_wiki_sm model, a named entity recognition (NER) model trained on Wikipedia that works in Spanish, English, and other languages without additional configuration.
Entities it detects:
- PER — People (proper nouns)
- ORG — Organizations (companies, institutions)
- MISC — Miscellaneous proper nouns (brands, events, nationalities, etc.)
This operation does not detect geographic locations (LOC). If you need to identify place names, keep this in mind before configuring it.
Link to the documentation: https://help.athento.com/es/docs/extraccion-de-entidades-desde-un-pdf/
Recommendation: Run this operation before generating the knowledge base embeddings. If the results are stored in a metadata field included in the KB’s source_metadata, each document’s embedding will incorporate the names of people and companies found in it, which significantly improves semantic search for queries such as “documents that mention company X” or “contracts in which person Y participates”.
Native PDF to Markdown conversion
Name in the platform: Native PDF to Markdown
This operation uses PyMuPDF to read the internal font and layout data of the PDF and convert it into a structured Markdown file, which is saved as a related document linked to the original.
What it does intelligently:
- Detects headings by font size relative to body text (H1 ≥ 1.55×, H2 ≥ 1.30×, H3 ≥ 1.12× + bold, or numbered sections such as 1.1 Title)
- Detects and automatically removes repeated headers and footers between pages
- Removes page-number lines
- Fixes end-of-line hyphens (for example, docu-\nmento → documento)
Why this matters for the knowledge base:
The generated .md file is a TXT-type document that the knowledge base can index directly, with two important advantages over the original PDF:
- Headings provide semantic structure — the model better understands that a text fragment belongs to a specific section.
- Repeated headers and footers are removed — the 5,000-character limit is not wasted on repetitive text. In long documents with headers and footers on each page, this can make a real difference in what content actually reaches the embedding and the LLM.
This operation only works with native PDFs that have a real text layer. Scanned PDFs must first go through OCR.
Link to the documentation: https://help.athento.com/es/docs/conversion-de-pdf-nativo-a-markdown/