笔记 · 2026-11-09
把 llama.cpp 装进 Windows 程序:
安装器的五个坑
我想做到的效果很简单:用户下一个 exe,双击,勾一个“安装推理引擎”,就能跑模型。中间别出现命令行,别让人自己去挑 CUDA 版本。
功能其实两天就写完了。剩下那一周全耗在五个坑上,都是“代码看着没问题、装出来就是不工作”的类型。
坑一:打包用的那个 Python 没有 Tcl/Tk
第一次打出来的安装包双击没反应。没有窗口、没有报错,进程一闪就没了。我查了权限、关了杀软、换了目录,都没用。
真正的原因在打包环境:那个 Python 缺 Tcl/Tk 运行库。tkinter 模块能 import,但建根窗口时要加载 tcl86t.dll 和 _tkinter.pyd,缺了就直接静默退出,连堆栈都不给你。
判断一句话就够,在打包环境里跑:
python -c "import tkinter; tkinter.Tk().destroy(); print('tk ok')"
报 TclError: Can't find a usable init.tcl 或者直接崩,就是它。我后来换了个带完整 Tcl/Tk 的官方解释器来打包,PyInstaller 会把 tcl 目录一起收进 _internal。
坑二:给进度条起了个样式名,窗口全白
坑一修完,窗口终于出来了,但整个界面是白的,控件一个都不显示。日志里只有一句:
Layout Horizontal.Bar.TProgressbar not found
原因是我写了个 style.configure("Bar.TProgressbar", ...),给进度条派生了一个新样式名。ttk 会拿这个名字去找对应的 layout 定义,而 Progressbar 只有内置那一个 layout,找不到就整个布局解析失败,于是整窗白屏。
改法是别派生,直接配默认样式:
style.configure("TProgressbar", thickness=16, troughcolor="#E3EAEE",
background="#8AD3E2", bordercolor="#D7DEE3")
实例那边也不能再传 style=。顺便说另一个白屏原因,比上面这个更朴素:自定义了白底 Frame,却没给里面的 Label、Checkbutton 指定 bg,控件拿系统默认色画在白底上,看着跟没渲染一样。
坑三:别人机器上找不到 powershell
安装完要建开始菜单和桌面快捷方式,我图省事用 subprocess 调 powershell 去生成 .lnk。我自己机器上一直正常,给朋友装的时候报 FileNotFoundError——他 PATH 里没有 powershell。
换成绝对路径就好了,Windows 上这个位置是固定的:
%SystemRoot%\System32\WindowsPowerShell\v1.0\powershell.exe
坑四:1.2 GB 的引擎包,断一次网就全废
最初用的是 urllib.request.urlretrieve,一条连接从头拉到尾。国内连这台服务器实测大概 0.4 MB/s,1.2 GB 要跑四十分钟往上,中间任何一次抖动都会抛 WinError 10054 远程主机强迫关闭了一个现有的连接,然后整包重来。用户看到的就是“装到 43% 失败”,重试两次就骂人了。
改成 16 MB 一块的 Range 请求,每块独立,失败了只重试这一块,已落盘的字节数记下来做续传:
have = os.path.getsize(part) if os.path.exists(part) else 0
req = urllib.request.Request(url, headers={"Range": f"bytes={have}-{have+CHUNK-1}"})
三个边界必须处理:返回 416 说明已经到文件尾;返回 200 说明服务器不支持 Range,只能整体重下;连续十次没有新字节才算真失败,中间一律当抖动。
下完再算 SHA-256 比对。这一步比续传本身更要紧——分块的代价是任何一块都可能被中间网络换掉,不校验等于白做。
坑五:域名没备案,下载链接被“合法”掐断
这个最难受。安装器逻辑全对,就是下载不下来。一层层试出来是这样:
http://域名返回 403,响应头Server: Beaver,正文是一张Non-compliance ICP Filing的提示页;https://域名对 Python(OpenSSL 3.0)和系统curl(Schannel)立刻 RST;- 同一台机器用 Edge 打开同域名,正常。
域名还没完成 ICP 备案,云厂商在 80 端口按 Host 拦,在 443 上对“不像浏览器”的客户端直接重置连接。所以我一开始以为是网络问题,其实是合规拦截——浏览器能过,只因为它的 TLS 指纹被放行。
临时解法是加一条直连 IP 的备用通道:拦截按 Host 和 SNI 做,带 IP 访问不受影响,主通道失败自动切过去。但这只是兜底,IP 一变就失效,而且不该让用户看到裸 IP。真正的修复是去备案。
验收别写“能跑”
安装器有两条路径要走:勾引擎和不勾引擎。两条都得能验,所以给安装器加了静默参数,脚本能直接跑:
setup.exe --silent --dir=D:\test --engine=1 --desktop=0
不勾时应该只有程序本体,几十 MB;勾了应该多出 engine\llama-server.exe 和上千 MB 的运行库。这两条我每次都验,因为“在我机器上能跑”不算数。
还有个设计上的取舍:引擎下载失败不该把整个安装判死。程序本体已经装好了,把“引擎未就绪”降级成一条提示,告诉用户两条补救路(把 zip 放到安装包同目录重跑,或者首次启动让主程序自己补),比让人从头再装一遍强。
本地AI模型工作台
单文件安装包 33 MB · 安装时可选勾引擎(1.2 GB)· Windows 10 / 11 x64 · 装到用户目录,不要管理员权限
打开工具页 模型库、参数与下载安装包直链:/downloads/LocalAIStudio-Setup-1.0.0.exe · 引擎包:/downloads/engine-cuda12.4.zip