打开 Demo
文件与检索不是单一开关，而是一条处理链路：上传限制、内容提取、OCR、全文注入、向量化、语义召回、RAG 拼接和上下文压缩都会影响最终回答质量。管理员需要知道每个参数控制哪一段链路，以及链路缺失时系统会如何回退。

处理链路#

用户上传文件后，系统通常会经历以下阶段：先检查上传限制，再保存并识别文件类型，随后提取文本或执行 OCR。获得文本后，小文件可以全文注入，大文件优先进入向量化和 RAG 召回。召回不到内容、索引不可用或文件无法提取时，系统会按能力回退到阈值内全文、原图/附件上下文，或者只使用用户问题。

从管理员视角看，这条链路可以拆成六个连续阶段：

  1. 检查文件数量、大小、类型和用户容量。
  2. 保存文件并识别类型。
  3. 提取文本、解析文档或执行 OCR。
  4. 根据策略决定全文注入或向量检索。
  5. 在对话中召回相关内容。
  6. 必要时压缩上下文，保留关键信息。

管理员配置的每个参数都对应这条链路中的一个控制点。

配置入口总览#

进入管理端，打开“文件与检索”。页面按链路分为上传限制、内容提取、全文注入、向量化检索、语义增强、RAG、上下文压缩增强。建议从前往后配置，因为后面的检索和压缩依赖前面的上传、提取和向量化结果。

配置分组控制链路没有配置时的影响
上传限制文件能否进入系统用户可能无法上传，或存储增长不可控。
内容提取文件是否能变成可读文本只能预览原文件，模型无法基于文本回答。
OCR图片和扫描件是否能识别文字图片文字、扫描 PDF 可能没有可检索文本。
全文注入小文件是否直接进入上下文小文件可能无法完整参与回答，或大文件挤占上下文。
向量化检索大文件和多文件是否可召回片段RAG 不可用，只能回退到全文或用户问题。
语义增强是否召回历史对话相关片段长会话跨轮记忆能力下降。
RAG检索片段如何筛选和注入召回过少会漏资料，过多会带入噪声。
上下文压缩增强长上下文如何保留关键信息长会话容易超过上下文预算或丢失早期信息。

上传限制#

上传限制决定用户能上传什么、一次能带多少文件、每个用户最多占用多少存储。它是整条链路的入口控制。

参数功能配置建议
附件数量上限限制单条消息可携带的文件数量。按模型和处理能力设置，避免一次消息触发过多提取和检索任务。
默认大小上限设置单个附件默认大小上限，页面单位为 MB。先按普通文档设置，再用图像/文档大小上限做分类覆盖。
用户存储配额限制每位用户可占用的总存储空间，0 表示不限制。团队和公开部署建议设置，避免个别用户占满存储。
附件 MIME 白名单限制允许上传的附件类型，多个值用逗号分隔。只开放业务需要的类型；新增类型后要测试提取和预览。
图像大小上限单独覆盖图像附件大小上限。图片 OCR 或视觉模型成本较高时应单独收紧。
文档大小上限单独覆盖文档附件大小上限。大文档建议配合 RAG，不建议全部走全文注入。

如果用户上传失败，优先检查 MIME 白名单、文件大小、附件数量和用户存储配额。上传通过后，后续提取失败不会回头放宽上传限制。

内容提取#

内容提取决定文件能否转成可读文本。没有文本，就无法稳定进入全文注入和 RAG。

不同服务适合不同文件：

