Skip to content

v1.0.0

Choose a tag to compare

View all tags
@jaja1620 jaja1620 released this 05 Nov 14:10
· 6 commits to master since this release
v1.0.0
b6443bd

适用版本：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
Assets 3
Loading