Skip to main content
Version: v1.7.5-2 🚧

Ingestion modes

When you add documents to a Collection, Enterprise h2oGPTe processes each file so it can be searched and used for retrieval-augmented generation (RAG). The ingestion mode controls how much processing each file receives, which affects retrieval quality, ingestion speed, and whether an agent can read the original file.

This page describes the three ingestion modes and helps you pick the right mode for your files and goals. To set the mode when you add documents, see the Ingest Mode option in Add documents to a Collection.

The three ingestion modes​

h2oGPTe offers three ingestion modes. The following table summarizes how they differ.

ModeProcessingSearchable by RAGBest for
Standard (default)Selective OCR, layout and table analysis, and image captioningYesHighest retrieval quality for most documents
LiteUp to 2× faster; skips layout and table analysis for every file, and skips OCR for non-image filesYesClean, text-based files with simple structure
Agent OnlyNone; the original file is stored as-isNo (agent access only)Files an agent reads or computes over directly

If you don't specify a mode, h2oGPTe uses Standard.

note

Both Standard and Lite can also generate short document summaries and sample questions when you enable those upload options, and both generate a document thumbnail automatically. Agent Only produces none of them.

Standard​

Standard is the default mode and produces the highest retrieval quality. It includes:

  • Selective OCR. For each page, h2oGPTe checks whether text can be extracted directly:
    • If the page already has extractable text, h2oGPTe skips OCR.
    • If the page has no extractable text, such as a scan or a photo, h2oGPTe runs OCR on the whole page, unless the page is a solid color.
    • If the page mixes text and images, h2oGPTe runs OCR only on the embedded images that are large enough to hold readable content and are not a single solid color.
  • Layout and table analysis. h2oGPTe detects tables, figures, titles, and section headers, and keeps tables intact during chunking.
  • Infographic detection and image captioning. h2oGPTe detects figures and infographics, then a vision-language model writes a short caption for each page that contains one. Because the caption is embedded like any other text, you can find the figure by searching for what it depicts.
  • Chunking and embedding. The document becomes fully searchable for RAG.

Best for: scanned or photographed documents, complex layouts, tables, forms, and non-Latin or handwritten text.

Lite​

Lite ingests files up to 2× faster than Standard by skipping the most time-consuming steps. Files remain searchable by RAG, but with less structural detail:

  • Non-image files. h2oGPTe skips both OCR and layout and table analysis, and extracts the native text of each page.
  • Image files. h2oGPTe still runs OCR but skips layout and table analysis.
  • Infographics and captions. h2oGPTe does not run infographic detection, and it does not caption figures embedded inside other documents. Image files still receive a caption.

Best for: digital, text-based files with a simple structure, such as plain text, code, Markdown, configuration files, and clean single-column PDFs without important tables.

note

Lite is not recommended for scanned documents or for PDFs whose images contain text you need to search. Use Standard for those files.

Agent Only​

Agent Only bypasses ingestion entirely. h2oGPTe stores the original file exactly as uploaded, with no PDF conversion, no OCR, no chunking, and no embedding.

Because the file is never embedded, Agent Only files are not searchable by RAG or by normal chat retrieval. They are usable only when an agent is involved: the agent receives the whole, original file and can read it or run code over it.

Best for: large data files an agent computes over, such as spreadsheets and CSVs; files that require calculation rather than semantic search; and custom agent tool code. Agent Only is also the only mode that accepts unsupported or unknown extensions. Because nothing is unpacked, an archive uploaded as Agent Only is stored as a single archive file; Standard and Lite unpack the archive and ingest each file inside it as its own document.

tip

Because Agent Only files are never parsed, h2oGPTe does not run document-level PII detection or redaction on them, and it stores audio and video as raw media rather than transcribing them. Use Standard or Lite if you need document-level PII handling or a searchable transcript.

CSV, TSV, XLS, and XLSX files are the exception. If the Collection's PII parse action is Redact or Fail, h2oGPTe checks their columns for PII before it stores them and blanks any column whose sampled values are mostly PII, even in Agent Only.

Choose a mode by file type​

The following table recommends a mode for common file types. For the full list of file types h2oGPTe accepts, see Supported file types for a Collection.

