尧图网站建设 
DeepTutor v1.0.0-beta.2 发布解读设置热重载、MinerU 嵌套目录修复与 Python 3.11 基线【免费下载链接】DeepTutorDeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.项目地址: https://gitcode.com/GitHub_Trending/dee/DeepTutorDeepTutor v1.0.0-beta.2发布于 2026.04.07是一次以运行时体验为核心的版本更新模型设置API Key、模型选择、Endpoint在保存后立即生效而无需重启服务问题提取器能够发现 MinerU 嵌套输出目录如hybrid_auto/中成功解析出的 Markdown同时修复了/mimicWebSocket 端点的NameError崩溃并将 Python 最低版本要求提升至 3.11。读完本文你将掌握这四项变更在 DeepTutor 源码中的具体落点设置缓存失效的调用链、MinerU 目录发现算法的实现细节以及对应的回归测试位置便于在自部署环境中验证与排查同类问题。版本定位与变更总览v1.0.0-beta.2 的发布说明位于 assets/releases/past_releases/ver1-0-0-beta-2.md它承接 beta.1 进入 1.0 稳定化阶段变更可归纳为四类类别变更影响的代码位置功能增强Hot Settings Reload设置热重载deeptutor/api/routers/settings.py功能增强MinerU 嵌套输出目录支持deeptutor/tools/question/question_extractor.py缺陷修复/mimicWebSocketNameError崩溃deeptutor/api/routers/question.py基线调整最低 Python 版本提升至 3.11pyproject.toml以下逐一展开并结合当前仓库源码印证每项变更的实际实现。Hot Settings Reload保存即生效的设置热重载这是本版本最重要的体验改进。在此之前的行为是修改 API Key、切换模型或更换 Endpoint 后运行中的 LLM 客户端、嵌入Embedding客户端以及配置缓存仍持有旧值必须重启服务才能生效。v1.0.0-beta.2 之后通过 Settings 页面或引导向导onboarding tour保存设置时运行时缓存会被自动失效下一次调用即加载最新配置。失效机制的源码实现核心实现是 deeptutor/api/routers/settings.py 中的_invalidate_runtime_caches()函数def _invalidate_runtime_caches() - None: Force runtime clients/config to pick up the latest saved catalog. The LLM and embedding clients are process-wide singletons, so resetting them here will affect any user turn that is mid-flight on another worker. Admins issuing Apply during active sessions accept that trade-off; we log a WARNING so the cause is visible in the audit trail. logger.warning( Admin applied catalog; resetting global LLM/embedding clients. In-flight user turns may flip backend client mid-call. ) clear_llm_config_cache() reset_llm_client() reset_embedding_client()从源码结构看热重载由三个步骤组成clear_llm_config_cache()—— 清空 LLM 配置缓存。DeepTutor 中 LLM 客户端与嵌入客户端是进程级单例配置一旦解析就会驻留在内存中不清缓存的话即使落盘了新配置下一次get_llm_config()仍会返回旧值。reset_llm_client()—— 重置 LLM 客户端实例使下一次请求按新的 API Key / Endpoint / 模型重新构造连接。reset_embedding_client()—— 对嵌入客户端做同样处理保证向量化服务如知识库构建、RAG 检索也切换到新配置。值得注意的是函数体中的 WARNING 日志由于客户端是进程级单例若管理员在有用户会话进行中时执行 Apply正在飞行的请求mid-flight turn可能会在调用中途切换后端客户端。DeepTutor 没有为避免这一竞态而引入复杂的事务机制而是接受这一权衡通过日志保证审计可见——这是从单例缓存失效方案中推断出的设计取舍。该函数在路由中至少被三处触发对应 Settings 页的保存、目录 Apply 以及 onboarding tour 完成等入口# deeptutor/api/routers/settings.py ... _invalidate_runtime_caches() # L1016 ... _invalidate_runtime_caches() # L1025 ... _invalidate_runtime_caches() # L1242回归测试保障发布说明中提到为设置缓存失效新增了回归测试对应实现位于 tests/api/test_settings_router.py其中包含三个针对性用例test_update_catalog_invalidates_runtime_caches约 L528——验证更新模型目录接口会触发缓存失效test_apply_catalog_invalidates_runtime_caches约 L573——验证Apply操作路径同样失效缓存test_complete_tour_invalidates_runtime_caches约 L641——验证 onboarding tour 完成时也会失效运行时缓存。这些测试通过对llm_config_module.clear_llm_config_cache()与llm_client_module.reset_llm_client()打桩monkeypatch来断言失效逻辑确实被执行与源码中保存 → 失效 → 下次请求重建的调用链一一对应。MinerU 嵌套输出目录支持问题背景DeepTutor 的仿真题生成mimic exam等工作流依赖文档解析引擎MinerU先把 PDF 解析为 Markdown再由问题提取器question extractor读取这些 Markdown 来出题。MinerU 的输出目录结构并不固定不同版本/模式下解析产物可能位于输出目录顶层也可能嵌套在auto/、hybrid_auto/等子目录中。v1.0.0-beta.2 之前的问题是MinerU 明明成功解析了文档但解析产物落在嵌套子目录里提取器只按旧规则查找找不到 Markdown最终导致解析成功但出题失败的假性故障。目录发现算法修复后的核心逻辑是 deeptutor/tools/question/question_extractor.py 中的_find_parsed_content_dir()def _find_parsed_content_dir(paper_dir: Path) - Path: Locate the MinerU output directory that contains parsed markdown artifacts. candidate_dirs: list[Path] [] for preferred_name in (auto, hybrid_auto): preferred_dir paper_dir / preferred_name if preferred_dir.is_dir(): candidate_dirs.append(preferred_dir) for child in sorted(paper_dir.iterdir()): if child.is_dir() and child not in candidate_dirs: candidate_dirs.append(child) nested_artifact_dirs { artifact.parent for pattern in (*.md, *_content_list.json) for artifact in paper_dir.rglob(pattern) } for artifact_dir in sorted(nested_artifact_dirs): if artifact_dir not in candidate_dirs: candidate_dirs.append(artifact_dir) for candidate_dir in candidate_dirs: if list(candidate_dir.glob(*.md)): return candidate_dir return candidate_dirs[0] if candidate_dirs else paper_dir可以将其理解为三层候选收集 一次 Markdown 验证的策略优先目录先检查auto/与hybrid_auto/两个已知嵌套模式目录存在即纳入候选这正是本版本修复的核心场景直接子目录把paper_dir下其余所有子目录按排序加入候选保持确定性递归产物定位用rglob递归查找*.md与*_content_list.jsonMinerU 的解析产物清单文件把所有产物所在父目录收集为候选——无论嵌套多深都能命中最后遍历候选目录返回第一个确实包含*.md文件的目录若所有候选都没有 Markdown则退化为返回第一个候选或原始paper_dir由上层加载逻辑继续判定。同样的嵌套目录意识也出现在解析结果缓存层deeptutor/services/parsing/cache.py 中对auto//hybrid_auto/的查找逻辑保持一致Engines (MinerU especially) may nest output under auto/ / hybrid_auto/说明这是对整个 MinerU 输出约定的系统性适配而非单点修补。该能力有专门测试覆盖见 tests/tools/test_question_extractor.py 与 tests/tools/test_mineru.py发布说明中的question extractor regression tests即包含此项。Mimic WebSocket 崩溃修复/mimic是仿真题生成的 WebSocket 端点定义于 deeptutor/api/routers/question.pyrouter.websocket(/mimic) async def websocket_mimic_generate(websocket: WebSocket): WebSocket endpoint for mimic exam paper question generation. Supports two modes: 1. Upload PDF directly via WebSocket (base64 encoded) 2. Use a pre-parsed paper directory path 本版本修复了该端点因缺少sys与Path导入而在运行时抛出NameError的崩溃——即模块内代码引用了sys/Path但头部没有对应 import导致相关分支一执行就中断连接。当前仓库中该文件头部已包含这两处导入# deeptutor/api/routers/question.py from pathlib import Path # L5 ... import sys # L7从该端点的实现还可以看到本次热重载之外的工程细节出题产物输出目录_mimic_output_dir()采用每次调用时动态解析get_path_service().get_question_dir() / mimic_papers见 question.py L36-L40以确保多用户场景下按认证后的调用者工作区路由而不是使用 import 时刻固化的管理员目录。对应的路由回归测试位于 tests/api/test_question_router.py。Python 3.11 最低版本基线v1.0.0-beta.2 移除了对 Python 3.10 的支持最低要求为Python 3.11CI 矩阵、pyproject.toml 与全部文档同步更新。当前仓库中的声明为# pyproject.toml requires-python 3.11,3.14即安装 DeepTutor 时 Python 解释器须满足 3.11 及以上且上限为 3.13。这一约束直接影响自部署在 3.10 环境的 Docker 镜像或 venv 中pip install -e ./pip install -r requirements/server.txt见 requirements/server.txt会因解释器版本不满足元数据而直接失败属于安装前置条件而非可选建议。配合的 CI 维护变更包括精简 CI 测试矩阵为 Python3.11 / 3.12两档移除 Dependabot 自动依赖更新 PR为问题提取器、mimic WebSocket 路由、设置缓存失效新增回归测试前文各节已分别给出对应测试文件。社区贡献与版本脉络本版本由社区贡献者完成主要修复2023Anita— MinerU 嵌套输出修复与 Python 3.11 依赖标记PR #250、#251YizukiAme— Mimic WebSocket 导入修复与设置缓存失效PR #253、#254。在仓库的发布文档序列中ver1-0-0-beta-1 之前为 0.x 系列如 ver0-5-0beta.2 之后依次有 beta-3、beta-4 直至正式版 v1.0.1。如果你正在维护较旧的 beta.1 部署本文列出的三项修复热重载、MinerU 嵌套目录、/mimic崩溃正是升级到 beta.2 及以上的直接收益若部署环境仍停留在 Python 3.10需要先升级解释器再应用该版本。小结v1.0.0-beta.2 虽然是一个 beta 里程碑版本但四项变更分别命中了自部署场景的三个高频痛点改配置要重启_invalidate_runtime_caches的三函数失效链、MinerU 解析成功却出题失败_find_parsed_content_dir的三层候选目录算法、以及/mimic端点因导入缺失而崩溃补上sys/Path。所有关键行为均有tests/下的回归测试对应且 Python 3.11 基线写入了 pyproject.toml 的requires-python元数据作为安装时机的硬性校验。【免费下载链接】DeepTutorDeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.项目地址: https://gitcode.com/GitHub_Trending/dee/DeepTutor创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 DeepTutor v1.0.0-beta.2 发布解读：设置热重载、MinerU 嵌套目录修复与 Python 3.11 基线
DeepTutor v1.0.0-beta.2 发布解读设置热重载、MinerU 嵌套目录修复与 Python 3.11 基线【免费下载链接】DeepTutorDeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.项目地址: https://gitcode.com/GitHub_Trending/dee/DeepTutorDeepTutor v1.0.0-beta.2发布于 2026.04.07是一次以运行时体验为核心的版本更新模型设置API Key、模型选择、Endpoint在保存后立即生效而无需重启服务问题提取器能够发现 MinerU 嵌套输出目录如hybrid_auto/中成功解析出的 Markdown同时修复了/mimicWebSocket 端点的NameError崩溃并将 Python 最低版本要求提升至 3.11。读完本文你将掌握这四项变更在 DeepTutor 源码中的具体落点设置缓存失效的调用链、MinerU 目录发现算法的实现细节以及对应的回归测试位置便于在自部署环境中验证与排查同类问题。版本定位与变更总览v1.0.0-beta.2 的发布说明位于 assets/releases/past_releases/ver1-0-0-beta-2.md它承接 beta.1 进入 1.0 稳定化阶段变更可归纳为四类类别变更影响的代码位置功能增强Hot Settings Reload设置热重载deeptutor/api/routers/settings.py功能增强MinerU 嵌套输出目录支持deeptutor/tools/question/question_extractor.py缺陷修复/mimicWebSocketNameError崩溃deeptutor/api/routers/question.py基线调整最低 Python 版本提升至 3.11pyproject.toml以下逐一展开并结合当前仓库源码印证每项变更的实际实现。Hot Settings Reload保存即生效的设置热重载这是本版本最重要的体验改进。在此之前的行为是修改 API Key、切换模型或更换 Endpoint 后运行中的 LLM 客户端、嵌入Embedding客户端以及配置缓存仍持有旧值必须重启服务才能生效。v1.0.0-beta.2 之后通过 Settings 页面或引导向导onboarding tour保存设置时运行时缓存会被自动失效下一次调用即加载最新配置。失效机制的源码实现核心实现是 deeptutor/api/routers/settings.py 中的_invalidate_runtime_caches()函数def _invalidate_runtime_caches() - None: Force runtime clients/config to pick up the latest saved catalog. The LLM and embedding clients are process-wide singletons, so resetting them here will affect any user turn that is mid-flight on another worker. Admins issuing Apply during active sessions accept that trade-off; we log a WARNING so the cause is visible in the audit trail. logger.warning( Admin applied catalog; resetting global LLM/embedding clients. In-flight user turns may flip backend client mid-call. ) clear_llm_config_cache() reset_llm_client() reset_embedding_client()从源码结构看热重载由三个步骤组成clear_llm_config_cache()—— 清空 LLM 配置缓存。DeepTutor 中 LLM 客户端与嵌入客户端是进程级单例配置一旦解析就会驻留在内存中不清缓存的话即使落盘了新配置下一次get_llm_config()仍会返回旧值。reset_llm_client()—— 重置 LLM 客户端实例使下一次请求按新的 API Key / Endpoint / 模型重新构造连接。reset_embedding_client()—— 对嵌入客户端做同样处理保证向量化服务如知识库构建、RAG 检索也切换到新配置。值得注意的是函数体中的 WARNING 日志由于客户端是进程级单例若管理员在有用户会话进行中时执行 Apply正在飞行的请求mid-flight turn可能会在调用中途切换后端客户端。DeepTutor 没有为避免这一竞态而引入复杂的事务机制而是接受这一权衡通过日志保证审计可见——这是从单例缓存失效方案中推断出的设计取舍。该函数在路由中至少被三处触发对应 Settings 页的保存、目录 Apply 以及 onboarding tour 完成等入口# deeptutor/api/routers/settings.py ... _invalidate_runtime_caches() # L1016 ... _invalidate_runtime_caches() # L1025 ... _invalidate_runtime_caches() # L1242回归测试保障发布说明中提到为设置缓存失效新增了回归测试对应实现位于 tests/api/test_settings_router.py其中包含三个针对性用例test_update_catalog_invalidates_runtime_caches约 L528——验证更新模型目录接口会触发缓存失效test_apply_catalog_invalidates_runtime_caches约 L573——验证Apply操作路径同样失效缓存test_complete_tour_invalidates_runtime_caches约 L641——验证 onboarding tour 完成时也会失效运行时缓存。这些测试通过对llm_config_module.clear_llm_config_cache()与llm_client_module.reset_llm_client()打桩monkeypatch来断言失效逻辑确实被执行与源码中保存 → 失效 → 下次请求重建的调用链一一对应。MinerU 嵌套输出目录支持问题背景DeepTutor 的仿真题生成mimic exam等工作流依赖文档解析引擎MinerU先把 PDF 解析为 Markdown再由问题提取器question extractor读取这些 Markdown 来出题。MinerU 的输出目录结构并不固定不同版本/模式下解析产物可能位于输出目录顶层也可能嵌套在auto/、hybrid_auto/等子目录中。v1.0.0-beta.2 之前的问题是MinerU 明明成功解析了文档但解析产物落在嵌套子目录里提取器只按旧规则查找找不到 Markdown最终导致解析成功但出题失败的假性故障。目录发现算法修复后的核心逻辑是 deeptutor/tools/question/question_extractor.py 中的_find_parsed_content_dir()def _find_parsed_content_dir(paper_dir: Path) - Path: Locate the MinerU output directory that contains parsed markdown artifacts. candidate_dirs: list[Path] [] for preferred_name in (auto, hybrid_auto): preferred_dir paper_dir / preferred_name if preferred_dir.is_dir(): candidate_dirs.append(preferred_dir) for child in sorted(paper_dir.iterdir()): if child.is_dir() and child not in candidate_dirs: candidate_dirs.append(child) nested_artifact_dirs { artifact.parent for pattern in (*.md, *_content_list.json) for artifact in paper_dir.rglob(pattern) } for artifact_dir in sorted(nested_artifact_dirs): if artifact_dir not in candidate_dirs: candidate_dirs.append(artifact_dir) for candidate_dir in candidate_dirs: if list(candidate_dir.glob(*.md)): return candidate_dir return candidate_dirs[0] if candidate_dirs else paper_dir可以将其理解为三层候选收集 一次 Markdown 验证的策略优先目录先检查auto/与hybrid_auto/两个已知嵌套模式目录存在即纳入候选这正是本版本修复的核心场景直接子目录把paper_dir下其余所有子目录按排序加入候选保持确定性递归产物定位用rglob递归查找*.md与*_content_list.jsonMinerU 的解析产物清单文件把所有产物所在父目录收集为候选——无论嵌套多深都能命中最后遍历候选目录返回第一个确实包含*.md文件的目录若所有候选都没有 Markdown则退化为返回第一个候选或原始paper_dir由上层加载逻辑继续判定。同样的嵌套目录意识也出现在解析结果缓存层deeptutor/services/parsing/cache.py 中对auto//hybrid_auto/的查找逻辑保持一致Engines (MinerU especially) may nest output under auto/ / hybrid_auto/说明这是对整个 MinerU 输出约定的系统性适配而非单点修补。该能力有专门测试覆盖见 tests/tools/test_question_extractor.py 与 tests/tools/test_mineru.py发布说明中的question extractor regression tests即包含此项。Mimic WebSocket 崩溃修复/mimic是仿真题生成的 WebSocket 端点定义于 deeptutor/api/routers/question.pyrouter.websocket(/mimic) async def websocket_mimic_generate(websocket: WebSocket): WebSocket endpoint for mimic exam paper question generation. Supports two modes: 1. Upload PDF directly via WebSocket (base64 encoded) 2. Use a pre-parsed paper directory path 本版本修复了该端点因缺少sys与Path导入而在运行时抛出NameError的崩溃——即模块内代码引用了sys/Path但头部没有对应 import导致相关分支一执行就中断连接。当前仓库中该文件头部已包含这两处导入# deeptutor/api/routers/question.py from pathlib import Path # L5 ... import sys # L7从该端点的实现还可以看到本次热重载之外的工程细节出题产物输出目录_mimic_output_dir()采用每次调用时动态解析get_path_service().get_question_dir() / mimic_papers见 question.py L36-L40以确保多用户场景下按认证后的调用者工作区路由而不是使用 import 时刻固化的管理员目录。对应的路由回归测试位于 tests/api/test_question_router.py。Python 3.11 最低版本基线v1.0.0-beta.2 移除了对 Python 3.10 的支持最低要求为Python 3.11CI 矩阵、pyproject.toml 与全部文档同步更新。当前仓库中的声明为# pyproject.toml requires-python 3.11,3.14即安装 DeepTutor 时 Python 解释器须满足 3.11 及以上且上限为 3.13。这一约束直接影响自部署在 3.10 环境的 Docker 镜像或 venv 中pip install -e ./pip install -r requirements/server.txt见 requirements/server.txt会因解释器版本不满足元数据而直接失败属于安装前置条件而非可选建议。配合的 CI 维护变更包括精简 CI 测试矩阵为 Python3.11 / 3.12两档移除 Dependabot 自动依赖更新 PR为问题提取器、mimic WebSocket 路由、设置缓存失效新增回归测试前文各节已分别给出对应测试文件。社区贡献与版本脉络本版本由社区贡献者完成主要修复2023Anita— MinerU 嵌套输出修复与 Python 3.11 依赖标记PR #250、#251YizukiAme— Mimic WebSocket 导入修复与设置缓存失效PR #253、#254。在仓库的发布文档序列中ver1-0-0-beta-1 之前为 0.x 系列如 ver0-5-0beta.2 之后依次有 beta-3、beta-4 直至正式版 v1.0.1。如果你正在维护较旧的 beta.1 部署本文列出的三项修复热重载、MinerU 嵌套目录、/mimic崩溃正是升级到 beta.2 及以上的直接收益若部署环境仍停留在 Python 3.10需要先升级解释器再应用该版本。小结v1.0.0-beta.2 虽然是一个 beta 里程碑版本但四项变更分别命中了自部署场景的三个高频痛点改配置要重启_invalidate_runtime_caches的三函数失效链、MinerU 解析成功却出题失败_find_parsed_content_dir的三层候选目录算法、以及/mimic端点因导入缺失而崩溃补上sys/Path。所有关键行为均有tests/下的回归测试对应且 Python 3.11 基线写入了 pyproject.toml 的requires-python元数据作为安装时机的硬性校验。【免费下载链接】DeepTutorDeepTutor: Lifelong Personalized Tutoring. https://deeptutor.info/.项目地址: https://gitcode.com/GitHub_Trending/dee/DeepTutor创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考