服务类型适合文件说明
通用文档提取PDF、Word、表格、PPT、文本适合从普通文档中提取文本。
OCR图片、扫描 PDF适合图片文字和扫描件。
复杂文档解析版式复杂的 PDF、报告、论文更关注结构、段落和版面。
LLM OCR难以用传统 OCR 处理的图片或文档成本更高，应控制使用范围。
参数功能配置建议
提取引擎选择主提取链路：内置、Tika、Docling、MinerU。内置适合轻量文本；Tika 覆盖常见文档；Docling/MinerU 更适合复杂 PDF、报告和论文。
Tika 服务地址 / 鉴权密钥 / 超时时间配置 Tika 文档解析服务。用于 PDF、Office、表格、PPT 等常见文档；超时时间要覆盖大文件解析。
Docling 服务地址 / 鉴权密钥 / 超时时间配置 Docling 解析服务。适合结构复杂、版式要求高的文档；成本和耗时通常高于普通提取。
MinerU 服务类型 / 服务地址 / 鉴权密钥 / 超时时间配置 MinerU 云服务或自部署服务。适合论文、报告、复杂 PDF；选择云服务或自部署后要确认地址和凭据。

提取服务不可用时，系统会保留原文件用于预览；如果模型支持图片或附件上下文，可以继续走原图/附件上下文，否则只能基于用户问题回答。

OCR 策略#

OCR 用于图片文字和扫描 PDF。它不应该无差别开启，因为 OCR 会增加延迟和成本。

OCR 不是越多越好。对纯文本 PDF 反复 OCR 会浪费时间和成本；对扫描件不 OCR 又无法获得文本。

建议按文件类型和提取结果决定是否启用 OCR 回退。对于高成本云 OCR 或 LLM OCR，应限制触发条件，避免所有文件都走昂贵链路。

参数功能配置建议
图片 OCR图片附件进入 OCR 链路并生成文本结果。需要基于截图、票据、图片文字问答时开启。
PDF OCR 回退PDF 原生文本提取失败或质量较差时启用 OCR。扫描 PDF 必开；普通文本 PDF 不建议强制 OCR。
OCR 引擎选择 Rapid OCR、Tesseract OCR、Paddle OCR、腾讯云 OCR、阿里云 OCR、LLM OCR。本地引擎适合低成本；云 OCR 适合稳定识别；LLM OCR 适合复杂图文但成本更高。
各 OCR 服务地址 / 鉴权密钥 / 超时时间配置所选 OCR 引擎的连接和等待时间。引擎开启后对应地址或凭据必须可用，否则 OCR 链路会失败。
腾讯云/阿里云地域和接入点配置云 OCR 的地域和接入点。应与账号资源和延迟要求一致。
LLM OCR 请求模型 / 提示词指定视觉模型和 OCR 指令。提示词应要求只提取文字和必要结构，避免让模型扩写内容。

如果 OCR 没有启用或识别失败，图片和扫描件可能只能作为原图上下文传给支持视觉输入的模型；不支持视觉输入的模型无法直接读取图片文字。

全文注入#

全文注入会把文件文本直接放入模型上下文。它适合小文件、短合同、代码片段、逐段审阅和需要完整资料的问题。

它的优点是信息完整，适合合同条款、短代码、精确审阅和逐段分析。风险是占用上下文，超大文件全文注入可能挤掉用户问题、历史对话或其他关键资料。

建议：小文件使用全文注入，大文件使用向量检索。PDF 页数多但用户只问局部问题时，不应强行全文注入。

参数功能配置建议
全文注入限制开启后按大小、Token 和 PDF 页数控制全文注入。建议开启，避免大文件挤占用户问题和历史上下文。
全文大小上限限制全文注入允许的最大文本字节数，0 表示不限制。按常见小文档设置；大于阈值的文件转向 RAG。
全文 Token 上限限制全文注入占用的 Token 预算，0 表示不限制。应小于模型上下文预算，给用户问题、历史和检索证据留空间。
全文页数上限限制 PDF 全文注入允许的最大页数，0 表示不限制。页数多的 PDF 更适合 RAG，除非用户明确要求全文审阅。

全文注入不可用或超过阈值时，系统会优先走向量检索；如果向量检索也不可用，则回退到阈值内可用内容或仅使用用户问题。

向量化检索#

向量化检索负责把文件切分、向量化并建立索引，是大文件、多文件和知识库问答的核心能力。

