知识库中的源视觉内容¶
当 PDF 或 EPUB 解析器输出图像文件时，DeepTutor 可以保留提取出的源图像。KB 以确定性的资产 ID、文档哈希、解析器身份、源定位符、标题和邻近文本存储经解析器验证提取的 PNG、JPEG、GIF 或 WebP 字节。结构化解析器块在可用时还会保留页面索引和边界框。视觉记录位于 KB 的 visual_assets/ 目录下，与向量索引分开。经过访问检查的 API 路由 /api/knowledge-bases/{kb_name}/visual-assets/{asset_id} 提供这些确切的字节，删除原始源文件会同时移除其视觉资产。
LlamaIndex KB 管道为每个源视觉内容索引一条文本记录，因此文本嵌入模型可以通过其标题和上下文进行检索。当 rag 在聊天循环中检索到该记录时，具备视觉能力的答案模型会在其下一个请求中收到经验证的图像像素。纯文本模型会收到标题和上下文，并附带一条明确警告：它尚未看到这些像素。所有受支持的提取图像都会被保留，每张图像限制为 5 MiB，每次模型续写最多发送两张检索到的图像。文档保留数量与此模型请求预算无关。没有文档图表数量上限，也没有 KB 级的 16 MiB 清单上限。无法读取的清单会明确地使写入失败，并保持原样保留。
当前的提取覆盖范围取决于所选解析器。MinerU 可以输出结构化的 PDF 图表。PyMuPDF4LLM 在启用图像提取时可以输出 PDF 和 EPUB 图像，但其 Markdown 输出不提供页面边界框。默认的纯文本解析器和当前的 Docling 适配器不会输出源图像资产。仅由矢量绘图命令组成的图像，或者在未配置可用 OCR 引擎时需要 OCR 的页面，可能会缺失。其他 RAG 提供商尚未为此视觉清单编制语义发现索引。精确的视觉检查和 PDF 页面检查与嵌入引擎无关。
精确图表、原始页面与覆盖范围¶
在 KB 的“文件”视图中，选择一份文档并展开 源视觉覆盖范围。它会显示已保留的图表、分页的原始图像链接，以及已知的跳过、失败或未验证的提取位置。解析器未返回图像绝不代表文档没有视觉信息。该报告描述的是提取情况；它不证明索引就绪状态，也不证明书中的每一个视觉内容。
现有的 rag 工具还接受 source_path、figure、asset_id、page、region 和 source_hash 参数。使用 kb_files 获取精确的文档路径。图表和表格引用会保留其类型和编号；英文/中文标签是等效的。不同来源共用的标签会产生歧义，需要用户选择。对于概念发现，请使用现有的语义检索，并在需要时使用源语言进行查询。将得到的文档、章节、标题和页面放在一起，而不是将相似的图表视为匹配项。
对于矢量绘图、稀疏标题或依赖布局的表格，请直接检查 PDF 页面。精确印刷引用发现功能仅扫描选定的未锁定 PDF，最多 2000 页；多次提及仍保留为页面选项。已知页面可以独立于该发现限制进行选择。渲染在本地读取原始 PDF，无需 OCR/模型下载或云端调用。完整页面保留布局；归一化的 region=[x0,y0,x1,y1] 裁剪将有限的像素预算用于更多细节。解析器提供的同一 PDF 页面上的面板组会解析为完整页面。结构化的表头/单元格/单位和注释在提供时仍作为文本证据；原始页面可用于验证。
页面检查支持最大 512 MiB 的 PDF，渲染像素最多 800 万，图像字节最多 5 MiB。锁定/损坏的 PDF、无效区域和不可读标签存在明确的限制。其他格式保留受支持的提取图像和原始文档访问权限；PDF 渲染不会静默应用于这些格式。提高渲染比例无法恢复扫描件中不存在的信息。
每项解释都包含原始像素和源位置。标题和页面文本与观察到的图像事实相区分。重新检索相同的不可变 asset_id 以进行详细跟进；source_hash 保护页面链接。兼容的重新索引会保留旧资产 ID 的可用性。已更改或缺失的来源会被报告，旧引用绝不会被重定向到新材料。在两次独立的有界调用中比较两个来源。如果任一证据无法检查，请选择页面/区域、澄清来源，或说明无法进行受支持的比较。无需上传整本书的图像，也无需强制外部增强。
合成回归测试夹具包含 100 个源图表，以及矢量、结构化表格和多面板页面。预期的早期/中期/晚期引用、中文到英文的图表标签、表头/单位/注释、原始字节、歧义匹配、不可用像素和来源变更时的弃权都会被检查，且独立于语言模型的流畅度。
基于来源的练习与学习证据¶
在引导式学习中，请明确请求解释、练习或复习。仅解释的回合无需提出问题；mastery_note_explained 记录所教内容，但不授予掌握状态。推迟目标会将其保留为未完成状态。对于需要视觉理解的目标，大纲目标可以声明 required_visual_tasks：identification、relationship、table_graph 或 comparison。通用文本分数不能满足这些视觉要求。目标视图显示剩余的独立证据。
针对所附加 KB 中的精确原始图表或页面请求练习。导师会检索其像素，然后以 visual 上下文提出 mastery_quiz。问题卡片显示原始证据和文档/页面链接。支持编号标签识别、基于来源的关系问题、表格或图形解读以及受限的双来源比较。不会使用自动分割、编造的标签遮罩或生成的替代示意图。源图像加载失败时，提交会被禁用，但学习者仍可跳过或寻求帮助。
参考键使用规范来源术语及辅助说明文字、解释或页面引用。经明确验证的等价术语（包括其他语言）可以回答同一问题。选择题能区分有依据的错误答案；未知的自由文本措辞会请求澄清，而不是进行模糊的关键词评分。不确定/冲突的键、不可访问或已更改的来源，以及缺失的模型输入像素，均保持不评分，并且不会产生负面掌握或保持证据。仅提供图片 URL 或声明视觉能力是不够的：活动循环会检查已接受提供商请求中的匹配图像字节，包括实际的纯文本回退。
可见/未知答案提示属于引导式练习，保留辅助记录且复习证据较弱。它们不能证明独立掌握。暴露参考答案的整页仍算引导式；当答案提示位于视图之外时，经过验证的原页面区域可以支持独立解读，同时保留完整来源以供参考验证。近期的辅助、重复的答案键暴露以及问题后提供的帮助，仍可通过现有的保持会话边界加以区分。
使用 审阅或质疑此评估 来请求来源审查。现有的 mastery_repair_question 会使错误评估失效，并重新计算其掌握/错误/复习效果。修正视觉键也需要来源支持；仅凭质疑永远不会授予掌握。手动学习者覆盖保留其独立的来源出处。来源/图片身份、目标、任务、提示/帮助、答案和尝试身份在重启后仍然保留。传输重试记录一次尝试；一个新问题记录新证据。大纲替换保留受信任的目标身份，而不是按标题或位置转移成就。未评估、已解释、受辅助和独立演示的工作保持彼此区分。
回归工作流使用独立指定的合成编号图片、关系和表格值，包括等效语言答案、错误选项、未评分的歧义、修复、推迟、重复提交、大纲替换、来源更改和重启。这一受支持集合为不确定性提供了明确的恢复机制，而不是承诺对每张图片或任意散文答案进行无限制的评分。
图像请求的 Token 估算¶
当提供商返回用量时，DeepTutor 使用这些报告的计数器。当用量缺失时，对话统计会被标记为估算值。回退逻辑按每 token 约 3.5 个字符计算序列化文本，并为每个结构化图像块增加 1,024 个 token。它从文本估算中排除图片 URL 和 Base64 载荷，因此编码后的文件大小不会将计数器膨胀到数百万个 token。
图像配额是一个粗略的占位值，与分辨率、细节、模型和提供商无关；它不是计费计算。一次对话中的每次模型调用仍会计入其自身输入，包括任何重放的图片。现有存储的估算不会因这一更改而被重写，对话内容会保留。
恢复 MinerU 云 PDF 切片¶
大型云 PDF 使用文档解析设置中的 engines.mineru.max_pages_per_part 进行切片（默认 180；限制在 1–200）。保存旧版 MinerU 设置表单时，此高级设置会被保留。本地解析和小型/非 PDF 输入保持其现有行为。
合并后的内容列表 page_idx 值指向原始 PDF，包括嵌套块。例如，第二个 180 页切片的页索引 0 变为 180。无效的本地索引会使解析失败，而不是静默地错误标记源页面。其他逐部分诊断产物保留其原始本地编号和 partNN_ 文件名前缀。
已完成的切片归档保存在活动工作区解析缓存的 .mineru-segments/ 目录下，位于一次性的失败解析目录之外。使用相同来源和解析器设置重试时，会复用已完成的切片；如果文档、端点、模型、语言、OCR/公式/表格设置或切片大小发生变化，则会启动新的检查点集合。API token 和签名 URL 永远不会写入检查点。每个归档在复用前都会经过 SHA-256 校验；不完整或损坏的检查点会重新下载。并发任务可能仍然重复发起云请求，但检查点写入是原子的。缓存写入失败不会导致已成功的解析失败。
这些归档包含解析后的文档内容、图片以及 MinerU 返回的任何源副本，与普通解析缓存相同。它们会一直保留到工作区缓存被清除；在没有解析运行的情况下删除 .mineru-segments/ 只会丢弃可恢复的进度。此更改对云解析器签名进行了版本化，因此较旧的合并页索引不会从普通解析缓存中被复用。现有知识库索引需要显式重建才能使用修正后的页面。
重试本地 MinerU 文档¶
本地 MinerU 重试会从开头重新开始被中断的文档；CLI 在推理调用内部不提供可靠的检查点。兼容的已完整解析文档在重试或重启后仍然可复用，包括仅更改嵌入配置的情况。空或不可读的缓存输出会被重新解析，而不是被视为完整。
新的本地输出在替换现有解析之前，会检查是否包含可用的 Markdown 或内容块。失败的尝试会保留其产物以供诊断。在工作区解析缓存中，这些产物会被移动到受影响签名旁边的隐藏 .failed- 目录中，位于下一次重试的工作目录之外。它们永远不会被视为已完成的缓存条目。清除工作区解析缓存也会移除这些诊断产物。在调用方开始另一次尝试之前，被中断的本地子进程会被停止。
MinerU 处理微型扫描 PDF 页面¶
某些扫描 PDF 会在异常小的物理页面框中编码全分辨率页面。MinerU 的官方云后端可以选择在临时上传副本中放大这些页面。原始文件、页面顺序、压缩图片字节和软掩码都会被保留；语言、OCR、模型、公式和表格设置保持已配置状态。这是一种几何处理变通方案，并不保证更好的 OCR 或保留任意交互式 PDF 语义。
该选项默认处于关闭状态。管理员可以通过现有的 PUT /api/settings/document-parsing 端点，使用以下部分载荷来启用它：
使用 false 可将其禁用。该选项也位于 document_parsing.json 中的 engines.mineru.normalize_tiny_scans 路径下。启用它会改变云端解析缓存签名；旧的解析结果保持不变。现有索引不会自动重建。可选的 deeptutor[parse-pymupdf4llm] wheel 额外依赖提供了所需的 PyMuPDF 依赖。对于源码检出，请使用 python scripts/install_extras.py parse-pymupdf4llm（参见模块安装）。
只有最长边小于 144 磅的无文本页面才符合条件，并且页面上需有高分辨率图像，其表观密度至少为 1200 DPI，覆盖页面至少 80% 的面积。最长边会被缩放至 768 磅。旋转、裁剪、带注释、含矢量图形或使用非默认 UserUnit 的页面将保持不变。本地 MinerU、自定义云端点、普通 PDF 和非 PDF 输入保持其现有行为。临时副本会在成功或失败后被移除；如果压缩图像流发生变化，则拒绝上传。
可选的图像描述批次¶
现有的 LlamaIndex 图像描述流程可以在每次视觉请求中发送多张图像。通过 PUT /api/knowledge-bases/rag-pipelines/llamaindex/config 设置 image_description_batch_size，例如：
默认值为 1，保持单个请求不变；接受的值会被限制在 1–8 之间。启用后，并发限制按批次计数，现有超时设置覆盖整个批次，包括任何拆分尝试。返回的说明文字通过显式 ID 匹配，绝不依赖响应顺序。格式错误的 JSON/ID 映射以及显式上下文溢出会拆分为更小的组，最终使用现有的单图像提示。一组 N 张图像最多会产生 2N−1 次补全调用，并且此模式禁用提供方重试。身份验证和速率限制会导致任务中已排队的组停止；其他 API/传输错误不会触发拆分。
这仅影响现有 LlamaIndex 描述流程中后续处理的图像。它不会为结构化源视觉内容启用描述，也不会改变阅读材料的说明文字。批次使用不同的结构化提示，并将完整、成功的组与独立的单图像说明分开缓存。该摘要包含有序的图像内容和元数据、提示、模型身份以及重试策略。失败、不完整或已取消的组不会被缓存；成功拆分的组可以被复用。将大小设回 1 即可恢复正常单图像路径。模型必须支持多个图像块；不支持的 API 响应会被报告，而不会引发成批的回退请求。
实现与验证¶
本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 dee/DeepTutor