Skip to content

Local Index Optimization

This page covers advanced configuration options for indexed collections.

Choosing an Embedding Model

An embedding model converts your documents into a numeric form so the chatbot can search by meaning instead of exact keywords. It finds related content even when a participant uses different words. You choose the model when you create a local index, and it affects how relevant the retrieved content is.

Different embedding models have different strengths:

  • Some perform better on short, conversational text (FAQs, chat logs).
  • Others are optimised for long, technical documents (reports, manuals, legal text).
  • Models trained on domain-specific data (medical, legal, code) can outperform general-purpose models in those domains.

To see a provider's embedding models, open the Models tab of its page in your team's LLM provider settings and filter for embedding models. If you are unsure which to choose, use the provider's default, which suits general-purpose retrieval.

Chunking and Optimization

Info

Chunk size and overlap apply to remote indexes too. For a remote index, OCS passes them to the provider when it adds the files.

OCS breaks each document uploaded to a local index into smaller parts called chunks, converts each chunk into a vector and stores it in the index. The default chunking strategy works well in most cases. If needed, you can customise it per set of uploaded files:

Setting What it controls When to adjust
Chunk size How large each chunk is, measured in tokens Increase for long, dense documents; decrease for short snippets
Chunk overlap How much each chunk overlaps with the next Increase to preserve context across chunk boundaries

Files synced by a document source always use a chunk size of 800 tokens and an overlap of 400 tokens. You can't change these values per source.

Guidelines

  • Short documents or FAQs: Use smaller chunks (e.g. 256–512 tokens) with low overlap. Each answer fits in one chunk, so large chunks add noise.
  • Long technical documents or reports: Use larger chunks (e.g. 512–1024 tokens) with moderate overlap (10–20%) to preserve context across sections.
  • Structured data (tables, forms): Experiment with overlap settings — tables often lose meaning when split mid-row.

Changing the chunking strategy after upload requires re-indexing your files.

CSV/TSV row import limits

Importing a .csv or .tsv file as individual rows is an alternative to chunking. It's available for local indexes only. See Importing CSV/TSV rows for the concept, and Import CSV/TSV Rows into a Collection for the steps.

Three limits apply to a row import:

Limit Default What it controls
COLLECTION_ROW_IMPORT_MAX_ROWS 10,000 Maximum number of rows a single import can hold
COLLECTION_ROW_IMPORT_MAX_ROW_TOKENS 2,000 Maximum tokens allowed per rendered row before it's rejected
COLLECTION_FILE_MAX_METADATA_COLUMNS 16 Maximum number of columns that can be kept as metadata per row

These are constants in the application settings, not environment variables, so self-hosted operators who need different limits must override the settings values in their deployment.