)
文章目录
- 前言
- 一、错误记录
- 二、报错分析
- 三、解决方案
- 1、再次执行命令 ( 最简单不一定能成功 )
- 2、配置网络工具 ( 完美解决问题 )
- 四、解决方案 - 手动下载模型 ( 仅做参考 )
- 1、基本思路
- 2、从镜像站拿到 GGUF 文件
- 3、写 Modelfile 并本地建模型
- 4、处理历史缓存
- 五、新手必懂的背景知识
- 1、Ollama 的本地仓库长什么样
- 2、GGUF 文件名里的量化后缀
- 3、Modelfile 还能配置什么
- 4、常用命令与环境变量速查
- 六、注意事项与避坑
- 总结
前言
随着大模型技术的不断发展 , 把模型搬到自己电脑上跑 , 已经从 " 极客玩具 " 变成了常规开发需求 ;
本地跑模型有三个很实在的好处 :
- 数据不出本机 , 不用担心隐私泄露 ;
- 没有按 Token 计费 , 想跑多久跑多久 ;
- 断网环境也能正常推理 ;
在众多本地推理方案中 , Ollama 是新手门槛最低的那一个 ;
Ollama 把模型的下载 , 解压 , 加载 , 显存分配 , 对外接口全部封装起来, 理论上 只需要记住一条命令ollama run就够了 ;
但是 , 当我们尝试用 Ollama 直接从 HuggingFace 拉取第三方 GGUF 模型时 , 在国内网络环境下几乎必然会遇到各种下载失败 ;
本文记录的Error: max retries exceeded就是其中最典型的一种 ;
本文的目标 , 是让读者看懂每一行日志背后的含义 , 而不是单纯地复制几条命令 ;
因此在完整还原排错过程的基础上 , 额外补充了Ollama 模型仓库结构 ,GGUF 与量化后缀 ,Modelfile 配置等新手必备知识点 ;
即使你是第一次接触 Ollama , 也能跟着文章一步步把模型跑起来 ;
阅读前先建立几个基础认知 :四个概念构成了本文的前提 ;
- Ollama :一个跨平台的大模型本地运行框架 ,负责 模型的拉取 , 管理 , 加载 ,并对外提供 HTTP 推理接口 ;
- HuggingFace :全球最大的开源模型社区, 可以理解为 " 模型的 GitHub " ,命令中的
hf.co就是它的短地址 ; - GGUF :一种为 本地推理 设计的 单文件格式, 把模型权重 , 分词器 , 词表 , 超参数 全部打包进一个文件, 方便 Ollama , llama.cpp 这类框架直接加载 ;
- Q4_K_M :GGUF 文件的量化等级标识 , 表示权重被压缩到约 4 bit,牺牲少量精度 , 换取显存与内存占用的大幅下降 ;
一、错误记录
本次要本地部署的模型 , 是社区作者mradermacher发布的Qwen3-14B-abliterated, 选择的是体积与效果都比较均衡的Q4_K_M量化版本 ;
Ollama 支持把 " 仓库地址 + 量化标签 " 直接写进模型名, 因此一条命令就能同时完成拉取与运行 ;
执行下面的命令 , 可以在本地部署大模型 ;
ollama run hf.co/mradermacher/Qwen3-14B-abliterated-GGUF:Q4_K_M回车之后 ,控制台先输出了下载进度, 9 GB 的主文件看起来已经拉完了 , 紧接着却抛出了下面这一大段错误信息 :
D:\Ollama>ollama run hf.co/mradermacher/Qwen3-14B-abliterated-GGUF:Q4_K_M pulling manifest pulling b36d0edb573c:100%▕██████████████████████████████████████████████████████████▏9.0GBError:max retries exceeded:Get"https://huggingface.co/v2/mradermacher/Qwen3-14B-abliterated-GGUF/blobs/sha256:2d54db2b9bb29ce7db54fea63a891f5859603813c555b1f88b5e0994652897f9?__sign=eyJhbGciOiJFZERTQSIsImtpZCI6IjVHZDBvd0g5MTM2eDZjc1FvbE1zcktNWUZoRVFoUm5PVVVybEpjOUhaUEEifQ.eyJyZWFkIjp0cnVlLCJwZXJtaXNzaW9ucyI6eyJyZXBvLmNvbnRlbnQucmVhZCI6dHJ1ZX0sInJlcG9JZHMiOlsiNjgxMjRmMDA1NWJlNWExM2EwZmI5ZTg2Il0sImlhdCI6MTc5MTk4ODEwOSwianRpIjoiMzI3NDUyMTctOGJmNy00M2I1LTliMzUtZWYzNTdjMTgzMDMxIiwic3ViIjoiL21yYWRlcm1hY2hlci9Rd2VuMy0xNEItYWJsaXRlcmF0ZWQtR0dVRiIsImV4cCI6MTc5MTk4ODcwOSwiaXNzIjoiaHR0cHM6Ly9odWdnaW5nZmFjZS5jbyJ9.rzy85d8uXmjyH_P_-yES6rd8d5x_T0GREHVCmbmgWaQdMCKl7XNdKvX7A0MveOAWQGi48flQ1dROnOLlFbpWBQ":dial tcp179.60.193.16:443:connectex:Aconnection attempt failed because the connected party did not properly respond after a period of time,or established connection failed because connected host has failed torespond.D:\Ollama>核心报错信息 :完整内容如下 , 这一段是本次排错的唯一线索 ;
Error: max retries exceeded: Get “XX” : dial tcp 179.60.193.16:443: connectex: A connection attempt failed because the connected party did not properly respond after a period of time, or established connection failed because connected host has failed to respond.
二、报错分析
很多新手看到一长串英文就慌了 , 其实这类日志完全可以逐句拆开读 ;
只要先把Ollama 拉取模型的工作流程搞清楚, 报错原因就不难理解 ;
Ollama 在拉取模型时 , 采用的是与 容器镜像仓库 一致的 " 内容寻址 " 思路, 整体分成三步 :
- 首先 ,获取一份 manifest 清单 ,
- 然后 , 根据 manifest 清单逐个拉取 blob 数据块 ,
- 最后 ,校验 sha256 摘要 并 落盘 ;
理解了这三步 , 下面每一行日志所处的位置就很清楚了 ;
逐行日志拆解 :每一行日志对应的真实状态如下 ;
- pulling manifest 成功 :模型的 " 清单文件 " 已经拿到了, 清单里记录了模型由哪些文件组成 , 每个文件多大 , 校验值分别是多少 ;
- pulling b36d0edb573c: 100% 9.0 GB 成功 :这是 清单里体积最大的主模型文件, 也就是 GGUF 本体 , 9 GB 已经完整下载到本地 ;
- Error: max retries exceeded :Ollama 继续拉取后续 blob 时反复失败, 超过了内置的最大重试次数 , 于是主动放弃 ;
- Get “https://huggingface.co/v2/…/sha256:2d54db2b…” :失败的这个 blob 编号是
2d54db2b...,体积很小 , 通常是 配置文件 , 分词器或模板文件 ; - pulling xxx: verifying sha256 digest 没出现 :说明流程还没走到校验环节 , 模型并未真正可用 , 此时直接运行
ollama run命令 会提示模型不存在 ; - dial tcp 179.60.193.16:443 … did not properly respond :这是最关键的一句 , 表示程序向这个 IP 的 443 端口发起 TCP 连接时, 对方在超时时间内一直没有回应 ;
为什么会卡在这一步 :结合国内网络环境 , 可以判断出下面几个方向 ;
- 静态资源 CDN 被限速 :HuggingFace 的 模型大文件 走的是 独立下载域名,出口 IP 与 官网不同, 这一段链路在跨境时经常出现丢包 ;
- TLS 握手被中断 :已经建立的长连接还能勉强传完大文件 , 而后续新请求需要重新握手 , 更容易在中途被掐断 ;
- DNS 解析不稳定 :域名有时被解析到不可达的地址, 外在表现同样是连接超时 ;
- 不是命令写错 :既然能 拉到 manifest, 还能传完 9 GB , 就说明模型名 , 量化标签 , 鉴权配置都没有问题 ;
如何自行确认是不是网络问题 :打开一个新的命令行窗口 , 用下面几条命令做一次快速体检 ;
# 查看域名被解析到哪个 IP，多次执行结果差别很大，通常意味着 DNS 环节存在干扰nslookuphuggingface.co# 观察实际托管大文件的下载域名的丢包与延迟情况pingcdn-lfs.huggingface.co# 直接发起 HTTPS 请求，观察是否能完成握手并返回响应头curl-Ihttps://huggingface.co结论 :
机器到 HuggingFace 的这条链路不稳定 , 大文件能侥幸传一段 , 后续请求被掐断 ;
这是国内访问 HuggingFace 非常典型的现象, 不是命令写错 , 单纯重试也只能碰运气 ;
三、解决方案
既然根因是网络链路 , 思路就很清晰了 :要么让链路变通畅, 要么干脆绕开这条链路;
下面给出三种由易到难的方案 ;
三种方案对比 :按自身环境选择合适的路线即可 ;
| 方案 | 操作成本 | 成功率 | 适用场景 |
|---|---|---|---|
| 方案一 重试 | 极低 | 低 | 偶发性网络抽风 , 只想快速碰运气 |
| 方案二 网络加速 | 中 | 高 | 本地开发机 , 已有合规可用的网络加速工具 |
| 方案三 手动导入 | 较高 | 高 | 公司内网 , 服务器放行受限 , 无法直连外网 |
1、再次执行命令 ( 最简单不一定能成功 )
先搞清楚为什么重试是有意义的 : Ollama 的每个 blob 都按内容寻址存储 , 已经下载完成的 9 GB 会原样保留在本地仓库里 , 不会白下载 ;
重新执行命令时 , Ollama 会跳过已存在的 blob , 只补齐缺失的那部分 ;
Ollama 已经缓存了那 9 GB 主文件 , 再跑一次往往会续传剩余的小文件 , 有时换个时间点就通了 :
ollama run hf.co/mradermacher/Qwen3-14B-abliterated-GGUF:Q4_K_M建议连试 2 到 3 次 , 每次间隔几分钟 ;
如果每次都卡在同一个sha256:2d54db2b...上 ,说明该端点被稳稳挡住 ,靠重试没用 , 直接走下面的方案 ;
先后重试了 2 次 还是报错 ;
2、配置网络工具 ( 完美解决问题 )
配置网络工具 , 然后再次重试 , 下载成功 ;
D:\Ollama>ollama run hf.co/mradermacher/Qwen3-14B-abliterated-GGUF:Q4_K_M pulling manifest pulling b36d0edb573c:100%▕██████████████████████████████████████████████████████████▏9.0GB pulling4a6ce91d86a8:100%▕██████████████████████████████████████████████████████████▏99Bpulling6031c63420f0:100%▕██████████████████████████████████████████████████████████▏549Bverifying sha256 digest writing manifest successThinking...嗯，用户发来“你好”，看起来是个简单的问候。我需要先回应他的问候，保持友好。可能他只是测试一下，或者想开始聊天。我应 该用中文回复，保持自然，不要太正式。可以问问他有什么需要帮忙的，或者有没有什么话题想聊。不过用户可能没有明确的需求， 所以先打个招呼，然后询问是否需要帮助。确保回复简洁，符合之前的例子。检查有没有拼写错误，保持口语化。好的，准备回复。...done thinking.你好！很高兴见到你。有什么我可以帮你的吗？>>>Senda message(/?forhelp)从这段日志可以看出一次完整的成功流程 :
- 拉取清单 :
pulling manifest拿清单 , - 下载主体 :三个 blob 全部拉取完毕 ,
- 数据校验 :接着
verifying sha256 digest校验完整性 , - 写元数据 :
writing manifest写入元信息 , - 交互对话 :最后
success并进入交互式对话 ;
最后那个>>> Send a message (/? for help)提示符 , 说明模型已经在本地跑起来了 , 可以直接打字聊天 , 输入/bye退出 ;
补充一个小知识点 :这次多出来的两个很小的 blob , 分别是 99 B 与 549 B , 它们就是第一轮失败时没拉下来的配置文件 , 也就是报错信息里反复提到的那个2d54db2b...一类的东西 ; 大文件反而先成功了 , 小文件卡住 , 恰恰说明这不是磁盘空间不足 , 而是短连接被掐断 ;
四、解决方案 - 手动下载模型 ( 仅做参考 )
1、基本思路
既然hf.co直连不稳 , 就改用 HuggingFace 国内镜像站hf-mirror.com把模型文件拉下来, 然后用ollama create在本地从文件建模型 ;
这条路的本质 , 是把 " 在线拉取 " 换成 " 离线导入 " : 下载环节由你用任意稳定的方式完成 ,Ollama 只负责读取本地文件并注册模型 ;
对于公司内网 ,无外网开发机 ,或者 需要把模型拷给同事的场景 , 这是最稳的做法 ;
2、从镜像站拿到 GGUF 文件
先去https://hf-mirror.com/mradermacher/Qwen3-14B-abliterated-GGUF确认文件名为Qwen3-14B-abliterated-Q4_K_M.gguf, 然后下载到本地 , 这里以 D 盘为例 ;
设置镜像环境变量 , 仅当前窗口有效 :
setHF_ENDPOINT=https://hf-mirror.com用huggingface-cli下载 , 文件会进D:\Ollama目录 :
huggingface-cli download mradermacher/Qwen3-14B-abliterated-GGUFQwen3-14B-abliterated-Q4_K_M.gguf--local-dirD:\Ollama如果没装huggingface-cli, 也可以直接用浏览器或下载工具打开镜像直链 :https://hf-mirror.com/mradermacher/Qwen3-14B-abliterated-GGUF/resolve/main/Qwen3-14B-abliterated-Q4_K_M.gguf
关于 huggingface-cli :这是HuggingFace 官方提供的命令行下载器 , 没有安装时用下面这条命令即可 ;它对大文件支持断点续传 , 比浏览器直接下载更稳 ;
# 安装命令行下载工具，建议指定国内 PyPI 源加快速度pipinstall-Uhuggingface_hub-ihttps://pypi.tuna.tsinghua.edu.cn/simple# HF_ENDPOINT 变量会让所有请求自动走镜像站，不需要修改任何 Python 代码setHF_ENDPOINT=https://hf-mirror.com3、写 Modelfile 并本地建模型
在D:\Ollama下新建文件Modelfile, 注意没有任何后缀名 , 内容只有一行 :
FROM./Qwen3-14B-abliterated-Q4_K_M.gguf然后执行 :
cd/dD:\Ollamaollama createQwen3-14B-abliterated-fModelfileollama runQwen3-14B-abliterated这样模型完全走本地文件 , 不再依赖hf.co在线拉取, 网速也取决于你访问镜像站的快慢 , 镜像站通常明显比直连稳定 ;
需要注意 ,Modelfile里的相对路径 是相对于 执行命令 时 所在的目录 解析的, 所以先cd到 GGUF 文件所在目录是最省事的做法 ;
也可以直接写绝对路径FROM D:\Ollama\Qwen3-14B-abliterated-Q4_K_M.gguf, 这样在任何目录下执行都没问题 ;
4、处理历史缓存
顺带确认两件事 :
已缓存的 9 GB 在哪儿 :之前设置了OLLAMA_MODELS=D:\Ollama\models, 那它就落在D:\Ollama\models\blobs目录 ;如果重装过或者环境变量没生效 , 会默认跑到 C 盘的C:\Users\用户名\.ollama\models;重试能续传的前提 , 就是这个目录还在 ;
没必要重下 9 GB :走镜像方案下载时 , 如果D:\Ollama\models\blobs里已经有 9 GB 对应的b36d0edb573c分块 , 可以删掉它再下载镜像版同名文件 , 避免重复占空间 ;
为什么不能直接把 GGUF 拷进 blobs 目录 :blobs 目录是按 sha256 内容寻址的 , 文件名是文件内容的哈希值 , 不是原始文件名 ; 手动放进去的文件名对不上 , Ollama 依然找不到 ; 唯一正确的导入入口是ollama create;
五、新手必懂的背景知识
前面四章解决的是 " 怎么把模型跑起来 " , 这一章解决 " 为什么这么做 " ; 搞清楚下面几个概念 , 以后遇到任何本地部署问题都能自己推导 ;
1、Ollama 的本地仓库长什么样
Ollama 下载的所有模型 , 都存在模型目录里, 由OLLAMA_MODELS环境变量指定 , 默认在C:\Users\用户名\.ollama\models;
目录下面主要有两个子目录 , 职责完全分开 ;
仓库目录结构 :各目录的分工如下 ;
- blobs :存放真正的数据块 , 每个文件用
sha256-xxxx命名 , 没有扩展名 ,看不出原始文件类型 ,这是 " 内容寻址 " 的典型特征 ,好处是天然去重与秒级校验 ; - manifests :存放模型清单 ,记录了某个模型版本由哪些 blob 组成 ,各自的大小与校验值 , 相当于模型的 " 目录页 " ;
# 通过环境变量把模型仓库迁移到大分区，避免 C 盘被撑爆setOLLAMA_MODELS=D:\Ollama\models# 查看当前生效的模型仓库路径与 Ollama 版本ollama--version设置环境变量的正确姿势 :Windows 下在 CMD 里用set只在当前窗口有效 , 关掉就丢失 ;
想要永久生效 , 用setx或者在 " 系统属性 - 环境变量 " 里配置 ,并且要重启 Ollama 服务与命令行窗口才会生效 ;
# 永久写入用户级环境变量，新开的命令行窗口才会读取到setx OLLAMA_MODELS D:\Ollama\models2、GGUF 文件名里的量化后缀
同一个模型 , 在 HuggingFace 仓库里通常会有十几个 GGUF 文件, 例如Q2_K,Q4_K_M,Q5_K_M,Q8_0等等 ;
这些后缀代表不同的量化等级 , 直接决定了文件体积 , 显存占用与生成质量 ;
本次下载的 14B 模型Q4_K_M版本正好是 9.0 GB, 这不是巧合 , 而是量化位宽决定的 ;
一个简单的估算规律是 :显存 / 内存 占用 约等于文件体积再加一部分运行时开销 ,通常再留出 1 到 2 GB 给上下文即可 ;
常见量化等级对照 :参考下表选择适合自己的版本 ;
| 量化后缀 | 每个权重大致位数 | 资源占用 | 适用场景 |
|---|---|---|---|
| Q2_K | 约 2 bit | 最低 | 显存极度紧张 , 只想先跑起来尝鲜 |
| Q4_K_M | 约 4 bit | 中等 | 日常使用性价比最高 , 新手首选 |
| Q5_K_M | 约 5 bit | 略高 | 想要更好的生成质量 , 资源还有余量 |
| Q6_K | 约 6 bit | 较高 | 接近原版效果 , 对质量敏感的任务 |
| Q8_0 | 8 bit | 高 | 需要较高精度还原 , 如评测或对比实验 |
| FP16 | 16 bit | 最高 | 未量化的原始权重 , 仅供高性能设备 |
顺带解释一下模型名里的abliterated: 它表示社区在原版模型基础上做了对齐策略的移除处理 , 属于第三方修改版本 , 并非官方发布 ;
这类模型自由度更高 ,但使用时应自行评估输出的合规性与适用场景 ;
3、Modelfile 还能配置什么
第四章里用到的 Modelfile 只有一行FROM, 那是最简形态 ;
实际上 Modelfile 是 Ollama 的模型构建配置文件 , 语法接近 Dockerfile , 常用指令有下面这些 ;
常用指令一览 :按需组合即可 ;
- FROM :必填 , 指向本地 GGUF 文件或基础模型 ;
- PARAMETER :设置推理参数 , 例如
num_ctx上下文长度 ,temperature随机性 ,top_p采样阈值 ,num_gpu显卡层数 ; - SYSTEM :设置系统提示词 , 给模型一个固定的角色设定 ;
- TEMPLATE :自定义对话模板 , 一般不需要手写 , GGUF 里已内置 ;
# 指定本地 GGUF 文件，支持相对路径或绝对路径FROM ./Qwen3-14B-abliterated-Q4_K_M.gguf# 上下文长度，默认 2048，调大会显著增加显存占用PARAMETER num_ctx4096# 采样温度，值越小输出越稳定，越大越有创意PARAMETER temperature0.7# 系统提示词，用于给模型设定角色与行为边界SYSTEM" 你是一个严谨、乐于助人的中文技术助手 ; "写好之后用ollama create构建 , 之后每次ollama run 模型名都会自动带上这些配置 , 不需要在命令行里重复传参 ;
4、常用命令与环境变量速查
日常高频命令 :记住这几条就够应付 90% 的场景 ;
# 查看本机已经下载好的所有模型ollama list# 只下载不运行，适合先把模型拉下来ollama pull qwen3:14b# 运行模型，没有则自动先下载ollama run qwen3:14b# 查看当前正在运行、占用显存的模型ollamaps# 查看某个模型的详细信息，包括 Modelfile 与参数ollama show Qwen3-14B-abliterated# 删除不再使用的模型，释放磁盘空间ollamarmQwen3-14B-abliterated常用环境变量 :这几个变量决定了 Ollama 的行为 ;
| 环境变量 | 作用 | 典型取值 |
|---|---|---|
| OLLAMA_MODELS | 指定模型仓库路径 | D:\Ollama\models |
| HF_ENDPOINT | 让 huggingface 工具链走镜像站 | https://hf-mirror.com |
| OLLAMA_HOST | 修改对外服务监听地址与端口 | 0.0.0.0:11434 |
六、注意事项与避坑
把这次排错过程中容易反复踩的坑整理出来 , 遇到问题时先对照这张表 , 能省下大量时间 ;
常见报错对照 :看到这些信息时可以直奔对应的处理思路 ;
| 报错信息 | 可能原因 | 处理思路 |
|---|---|---|
| max retries exceeded + dial tcp 超时 | 跨境链路被掐断 | 重试 , 配置网络加速 , 或改用镜像站手动导入 |
| connection refused | 转发端口不对或 Ollama 服务未启动 | 核对转发端口 , 重启 Ollama 应用 |
| model requires more system memory | 内存或显存不足 | 换更小的量化等级 , 或缩短 num_ctx |
| pull model manifest: file does not exist | 标签写错 | 检查仓库名与量化标签是否完全匹配 |
| invalid model name / gguf parse error | GGUF 文件损坏或不完整 | 重新下载 , 校验文件大小与 sha256 |
| 命令执行后仍然直连不走加速通道 | 环境变量仅当前窗口生效 | 在同一窗口执行 , 或改用加速工具的全局接管模式 |
其它容易忽略的细节 :这些小问题往往最难排查 ;
- 窗口隔离 :CMD 里
set出来的环境变量只对当前窗口生效 , 换个窗口执行ollama就失效了 ; - 服务重启 :修改了永久环境变量之后 , 必须完全退出并重启 Ollama , 光关命令行窗口没用 ;
- 磁盘预留 :下载过程中需要额外的临时空间 , 目标分区至少预留模型体积的 1.2 倍 , 否则会在最后一步失败 ;
- 中文与空格路径 :Modelfile 的绝对路径尽量不要包含中文与空格 , 部分版本解析时会出问题 ;
- 盗名文件 :Modelfile 在 Windows 下务必确认不是
Modelfile.txt, 建议在资源管理器里打开 " 文件扩展名 " 显示后再创建 ; - C 盘占用 :长期不配置
OLLAMA_MODELS, 几个 14B 以上的模型就能吃掉几十 GB , 建议第一次使用就把仓库迁到 D 盘 ;
总结
本文完整记录了一次 Ollama 从 HuggingFace 拉取 GGUF 模型失败的排错过程 ;
表面上看是一条命令的事 , 实际上涉及 Ollama 的拉取机制 ,网络链路判断 ,以及本地模型的离线导入方法 ;
回顾一下整条主线 :pulling manifest成功说明模型名与鉴权没问题 ;
9 GB 主文件下载完成说明磁盘与并发没问题 ;
卡在几十 KB 的小 blob 上 , 且报错为dial tcp超时 , 基本可以锁定是跨境链路在握手阶段被掐断 ;
于是解决思路自然分成三条 :重试碰运气 ,配置网络加速让链路通畅 ,或者改用镜像站下载后用ollama create离线导入 ;
最后提醒一句 , 无论用哪种方式把模型成功跑起来 , 都建议第一时间配置OLLAMA_MODELS到非系统盘 , 顺手熟悉ollama list,ollama ps,ollama rm这几条命令 , 后续管理模型会轻松很多 ;
