ERNIE模型下载与安装详细教程

从选型准备到首次任务与结果核验

核对日期 2026年11月2日

ERNIE教程与配套资料 夸克网盘

本模型的教程与配套资料已整理到夸克目录。先打开目录核对文件名，再按正文完成准备与运行。

ERNIE由百度发布，本教程以baidu/ERNIE-4.5-0.3B-PT为主示例，按选型、环境准备、固定版本下载、文件校验和首次运行的顺序展开。系列内其他模型的参数量、输入类型和许可可能不同，不应只把示例命令中的仓库名换掉后直接运行。

本示例属于通用与推理方向。先读第1节确认任务，再完成下载与校验；只有设备、运行库和输入材料都准备好，才进入推理章节。文件下载成功只是取得了模型资料，不能据此认定该模型已在本机运行。

1 先选对模型与任务

容量来自固定提交下的官方文件元数据加总，包含仓库中的说明、配置、不同格式副本及其他附属文件。GB按十进制，GiB按二进制；它们都不是运行内存或显存的最低要求。若文件大小字段缺失，资料清单会保留未提供标记，不把未知大小当成零容量。

本模型需要先分清的事项

PT是预训练版本而非对话指令版。

小版本用于验证文本续写，不能假装具备所有旗舰能力。

所选仓库是基础预训练模型。本教程的首次运行验收是生成一段文本续写；它不是聊天应用，也不保证自动遵守系统角色、工具调用或复杂问答格式。需要对话服务时，应重新选择该系列的正式指令版本，并重新核对下载清单与提示模板。

2 检查设备与存储空间

下载目录建议预留至少6 GB可用空间，按当前已知整仓大小加约30%余量和5 GB基础空间估算。这只是下载规划，不包含Python环境、额外转换文件、项目依赖、临时缓存或生成结果。若只选择部分文件，需要重新按筛选后的清单计算，不能机械使用整仓估计。

1. Windows打开设置中的系统信息查看内存，在任务管理器的性能页查看GPU型号和专用显存；macOS在关于本机中查看芯片与统一内存；Linux可使用系统监视器或显卡厂商提供的工具。先记录设备信息，不根据型号名称猜测显存。

2. 确认目标磁盘支持大文件。Windows常见NTFS，Mac常见APFS；跨平台外置盘可按自身需求选择支持大文件的格式。FAT32不能保存大于4 GB的单个文件，不应为了下载而随意格式化已有资料的磁盘。

3. 运行资源取决于权重数据类型、序列长度、输入图像或音视频长度、并发数以及后端实现。普通FP16或BF16权重的基础占用可以用总参数量乘2字节作量级估计，但量化、MoE、解码器和缓存都需要另算。

4. 先选择一条最小任务完成安装验证。出现显存不足时，先减少输出长度、图像画幅或视频帧数；只有模型和后端明确支持时，再尝试量化、CPU卸载或多卡并行。不要把硬盘容量当作可用显存。

下载不要求具备模型推理所需的显卡，但后续运行有独立要求。Apple Silicon上的MPS、CPU和NVIDIA CUDA不是相同后端；项目写明只支持某类CUDA环境时，不能直接把设备字段改成mps就视为已支持Mac。

3 安装工具并创建独立环境

下载和清单脚本只依赖Python基础库，实际传输另需huggingface_hub。专用项目的Python版本以第6节和对应项目说明为准；本例建议单独准备Python 3.10环境，避免与其他模型的依赖混装。Python版本号相同也不代表PyTorch、CUDA和扩展包必然兼容。

Windows操作顺序

从Python官方发行渠道安装所需版本，重新打开PowerShell。将本模型的资料文件夹解压到路径较短的位置，然后在该文件夹打开终端。每次复制一行，等命令结束再执行下一行；不要一次粘贴多个模型的安装命令。

py --version
py -3.10 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip huggingface_hub
python environment_probe.py

如果系统没有py命令，先确认Python安装和路径设置，再使用已安装解释器创建环境。PowerShell若不允许激活脚本，可以直接运行.venv中的python.exe执行后续命令；无需为了一个模型长期降低系统级脚本策略。

macOS与Linux操作顺序

python3 --version
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip huggingface_hub
python environment_probe.py

若Linux缺少venv组件，按发行版官方包管理说明安装后重建环境。若项目明确只提供Linux和CUDA方案，Mac可用于下载与资料校验，运行环节应另选受支持设备。environment_probe.py只显示环境，不会加载大型权重或修改显卡驱动。

4 固定版本下载与访问权限

同目录model_manifest.json保存本次主示例的仓库ID、固定提交、目标目录和文件清单。download_model.py默认只预览，只有显式加--download才开始传输。脚本固定到清单中的revision，避免下载过程中main分支变化而混合不同版本。

python download_model.py --dry-run

预览应显示与第1节相同的仓库和提交、文件数、已知字节总量以及本地保存路径。先检查磁盘空间和目标目录，再开始下载。如果清单与文档不一致，先停止操作并确认是否混用了其他模型的资料包。

python download_model.py --download

公开仓库可在服务允许的范围内直接下载；标记为受限的仓库需要先用自己的账号在官方模型页完成访问申请或许可确认，再执行hf auth login。不要把读取令牌写入文章、文件清单或公开脚本。登录成功也不等于已经获得某个受限仓库的许可。

hf auth login
hf auth whoami

中断后保持原目录和同一份清单，再执行相同下载命令。huggingface_hub会按缓存和服务器信息处理已有文件；不要改动文件名、删除权重索引或把不同模型的分片放在同一目录。若确实需要重下某个文件，先在file_manifest.csv找到精确文件路径。

