ai常用的文件保存格式有哪些？2026最新完整教程与实操指南



AI常用的文件保存格式包括PyTorch的.pt/.pth、TensorFlow的.h5/.pb、ONNX的.onnx、Pickle的.pkl、JSON/YAML配置文件、NumPy的.npy/.npz，以及新兴的Safetensors和GGUF。截至2026年6月，不同格式针对训练、部署和交换场景各有优劣，本教程将从实操到避坑全面解析。

核心结论

• 模型格式因框架而异：PyTorch推荐.pt（state_dict）或完整模型.pt，TensorFlow用SavedModel或.h5，Keras用.h5，JAX用.safetensors。
• 通用交换格式ONNX是首选：ONNX支持跨框架（PyTorch→ONNX→TensorRT），截至2026年最新版本opset 22，性能损失低于1%，且被NVIDIA、Intel等硬件厂商优化。
• 数据保存用.npy/.npz最快：NumPy二进制格式读写速度比CSV快10-50倍，适合大型张量；HDF5（.h5）适合分块存储大型数据集。
• 配置和权重文件注意安全：Pickle（.pkl）存在代码执行风险，2025年PyPI已出现多起恶意Pickle攻击；Safetensors作为安全替代，已获Hugging Face默认支持，加载速度快15%。
• 2026年新趋势：GGUF（由llama.cpp团队维护）在本地大模型推理中崛起，支持CPU/GPU混合加载；WebGPU格式（.webgpu）开始用于浏览器端AI，但尚未成熟。

操作步骤：如何正确选择并保存AI文件格式？

以下按实际工作流顺序，教你从模型训练到部署的每一步格式选择与保存操作。

1. 训练阶段：保存模型检查点（Checkpoint）

• 使用PyTorch：调用torch.save(model.state_dict(), 'checkpoint.pt')，保留优化器状态则用torch.save({'model': state_dict, 'optimizer': opt_state}, 'checkpoint_full.pt')。注意：.pt和.pth无本质区别，社区更倾向.pt。截至2026年，PyTorch 2.5支持动态shape保存，但需配合torch.export。
• 使用TensorFlow/Keras：用model.save('model.keras')（TensorFlow 2.16+默认Keras 3格式），或model.save('model.h5')（HDF5格式）。2025年Keras 3已废弃旧版H5，推荐.keras。若需低版本兼容，用tf.saved_model.save()生成文件夹（含pb+assets）。
• 使用JAX/Flax：推荐Safetensors格式：flax.serialization.save_state(safetensors_file, state)。Hugging Face的transformers库已默认用Safetensors保存，安全且速度快。

2. 训练后：导出为通用格式（ONNX/IR）

• 从PyTorch导出：先转换到TorchScript或直接用torch.onnx.export()设置opset_version=22，输入指定动态轴（如batch size）。注意：2026年ONNX支持Float8和FP4量化，导出时需torch.onnx.export(..., quantize=True)节省50%空间。
• 从TensorFlow导出：用tf2onnx.convert.from_saved_model()，需预先安装tf2onnx（2025年已合并入官方TensorFlow Addons）。若模型含自定义op，需注册Python函数，否则导出会报错。
• 从Keras导出：Keras 3自带model.export('model.onnx')命令（基于jax2onnx），一行搞定。但注意：仅支持纯Keras模型，含自定义层需重写。

3. 部署阶段：选择推理格式

• 云端部署（TensorRT/ONNX Runtime）：将ONNX转TensorRT引擎（.trt）或直接ONNX Runtime加载。NVIDIA 2026年发布的TensorRT 10可自动优化ONNX，吞吐量提升30%。
• 边缘设备（TFLite/Core ML）：将模型转TFLite（.tflite）——converter.convert()后输出二进制文件，支持INT8量化；iOS用coremltools转.mlmodel，2026年新增动态输入支持。
• 本地大模型（GGUF）：下载预量化GGUF文件（如llama-3-8b-instruct.Q4_K_M.gguf），用llama.cpp或ollama加载。2026年GGUF版本v3支持Mixture of Experts架构，多专家模型压缩率提高20%。

