DeepSeek-V3 检查点解析实战.safetensors 与权重索引671B 权重怎么落地【免费下载链接】DeepSeek-V3项目地址: https://gitcode.com/GitHub_Trending/de/DeepSeek-V3AssertionError: Number of experts must be divisible by model parallelism——把--model-parallel 16配错到 24convert.py会在分片第一步就崩给你看而更早一点load_file()报CUDA out of memory的那一刻你手里其实只是一堆 4GB 出头的.safetensors分片根本摸不到671B这三个字的分量。这篇指南把 DeepSeek-V3 检查点从落盘字节到可推理权重整条链路拆开讲config.json里的量化描述、model.safetensors.index.json的张量寻址、*_scale_inv反量化因子以及官方inference/目录下两个转换脚本的真实行为帮你把 685B 规模的权重文件变成一条可验证的部署链路。先给结论这篇文章能帮你跑通什么看懂检查点全貌685B 总规模 主模型 671B61 层 Transformer 嵌入 输出头每 token 激活 37B MTP 多 token 预测模块 14B官方只提供 FP8 权重BF16 需用脚本反量化生成。会读两份地图文件config.json决定模型形状层数、专家数、quantization_configmodel.safetensors.index.json的weight_map决定每个张量在哪个分片——所有加载和转换都从这两处出发。跑通两条转换链路FP8 → BF16 用fp8_cast_bf16.py公式就是128×128 块 ×weight_scale_invHugging Face 格式 → 张量并行分片格式用convert.py配configs/config_671B.json起双机 16 卡推理。手里有排错手册scale_inv找不到、n_experts整除断言、GPU 显存爆掉、transformers加载失败这几类高频问题每个都给出现象、原因和解决办法。有选型依据生产服务选框架、量化格式取舍、磁盘与显存预估收尾附一份可逐条执行的自检清单。数据流拆解一个张量从分片字节到矩阵乘法下面按数据旅程走五站下载落盘 → 校验 → 解析 → 量化/反量化 → 推理。每一站都说明在做什么、为什么这么设计。文件角色关键内容config.json模型形状 量化描述model_type: deepseek_v3、num_hidden_layers: 61、num_nextn_predict_layers: 1、quantization_configmodel.safetensors.index.json张量寻址表weight_map张量名 → 所在.safetensors分片*.safetensors二进制权重分片JSON 头张量名/形状/ dtype/偏移 连续数据区每个分片数 GB第 1 站下载落盘。.safetensors相比传统.bin是安全内存映射格式头部 JSON 记录每个张量的名字、形状、数据类型与数据区偏移加载器按偏移mmap读取不必把整个 300GB 的文件读进内存。算一笔体积账671B 参数 × 1 字节 FP8 ≈ 671GB再加上float32的 scale 张量约 1/8 个权重张量体积整个检查点约760GB规划存储时先按这个数留。第 2 站校验。拿到目录后先看config.json的三个新增字段。model_type应为deepseek_v3num_nextn_predict_layers为 1即带 1 个 MTP 模块quantization_config长这样quantization_config: { activation_scheme: dynamic, fmt: e4m3, quant_method: fp8, weight_block_size: [128, 128] }含义权重以e4m3对应torch.float8_e4m3fn存储按 128×128 块各存一个缩放因子激活值不做离线量化推理时动态计算。校验脚本可以直接跑import json from safetensors import safe_open idx json.load(open(model.safetensors.index.json))[weight_map] shards sorted(set(idx.values())) print(f分片数: {len(shards)}, 张量数: {len(idx)}) missing 0 for f in shards: with safe_open(f, frameworkpt) as st: names set(st.keys()) missing sum(1 for n, sf in idx.items() if sf f and n.endswith(_scale_inv) and n[:-len(_scale_inv)] not in names) print(缺失 scale 对:, missing)输出应为分片数 100 左右、缺失 scale 对: 0再比对config.json的num_hidden_layers与索引里model.layers.0~model.layers.61前缀是否齐全主模型 61 层 MTP 层 ID 61。第 3 站解析与加载。加载器不预读全量权重而是查weight_map按需定位分片——这正是官方脚本的写法fp8_cast_bf16.py里get_tensor()先查weight_map[tensor_name]再加载对应文件且缓存里最多同时驻留 2 个分片超出即torch.cuda.empty_cache()这是它能在单卡上处理数百 GB 权重的关键。MTP 模块的层 ID 紧跟主模型之后num_hidden_layers 61时它落在model.layers.61含enorm/hnorm/eh_proj三个投机解码专用参数嵌入层与输出头则与主模型共享、不重复存储。官方 demo 加载时会主动跳过这一层自建框架则要把它当普通层读入。第 4 站量化与反量化。每个 FP8 权重张量都有配套的*_scale_invfloat32形状为权重形状 ÷ 128。反量化是逐块乘回缩放因子Triton 内核inference/kernel.py中weight_dequant的核心就是y x * s。细节块不整除 128 时先零填充到 128 再算 scale量化后裁掉填充。推理方向相反——激活值按 per-token-per-128-channel 动态量化内核里s amax / 448448 是e4m3的最大可表示值然后 FP8 GEMM 累加时按块乘回两侧 scale。权重体积对比FP8 约340GB反量化成 BF16 后约680GB671B × 2 字节。第 5 站推理。generate.py读--config configs/config_671B.json关键参数n_layers: 61、n_dense_layers: 3、n_routed_experts: 256、n_activated_experts: 8、dim: 7168配torchrun张量并行把权重按 rank 切到各卡vocab_size为 129280上下文 128K。convert.py的分片逻辑也值得一读专家权重按idx // (n_experts // mp)归到各 rank其余权重沿mapping表中声明的维度narrow均分。场景化实战三条路径各给最小可用步骤部署方快速上线直接上 SGLang 或 vLLM生产部署不需要手写加载逻辑。README 中 SGLang 是首选推荐NVIDIA/AMD 通吃、FP8 W8A8、FP8 KV Cache、多机张量并行vLLM 提供管道并行与 OpenAI 兼容接口LMDeploy 适合离线批处理。最小步骤git clone https://gitcode.com/GitHub_Trending/de/DeepSeek-V3 cd DeepSeek-V3/inference pip install -r requirements.txt权重从 Hugging Face 拉取后放入本地目录SGLang/vLLM 直接指向该目录启动即可各框架启动参数见其官方文档。注意 demo 脚本的环境限制仅 Linux Python 3.10依赖锁在torch2.4.1、triton3.0.0、transformers4.46.3、safetensors0.4.5。研究者改权重FP8 转 BF16 三步走有些实验必须吃 BF16例如对比量化误差、接入只认高精度的工具链。用官方fp8_cast_bf16.py它逐分片读 FP8 张量、按块乘回scale_inv、输出同名 BF16 分片并同步改写索引文件删掉所有*_scale_inv条目。python fp8_cast_bf16.py --input-fp8-hf-path /path/to/fp8_weights --output-bf16-hf-path /path/to/bf16_weights三个前置条件至少 1 张显存足够的 GPU脚本把分片加载到 CUDA 上做反量化输出目录预留约700GB执行期间磁盘占用接近输入 输出双份。转换产物是标准 HF 格式可直接喂给支持 BF16 的推理框架。二次开发接入自有框架只依赖索引 weight_map自建推理栈时建议把model.safetensors.index.json当作唯一事实来源safe_open()按分片流式取张量不整包读入。两个必须处理的点命名映射inference/convert.py顶部的mapping字典就是 HF 张量名到自定义名的对照表q_a_proj→wq_a、gate_proj→w1、weight_scale_inv→scale等可以直接借来对齐命名空间。MTP 层convert.py里if model.layers.61 in name: continue说明官方 demo 丢弃 MTP 层若你要支持投机解码这层必须保留且它的embed_tokens/lm_head要与主模型共享同一份权重对象。高频踩坑与排错1.Warning: Missing scale_inv tensor for ..., skipping conversion现象跑fp8_cast_bf16.py时个别权重被跳过输出目录里出现未反量化的 FP8 张量。原因权重和它的*_scale_inv被切进了不同分片脚本的get_tensor()依赖weight_map跨文件查找若你拿到的索引不完整、或手工拆分过分片对应关系就断了。解决确认输入目录里model.safetensors.index.json完整未被裁剪且weight_map中每个 FP8 张量都有*_scale_inv条目用第 2 站的校验脚本扫一遍被拆散的分片先合并再转。2.AssertionError: Number of experts must be divisible by model parallelism现象convert.py启动即挂。原因n_experts必须能被model_parallel整除——专家是整体切分单元不能把一个专家劈到两个 rank。解决让mp成为专家数的约数。671B 有 256 个路由专家--model-parallel 16时每 rank 拿 16 个专家想改 8 卡/32 卡就传 8 或 32。3.KeyError: Key xxx not found in mappingconvert.py 中现象自定义 checkpoint 跑convert.py断言失败。原因张量名的倒数第二段如 MTP 层的enorm、hnorm不在脚本的mapping字典里。解决在mapping中补上对应条目或直接过滤掉不需要加载的前缀。4.load_file()阶段 CUDA out of memory现象官方 demo 或转换脚本在加载单个分片时显存爆掉。原因单卡同时驻留了过多分片。解决转换脚本自带最多缓存 2 个分片策略自定义代码请照抄推理侧先用小配置冒烟--max-new-tokens 200确认链路后再扩。5. transformers 里AutoModel无法识别deepseek_v3现象from_pretrained()报不支持的 model type。原因官方明确说明 Transformers 暂不支持直接加载该权重。解决走 SGLang、vLLM、LMDeploy、TensorRT-LLM 或仓库内 demo不要用transformers硬加载。6. 转换后磁盘写满现象save_file中途报No space left on device。原因FP8→BF16 输出约 680GB很多人只按输入体积预留了空间。解决执行前df -h确认输出目录可用空间 ≥ 700GB最好与输入分盘。决策建议与上手自检清单框架怎么选。按生产服务还是科研改权重分框架量化支持适用场景SGLangBF16 FP8W8A8、FP8 KV Cache生产首选NVIDIA/AMD 通吃多机张量并行vLLMBF16 FP8管道并行跨机、OpenAI 兼容接口接入LMDeployBF16 FP8离线批处理与在线服务TensorRT-LLMBF16 INT4/INT8FP8 开发中极致单卡延迟官方 demoBF16 FP8学习张量并行与 MLA 加载逻辑的参考实现量化格式怎么选。生产环境保留原生 FP8权重体积减半FP8 GEMM 更快且quantization_config已完整描述块缩放主流框架都能消费BF16 只在科研对比、误差分析或框架只认高精度时使用显存极度紧张再考虑 INT4/INT8 权重量化。存储与显存预估。磁盘FP8 检查点约 760GB含 scaleBF16 输出约 680GB转换期间需要两者并存。显存671B FP8 权重按 2×8 的 H 卡规模起步16 卡张量并行每卡约 21GB 权重 KV Cache 与激活开销128K 上下文的 KV Cache 另算建议按官方多机配置对齐。上手自检清单按序执行每步 5 分钟内环境Linux Python 3.10 CUDA GPUdf -h确认 ≥ 2× 模型体积的磁盘。检查点完整性config.json含quantization_config且weight_block_size为[128, 128]跑第 2 站的校验脚本确认分片可读、scale对缺失数为 0、model.layers.0~model.layers.61前缀齐全。最小冒烟按场景一启动 SGLang或 demo 双机 16 卡 configs/config_671B.json请求 200 token 验证输出再逐级放开上下文与并发。三步全绿你的 DeepSeek-V3 权重链路就算真正落地了。【免费下载链接】DeepSeek-V3项目地址: https://gitcode.com/GitHub_Trending/de/DeepSeek-V3创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 DeepSeek-V3 检查点解析实战：.safetensors 与权重索引，671B 权重怎么落地
DeepSeek-V3 检查点解析实战.safetensors 与权重索引671B 权重怎么落地【免费下载链接】DeepSeek-V3项目地址: https://gitcode.com/GitHub_Trending/de/DeepSeek-V3AssertionError: Number of experts must be divisible by model parallelism——把--model-parallel 16配错到 24convert.py会在分片第一步就崩给你看而更早一点load_file()报CUDA out of memory的那一刻你手里其实只是一堆 4GB 出头的.safetensors分片根本摸不到671B这三个字的分量。这篇指南把 DeepSeek-V3 检查点从落盘字节到可推理权重整条链路拆开讲config.json里的量化描述、model.safetensors.index.json的张量寻址、*_scale_inv反量化因子以及官方inference/目录下两个转换脚本的真实行为帮你把 685B 规模的权重文件变成一条可验证的部署链路。先给结论这篇文章能帮你跑通什么看懂检查点全貌685B 总规模 主模型 671B61 层 Transformer 嵌入 输出头每 token 激活 37B MTP 多 token 预测模块 14B官方只提供 FP8 权重BF16 需用脚本反量化生成。会读两份地图文件config.json决定模型形状层数、专家数、quantization_configmodel.safetensors.index.json的weight_map决定每个张量在哪个分片——所有加载和转换都从这两处出发。跑通两条转换链路FP8 → BF16 用fp8_cast_bf16.py公式就是128×128 块 ×weight_scale_invHugging Face 格式 → 张量并行分片格式用convert.py配configs/config_671B.json起双机 16 卡推理。手里有排错手册scale_inv找不到、n_experts整除断言、GPU 显存爆掉、transformers加载失败这几类高频问题每个都给出现象、原因和解决办法。有选型依据生产服务选框架、量化格式取舍、磁盘与显存预估收尾附一份可逐条执行的自检清单。数据流拆解一个张量从分片字节到矩阵乘法下面按数据旅程走五站下载落盘 → 校验 → 解析 → 量化/反量化 → 推理。每一站都说明在做什么、为什么这么设计。文件角色关键内容config.json模型形状 量化描述model_type: deepseek_v3、num_hidden_layers: 61、num_nextn_predict_layers: 1、quantization_configmodel.safetensors.index.json张量寻址表weight_map张量名 → 所在.safetensors分片*.safetensors二进制权重分片JSON 头张量名/形状/ dtype/偏移 连续数据区每个分片数 GB第 1 站下载落盘。.safetensors相比传统.bin是安全内存映射格式头部 JSON 记录每个张量的名字、形状、数据类型与数据区偏移加载器按偏移mmap读取不必把整个 300GB 的文件读进内存。算一笔体积账671B 参数 × 1 字节 FP8 ≈ 671GB再加上float32的 scale 张量约 1/8 个权重张量体积整个检查点约760GB规划存储时先按这个数留。第 2 站校验。拿到目录后先看config.json的三个新增字段。model_type应为deepseek_v3num_nextn_predict_layers为 1即带 1 个 MTP 模块quantization_config长这样quantization_config: { activation_scheme: dynamic, fmt: e4m3, quant_method: fp8, weight_block_size: [128, 128] }含义权重以e4m3对应torch.float8_e4m3fn存储按 128×128 块各存一个缩放因子激活值不做离线量化推理时动态计算。校验脚本可以直接跑import json from safetensors import safe_open idx json.load(open(model.safetensors.index.json))[weight_map] shards sorted(set(idx.values())) print(f分片数: {len(shards)}, 张量数: {len(idx)}) missing 0 for f in shards: with safe_open(f, frameworkpt) as st: names set(st.keys()) missing sum(1 for n, sf in idx.items() if sf f and n.endswith(_scale_inv) and n[:-len(_scale_inv)] not in names) print(缺失 scale 对:, missing)输出应为分片数 100 左右、缺失 scale 对: 0再比对config.json的num_hidden_layers与索引里model.layers.0~model.layers.61前缀是否齐全主模型 61 层 MTP 层 ID 61。第 3 站解析与加载。加载器不预读全量权重而是查weight_map按需定位分片——这正是官方脚本的写法fp8_cast_bf16.py里get_tensor()先查weight_map[tensor_name]再加载对应文件且缓存里最多同时驻留 2 个分片超出即torch.cuda.empty_cache()这是它能在单卡上处理数百 GB 权重的关键。MTP 模块的层 ID 紧跟主模型之后num_hidden_layers 61时它落在model.layers.61含enorm/hnorm/eh_proj三个投机解码专用参数嵌入层与输出头则与主模型共享、不重复存储。官方 demo 加载时会主动跳过这一层自建框架则要把它当普通层读入。第 4 站量化与反量化。每个 FP8 权重张量都有配套的*_scale_invfloat32形状为权重形状 ÷ 128。反量化是逐块乘回缩放因子Triton 内核inference/kernel.py中weight_dequant的核心就是y x * s。细节块不整除 128 时先零填充到 128 再算 scale量化后裁掉填充。推理方向相反——激活值按 per-token-per-128-channel 动态量化内核里s amax / 448448 是e4m3的最大可表示值然后 FP8 GEMM 累加时按块乘回两侧 scale。权重体积对比FP8 约340GB反量化成 BF16 后约680GB671B × 2 字节。第 5 站推理。generate.py读--config configs/config_671B.json关键参数n_layers: 61、n_dense_layers: 3、n_routed_experts: 256、n_activated_experts: 8、dim: 7168配torchrun张量并行把权重按 rank 切到各卡vocab_size为 129280上下文 128K。convert.py的分片逻辑也值得一读专家权重按idx // (n_experts // mp)归到各 rank其余权重沿mapping表中声明的维度narrow均分。场景化实战三条路径各给最小可用步骤部署方快速上线直接上 SGLang 或 vLLM生产部署不需要手写加载逻辑。README 中 SGLang 是首选推荐NVIDIA/AMD 通吃、FP8 W8A8、FP8 KV Cache、多机张量并行vLLM 提供管道并行与 OpenAI 兼容接口LMDeploy 适合离线批处理。最小步骤git clone https://gitcode.com/GitHub_Trending/de/DeepSeek-V3 cd DeepSeek-V3/inference pip install -r requirements.txt权重从 Hugging Face 拉取后放入本地目录SGLang/vLLM 直接指向该目录启动即可各框架启动参数见其官方文档。注意 demo 脚本的环境限制仅 Linux Python 3.10依赖锁在torch2.4.1、triton3.0.0、transformers4.46.3、safetensors0.4.5。研究者改权重FP8 转 BF16 三步走有些实验必须吃 BF16例如对比量化误差、接入只认高精度的工具链。用官方fp8_cast_bf16.py它逐分片读 FP8 张量、按块乘回scale_inv、输出同名 BF16 分片并同步改写索引文件删掉所有*_scale_inv条目。python fp8_cast_bf16.py --input-fp8-hf-path /path/to/fp8_weights --output-bf16-hf-path /path/to/bf16_weights三个前置条件至少 1 张显存足够的 GPU脚本把分片加载到 CUDA 上做反量化输出目录预留约700GB执行期间磁盘占用接近输入 输出双份。转换产物是标准 HF 格式可直接喂给支持 BF16 的推理框架。二次开发接入自有框架只依赖索引 weight_map自建推理栈时建议把model.safetensors.index.json当作唯一事实来源safe_open()按分片流式取张量不整包读入。两个必须处理的点命名映射inference/convert.py顶部的mapping字典就是 HF 张量名到自定义名的对照表q_a_proj→wq_a、gate_proj→w1、weight_scale_inv→scale等可以直接借来对齐命名空间。MTP 层convert.py里if model.layers.61 in name: continue说明官方 demo 丢弃 MTP 层若你要支持投机解码这层必须保留且它的embed_tokens/lm_head要与主模型共享同一份权重对象。高频踩坑与排错1.Warning: Missing scale_inv tensor for ..., skipping conversion现象跑fp8_cast_bf16.py时个别权重被跳过输出目录里出现未反量化的 FP8 张量。原因权重和它的*_scale_inv被切进了不同分片脚本的get_tensor()依赖weight_map跨文件查找若你拿到的索引不完整、或手工拆分过分片对应关系就断了。解决确认输入目录里model.safetensors.index.json完整未被裁剪且weight_map中每个 FP8 张量都有*_scale_inv条目用第 2 站的校验脚本扫一遍被拆散的分片先合并再转。2.AssertionError: Number of experts must be divisible by model parallelism现象convert.py启动即挂。原因n_experts必须能被model_parallel整除——专家是整体切分单元不能把一个专家劈到两个 rank。解决让mp成为专家数的约数。671B 有 256 个路由专家--model-parallel 16时每 rank 拿 16 个专家想改 8 卡/32 卡就传 8 或 32。3.KeyError: Key xxx not found in mappingconvert.py 中现象自定义 checkpoint 跑convert.py断言失败。原因张量名的倒数第二段如 MTP 层的enorm、hnorm不在脚本的mapping字典里。解决在mapping中补上对应条目或直接过滤掉不需要加载的前缀。4.load_file()阶段 CUDA out of memory现象官方 demo 或转换脚本在加载单个分片时显存爆掉。原因单卡同时驻留了过多分片。解决转换脚本自带最多缓存 2 个分片策略自定义代码请照抄推理侧先用小配置冒烟--max-new-tokens 200确认链路后再扩。5. transformers 里AutoModel无法识别deepseek_v3现象from_pretrained()报不支持的 model type。原因官方明确说明 Transformers 暂不支持直接加载该权重。解决走 SGLang、vLLM、LMDeploy、TensorRT-LLM 或仓库内 demo不要用transformers硬加载。6. 转换后磁盘写满现象save_file中途报No space left on device。原因FP8→BF16 输出约 680GB很多人只按输入体积预留了空间。解决执行前df -h确认输出目录可用空间 ≥ 700GB最好与输入分盘。决策建议与上手自检清单框架怎么选。按生产服务还是科研改权重分框架量化支持适用场景SGLangBF16 FP8W8A8、FP8 KV Cache生产首选NVIDIA/AMD 通吃多机张量并行vLLMBF16 FP8管道并行跨机、OpenAI 兼容接口接入LMDeployBF16 FP8离线批处理与在线服务TensorRT-LLMBF16 INT4/INT8FP8 开发中极致单卡延迟官方 demoBF16 FP8学习张量并行与 MLA 加载逻辑的参考实现量化格式怎么选。生产环境保留原生 FP8权重体积减半FP8 GEMM 更快且quantization_config已完整描述块缩放主流框架都能消费BF16 只在科研对比、误差分析或框架只认高精度时使用显存极度紧张再考虑 INT4/INT8 权重量化。存储与显存预估。磁盘FP8 检查点约 760GB含 scaleBF16 输出约 680GB转换期间需要两者并存。显存671B FP8 权重按 2×8 的 H 卡规模起步16 卡张量并行每卡约 21GB 权重 KV Cache 与激活开销128K 上下文的 KV Cache 另算建议按官方多机配置对齐。上手自检清单按序执行每步 5 分钟内环境Linux Python 3.10 CUDA GPUdf -h确认 ≥ 2× 模型体积的磁盘。检查点完整性config.json含quantization_config且weight_block_size为[128, 128]跑第 2 站的校验脚本确认分片可读、scale对缺失数为 0、model.layers.0~model.layers.61前缀齐全。最小冒烟按场景一启动 SGLang或 demo 双机 16 卡 configs/config_671B.json请求 200 token 验证输出再逐级放开上下文与并发。三步全绿你的 DeepSeek-V3 权重链路就算真正落地了。【免费下载链接】DeepSeek-V3项目地址: https://gitcode.com/GitHub_Trending/de/DeepSeek-V3创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考