对同时包含多个格式、多个尺寸或多个检查点的仓库，可以用--only精确选择路径模式。筛选后执行校验时也要带相同的--only规则，否则未下载的其他文件会被报告为缺失。权重分片、索引、配置和分词器/处理器应作为一套完整组件选择，不要只下载最大的一个文件。

5 校验文件并保存版本记录

python verify_files.py
python verify_files.py --sha256

普通校验逐项检查文件是否存在以及字节大小是否匹配；--sha256只对官方元数据中提供LFS SHA256的文件计算摘要。没有SHA256的文件不会被虚构一个校验值。校验通过说明文件符合清单，仍不能证明推理环境和模型输出正确。大型权重计算摘要会花费时间，这是读取文件而不是重新下载。

缺失文件时回到下载步骤确认权限、筛选规则和保存目录；大小不符时优先对该文件重新传输。不要用空文件或改后缀代替缺失权重。浏览器下载到登录页面或错误页的同名文件，也应当作下载失败处理。

至少保留model_manifest.json、file_manifest.csv、安装后的环境版本和生成参数。后续更新模型时先新建目录，完成独立校验与短任务测试后再切换，避免覆盖当前可复现的版本。

6 安装运行组件并完成第一次输出

选择与示例相符的运行路线

安装适合本机驱动和设备的PyTorch，再安装模型卡要求的Transformers和辅助库。对原生新架构，旧版Transformers可能不认识模型类型；对旧式自定义架构，任意升级到新的主版本也可能破坏接口。先遵循所选固定版本模型卡的安装说明，再把完整依赖版本记录下来。

python -m pip install transformers accelerate safetensors sentencepiece
python -m pip check
python run_text.py --max-new-tokens 128

先输入一条短任务，等待模型加载后查看新增文本。首次运行可能包含权重读盘、内存分配和算子初始化，不能把这段时间直接当作稳定生成速度。若返回内容只重复输入，检查聊天模板、基础版/指令版选择和输出截取方式。

第一次任务的输入与验收

输入示例：用三句话说明如何给学习资料分类。先不上传长文档，也不调用外部工具。对基础预训练模型，改为给出一句开头并观察续写，不拿它测试聊天角色遵循。

验收时看三个方面：进程未因加载错误中止；输出是新生成的可读文本；内容与输入任务有关。模型可能产生错误内容，格式合格并不代表事实正确。推理模型若把预算用在思考阶段，可适当增加输出预算后复测，不应凭一次空答案断言模型无能力。

7 调整参数与保存结果

先固定提示词和max_new_tokens，再调整采样参数。短任务可用确定性生成排查模板问题；需要更丰富的写作再使用模型支持的temperature和top_p。不同模型的默认参数不可直接当作可比条件。

长上下文会增加缓存消耗。先用短输入记录首token时间和生成速度，再逐步加长；并发、批量大小和最大上下文不要同时提高。多卡加载成功也不等于所有卡都能有效并行。

成功生成后立即记录本次模型目录、固定提交、Python和主要库版本、设备、参数与结果文件名。生成结果先保存到outputs子目录，再从本地打开检查，避免只看终端最后一行就判断成功。若后续换模型或换精度，重新做一次最小任务验证。

python -m pip freeze > environment_versions.txt

8 常见问题逐项排查

找不到命令或导入了错误的环境

先运行python --version和python -m pip --version，确认二者属于本模型的独立环境。安装包时使用python -m pip，避免把依赖装到另一个解释器。切换终端或重启后需要重新进入对应环境。

访问失败或下载结果不完整

先区分网络超时、限流、登录和仓库权限问题。401或403不应通过反复换文件名解决；确认自己的账号确有访问权限。下载后执行文件校验，不把保存成功的网页错误提示当作权重。

模型类型或处理器不被识别

检查仓库ID、配置文件、固定提交和安装的框架版本。原生新架构需要后端明确支持，专用架构可能依赖项目代码；不要盲目把model_type改成别的模型，也不要删除配置项来绕过错误。

显存或系统内存不足

先关闭其他占用较大的进程并降低本次任务规模，再核对精度、缓存和卸载配置。若完整权重本就超过设备能力，应改用更小的正式版本或受支持服务器方案；磁盘还有空位不能解决显存不足。

结果为空或与任务不一致

先检查输入文件是否能正常打开、参数是否属于当前模型版本、生成预算是否足够，以及基础版与指令版是否选错。对照最小样例一次只改变一项。运行无报错但没有满足验收条件，仍应继续排查。

更新依赖后原来能用的流程失效

回到已记录的环境版本和固定提交，新建环境复现原任务。不要直接在唯一可用环境上连续升级全部库。若项目接口发生变化，按对应发行版说明迁移，并重新核对本模型的专用步骤。

9 配套资料文件怎么使用

本资料包不包含模型权重。CSV中的固定文件地址用于定位与核对，下载仍受原服务的访问权限、限流和许可约束。本模型的夸克资料入口见文档开头。网盘目录提供教程与配套文件，按实际目录内容选择所需资料。

10 主示例文件清单与来源

来源依据：百度公开发布信息，baidu/ERNIE-4.5-0.3B-PT固定提交b565cf6caebdb7a1eadf00100857b1ed5e044f12的官方文件元数据与模型卡，以及对应项目的公开运行说明。模型和项目代码的后续版本可能改变接口，本教程的容量与文件清单对应本次固定提交。