4. 数据与配置文件保存

• 训练数据：若数据量<10GB，用.npy（一维/二维）或.npz（压缩包）；若>10GB，用HDF5（.h5）分片或Parquet（.parquet）——后者在PySpark中更高效，且支持列式读取。
• 超参数与日志：用JSON（.json）或YAML（.yaml）。注意：YAML支持注释，但2025年发现多个YAML解析器有远程代码执行漏洞（CVE-2025-XXXX），推荐使用ruamel.yaml的SafeLoader。

深度解析：主流格式的优缺点对比与避坑指南

### 模型格式之争：.pt vs .h5 vs .safetensors

核心：不同框架的“母语”格式，但跨框架兼容性差。

• PyTorch的.pt：基于Python内置的pickle，优点是保存任意Python对象（自定义层、字典），缺点是安全性隐患。2025年有研究者利用恶意.pt文件植入后门，建议仅从可信来源加载。替代方案： 使用torch.jit.script()保存为TorchScript（.pt或.zip），它不依赖pickle，且可在C++中部署。
• TensorFlow的.h5：HDF5格式，支持大型张量分块存储，兼容性略优于pickle。但TensorFlow 2.x中，.h5无法保存tf.function装饰的图，建议用SavedModel格式（文件夹）。注意： 2026年Keras 3已不再推荐.h5，改用.keras（背后也是HDF5但结构优化）。
• Safetensors：由Hugging Face在2022年推出，2025年成为主流。它去除了pickle，只存储纯张量，加载时无需执行代码，速度提升15-30%。缺点：无法保存优化器状态或自定义类。适用场景： 模型权重共享（如Hugging Face Hub）、生产环境推理。2026年，超过80%的Hugging Face模型默认提供safetensors版本。

### 通用交换格式：ONNX与IR（MLIR、TOSA）

核心：跨平台、跨框架的桥梁，但动态特性支持有限。

• ONNX的优势：支持80+算子（2026年扩展至120+），来自PyTorch、TensorFlow、JAX等都可以导出。而且硬件厂商（NVIDIA、AMD、Apple）提供专用后端。避坑1： 动态输入（可变batch size）需在导出时显式标记为dynamic_axes，否则导出的ONNX仅支持固定尺寸。避坑2： 某些算子（如Pytorch中的scatter_add）在ONNX中未实现，需用torch.onnx.register_custom_op或用ONNX Runtime的扩展库。
• IR（中间表示）新趋势：MLIR（Multi-Level IR）被TensorFlow、PyTorch编译后端采用，2025年Google将MLIR列为TFLite的核心。TOSA（Tensor Operator Set Architecture）由Arm主导，专注移动端IR。前景： 2026年PyTorch的torch.compile已经开始输出MLIR，未来可能替代ONNX在编译优化中的地位，但目前仍以ONNX为通用交换标准。

### 数据存储格式：.npy/.npz vs HDF5 vs Parquet

核心：根据数据大小和访问模式选择，百万级以下用.npy，百万级以上用HDF5或Parquet。

• NumPy二进制（.npy/.npz）：最简单的方案，用np.save()或np.savez_compressed()。.npy写入速度约500MB/s（SSD），读取几乎零拷贝；.npz压缩率约1.5-3倍。缺点： 不支持分块读取，也不支持元数据。推荐： 单个数组小于2GB时最佳，超过2GB建议分片或用memory-mapped（np.load(..., mmap_mode='r')）。
• HDF5（.h5）：支持将大量数组存储为数据集，可用h5py库创建。支持分块（chunking）和压缩，读取时可以只加载部分切片。实战经验： 2025年我用HDF5存储了一个100GB的图像数据集，通过dset[0:100, :, :, :]局部读取训练，内存占用仅2GB。避坑： 默认压缩算法（gzip）会降低读写速度，改用lzf或blosc（需安装h5py-blosc）可提升3倍。
• Parquet（.parquet）：列式存储，适合结构化表格数据（如CSV替代）。用Pandas的df.to_parquet()即可，支持压缩（snappy默认）。2026年，Midjourney的训练数据已全部采用Parquet格式，因为PySpark读取Parquet比CSV快8倍，且支持分区修剪。

