打开 Demo
文件与检索把一次上传变成模型上下文，中间经过上传校验、内容提取、OCR、全文注入、向量化、RAG 和上下文压缩。这一页给出真实顺序、回退规则，以及每一段对应的配置键。

入口位置#

管理端 > 文件与检索。页面按上传限制、内容提取、全文注入、向量化检索、语义增强、RAG 分组。上下文压缩在会话配置 > 上下文管理里配置。

一个文件怎么变成上下文#

  1. 上传时校验数量、大小、MIME 类型和用户存储配额。
  2. 保存文件并识别类型。
  3. 提取文本。图片走 OCR，PDF 可以回退到 OCR。
  4. 为每个附件分配上下文模式：
    • 本轮图片或用户消息里的图片按原图直传。
    • 其余文件在全文注入和 RAG 之间选择。
  5. 对进入 RAG 的附件，先把查询向量化，再检索片段，按相似度过滤，并受注入 Token 预算限制。
  6. 检索为空、失败或超时，且文件在全文限制内时回退全文；否则跳过该附件。
  7. 组装好的上下文按 Token 预算裁剪，超过轮次或 Token 阈值时执行压缩。

自动模式的全文 / RAG 判断是：

  • 文件无法全文注入，或开启了 Token 预算保护且文件文本超过模型有效输入预算的 40% 时，走 RAG。
  • 其余情况走全文注入。

全文注入模式不会走 RAG。向量检索模式优先 RAG，但文件不可检索时回退全文。用户侧的 chat.file_mode 只是个人偏好，平台仍会套用自己的限制。

上传限制#

配置项配置键说明
附件数量上限storage.max_message_files单条消息 1–50 个文件。
默认大小上限storage.max_upload_file_bytes单文件默认上限，页面单位为 MB。
用户存储配额storage.user_storage_quota_bytes每位用户的总存储，页面单位为 MB，0 表示不限。
附件 MIME 白名单file.allowed_mime_types逗号分隔，只有列出的类型可以上传。
图像大小上限file.image_max_bytes覆盖图像的默认上限，留空使用默认值。
文档大小上限file.doc_max_bytes覆盖文档的默认上限，留空使用默认值。

图像或文档的实际上限取默认上限与覆盖值中较小的一个。MIME 类型不在白名单里时，文件在提取之前就会被拒绝。

内容提取与 OCR#

配置项配置键说明
提取引擎extract.enginebuiltin、tika、docling 或 mineru。
Tika 来源 / 地址 / 密钥 / 超时extract.tika_source、extract.tika_base_url、extract.tika_auth_token、extract.tika_timeout_seconds来源取 external 或 managed。
Docling 地址 / 密钥 / 超时extract.docling_base_url、extract.docling_auth_token、extract.docling_timeout_seconds适合版式复杂的文档。
MinerU 类型 / 地址 / 文件类型 / 密钥 / 超时extract.mineru_source、extract.mineru_base_url、extract.mineru_file_types、extract.mineru_auth_token、extract.mineru_timeout_seconds类型取 cloud 或 self_hosted；文件类型取 pdf、word、presentation、excel。
图片 OCRextract.image_ocr_enabled图片附件进入 OCR，默认关闭。
PDF OCR 回退extract.pdf_ocr_fallback_enabledPDF 原生文本缺失或质量差时启用 OCR，默认关闭。
OCR 引擎extract.ocr_enginerapidocr、tesseract、paddle、tencent、aliyun、mistral 或 llm。

选中的引擎不支持某个文件时，文档类文件会回退到内置提取器。PDF 开启 OCR 回退后，先探测原生文本层，只对薄弱页做选择性 OCR，仍不足时再整体 OCR。

每种 OCR 引擎需要各自的连接字段，例如 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 和 extract.llm_ocr_base_url。LLM OCR 使用配置的视觉模型；Mistral OCR 需要地址、API Key 和模型。

图片 OCR 关闭时，图片不产生文本，只能发给支持视觉输入的模型。文档提取失败时，文件仍可预览，但没有可检索文本。

全文注入#

全文注入把提取文本直接放进模型上下文。它信息完整，适合小文件、合同和短代码，但会占用上下文。

