Hy3 权重就位后先核对文件清单 / 再挑推理框架起服务

Hy3 权重下载到本地之后，真正容易卡住的不是启动命令，而是两件事：目录里的文件是否成套，以及这套权重能不能被某个推理框架直接加载。文件数量对不上，框架无论怎么配都会在加载阶段报错；文件齐全但结构字段超出框架支持面，同样起不来。可行的顺序是先点清文件，再从模型配置里读出层数、头数、专家数这类结构字段，用它们筛框架，最后用一份最小配置把服务拉起来，发一条短请求确认模型在出结果。

权重落地后建议按“清点文件 → 读结构字段 → 选框架 → 最小启动 → 最小请求”推进。先确认配置文件、分片索引与分片文件成套，再从配置里读层数、注意力头数、专家数等字段判断框架支持面。先用短上下文启动，用一条短请求验证输出正常，再逐步加长输入。加载失败时按文件层、配置层、框架层分段定位，不要反复重装。具体字段名和命令需以实际框架与权重格式为准。

在权重目录里核对配置文件与分片索引是否成套

权重目录通常由三类文件组成：配置文件（描述模型结构、词表、精度等元信息）、分片索引文件（记录每个参数分片落在哪个文件里）、分片文件本身（实际张量数据）。分片索引与实际分片必须数量一致、名称对得上，否则加载器在拼装参数时会缺键或找不到文件。这一步排除的是文件缺失或下载中断，属于最低级也最常见的失败。

先列目录，确认三类文件都在，再核对分片数量。常见做法如下，具体文件名以权重格式为准：

# 1. 列目录，看文件类别与总数
ls -lh ./hy3-weights/

# 2. 查看索引文件中登记的分片条目（以 JSON 索引为例）
python -c "import json;d=json.load(open('model.safetensors.index.json'));print(len(d['weight_map']))"

# 3. 统计实际分片文件个数
ls ./hy3-weights/*.safetensors | wc -l

# 4. 校验分片文件哈希（若发布方提供了校验清单）
sha256sum ./hy3-weights/*.safetensors

索引登记的条目数应与实际分片文件数基本一致（同一分片承载多个参数时条目数会多于文件数，需要结合索引内容判断）。如果数量明显对不上，或校验值与发布清单不一致，先补齐或重新下载，不要在框架层继续折腾。这一步确认通过后，再进入结构字段的判断。

从模型配置里读出层数、头数与专家数，判断框架支持面

配置文件是把“能不能加载”变成几个可读字段的关键。建议先读这些字段：

模型类型 / 架构名：决定框架是否有对应实现，名字对不上通常直接加载失败。
层数：决定网络深度，也影响框架对层结构的假设。
注意力头数与头维度：决定注意力实现的形状，部分框架对头数有整除或对齐要求。
专家数与每 token 激活专家数：存在专家字段说明是稀疏结构，框架需要支持对应的路由与前向逻辑。
词表大小与隐藏维度：决定嵌入层与显存占用规模，主要影响资源规划。
精度 / 量化配置：决定权重加载时的数据类型与显存规模。

可以这样一次性把字段读出来（字段名以实际配置为准）：

python -c "import json;c=json.load(open('config.json'));\
print({k:c.get(k) for k in ['model_type','num_hidden_layers','num_attention_heads','num_key_value_heads','num_experts','num_experts_per_tok','hidden_size','vocab_size','torch_dtype']})"

判断方式可以归纳为：模型类型和稀疏结构字段决定框架能否加载；层数、头数、隐藏维度、精度共同决定显存规模和并行切分策略。如果框架文档里没有列出该模型类型，或明确不支持专家组路由，就换一个框架，而不是硬改配置去凑。

用一份最小启动配置把服务拉起来

确定框架后，先用能跑通的最小配置启动，把权重路径、并行度和上下文都压到保守值。下面是一份通用骨架，字段名为占位，需替换成实际框架的参数名：

model_path: /abs/path/hy3-weights   # 必须与清点过的目录一致
tensor_parallel_size: 1            # 从单卡开始，与层数/头数可切分性有关
pipeline_parallel_size: 1
max_model_len: 2048               # 先取小值，来自配置中可支持的上限
max_num_seqs: 1
dtype: auto                       # 与配置里的精度字段一致
enforce_eager: true               # 首次启动建议关闭图优化，便于看报错

其中 model_path 和 dtype 必须来自前面读到的信息；并行度是否可行，取决于层数、注意力头数能否被切分整除。第一次不要同时开高并发和大上下文，先让进程起来并完成权重加载。

起服务后先跑一条最小请求再逐步加长输入

进程在跑不等于模型在出结果。先发一条最短请求：

curl -s http://127.0.0.1:8000/v1/completions \
  -H 'Content-Type: application/json' \
  -d '{"model":"hy3","prompt":"你好","max_tokens":8,"temperature":0}'

观察点是：返回体里有没有非空的生成文本、有没有 finish_reason、服务日志里有没有异常堆栈。第一段通过后再逐步加长：短句 → 一段话 → 接近 max_model_len 的长输入，每一步都看输出是否完整、是否中途截断、显存是否接近上限。若短输入正常而长输入失败，通常是上下文或显存配置问题，回到启动参数调整，而不是怀疑权重。

加载失败时按文件层、配置层、框架层三段排查

三段各自的特征与验证方式如下，报错文案为占位示意，实际以日志为准：

文件层：报错特征多为找不到文件、分片键缺失、哈希不匹配。验证方式：重新执行上一节的列目录与校验命令，确认索引条目与分片文件对应。确认通过后再动配置。
配置层：报错特征多为字段缺失、类型不符、维度不匹配。验证方式：用一个最小脚本加载 config.json，逐项打印前面列出的字段，确认与框架期望的键名和取值范围一致。确认通过后再换框架。
框架层：报错特征多为不支持该模型类型、算子缺失、显存不足。验证方式：查看框架日志中的模型注册与算子加载信息，必要时用官方支持列表里的小模型跑通同一套启动流程作为对照。确认框架本身可用后，再回来处理 Hy3 的适配问题。

按这三段顺序排查，可以把问题定位到一层，避免在文件齐全的情况下反复重装权重。