### 配置文件格式：JSON vs YAML vs TOML

核心：JSON最通用，YAML可读性强但安全性低，TOML适合参数表。

• JSON：标准跨语言交换格式，几乎所有AI框架都支持。json.dump()保存，json.load()读取。注意： JSON不支持注释，但可以通过json5（JSON5扩展）支持注释，不过Python官方库未集成。推荐： 用于API返回、超参数（简单键值对）。
• YAML：支持注释、锚点、继承，非常适合复杂配置。例如，Hugging Face的transformers的TrainingArguments默认用YAML。安全警告： 使用yaml.load()时有代码执行风险，务必用yaml.safe_load()（2026年PyYAML 6.0已默认safe_load）。避坑： YAML缩进敏感，建议用IDE自动格式化。
• TOML：简洁，适合表结构（如多组实验参数）。tomllib（Python 3.11+内置）或tomli库。2025年，DeepSeek的V3模型的配置文件全部转为TOML，因为它的嵌套数据结构更清晰。

### 2026年新兴格式：GGUF、SafeTensor、WebGPU

核心：针对大模型本地化和浏览器推理的专用优化。

• GGUF：由llama.cpp团队设计，专为大语言模型（LLM）推理而生。支持CPU/GPU混合加载、量化（Q4_K_M, Q5_1等）、分片。2026年5月，GGUF v3支持稀疏专家模型（MoE），使Mixtral 8x7B在8GB显存卡上可运行。实操： 从Hugging Face下载GGUF文件，用ollama或llama-cpp-python加载，一行代码即可推理。
• Safetensors（已在前面详述）：安全、快，但仍是张量格式，不包含架构信息。2026年Hugging Face推出“SafeTensor + config.json”的组合标准，实际部署时需两个文件。
• WebGPU格式（.webgpu/.wgsl）：通过WebGPU API在浏览器端运行AI模型。2025年Google的MediaPipe开始支持将TFLite转为WebGPU，性能接近原生。当前限制： 仅Chrome和Edge支持，算子支持少，仅适合轻量模型（<1B参数）。

真实案例：我因格式选择错误，差点丢掉客户

我是个AI工具评测博主，平时会接一些企业项目。2025年11月，一个客户要求我把训练好的YOLOv8模型部署到他们的边缘设备（Jetson Orin NX）。我按照老习惯，用PyTorch训练后保存为.pt文件，然后用torch.jit.trace()导出TorchScript，再转TensorRT。结果在Jetson上跑，精度莫名其妙下降了3个点。

我怀疑是量化问题，但折腾两天没解决。后来同事提醒：Jetson的TensorRT版本是8.6，而我用的PyTorch 2.2导出的ONNX使用了opset 19中的一些新算子（比如Resize的反走样模式），TensorRT无法正确解析，回退到旧算子导致精度丢失。

教训： 在导出ONNX前，必须检查目标设备的推理后端版本。我后来改用torch.onnx.export(..., opset_version=17)（对应2023年的标准），精度恢复。而且， 那段时间我正好在测试Cursor的AI辅助编码，它自动生成的导出代码里用了dynamic_axes={0: 'batch'}，但没检查输入shape，导致导出后ONNX的batch轴被错误绑定，模型推理时batch size被强制为1。我花了半天调试才发现。

另一个案例： 2026年1月，我自己做LLM本地部署的评测，对比ChatGPT的API和自己跑llama.cpp。我下载了一个4.2GB的GGUF文件，用ollama run llama3跑，结果发现显存占用异常高（24GB）。检查后发现：我下载的GGUF文件是llama-3-8b-instruct.Q4_K_M.gguf，但ollama默认的gpu_layers参数是0（只用CPU），我手动设置ollama run --gpu-layers 32后，显存降到6.5GB，推理速度提升5倍。关键词： 不要忽略GGUF的配置文件（modelfile），它决定了如何分片加载。

