v2.2.1 修复 >2GiB 模型校验死循环（数组维度超过了支持的范围）

v2.2.1 — 修复 >2 GiB 模型「校验失败(数组维度超过了支持的范围。)」死循环。特别提示：用下载器下载时##建议关闭梯子##，下载器会自动检测网速，检测时如果huggingface突发网速快，会优先用huggingface下载，不关梯子费流量。

症状

下载 Qwen_Image-Q6_K.gguf（16.82 GB）、Qwen_Image-Q2_K（7.06 GB）等模型，进度走到 100% 后报：

校验失败(数组维度超过了支持的范围。)，丢弃半成品（第 1 次）
校验失败(数组维度超过了支持的范围。)，丢弃半成品（第 2 次）
连续校验失败 2 次，放弃该文件
全部线路失败: Qwen_Image-Q6_K.gguf

重新点开始又从 0 字节下载，再次撞同样的报错，永远下不完。

根因

校验函数读取文件头时写的是 new byte[Math.Min(4096, (int)len)]，len 是 long 类型的文件字节数。当文件大小对 4 GiB 取模落在 2 GiB ~ 4 GiB 区间时，(int)len 溢出成负数，new byte[负数] 抛出 OverflowException，其文案正是「数组维度超过了支持的范围。」。该异常又被外层 catch (Exception) 当作数据损坏处理，于是删除 .part 重下。

因此表现为「有的模型能下、有的死活不行」：

模型	大小	模 4 GiB	v2.2.0 结果
Qwen_Image-Q2_K	7,062,518,304 B	2.77 GB	必败
Qwen_Image-Q6_K	16,824,990,240 B	3.94 GB	必败
Qwen_Image-Q3_K_M	9,679,567,392 B	1.09 GB	正常
Qwen_Image-Q4_K_M	13,065,746,976 B	0.18 GB	正常

修复

1. 头部长度全程按 long 计算（Math.Min(len, 4096L)）后再收窄为 int，并改为循环读满文件头（顺带修掉 4 GiB 整数倍时 (int)len 归零、读不到文件头的同一隐患）。
2. 校验异常分级：
   • InvalidDataException（HTML 页面、文件过小、GGUF 魔数错、safetensors 头部非法、SHA-256 不符）→ 判定数据不可信，清理半成品并限次重试（行为不变）；
   • 其他异常（溢出 / IO / 内存）→ 保留半成品并终止该文件，不再误删已下完的数据。
3. 「已存在文件」校验走同一函数，同样按异常类型分流：程序性异常不再把用户磁盘上的好文件转成 .part 重下。

验证

组	内容	结果
大文件校验单测	2.5 GiB、7.06 GB、16.82 GB、9.68 GB、13.07 GB、4 GiB 边界全部通过；HTML / 过小 / 魔数错 / safetensors 头非法 / SHA 不符仍被正确拒绝	16/16 PASS
端到端真实下载	本地 HTTP 下载 2.2 GB 文件：落盘长度正确、无「校验失败」、二次运行「已存在且校验通过，跳过」	6/6 PASS
v2.2 原有回归	站点解析归一化、测速排序、择优选线下载、真实 hf-mirror.com 测速	27/27 PASS

资产

资产	说明
LocModel-Downloader-v2.2.1.exe	单文件图形下载器（89 KB，.NET Framework 4.8，系统自带无需安装；文件名用 ASCII，下载后可直接改名）
locmodel-downloader-v2.2.1-src.zip	完整 C# 源码（src/），可用系统自带 csc.exe 自行编译

升级说明

直接替换旧 exe 即可，模型目录、自定义站点配置均沿用。v2.2.0 及更早版本保留在仓库与历史 Release 中，不做删除。

已存在的大小正确文件无需重新下载：新版启动后会校验通过并跳过；若之前因该缺陷残留了 .part，新版会先校验再决定续传或丢弃，不会误删完好的目标文件。

---

v2.2.1 — Fix the endless verify loop on model files larger than 2 GiB

Symptom: after reaching 100% on Qwen_Image-Q6_K.gguf (16.82 GB) or Qwen_Image-Q2_K (7.06 GB), the downloader logged 校验失败(数组维度超过了支持的范围。)，丢弃半成品 twice, dropped the finished .part file and restarted from zero — forever.

Root cause: the verifier read the file header with new byte[Math.Min(4096, (int)len)] where len is a long file size. For any file whose size mod 4 GiB falls between 2 GiB and 4 GiB, the cast overflows to a negative int, and new byte[negative] throws OverflowException (message: 数组维度超过了支持的范围。). The outer catch (Exception) treated it as corrupt data and deleted the .part.

Fixes: (1) compute the header length in long before narrowing and read the header in a loop; (2) split verify error handling — only InvalidDataException clears the .part, any other exception keeps it and aborts that file; (3) the existing-file check follows the same split, so a good file on disk is never converted into a .part.

Verified: 16/16 large-file verify cases, 6/6 end-to-end real 2.2 GB download cases, 27/27 existing v2.2 site/download regression cases.

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

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....

v1.0.0

适用版本：LocModel 2.1.0 ✅ · LocModel 3.1.0 ✅（两版均已本机实测）
平台：Windows 10 / 11（.NET Framework 4.x，目标机无需安装任何运行库）

把 LocModel 配置文件 settings.json 中的 custom_mirror 字段改为 https://hf-mirror.com，解决国内网络下 LocModel「网络无法连接」、拉不到模型列表、模型下载失败的问题。使用时，经实测，打开locmodel后点击下载，如果下载过程中报错或开始就报错，不要点重试，一定直接退出locmodel再重新打开程序点下载，中途断掉的可以续传，有的模型多次报错就关掉程序在重开再试就可成功。镜像连接后的速率一般在25-90MB/s。

---

一、3.1.0 兼容性验证（2026-11-09 实测）

结论：LocModel 从 2.1.0 升级到 3.1.0 后，本补丁无需任何修改，原程序仍可正常使用。3.1.0 版经测试仍可使用。

核验项	2.1.0（原结论）	3.1.0（本次实测）	判定
部署与版本	—	LocModel.exe FileVersion = ProductVersion = 3.1.0（19,240,760 字节），进程正常运行	升级成功
custom_mirror 字段	存在	仍存在，值 https://hf-mirror.com 被保留；settings.json 被程序回写后该字段未被丢弃	有效
程序内镜像常量	内置 hf-mirror.com	仍内置该常量，紧邻模型列表探测逻辑	有效
HF_ENDPOINT 支持	不支持	仍不支持（字符串命中 0 次）	无变化
直连 huggingface.co	超时	仍不通：DNS 被污染为 199.59.148.8，curl 12.0s 超时（code=000）	仍不通
hf-mirror.com 可用性	HTTP 200	HTTP 200 / 1.02s，模型列表、仓库信息均 200，Range 请求 206	仍可用
实际下载链路	走镜像	实测走 hf-mirror 兜底线路，未走 huggingface.co	有效
真实下载落地	—	5690 MB 模型实测下载中，速度 448–567 KB/s，.part 断点续传正常	正常

下载链路抓包证据

点击 LocModel 模型页「下载」后，实时抓取进程连接：

• 目标连接：65.9.168.32:443、65.9.168.58:443（均为 Established）
• 服务端证书：CN=cas-bridge.xethub.hf.co
• SNI 探测：hf-mirror.com 正常建链；huggingface.co 被远程 RST
• 结论：流量经 hf-mirror 解析后直达 xet-bridge CDN，全程未直连 huggingface.co，即 custom_mirror 在 3.1.0 的下载流程中确实被读取并生效。

---

二、3.1.0 的机制变化（不影响本补丁，但需知晓）

变化	证据	对本补丁的影响
新增 hf_mirror 字段，默认值 member	settings.json + 程序内 set_hf_mirror(mode) 命令	无。未开通会员时该线路不可用，程序自动回落 custom_mirror 兜底
下载线路改为多线路优选	新增 accel_lines、preferred_line，报错文案改为「所有线路都下载失败」「换线路接着下」	无。兜底线路即 custom_mirror，补丁继续生效
手动选线路需开通会员	错误码 NEED_ACCEL｜手动选择下载服务器需要开通高速下载服务	无。member_token 为空时会员线路接口返回 404，本就走兜底
新增 github_mirror、hf_token、perf_fa、perf_kv、gpu_devices、images_dir、auto_restart 等字段	settings.json 字段对比	无。与本问题无关，补丁只改 custom_mirror 一个键

说明：3.1.0 若开通会员并使用「会员高速线路」，下载速度会更高；未开通时本补丁的镜像兜底仍是国内网络下最可靠的方案。

---

三、用法（与 2.1.0 时期完全一致）

情况 1：LocModel 已装好
双击 locmodel_patch.exe 即可。

情况 2：便携版 / 手动指定

locmodel_patch.exe --path "C:\Users\你的用户名\AppData\Local\LocModel\settings.json"

先看会改什么、不动任何东西：

locmodel_patch.exe --dry-run

3.1.0 的配置文件位置未变：%LOCALAPPDATA%\LocModel\settings.json。

---

四、参数与退出码

参数	作用
--path <路径>	指定 settings.json 完整路径或其所在目录
--dry-run	只打印将要做的改动，不写入、不备份、不碰进程
--no-process	跳过 LocModel 进程检查与关闭
--no-restart	改完不自动重启 LocModel
--silent	结束后不等待回车
--help	显示帮助

退出码	含义
0	成功（含「已是目标值，无需修改」）
1	未知错误 / 参数错误
2	找不到配置文件
3	配置里没有 custom_mirror 键（未做任何写入）
4	写入或校验失败（已用备份自动回滚）
5	LocModel 进程未能关闭（未做任何改动）

---

五、安全边界

• 只改 custom_mirror 一个值；缩进、换行符、BOM、键顺序、尾随换行全部原样保留。
• 只碰 settings.json；模型目录、apis.json、images.json、注册表一律不动。
• 改写前自动备份：settings.json.bak.20261105-212910，重复执行自动追加序号。
• 绝不强杀进程，15 秒不退就中止。
• 当前值已是 https://hf-mirror.com 时直接提示「已是目标值，无需修改」。

---

六、资产

文件	说明
locmodel_patch.exe	单文件补丁程序，双击即用
locmodel_patch.cs	完整源码，含中文注释
README.md	使用说明与实测记录

源码可用 Windows 自带编译器重新编译，无需 Visual Studio：

c:\Windows\Microsoft.NET\Framework64\v4.0.30319\csc.exe /nologo /target:exe /codepage:65001 /optimize+ /out:locmodel_patch.exe locmodel_patch.cs