配置项配置键说明
全文注入限制file.full_context_limit_enabled关闭后忽略大小、Token 和页数限制。
全文大小上限file.file_full_context_max_bytes提取文本字节数，页面单位为 MB，留空或 0 表示不限。
全文 Token 上限file.full_context_max_tokensToken 预算，留空或 0 表示不限。
全文页数上限file.full_context_pdf_max_pagesPDF 页数，留空或 0 表示不限。

视频不会走全文注入。只有文本非空且不超过所有已启用限制的文件才会注入。放不下的文件在检索可用时转向 RAG，否则被跳过。

向量化检索与 Embedding#

必须先启用并配置 Embedding，才能开启 RAG 或语义召回。修改模型、维度或接入地址会把已有向量标记为失效。

配置项配置键说明
启用 Embeddingfile.embedding_enabled向量化和检索的前提。
Embedding 服务地址 / 鉴权密钥file.embedding_host、file.embedding_key服务需兼容 OpenAI /embeddings 接口。
Embedding 模型file.rag_model变更后旧向量失效。
Embedding 超时file.embedding_timeout_seconds单次请求等待秒数。
向量维度file.embedding_output_dimensions64–4096，必须与模型输出一致。
维度参数策略file.embedding_dimensions_policysend 携带 dimensions；omit 不携带，但仍按配置维度校验返回向量。
归一化向量file.embedding_normalize写库和检索前做 L2 归一化。
自动向量化file.embed_trigger_on_upload上传后自动触发向量化。
批次大小file.embed_batch_size单次请求携带的文本片段数。
分片大小file.embed_chunk_size_tokens按 Token 估算的分片大小。
分片重叠file.embed_chunk_overlap_tokens相邻分片的 Token 重叠。
召回片段数file.rag_top_k最终返回并注入的片段数，1–50。

服务商拒绝 dimensions 参数时用 omit。返回向量仍会按 file.embedding_output_dimensions 校验，尺寸不符会直接失败，不会写入错误维度的向量。

向量索引状态#

状态面板会显示模型签名和各状态的计数。首次保存后签名自动生成。

状态含义处理方式
就绪向量与当前签名一致。可以正常检索。
失效模型、维度或接入地址已变更。点击重建索引。
待处理文件排队或处理中。等任务完成后再测试检索。
无文本提取没有产出文本，没有可向量化内容。检查提取；修好 OCR 后可用重建含无文本文件。
失败向量化失败。检查提取文本、Embedding 服务和分片参数。

尚未建立索引时，面板会提示暂无数据，配置 Embedding 服务后才可用。只要存在失效向量，就会出现重建提示。重建是后台任务，文件越多耗时越长。

RAG#

配置项配置键说明
RAG 开关chat.rag_enabled需要可用的 Embedding 服务。
相似度阈值chat.rag_min_similarity片段注入的最低分数。
注入 Token 预算chat.rag_token_budget检索片段可占用的上下文预算。
抓取倍数chat.rag_fetch_multiplier先抓取 top_k × 倍数 个候选再过滤。
就绪等待时长chat.rag_wait_ready_ms发送前等待检索的最长时间。
历史拼接轮次chat.rag_query_history_turns生成检索查询时带入的最近用户轮次。
检索缓存时长chat.rag_retrieval_cache_ttl_seconds缓存检索结果，0 表示不缓存。
混合检索chat.rag_hybrid_enabled并行执行向量检索和全文检索，用 RRF 合并。

缓存键包含查询、Embedding 地址与模型、维度、检索参数，以及每个文件的 ID、分片数、向量状态和更新时间，所以编辑文件会让对应缓存失效。

阈值太高可能召回为空，太低会带入噪声。没有片段通过时，系统不会注入无关内容，而是在文件放得下时回退全文，否则跳过。如果显式选择了知识库，知识库不可用会直接终止发送，召回为空则只给出“没有知识库依据”的提示。

语义增强#

配置项配置键说明
消息向量化chat.message_embedding_enabled每轮结束后生成消息向量，需要 Embedding 服务。
语义上下文召回chat.semantic_context_enabled发送前召回历史相关片段，需要先开启消息向量化。

