Skip to content

[Feature Request] 模型缓存目录生命周期:默认位置与依赖树解耦 + 首次启动自动迁移 #4

Closed

Description

@heptaspirit

背景 / 动机

transformers.js 的模型缓存默认位于包内
node_modules/@huggingface/transformers/.cache/,生命周期绑定在依赖树上。
用户执行 pnpm 重装 / 清理 node_modules 后模型即丢失,下次启动触发重新下载;
在网络不稳的环境下(大文件下载易断流),一次插件更新 = 重新下载一次模型

现状

  • embedModelCacheDir 配置已存在(v0.2+),可以指定缓存目录 ✅
  • 但默认值为空字符串 = 回落 transformers 包内 .cache,重装即丢 ❌
  • 无自动迁移、无面板可视化;docs/LOCAL_MODEL.md 字段名过时
    (写的是 embedCacheDir,实际 schema 是 embedModelCacheDir,照文档配会被静默丢弃)

建议方案

  1. 默认缓存目录改为用户级路径(如 ~/.dsh/mneme/models,或跟随 transformers
    标准 ~/.cache/huggingface),与依赖树彻底解耦;embedModelCacheDir 保留为高级覆盖项。
  2. 首次启动自动迁移:检测到默认缓存有模型、而 embedModelCacheDir 为空时,
    自动将模型搬移到新默认位置(或至少输出一条醒目提示),保证升级路径平滑。
  3. Web 面板展示缓存状态:模型位置 / 占用大小 / 完整性 / 缓存目录配置入口,
    减少手改 YAML。
  4. 修正文档字段名:LOCAL_MODEL.md 的 embedCacheDir → embedModelCacheDir,
    embedModel → localEmbedModel。

验收标准

  • 重装 / 清理 node_modules 后,模型不丢失、启动不触发重新下载。
  • 全新安装用户无需手改任何配置,即可获得持久化模型缓存。
  • 已有用户升级后,模型自动迁移(或给出明确的一次性提示)。

兼容性与影响

  • embedModelCacheDir 语义不变,已配置用户无感;仅默认值变化(CHANGELOG 标注)。
  • 迁移为纯文件移动,不涉及 SQLite schema / API 变更,无数据风险。

替代方案(可选)

  • 维持现状 + 仅在文档中强调手动配置 embedModelCacheDir:
    改动最小,但默认位置的坑仍在,新用户依然会踩。

Activity

  1. Anans-Amarre commented on Aug 16, 2026

    @Anans-Amarre
    Collaborator

    感谢建议!@heptaspirit 我们认同这个方向,分析如下:

    1. 默认缓存目录与依赖树解耦:认同,模型放 node_modules 里重装即丢是真实痛点。会评估改为用户级路径(如 ~/.dsh/mneme/models),embedModelCacheDir 保留为高级覆盖项
    2. 首次启动自动迁移:认同平滑升级,会考虑自动迁移或醒目提示的轻量方案
    3. Web 面板展示缓存状态:有价值,但优先级靠后(当前在修更核心的向量一致性问题)
    4. 文档字段名错误:LOCAL_MODEL.md 写 embedCacheDir / embedModel / embedDevice,实际是 embedModelCacheDir / localEmbedModel / localEmbedDevice —— 这个会立刻修(零成本,避免更多人照文档配错)

    修复优先级:先修文档字段名 → 再改默认值。会陆续处理,感谢宝贵的反馈!

  2. modusensus commented on Aug 16, 2026

    @modusensus
    Member

    已在 v0.3.3 修复,感谢建议。

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions