本地部署大模型：text-generation-webui 模型下载的完整操作手册

本地部署大模型：text-generation-webui 模型下载的完整操作手册

【免费下载链接】textgenOpen-source desktop app for local LLMs. Text, vision, tool-calling, OpenAI/Anthropic-compatible API. 100% private.项目地址: https://gitcode.com/GitHub_Trending/te/textgen

用 text-generation-webui 跑本地 LLM，模型获取是最容易卡住新手的一环。好消息是它的下载系统已经把脏活都包办了：自动建目录、替你在多种格式里挑一个、断点续传、SHA256 逐文件校验，网页界面和命令行两条路都能走。这篇按"从第一次下载到出问题时怎么办"的顺序，把所有常用操作一次讲清楚。

第一次下载：一条命令或一个输入框

这一节解决"我手里只有模型路径，怎么把它弄到本地"的问题。

最简路径是命令行：

python download-model.py facebook/opt-1.3b

这条命令背后发生的事：脚本解析出仓库名和分支（默认 main，想换分支就写成模型名:分支名），扫描仓库文件清单，按硬件适配规则选好格式，把文件放进user_data/models/下的专属文件夹。下载完你不需要做任何配置，刷新模型下拉列表就能看见它，选中后点 Load 即可开始对话。

如果你习惯图形界面，打开 Model 标签页，在 "Download model or LoRA" 输入框填同样的路径，点 Download。两种入口功能等价，网页版还能看到实时进度条，适合盯着大文件慢慢下。

按硬件挑格式：GGUF 量化与 4-bit 加载

这一节解决"仓库里有十几种格式，我该下哪个"的问题，也是 GGUF 模型下载教程里最常踩的坑。

脚本替你做了大部分决策：仓库里同时存在 safetensors 和 GGUF 时，它只保留 safetensors；如果仓库清一色 GGUF，它只会挑文件名里带 Q4_K_M 的那个量化版本——这是体积和质量比较均衡的一档，不想占磁盘的话正合适。

显存宽裕的情况（比如 12GB 以上），用 Transformers 加载器加载 safetensors，勾上load_in_4bit和use_double_quant，多数 7B 到 13B 的模型都能在消费级显卡上跑起来。

GGUF 仓库一般一次放出 Q2 到 Q8 好几个量化档，全下会浪费几十 GB。正确做法是：网页输入框里填好路径后先点 "Get file list"，从列表里复制你想要的那个具体文件名，粘贴到 "File name" 框再点 Download，只拉一个文件。

命令行进阶参数：断点续传与镜像源

这一节给批量下载或网络不稳定的场景准备的，记住四五个参数就够。

• --threads 8：并发文件数，默认 4。
• --max-retries 10：单文件重试上限，默认 7 次，采用指数退避。
• --output或--model-dir：改保存到别的磁盘。
• --clean：放弃断点续传，重新下载。

下载中途断网？不用重新来。重跑同一条命令，脚本会先比对本地已有字节数，从断点继续写文件。

访问 HuggingFace 本身很慢或不通时，在运行前设置环境变量HF_ENDPOINT指向你的镜像源，脚本里所有请求都会跟着换。私有模型则靠HF_TOKEN（或HF_USER/HF_PASS）带认证头，代理直接配置系统常规的HTTPS_PROXY环境变量即可。

校验失败与空间管理

这一节处理两类事后问题：文件对不对、磁盘够不够。

下载完成后，模型文件夹里会多一个huggingface-metadata.txt，记录了来源 URL、分支、下载时间和全部文件的 SHA256 清单。怀疑文件损坏时，加--check参数对已下文件重新算哈希比对，全过才打印 "Validated checksums of all model files"；个别文件不对，用--clean重跑即可。

几个省空间的实践：优先选 4-bit 量化档；不常用模型挪到机械硬盘，再用--model-dir把下载目录指过去，WebUI 照样会自动识别；LoRA 文件不用操心，脚本检测到 adapter 权重会自动改存到user_data/loras/，和主模型分开放，磁盘清理时互不干扰。

模型落位后，剩下的事就交给 Model 标签页的下拉列表了——本地部署大模型最难的一步，到这里已经走完。

【免费下载链接】textgenOpen-source desktop app for local LLMs. Text, vision, tool-calling, OpenAI/Anthropic-compatible API. 100% private.项目地址: https://gitcode.com/GitHub_Trending/te/textgen