File typeRecommended modeWhy
Scanned or photographed PDFsStandardOCR is needed to extract any text.
Digital PDFs with complex layout or tablesStandardLayout and table analysis runs only in Standard.
Digital PDFs with a simple, single-column layoutLiteLittle to gain from OCR or layout analysis, and Lite is faster. Use Standard if you are not certain every page has extractable text, because Lite runs no OCR on PDFs and a scanned page produces no searchable text.
Word or PowerPoint files with rich formattingStandardPreserves tables and layout after PDF conversion.
ImagesStandardFull OCR and image captioning make the text searchable.
Small spreadsheets or CSVs (500 KB or smaller)StandardTable-aware parsing keeps rows meaningful.
Large spreadsheets or CSVs (larger than 500 KB)Agent Only (or leave the default)On Standard or no selection, files this size are auto-promoted to Agent Only so an agent can read every row; only an explicit Lite keeps it in RAG, where it sees just a summary.
Plain text, code, JSON, XML, YAML, or configuration filesLiteAlready plain text, so OCR and layout analysis add nothing.
Markdown or reStructuredTextLiteLightweight text that needs no extra processing.
HTML, SVG, or web pagesStandard, or Lite for simple pagesStandard captures the visual and layout content of the rendered page. Choose Lite for text-heavy HTML pages with no important figures, such as a large web crawl. Keep Standard for SVG, whose text can be drawn as shapes that only OCR can read.
E-booksStandardOften contain images and figures worth OCR and captioning.
Email (.eml, .msg)Standardh2oGPTe converts the message and each supported attachment into a single PDF, so attachment content is searchable. Attachments in unsupported formats are left out.
Archives (.zip, .tar, .gz, .tgz, .bz2, .tbz2, .xz, .txz)Standard or Liteh2oGPTe unpacks the archive and ingests each contained file as its own document. Agent Only stores the archive as a single unopened file.
AudioStandard or LiteTranscription happens in the convert stage, so the transcript is the same in both modes — choose Lite for faster ingestion.
VideoStandard or LiteAudio is transcribed and, when a vision model is configured, visual scenes are captioned during conversion — the result is the same in both modes, so choose Lite for faster ingestion.
Non-Latin or handwritten documentsStandardSelects a language-specific OCR or handwriting model.
Custom agent tool code or files for computationAgent OnlyThe agent should read the whole file rather than search chunks.
Unsupported or unknown extensionsAgent OnlyOther modes reject files they can't parse; Agent Only stores the original for the agent.

Choose a mode by use case​

Pick a mode based on what you want to do with your files.

  • Chat with or search your documents: Use Standard for the best quality, especially for scans, images, tables, and complex layouts. Drop to Lite when you have many clean, text-only files and want faster ingestion.
  • Ingest many simple documents: Use Lite for plain text, code, Markdown, and clean digital PDFs.
  • Analyze a large dataset or run calculations on a spreadsheet: Use Agent Only and query the file with an agent so it can read every row. RAG alone cannot answer questions about the individual rows of a large spreadsheet — for how h2oGPTe handles tabular files larger than 500 KB in each mode, see How h2oGPTe handles large tabular files.
  • Perform exact lookups or full-file reasoning: Use Agent Only. Chunk-based retrieval returns only the top-ranked chunks most relevant to your query, so it can miss exact values or omit relevant rows. An agent that reads the whole file can do precise, deterministic work.
  • Upload custom tool code or a file the agent uses directly: Use Agent Only. Set the upload's Ingest Mode to Agent Only. For a Collection dedicated to agent tools, you can also set Agent Only as the Collection's default so that new uploads use it automatically.
  • Add files from an agent chat: When the agent is turned on in a chat, files you add from that chat have Ingest Mode preset to Agent Only, so they are not searchable by RAG. Change the mode in the upload dialog if you also need RAG search.
  • Make audio or video searchable: Use Standard or Lite; do not use Agent Only, which stores the raw media without transcribing it. Both modes transcribe the audio and, for video, caption the visual scenes when a vision model is configured. Because both modes produce the same transcript, prefer Lite for faster ingestion. Speaker diarization is enabled by default, so transcripts include speaker labels, and for video h2oGPTe embeds the combined timestamped transcript for RAG.

How h2oGPTe handles large tabular files​

Large tabular files behave differently from other files, because embedding only a summary of a large spreadsheet loses the individual rows.

  • Automatic promotion to Agent Only: When you upload a CSV, TSV, XLS, or XLSX file larger than 500 KB without specifying a mode, or with Standard selected, h2oGPTe automatically switches it to Agent Only so an agent can read every row. h2oGPTe honors an explicit Lite or Agent Only request as-is.
  • Statistical summary under RAG: If a tabular file larger than 500 KB stays in the RAG path, which happens with an explicit Lite request, h2oGPTe reduces it to a describe()-style statistical summary. Retrieval can then answer questions about the summary, but not about individual rows. Setting Lite as the Collection's default Ingest Mode counts as an explicit Lite request, so large tabular files uploaded to that Collection are summarized instead of promoted.

Change a file's mode after upload​

You are not locked into the mode you chose at upload time.

  • Re-ingest Agent Only files into Standard: Files uploaded as Agent Only can be re-ingested into full Standard RAG later, either through a UI action or the ingest_agent_only_to_standard API. Two kinds of file cannot be converted, and h2oGPTe skips them without reporting an error: a file whose extension h2oGPTe does not support, which has no parsing path, and a CSV, TSV, XLS, or XLSX file larger than 500 KB, which automatic promotion returns to Agent Only. To make a large tabular file searchable, split it into files of 500 KB or smaller, or upload it again with Lite selected to index a statistical summary.
  • Set a mode when copying between Collections: When you import one Collection into another, you can apply a new ingest mode to all documents. Turn on Preserve Document Status to keep Agent Only documents as Agent Only while other documents follow the mode you select.

Next steps​

Feedback