Skip to content

LocModel 下载器 v2.2.0（独立下载器 · 多站点测速择优）

Choose a tag to compare

View all tags
@jaja1620 jaja1620 released this 12 Nov 17:07
· 2 commits to master since this release
v2.2.0
3efeee3

LocModel 下载器 v2.2.0 · LocModel Downloader v2.2.0

简体中文 | English

简体中文

English version below → English

LocModel 在国内直连 huggingface.co 会被阻断，导致模型列表拉空、下载失败。v1.0 镜像补丁解决了"能联网"，v2.2 独立下载器进一步解决了"下得稳、下得快、下得全"。

v2.2 做了什么（相对 v1.0 的能力增量）

  • 独立 GUI 下载器：不修改、不注入、不 patch LocModel，只读写相同的模型目录，下完即可被 LocModel 识别。
  • 自定义下载站点（新）：顶栏输入框默认 https://hf-mirror.com，可填多个站点，换行/逗号/分号/空格分隔；缺协议自动补 https://、去尾斜杠、协议小写、同协议+域名+端口去重、非法项丢弃并提示。
  • 下载前自动测速择优（新）：每站以 Range 实读 256 KB 测真实速度，3 站并发、单站超时 8 秒；按实测速度排序，优先用最快线路下载，首选失败自动降级到下一名，成功线路自动提前、失败线路自动降位；探测目标取本批最大文件的路径，与真实下载同构。
  • 测速预览（新）：点「测速预览」即时显示各站速度与线路顺序，不必等到下载才知道哪条快。
  • 覆盖全部 28 个模型：图像 6 + 视频 6 + 语言/推理 16，含全部量化档位、mmproj、image\common 共享组件，自动一次备齐。
  • 落盘与 LocModel 完全一致：
    • 图像/视频 → {模型目录}\image\{模型ID}\{上游原文件名}
    • 共享组件 → {模型目录}\image\common\
    • 语言/推理 → {模型目录}\{组织}__{仓库名}\
  • 下载链路加固：HEAD 预检换版、.part + .part.meta 断点续传、416 自愈、临时目录隔离、校验阶梯（长度 → HTML 错误页 → GGUF 魔数 / safetensors 头长 → SHA-256）、磁盘空间预检、单文件失败不中断整批。
  • 目录控制：可自定义模型目录；与 LocModel 默认目录不一致时红字提示并在下载前二次确认（外接硬盘换盘符导致配置漂移的实际情况已被覆盖）。

v2.2 与 v1.0 的设计思路差别，以及为什么

维度 v1.0 补丁 v2.2 下载器
思路 让本体会走镜像：改 settings.json 的 custom_mirror 自己成为下载器：独立进程直接写模型目录
镜像数量 只能 1 个 任意多个，自动归一化去重
线路选择 本体内部逻辑，用户不可干预 下载前测速，最快者优先，失败自动降级
生效范围 仅 LocModel 自己的下载页 全部 28 个模型含隐藏依赖文件
续传控制 受本体策略约束，失败后 custom_mirror 会被回写成会员线路，需重启再试 自管 .part 续传 + HEAD 预检 + ETag 变化识别 + 416 自愈
改动对象 settings.json（有备份、可回滚、支持 --dry-run） 不改任何配置，只写模型文件
体量 18 KB 控制台 88 KB 图形界面

为什么从 v1.0 演进到 v2.2：

  1. 本体没有可编程入口，端口注入这条路走不通。 实测 LocModel 主进程（Tauri + WebView2）不监听任何 TCP/UDP 端口，对 axum / warp / actix / TcpListener / HttpServer / tiny_http 全 0 命中；全部能力是 Tauri command，经 window.__TAURI_INTERNALS__.invoke 走 WebView2 postMessage，origin tauri://localhost，外部页面无法调用。设置里的 8686 只是 llama.cpp 推理端口（未启动不监听），8790 只是 stable-diffusion.cpp 的 WebUI（仅 /v1/models、/sdapi/v1/*），都不含下载语义。要突破限制只能自己做下载。
  2. 单镜像不够用。 custom_mirror 只有一个值，镜像抽风就只能干等；用户需要的是"填几个站点，让它自己挑最快的"，这是配置字段无法承载的能力。
  3. 本体在 3.1.0 引入了会员高速线路机制（hf_mirror 字段、accel_lines、preferred_line），下载失败会回写配置，用户很难稳定停留在镜像线路上；独立下载器不受这套回写逻辑影响。
  4. 本体下载页不暴露依赖细节（image\common 等），独立器可以一次把所有依赖备齐，避免 LocModel 下载到一半才报缺件。

一句话：v1.0 是"让本体会走镜像"，v2.2 是"自己成为下载器"。 v2.2 保留了 v1.0 的全部结论（hf-mirror 可用、huggingface.co 不可直连），但把"镜像"从一个配置值升级成"可测速的站点列表"。