消息向量化未开启时无法开启语义上下文召回。两者共用 Embedding 服务，修改 Embedding 配置也会影响历史召回效果。

上下文压缩#

压缩在会话配置 > 上下文管理里配置，用于把较早的对话整理成摘要，让长会话保持在模型预算内。

配置项配置键说明
上下文压缩chat.context_compact_enabled总开关；用户仍可在聊天设置里选择不使用。
Token 预算保护chat.context_token_budget_enabled按模型有效输入预算裁剪历史。
压缩触发轮次chat.context_max_turns超过该轮次时触发，0 表示关闭。
默认上下文窗口chat.context_window_fallback_tokens无法识别模型窗口时使用。
压缩触发比例chat.context_compact_trigger_percent达到有效输入预算的该比例时触发，0 表示关闭。
原文保留轮次chat.context_compact_preserve_recent_turns压缩时保留的最近原始轮次。
每角色摘要条数chat.context_compact_highlights_per_role用户和助手各自保留的摘要条数。
片段字符上限chat.context_compact_snippet_chars单条消息片段的最大字符数。
证据保留天数chat.context_artifact_retention_daysRAG、历史和工具证据的保留时长，0 表示不自动过期。
后台执行压缩chat.compact_async_enabled回复完成后执行压缩。
LLM 压缩chat.compact_llm_enabled用模型生成语义摘要；关闭时只用模板摘要。
压缩模型chat.compact_task_modelfollow 表示跟随当前模型，非聊天模型回退到默认聊天模型。
熔断阈值chat.compact_max_failures连续失败达到该次数后降级为模板摘要。
全量 / 轻量摘要提示词chat.compact_system_prompt、chat.compact_light_prompt自定义摘要指令。

回退规则#

条件系统行为
上传校验失败文件被拒绝。
提取失败文件可预览，但没有可检索文本。
OCR 关闭或失败图片或扫描件文本对不支持视觉的模型不可用。
全文超过限制文件转向 RAG；检索不可用时跳过。
Embedding 未启用RAG 和语义召回不可用。
索引失效或失败检索不完整，需要重建索引。
RAG 召回为空不注入无关片段；放得下时回退全文。
上下文过长执行 Token 预算裁剪或压缩。

验证配置#

  1. 设置上传数量、大小、MIME、图像与文档上限和存储配额。
  2. 配置提取引擎，用 PDF、Word、表格和文本文件分别测试。
  3. 只在需要时开启图片 OCR 和 PDF OCR 回退，并配置对应引擎。
  4. 为小文档开启全文注入限制。
  5. 配置 Embedding 服务、模型、维度、分片和自动向量化。
  6. 上传样例文件，确认索引状态为就绪。
  7. 开启 RAG，调整相似度阈值、召回片段数、Token 预算和混合检索。
  8. 长会话场景再开启消息向量化、语义召回和上下文压缩。

常见问题#

现象原因处理方式
上传被拒绝MIME 类型、大小、数量或配额。检查白名单以及大小、配额限制。
模型答不到文件内容提取失败或索引未就绪。检查提取状态、预览文本和索引状态。
PDF 没有文本属于扫描件，且 PDF OCR 回退关闭。开启 PDF OCR 回退并配置 OCR 引擎。
RAG 召回为空阈值过高、索引失效，或没有分片。调低阈值、重建索引，并检查 file.rag_top_k。
检索很慢Embedding 服务慢，或 chat.rag_wait_ready_ms 过长。检查服务延迟并调低等待时长。
结果忽略更早的对话消息向量化或语义召回未开启。先开启消息向量化，再开启语义上下文召回。
长会话丢失早期信息压缩触发太晚，或保留轮次太少。调低触发比例，提高原文保留轮次。

参考：配置键#

链路配置键
上传限制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
提取引擎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 开关extract.image_ocr_enabled、extract.pdf_ocr_fallback_enabled、extract.ocr_engine
本地 OCRextract.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
云与 LLM OCRextract.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
全文注入file.full_context_limit_enabled、file.file_full_context_max_bytes、file.full_context_max_tokens、file.full_context_pdf_max_pages
Embeddingfile.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
语义增强chat.message_embedding_enabled、chat.semantic_context_enabled
RAGchat.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
上下文压缩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

相关页面#