它适合知识库、多文件、大文档和长期资料管理。Embedding 模型一旦变更，旧向量和新向量不可混用，应执行重建索引。

参数功能配置建议
启用 Embedding开启文件向量化和向量检索能力。开启 RAG 或语义增强前必须先配置可用的 Embedding。
Embedding 服务地址 / 鉴权密钥配置向量服务连接信息。服务需与所选模型和维度一致。
Embedding 模型指定向量化使用的模型名称。变更模型会让旧向量失效，需要重建索引。
Embedding 超时设置单次向量化最长等待时间。大批量或远程服务建议适当增加。
向量维度指定写库和检索统一使用的向量维度。维度必须与模型输出一致；变更后需要重建索引。
归一化向量对向量执行归一化处理。使用余弦相似度或相似模型时通常建议保持一致。
自动向量化文件上传完成后异步触发向量化。建议开启，否则需要等待手动或后台任务补索引。
批次大小单次向量化携带的文本数量。过大可能超时，过小会降低吞吐。
分片大小文档向量化时的分片大小，按 Token 估算。过小会断上下文，过大会降低召回精度。
分片重叠相邻分片之间保留的重叠 Token。适度重叠能减少关键信息被切断。
召回片段数RAG 最终返回并参与注入的片段数量。从少量高质量片段开始，再按问题复杂度增加。

如果 Embedding 未开启或服务未配置，RAG、消息向量化和语义上下文召回会被停用或无法开启。

向量索引状态#

索引状态用于判断当前文件是否能可靠检索。

状态含义处理方式
就绪当前配置下索引可用。可以正常检索。
失效Embedding 模型或维度变更导致旧向量不匹配。点击“重建索引”。
待处理文件等待向量化或后台任务执行中。等待任务完成后再测试检索。
失败文件向量化失败。检查提取文本、Embedding 服务和分片参数。
暂无数据尚未配置或没有索引。先配置 Embedding，再上传样例文件。

页面会显示模型签名。首次保存配置后会自动生成签名；模型或维度变更时，旧向量会标记为失效。重建索引是后台任务，文件越多耗时越长。

语义增强#

语义增强用于召回历史对话相关片段，解决长会话中早期信息被上下文窗口挤掉的问题。

它依赖消息向量化或文件向量化。开启语义上下文召回前，应先开启消息向量化。否则系统缺少可检索的历史语义数据。

参数功能配置建议
消息向量化每轮对话完成后异步生成消息向量。开启语义上下文召回前必须先开启。
语义上下文召回发送消息时自动召回历史相关片段并注入上下文。适合长会话、跨轮任务、持续项目讨论。

如果消息向量化没有开启，语义上下文召回不能正常工作。它依赖 Embedding 服务，因此修改 Embedding 配置时也要重新观察历史召回效果。

RAG 参数#

RAG 决定如何从文件索引中取回内容，并把证据片段放进当前上下文。

参数功能配置建议
RAG 开关允许文件进入检索增强链路。依赖可用的 Embedding 服务。
相似度阈值片段注入的最低相似度。太高可能召回为空，太低会带入噪声。
注入 Token 预算限制检索片段可占用的上下文预算。需要给用户问题、历史消息和系统提示词留空间。
抓取倍数先抓取更多候选，再二次筛选。文档多、片段质量参差时提高；成本和耗时也会增加。
就绪等待时长发送消息时等待向量化结果就绪的最长时间。上传后立刻提问时有帮助；过长会拖慢回复。
历史拼接轮次生成检索查询时带入最近用户轮次。多轮追问时提高召回准确度。
检索缓存时长缓存检索结果的时间。重复提问可减少计算；文档频繁变更时不宜过长。
混合检索并行执行 BM25 和向量检索，并合并结果。专有名词、编号、精确关键词较多时建议开启。

召回数量太少会漏掉关键资料，太多会引入噪声并占用上下文。相似度阈值太高可能召回为空，太低可能带入无关片段。建议从少量高质量召回开始，再根据日志和用户反馈调整。