使用方法（速览）

  1. 下载本页资产 LocModel-Downloader-v2.2.exe，双击运行（Windows 10/11 自带 .NET Framework 4.8，无需安装任何运行库）。
  2. 启动自动读取 LocModel 模型目录与全部模型参数；左侧选分类与模型，右侧选量化档位。
  3. 站点栏保持默认 https://hf-mirror.com 即可直接下载；需要多站点时一行一个填入（或逗号/分号/空格分隔），可先点「测速预览」看速度排名。
  4. 点「开始下载」：先自动测速，再用最快线路下载；「取消」保留 .part，下次续传。
  5. 完成后在 LocModel 里刷新模型列表即可看到。

完整说明（含界面说明、落盘规则、常见问题、自行编译）：中文 README ｜ English README

兼容性与测试范围（必读）

  • v2.2 仅在 LocModel 3.1.0 上实测通过；未在 LocModel 2.1.0 上测试。 2.1.0 的目录规范与配置字段是否完全一致未经验证。
  • v2.2 读取的配置路径与字段沿用 3.1.0 实测结果：%LOCALAPPDATA%\LocModel\settings.json。
  • 平台：Windows 10 / 11，单文件 exe，无外部依赖。
  • 自定义站点必须能对 /{repo}/resolve/main/{文件路径} 返回文件（HF 镜像或反代）；*.locmodel.com 自有 CDN 不代理 HF 路径，会被自动排除。

验证记录

站点功能回归 27 用例全部 PASS：A 组解析/归一化/链路合并 15/15；B 组测速排序 5/5（快站 3.21 MB/s / 78 ms，慢站 260 KB/s / 984 ms，死站垫底）；C 组择优后选线下载 5/5（31,457,280 字节校验一致、请求只落最优站、慢站零使用、首选失联自动降级）；D 组真实 hf-mirror.com 测速 2/2（161 KB/s / 1593 ms，<10 秒）。下载链路沿用 v2.1 的本地 21 场景 + 真实 4 场景，全部 PASS。

资产说明

文件 说明
LocModel-Downloader-v2.2.exe 单文件图形下载器，双击即用（资产名用 ASCII 以避免下载时中文乱码）
README_zh-CN.md 中文完整说明（仓库 README.md 同源）
README_EN.md English full manual (same as repo README_EN.md)
locmodel-downloader-v2.2-src.zip v2.2 完整源码（5 个 .cs，含注释）

1.0 版保留声明

  • 仓库中 v1.0 的全部文件（locmodel_patch.cs、locmodel_patch.exe、build.cmd、原说明书 README-v1.0.0.md）原样保留，未做任何改动。
  • Release 中的 v1.0.0 保留不删，仍可正常下载使用。

English

中文版见上方 → 简体中文

LocModel cannot reach huggingface.co from mainland China, which leaves the model list empty and makes downloads fail. The v1.0 mirror patch fixed "can it connect"; the v2.2 standalone downloader goes further: stable, fast and complete downloads.

What v2.2 adds over v1.0

  • Standalone GUI downloader: no patching, no injection, no modification of LocModel. It reads/writes the same model directory, so downloaded files are recognized immediately.
  • Custom download sites (new): the top bar is pre-filled with https://hf-mirror.com and accepts multiple sites separated by newlines, commas, semicolons or spaces. Missing schemes get https://, trailing slashes are trimmed, schemes lower-cased, duplicates removed (same scheme+host+port), invalid entries dropped with a hint.
  • Automatic speed probing and best-line selection (new): each site is benchmarked with a real Range read of 256 KB, 3 in parallel, 8 s timeout. Sites are ranked by measured speed and the fastest line is used; on failure it falls back to the next, promoting winners and demoting losers. The probe uses the largest file of the batch, so it mirrors the real transfer.
  • Speed-preview button (new): see every site's throughput and the resulting line order before starting a download.
  • All 28 models covered: 6 image + 6 video + 16 language/reasoning, with every quant level, mmproj and shared image\common components fetched in one go.
  • Identical on-disk layout:
    • Image / video → {model dir}\image\{model-id}\{upstream filename}
    • Shared components → {model dir}\image\common\
    • Language / reasoning → {model dir}\{org}__{repo}\
  • Hardened download pipeline: HEAD pre-check for version changes, .part + .part.meta resume, 416 self-healing, isolated temp directory, verification ladder (length → HTML error page → GGUF magic / safetensors header → SHA-256), disk-space pre-check, per-file failure not aborting the batch.
  • Directory control: custom model directory supported; a red warning plus a confirmation dialog appears when it differs from LocModel's default (covers the real case of drive letters drifting after swapping external drives).

