Files & Retrieval turns an upload into model context through upload checks, extraction, OCR, full-text injection, embedding, RAG, and compaction. This page shows the real order, the fallbacks, and the setting keys behind each stage.
Where to find it#
Admin console > Files & retrieval. The page groups settings as Upload limits, Content extraction, Full-text injection, Vector retrieval, Semantic enhancement, and RAG. Context compaction lives in Conversation > Context management.
How a file becomes context#
- Upload checks count, size, MIME type, and the user's storage quota.
- The file is stored and its type is detected.
- Text is extracted. Images use OCR, and PDFs can fall back to OCR.
- Each attachment is assigned a context mode:
- A current or user-message image is sent as a direct image.
- Otherwise the system chooses full-text injection or RAG.
- For RAG attachments, the query is embedded and chunks are retrieved, filtered by similarity, and bounded by the token budget.
- If retrieval returns nothing, fails, or times out, the attachment falls back to full text when it fits the limits, otherwise it is skipped.
- The assembled context is trimmed by token budget and compacted when it exceeds the turn or token trigger.
The full-text or RAG decision for Auto mode is:
- Use RAG when the file cannot be injected in full, or when token-budget protection is on and the file text exceeds 40% of the model's effective input budget.
- Use full text otherwise.
Full context mode never uses RAG. Vector retrieval mode always prefers RAG, but falls back to full text when a file is not retrievable. The user-side chat.file_mode setting is only a personal preference; the platform still applies its own limits.
Upload limits#
| Setting | Key | Notes |
|---|---|---|
| Attachment limit | storage.max_message_files | 1–50 files per message. |
| Default size limit | storage.max_upload_file_bytes | Default single-file limit. The UI uses MB. |
| User storage quota | storage.user_storage_quota_bytes | Total storage per user. The UI uses MB; 0 is unlimited. |
| Attachment MIME allowlist | file.allowed_mime_types | Comma-separated. Only listed types can be uploaded. |
| Image size limit | file.image_max_bytes | Overrides the default for images. Empty uses the default. |
| Document size limit | file.doc_max_bytes | Overrides the default for documents. Empty uses the default. |
The effective image or document limit is the smaller of the default limit and the override. If a MIME type is not on the allowlist, the upload is rejected before extraction runs.
Content extraction and OCR#
| Setting | Key | Notes |
|---|---|---|
| Extraction engine | extract.engine | builtin, tika, docling, or mineru. |
| Tika source / URL / key / timeout | extract.tika_source, extract.tika_base_url, extract.tika_auth_token, extract.tika_timeout_seconds | Source is external or managed. |
| Docling URL / key / timeout | extract.docling_base_url, extract.docling_auth_token, extract.docling_timeout_seconds | For layout-heavy documents. |
| MinerU source / URL / types / key / timeout | extract.mineru_source, extract.mineru_base_url, extract.mineru_file_types, extract.mineru_auth_token, extract.mineru_timeout_seconds | Source is cloud or self_hosted. Types are pdf, word, presentation, excel. |
| Image OCR | extract.image_ocr_enabled | Sends image attachments through OCR. Off by default. |
| PDF OCR fallback | extract.pdf_ocr_fallback_enabled | Runs OCR when native PDF text is missing or poor. Off by default. |
| OCR engine | extract.ocr_engine | rapidocr, tesseract, paddle, tencent, aliyun, mistral, or llm. |
When the selected engine does not support a file, the platform falls back to the built-in extractor for document files. For PDFs with OCR fallback on, it first probes the native text layer and runs selective OCR only on weak pages, then falls back to full OCR if needed.
Each OCR engine needs its own connection fields, for example extract.rapidocr_base_url, extract.tesseract_ocr_base_url, extract.paddle_ocr_base_url, extract.tencent_ocr_secret_id, extract.aliyun_ocr_access_key_id, extract.mistral_ocr_base_url, and extract.llm_ocr_base_url. Image OCR uses the configured vision model for llm; Mistral needs a base URL, API key, and model.
If image OCR is off, an image is stored without extracted text and can only be sent to a vision-capable model. If extraction fails on a document, the file stays previewable but has no searchable text.
Full-text injection#
Full-text injection puts the extracted text directly into the model context. It is exact and works well for small files, contracts, and short code, but it consumes context.
| Setting | Key | Notes |
|---|---|---|
| Full-text injection limits | file.full_context_limit_enabled | When off, the size, token, and page limits are ignored. |
| Full-text size limit | file.file_full_context_max_bytes | Extracted text bytes. The UI uses MB; empty or 0 is unlimited. |
| Full-text token limit | file.full_context_max_tokens | Token budget. Empty or 0 is unlimited. |
| Full-text page limit | file.full_context_pdf_max_pages | PDF pages. Empty or 0 is unlimited. |
A video is never injected as full text. A file is injected only when it has non-empty text and stays within every enabled limit. Files that do not fit move to RAG when retrieval is available, otherwise they are skipped.
Vector retrieval and embedding#
Embedding must be enabled and configured before RAG or semantic recall can be turned on. Changing the model, dimensions, or endpoint marks existing vectors stale.
| Setting | Key | Notes |
|---|---|---|
| Enable Embedding | file.embedding_enabled | Required for vectorization and retrieval. |
| Embedding service URL / auth key | file.embedding_host, file.embedding_key | The service must be OpenAI /embeddings compatible. |
| Embedding model | file.rag_model | Changing it invalidates old vectors. |
| Embedding timeout | file.embedding_timeout_seconds | Per-request wait in seconds. |
| Vector dimensions | file.embedding_output_dimensions | 64–4096. Must match the model output. |
| Dimensions request policy | file.embedding_dimensions_policy | send includes dimensions; omit drops it but still validates the returned vector against the configured dimensions. |
| Normalize vectors | file.embedding_normalize | L2-normalizes vectors before storage and retrieval. |
| Auto-vectorize | file.embed_trigger_on_upload | Triggers embedding after upload. |
| Batch size | file.embed_batch_size | Text chunks per embedding request. |
| Chunk size | file.embed_chunk_size_tokens | Token-estimated chunk size. |
| Chunk overlap | file.embed_chunk_overlap_tokens | Token overlap between chunks. |
| Retrieved chunks | file.rag_top_k | Final chunks returned and injected, 1–50. |
Use omit for services that reject the dimensions parameter. The returned vector is still checked against file.embedding_output_dimensions, so a mismatch fails instead of storing a wrong-size vector.
Vector index status#
The status panel shows a model signature and counts per state. The signature is generated automatically after the first save.
| State | Meaning | Action |
|---|---|---|
| Ready | Vectors match the current signature. | Retrieval works. |
| Stale | The model, dimensions, or endpoint changed. | Use Rebuild index. |
| Pending | Files are queued or processing. | Wait before testing retrieval. |
| No text | Extraction produced no text, so there is nothing to embed. | Check extraction, or use Reindex including no-text files after fixing OCR. |
| Failed | Vectorization failed. | Check extracted text, the embedding service, and chunk settings. |
When no index exists yet, the panel shows that no data is available until the embedding service is configured. If any vectors are stale, a reindex warning appears. Rebuilding is a background task and takes longer as the file count grows.
RAG#
| Setting | Key | Notes |
|---|---|---|
| RAG | chat.rag_enabled | Requires a ready embedding service. |
| Similarity threshold | chat.rag_min_similarity | Minimum score for an injected chunk. |
| Injected token budget | chat.rag_token_budget | Context budget for retrieved chunks. |
| Fetch multiplier | chat.rag_fetch_multiplier | Fetches top_k × multiplier candidates before filtering. |
| Ready wait | chat.rag_wait_ready_ms | Maximum wait for retrieval before sending. |
| Query history turns | chat.rag_query_history_turns | Recent user turns added to the retrieval query. |
| Retrieval cache TTL | chat.rag_retrieval_cache_ttl_seconds | Caches retrieval results; 0 disables the cache. |
| Hybrid retrieval | chat.rag_hybrid_enabled | Runs vector and full-text search in parallel and merges with RRF. |
The cache key includes the query, the embedding host and model, dimensions, retrieval settings, and each file's ID, chunk count, embed status, and updated time, so editing a file invalidates its cached results.
A high threshold can return nothing; a low threshold adds noise. When no chunk passes, the system does not inject unrelated content. It falls back to full text for those attachments when they fit, otherwise it skips them. If a knowledge base was explicitly selected, an unavailable knowledge base stops the send, while an empty result adds a notice that there is no knowledge-base evidence.
Semantic enhancement#
| Setting | Key | Notes |
|---|---|---|
| Message embedding | chat.message_embedding_enabled | Generates message vectors after each turn. Requires the embedding service. |
| Semantic context recall | chat.semantic_context_enabled | Recalls historically relevant snippets before sending. Requires message embedding. |
Enabling semantic context recall while message embedding is off is rejected. Both features share the embedding service, so an embedding change also affects historical recall quality.
Context compaction#
Compaction is configured in Conversation > Context management. It summarizes older turns so long conversations stay inside the model budget.
| Setting | Key | Notes |
|---|---|---|
| Context compression | chat.context_compact_enabled | Master switch; users can still opt out in chat settings. |
| Token budget protection | chat.context_token_budget_enabled | Trims history by the model's effective input budget. |
| Compression trigger turns | chat.context_max_turns | Trigger when the conversation exceeds this turn count; 0 disables it. |
| Default context window | chat.context_window_fallback_tokens | Used when the model window cannot be identified. |
| Compression trigger ratio | chat.context_compact_trigger_percent | Trigger at this percentage of the effective input budget; 0 disables it. |
| Recent turns to preserve | chat.context_compact_preserve_recent_turns | Recent raw turns kept during compression. |
| Highlights per role | chat.context_compact_highlights_per_role | Summary highlights per user and assistant role. |
| Snippet character limit | chat.context_compact_snippet_chars | Maximum characters in one message snippet. |
| Evidence retention days | chat.context_artifact_retention_days | Retention for RAG, history, and tool evidence; 0 disables expiry. |
| Background compression | chat.compact_async_enabled | Runs compression after the response. |
| LLM compression | chat.compact_llm_enabled | Uses a model for semantic summaries; off uses template summaries only. |
| Compression model | chat.compact_task_model | follow uses the current model, falling back to the default chat model. |
| Circuit threshold | chat.compact_max_failures | After this many consecutive failures, falls back to template summaries. |
| Full / light summary prompt | chat.compact_system_prompt, chat.compact_light_prompt | Custom summary instructions. |
Fallback rules#
| Condition | Behavior |
|---|---|
| Upload check fails | The file is rejected. |
| Extraction fails | The file is previewable but has no searchable text. |
| OCR is off or fails | Image or scanned text stays unavailable to non-vision models. |
| Full text exceeds a limit | The file moves to RAG, or is skipped if retrieval is unavailable. |
| Embedding is off | RAG and semantic recall are unavailable. |
| Index is stale or failed | Retrieval is incomplete; rebuild the index. |
| RAG returns nothing | No unrelated chunks are injected; full text is used when it fits. |
| Context is too long | Token-budget trimming or compaction runs. |
Verify the setup#
- Set upload count, size, MIME, image and document limits, and the storage quota.
- Configure an extraction engine and test PDF, Word, spreadsheet, and text files.
- Enable image OCR and PDF OCR fallback only where needed, then configure the matching engine.
- Turn on full-text injection limits for small documents.
- Configure the embedding service, model, dimensions, chunking, and auto-vectorization.
- Upload sample files and confirm the index state is Ready.
- Turn on RAG and tune similarity, top K, token budget, and hybrid retrieval.
- For long sessions, turn on message embedding, semantic recall, and compaction.
Troubleshooting#
| Symptom | Cause | Fix |
|---|---|---|
| Upload is rejected | MIME type, size, count, or quota. | Check the allowlist and the size and quota limits. |
| The model cannot answer from a file | Extraction failed or the index is not ready. | Check the extract status, preview text, and index state. |
| A PDF has no text | It is a scan and PDF OCR fallback is off. | Turn on PDF OCR fallback and configure an OCR engine. |
| RAG returns nothing | The threshold is too high, the index is stale, or no chunks exist. | Lower the threshold, rebuild the index, and check file.rag_top_k. |
| Retrieval is slow | The embedding service is slow or chat.rag_wait_ready_ms is high. | Check the service latency and lower the wait. |
| Results ignore earlier turns | Message embedding or semantic recall is off. | Turn on message embedding, then semantic context recall. |
| Long chats lose early facts | Compaction triggers too late or preserves too few turns. | Lower the trigger percent and raise the preserved turns. |
Reference: setting keys#
| Stage | Keys |
|---|---|
| Upload limits | storage.max_message_files, storage.max_upload_file_bytes, storage.user_storage_quota_bytes, file.allowed_mime_types, file.image_max_bytes, file.doc_max_bytes |
| Extraction engines | extract.engine, extract.tika_source, extract.tika_base_url, extract.tika_auth_token, extract.tika_timeout_seconds, extract.docling_base_url, extract.docling_auth_token, extract.docling_timeout_seconds, extract.mineru_source, extract.mineru_base_url, extract.mineru_file_types, extract.mineru_auth_token, extract.mineru_timeout_seconds |
| OCR switches | extract.image_ocr_enabled, extract.pdf_ocr_fallback_enabled, extract.ocr_engine |
| Local OCR | extract.rapidocr_source, extract.rapidocr_base_url, extract.rapidocr_auth_token, extract.rapidocr_timeout_seconds, extract.tesseract_ocr_base_url, extract.tesseract_ocr_auth_token, extract.tesseract_ocr_timeout_seconds, extract.paddle_ocr_base_url, extract.paddle_ocr_auth_token, extract.paddle_ocr_timeout_seconds |
| Cloud and LLM OCR | extract.tencent_ocr_secret_id, extract.tencent_ocr_secret_key, extract.tencent_ocr_region, extract.tencent_ocr_endpoint, extract.tencent_ocr_timeout_seconds, extract.aliyun_ocr_access_key_id, extract.aliyun_ocr_access_key_secret, extract.aliyun_ocr_region, extract.aliyun_ocr_endpoint, extract.aliyun_ocr_timeout_seconds, extract.mistral_ocr_base_url, extract.mistral_ocr_auth_token, extract.mistral_ocr_model, extract.mistral_ocr_timeout_seconds, extract.llm_ocr_base_url, extract.llm_ocr_auth_token, extract.llm_ocr_model, extract.llm_ocr_timeout_seconds, extract.llm_ocr_prompt |
| Full-text injection | file.full_context_limit_enabled, file.file_full_context_max_bytes, file.full_context_max_tokens, file.full_context_pdf_max_pages |
| Embedding | file.embedding_enabled, file.embedding_host, file.embedding_key, file.rag_model, file.embedding_timeout_seconds, file.embedding_output_dimensions, file.embedding_dimensions_policy, file.embedding_normalize, file.embed_trigger_on_upload, file.embed_batch_size, file.embed_chunk_size_tokens, file.embed_chunk_overlap_tokens |
| Semantic enhancement | chat.message_embedding_enabled, chat.semantic_context_enabled |
| RAG | chat.rag_enabled, file.rag_top_k, chat.rag_min_similarity, chat.rag_token_budget, chat.rag_fetch_multiplier, chat.rag_wait_ready_ms, chat.rag_query_history_turns, chat.rag_retrieval_cache_ttl_seconds, chat.rag_hybrid_enabled |
| Compaction | chat.context_compact_enabled, chat.context_token_budget_enabled, chat.context_max_turns, chat.context_window_fallback_tokens, chat.context_compact_trigger_percent, chat.context_compact_preserve_recent_turns, chat.context_compact_highlights_per_role, chat.context_compact_snippet_chars, chat.context_artifact_retention_days, chat.compact_async_enabled, chat.compact_llm_enabled, chat.compact_task_model, chat.compact_max_failures, chat.compact_system_prompt, chat.compact_light_prompt |