RAG 没有召回到片段时，系统不会强行注入无关内容，会回退到阈值内全文或仅使用用户问题。排查“答不到文件内容”时，先看提取结果，再看索引状态，最后看阈值和召回数量。

上下文压缩增强#

上下文压缩用于长会话、大文件、多证据场景，控制历史内容和证据如何保留。

它把早期内容压缩成摘要，减少上下文压力。压缩模型应稳定、便宜、擅长总结。压缩异步执行可以减少当前回复阻塞，但摘要更新可能稍有延迟。关键场景应测试摘要是否保留事实、数字、结论和未完成任务。

参数功能配置建议
Token 预算截断根据当前模型上下文窗口裁剪可发送历史。建议开启，避免超过模型上下文限制。
压缩触发轮次按对话轮次触发压缩。长会话可设置较低，短任务可放宽。
压缩 Token 阈值按 Token 规模触发压缩。应低于模型上下文上限，并保留当前任务空间。
原文保留轮次压缩时保留最近原始轮次。最近几轮通常包含当前任务细节，建议保留。
每角色摘要条数模板压缩时用户和助手各保留多少条摘要。控制摘要密度，过多会占预算，过少会丢细节。
片段字符上限模板压缩时单条消息片段最大字符数。防止单条长消息撑爆摘要。
证据保留天数RAG 结果、历史证据、工具结果保留时间；0 表示不自动过期。有审计需要可延长；存储敏感时应设置过期。
LLM 压缩调用模型生成语义摘要。质量更好但有成本；关闭时使用模板摘要。
异步压缩后台执行压缩任务，减少当前回复阻塞。建议开启，但摘要更新可能略有延迟。
压缩模型指定摘要模型，可跟随当前模型。推荐稳定、便宜、擅长总结的模型。
熔断阈值LLM 压缩连续失败后降级为模板摘要。防止压缩模型故障影响主对话链路。
全量摘要提示词 / 轻量摘要提示词自定义压缩指令。应要求保留事实、数字、结论、约束和未完成任务。

回退规则#

条件系统行为管理员应检查
上传校验不通过文件不进入系统。数量、大小、MIME、用户配额。
文档提取不可用保留原文件，可预览但缺少可检索文本。提取引擎、服务地址、超时时间。
OCR 不可用图片文字或扫描件无法转成文本。图片 OCR、PDF OCR 回退、OCR 引擎配置。
全文超过阈值转向 RAG 或回退。全文大小、Token、PDF 页数上限。
Embedding 未配置RAG 和语义增强不可用。Embedding 服务地址、模型、维度。
索引失效或失败检索结果缺失或不可靠。重建索引、提取文本、分片参数。
RAG 召回为空不注入无关片段，回退到全文或用户问题。相似度阈值、召回片段数、混合检索。
上下文过长执行截断或压缩。Token 预算、压缩阈值、保留轮次。

推荐配置路径#

  1. 先配置上传数量、大小、MIME、图像/文档上限和用户存储配额。
  2. 配置提取引擎，并用 PDF、Word、表格、PPT、文本文件分别测试。
  3. 按需开启图片 OCR 和 PDF OCR 回退，再配置对应 OCR 引擎。
  4. 开启全文注入限制，给小文件保留完整上下文能力。
  5. 配置 Embedding 服务、模型、维度、分片和自动向量化。
  6. 上传样例文件，确认索引状态为就绪；如果失效或失败，先重建索引。
  7. 开启 RAG，调整相似度阈值、召回片段数、Token 预算和混合检索。
  8. 长会话场景再开启消息向量化、语义上下文召回和上下文压缩增强。

使用建议#

文件能力上线不要一次开满。先让上传、预览、提取稳定，再加入 OCR、向量化和 RAG。每次修改 Embedding 模型、向量维度、分片策略或提取引擎后，都要用样例文件验证索引和召回结果。用户反馈“答不到文件内容”时，按上传限制、提取结果、索引状态、RAG 参数、上下文预算的顺序排查。