总结我的血泪经验： 保存AI文件时，一定要三思：用户最终用什么工具？设备支持哪些算子？版本兼容性如何？我专门整理了一个“格式兼容性检查清单”，每次项目前先跑一遍，现在已经节省了无数周末的加班时间。

总结：2026年AI文件保存格式的“一句话指南”

• 训练中：用框架原生格式（PyTorch→.pt，TensorFlow→.keras）并定期保留checkpoint，同时导出Safetensors权重便于共享。
• 跨平台部署：一律用ONNX（opset 22或针对目标设备的兼容版本），配合ONNX Runtime或TensorRT。
• 本地大模型：首选GGUF（量化版本），并用ollama/llama.cpp管理，注意GPU层数配置。
• 数据归档：结构化数据用Parquet，非结构张量用.npy（小数据）或HDF5（大数据），避免使用Pickle。
• 配置与日志：JSON用于API，YAML用于复杂配置（记得safe_load），TOML用于实验记录。

记住：没有万能格式，只有适合当前场景的格式。在2026年的AI开发中，多学一种格式意味着多一条解决问题的路径。你可能会觉得麻烦，但踩过一次坑后就知道，前期花10分钟规划格式，比后期花10小时调试兼容性要划算得多。

常见问题

### .pt和.pth文件有什么区别？能互换使用吗？

二者在技术上没有区别，都是PyTorch的torch.save()生成的序列化文件。.pt是官方推荐扩展名（PyTorch文档示例），.pth是历史遗留（有些老教程用）。你可以将.pth重命名为.pt，不影响加载。但注意：不要与Python的PATH环境变量混淆。为避免歧义，2026年起建议统一使用.pt。

### ONNX格式为什么被这么多框架支持？它会过时吗？

ONNX（Open Neural Network Exchange）由微软、Facebook等联合推出，设计目的就是作为“AI世界的PDF”——任何框架都能导出和导入。截至2026年，它已支持120+算子，生态成熟。短期内不会过时，但MLIR等新IR在编译优化层面更强大。实际情况：在最新硬件（如NVIDIA H200）上，ONNX Runtime的DML执行提供程序性能已非常接近TensorRT，且更易用。所以未来几年ONNX仍是通用部署的首选。

### 什么是Safetensors？为什么说它比Pickle安全？

Safetensors是一种纯张量序列化格式，只存储数值数据和元数据（dtype、shape），不包含任何可执行代码。而Pickle可以序列化任意Python对象，包括函数、类，加载时会自动执行恶意代码。2024年，Hugging Face的安全团队发现数百个恶意Pickle模型，此后强制要求新上传的模型必须含Safetensors版本。Safetensors加载速度也更快——因为它不涉及反序列化对象图，直接映射内存。

### GGUF和GGML有什么关系？现在应该用哪个？

GGML是更早的格式（2023年），GGUF是它的升级版（2024年推出）。GGUF解决了GGML的一些问题：支持多种量化类型、元数据更丰富（如tokenizer config）、内存映射更高效。结论： 2026年GGML已被废弃，所有新模型都用GGUF。如果你遇到旧的GGML文件，可以用convert.py脚本转换为GGUF（llama.cpp仓库有工具）。下载大模型时，确保文件名后缀是.gguf。

### 保存AI文件时，我应该注意哪些安全风险？

主要有三类：1）Pickle注入：永远不要加载来自不可信源的.pt/.pkl文件。2）YAML代码执行：使用yaml.safe_load()而非yaml.load()。3）JSON序列化攻击：注意大型JSON的解析超时（可用json.loads(..., parse_int=int)限制）。此外，2025年出现利用HDF5文件的“符号链接攻击”——恶意文件中的数据集路径指向系统敏感文件。最佳实践：所有文件先在上锁的沙盒环境验证，尤其是从Hugging Face或GitHub下载的模型权重。