Design difference between v2.2 and v1.0, and why

Dimension v1.0 patch v2.2 downloader
Approach Make LocModel walk the mirror: rewrite custom_mirror in settings.json Become the downloader: a separate process writes the model directory
Mirrors Exactly one Unlimited, auto-normalized and de-duplicated
Line selection Internal to LocModel, user has no say Probed before download, fastest wins, automatic fallback
Coverage LocModel's own download page only All 28 models including hidden dependency files
Resume control Constrained by LocModel; after a failure custom_mirror is rewritten to the member line and the app must be restarted Own .part resume + HEAD pre-check + ETag change detection + 416 self-healing
What it touches settings.json (backup, rollback, --dry-run) No config at all; model files only
Size 18 KB console 88 KB GUI

Why we moved from v1.0 to v2.2:

  1. The GUI offers no programmable entry point, so port injection is impossible. The LocModel main process (Tauri + WebView2) listens on no TCP/UDP port: zero hits for axum / warp / actix / TcpListener / HttpServer / tiny_http. Everything is a Tauri command invoked through window.__TAURI_INTERNALS__.invoke → WebView2 postMessage with origin tauri://localhost, unreachable from external pages. 8686 is only the llama.cpp engine port (idle = not listening) and 8790 is the stable-diffusion.cpp WebUI (/v1/models, /sdapi/v1/* only) — neither carries download semantics. The only way past the limit is to implement downloading yourself.
  2. One mirror is not enough. custom_mirror holds a single value, so a degrading mirror leaves you waiting. Users wanted "fill in several sites and let it pick the fastest", which a config field cannot express.
  3. 3.1.0 added membership fast lines (hf_mirror, accel_lines, preferred_line) and rewrites config after a failed download, making it hard to stay on the mirror line. A standalone downloader is immune to that rewrite.
  4. The built-in page hides dependency details (image\common); a standalone tool fetches every dependency up front instead of failing halfway.

In one sentence: v1.0 makes LocModel walk the mirror; v2.2 becomes the downloader itself. v2.2 keeps every v1.0 finding (hf-mirror works, huggingface.co does not) while upgrading "a mirror" from a config value into "a list of sites you can benchmark".

Quick start

  1. Download LocModel-Downloader-v2.2.exe from this release and double-click it (Windows 10/11 ships .NET Framework 4.8; no runtime install needed).
  2. It reads LocModel's model directory and all model parameters on startup. Pick a category and a model on the left, a quant level on the right.
  3. Keep the default https://hf-mirror.com to download right away, or add more sites (one per line, or comma/semicolon/space separated) and press "Test speed" to preview the ranking.
  4. Press "Start download": it probes first, then downloads over the fastest line. "Cancel" keeps the .part, the next start resumes.
  5. Refresh the model list inside LocModel to see the downloaded models.

Full manual (UI reference, on-disk rules, FAQ, building from source): Chinese README | English README

Compatibility and tested scope (must read)

  • v2.2 was verified on LocModel 3.1.0 only; it was NOT tested on LocModel 2.1.0. Whether 2.1.0 shares the same directory layout and config fields was not verified.
  • The config path and fields used by v2.2 come from 3.1.0 measurements: %LOCALAPPDATA%\LocModel\settings.json.
  • Platform: Windows 10 / 11, single-file exe, no external dependencies.
  • Custom sites must serve /{repo}/resolve/main/{path} (an HF mirror or reverse proxy). *.locmodel.com own CDN does not proxy HF paths and is filtered out automatically.

Verification

27 site-feature cases, all PASS: group A parsing/normalization/chain merge 15/15; group B speed ranking 5/5 (fast 3.21 MB/s / 78 ms, slow 260 KB/s / 984 ms, dead port last); group C best-line download 5/5 (31,457,280 bytes verified, requests hit only the best site, slow site unused, automatic fallback when the best one dies); group D real hf-mirror.com probing 2/2 (161 KB/s / 1593 ms, under 10 s). The download pipeline reuses v2.1's 21 local scenarios plus 4 real-network scenarios, all PASS.

Assets

File Description
LocModel-Downloader-v2.2.exe Single-file GUI downloader, double-click to run (ASCII asset name to avoid mojibake)
README_zh-CN.md Full Chinese manual (same as repo README.md)
README_EN.md Full English manual (same as repo README_EN.md)
locmodel-downloader-v2.2-src.zip Complete v2.2 source (5 .cs files, commented)

v1.0 is preserved

  • Every v1.0 file in the repo (locmodel_patch.cs, locmodel_patch.exe, build.cmd, the original README-v1.0.0.md) is kept unchanged.
  • Release v1.0.0 remains published and downloadable.

（内容由AI生成，仅供参考）／ (This document was generated with AI assistance.)

Assets 2
Loading