模型文件识别与下载规范（跨平台版）

适用于 Hugging Face、Ollama、CivitAI、ModelScope、Replicate 等模型平台

目标：快速判断文件作用，避免无意义的全量下载

---

一、主流平台模型文件类型对照表

平台	核心权重文件	配置文件	分词文件	量化文件	其他说明
Hugging Face	.safetensors, .bin, .pt	config.json	tokenizer.json, vocab.txt, tokenizer.model	.gguf, .ggml, quantize_config.json	结构最完整
Ollama	.gguf	Modelfile	已内嵌	.gguf 内含量化	模型一次打包为 .gguf
CivitAI	.safetensors, .ckpt	模型卡说明	.pt / .bin（少见）	.safetensors 内部即量化	主要为 Stable Diffusion
ModelScope	.bin, .safetensors	configuration.json	tokenizer.json	.int8, .int4 等	国内模型平台
Replicate	.tar, .pkl	Dockerfile + metadata	含于镜像	依镜像结构	通常 API 调用

---

二、常见文件后缀与作用

后缀	含义	框架 / 平台	是否权重文件	可量化	下载建议
.safetensors	高效安全权重	HF / CivitAI	✅	✅	✅ 推荐
.bin	PyTorch 旧版权重	HF / ModelScope	✅	✅	✅
.pt	PyTorch 权重	通用	✅	✅	✅
.ckpt	TensorFlow / SD 快照	CivitAI	✅	✅	⚙️
.gguf	GGUF 量化文件	Ollama / llama.cpp	✅	✅	✅（单文件推理）
.ggml	GGML 旧量化格式	llama.cpp	✅	✅	⚙️（不推荐）
.onnx	ONNX 跨框架推理格式	HF / ONNX Runtime	✅	⚙️	✅
.tflite	TensorFlow Lite 移动端推理文件	Android / Edge	✅	✅	✅
.json	模型结构/配置	通用	❌	❌	✅
.model / .txt	分词器、词表	HF / SentencePiece	❌	❌	✅
.tar / .pkl	打包或 Pickle 格式	Replicate / Torch	✅	⚙️	⚙️
.onnx.zip / .tar.gz	模型压缩包	ModelScope / Replicate	✅	✅	⚙️

---

三、判断模型是否量化

判断方式	示例	说明
文件名包含 int4, int8, q4, q8, gguf, quantized	llama2-7b-q4.gguf	明确量化
存在 quantize_config.json / q_config.json	Hugging Face 常见	包含位宽设置
模型说明中提到 GGUF, GPTQ, AWQ, bitsandbytes	"支持 4bit/8bit"	说明量化
文件显著变小（如 13GB → 4GB）	-	高概率量化版

---

四、常见量化类型速查表

类型	位宽	精度影响	加速效果	常见格式	说明
FP16	16-bit	极低	中等	.safetensors, .bin	半精度浮点
INT8	8-bit	可忽略	明显	.gguf, .q8	常见服务器优化
INT4	4-bit	略降	显著	.gguf, .q4	轻端设备常用
NF4 / FP4	混合4bit	极低	高	.gguf	高保真量化
GGUF / GGML	多量化方案	自定义	高	.gguf	Ollama 使用

---

五、模型仓库识别示例

Hugging Face

meta-llama/Llama-2-7b-chat-hf/
├── config.json
├── tokenizer.json
├── tokenizer.model
├── model-00001-of-00002.safetensors
├── model-00002-of-00002.safetensors
├── generation_config.json
└── special_tokens_map.json

下载建议：

• config.json
• tokenizer.*
• 所有 model-*.safetensors

---

Ollama

llama2:7b.q4_0.gguf
Modelfile

说明：

• .gguf 含权重 + tokenizer + 量化信息
• 仅需下载 .gguf

---

CivitAI

majicmixRealistic_v7.safetensors
vae-ft-mse-840000-ema-pruned.safetensors

说明：

• 主模型 + 可选 VAE
• 推理时仅需主模型

---

六、内部命名规范（推荐统一格式）

<模型名>_<架构>_<参数量>_<用途>_<精度>_<平台>.<格式>

文件名	含义
llama2_7b_chat_fp16_hf.safetensors	Hugging Face 半精度
llama2_7b_instruct_q4_ollama.gguf	Ollama 4bit 量化
qwen1.5_14b_base_int8_modelscope.bin	ModelScope INT8
majicmix_v7_fp16_civitai.safetensors	SD 模型
phi3_3b_instruct_q8.gguf	Ollama 8bit 量化

---

七、下载策略（节省带宽）

需求	需下载文件	说明
推理	配置 + tokenizer + 核心权重	不下训练参数
LoRA 推理	base 模型 + adapter	合并时再加载
移动端	.tflite / .gguf	轻量版
调优	部分量化模型	不下全精度
Ollama	.gguf	单文件包含全部

---

八、推荐实践

1. 下载前先读 README / Modelfile
2. 下载后重命名为内部规范
3. 维护模型索引表
   • 来源平台
   • 模型大小
   • 是否量化
   • 任务类型（chat / vision / instruct）
4. 用 Git LFS 或模型管理脚本
5. 优先下载量化或裁剪版

---

九、推荐内部目录结构

/models
  /huggingface/
    llama2_7b_chat_fp16_hf.safetensors
  /ollama/
    phi3_3b_instruct_q8.gguf
  /civitai/
    majicmix_v7_fp16_civitai.safetensors
  /modelscope/
    qwen1.5_14b_base_int8_modelscope.bin
  index.json

---

建议配合版本控制与索引管理：

• index.json 记录每个模型的：
  • 平台
  • 量化信息
  • 用途
  • 文件大小
  • 下载链接

可快速查找并只下载所需模型。