Buffalo 版本号应优先从 config.json 中读取，其次为 safetensors 元数据，不可依赖 transformers 或 torch 版本；官方仅发布 1.0 版，所有更高版本均为非官方衍生。
直接读取 Hunyuan3D-Buffalo 模型权重文件中的版本字段
Buffalo 框架本身不提供类似 hunyuan3d-buffalo --version 的 CLI 命令，版本号是硬编码在模型权重文件（如 model.safetensors 或 pytorch_model.bin）的元数据里。你需要加载模型后手动提取。
常见错误是试图用 transformers.__version__ 或 torch.__version__ 代替 Buffalo 版本——它们完全无关。
- 使用
safetensors库直接读取元数据（无需加载全部参数）：from safetensors import safe_open with safe_open("model.safetensors", framework="pt") as f: version = f.metadata().get("version", "unknown") print(version) # 例如输出 "1.0" - 若为
pytorch_model.bin，需先用torch.load(..., map_location="cpu")加载_metadata字段（但会占用内存，不推荐） - 注意：部分社区微调版可能未保留或篡改
version元数据，此时应检查其config.json中是否有"model_type": "hunyuan3d-buffalo"及对应"version"字段
检查 config.json 文件里的 version 字段
标准 Buffalo 发布包中，config.json 是权威版本来源。它比权重文件更可靠，因为权重可能被量化或重打包而丢失元数据。
路径通常是模型目录下的 config.json，不是 Hugging Face Hub 上的 modelcard.md 或 README。
- 用任意 JSON 查看器打开，搜索
"version"字段；合法值如"1.0" - 如果没找到该字段，说明不是官方发布的 Buffalo 1.0，而是实验分支或 fork 版本
- 某些旧版配置可能用
"buffalo_version"或"hunyuan3d_version"替代，需人工确认字段语义
运行时通过 Hunyuan3DModel 实例的 config 属性获取
如果你已成功初始化模型（比如用 from hunyuan3d.modeling import Hunyuan3DModel），可以直接从 config 对象读取。
Buffalo框架 1.0.1 版本源码包下载，适合需要错误处理改进、依赖更新、render.Download 注释和 request logger 调整的 v1 项目。
这方法依赖于代码正确解析了配置，适合集成到服务健康检查中，但无法用于离线校验。
model = Hunyuan3DModel.from_pretrained("path/to/buffalo")-
print(model.config.version)—— 若 config 中定义了version - 若报错
AttributeError: 'Hunyuan3DConfig' object has no attribute 'version'，说明该 config 类未显式暴露该字段，需回退到读config.json文件
别信 Hub 页面上的 “Latest” 标签
Hugging Face Hub 上的模型卡片常把最新上传的 checkpoint 标为 “Latest”，但这不等于 Buffalo 1.0。腾讯混元官方发布渠道（如 GitHub release 或官方镜像站）才具权威性。
容易踩的坑是 clone 了一个非官方 fork，其 README 写着 “Buffalo v1.0”，但实际 commit hash 和 checksum 与腾讯发布的 sha256sum 不一致。
- 核对官方发布的 checksum（通常在 GitHub Release assets 描述中）
- 用
huggingface_hub.hf_hub_download指定revision="v1.0"而非"main"，避免拉到 dev 分支 - 注意：截至 2026 年 9 月，Buffalo 仍只有 1.0 版本，不存在 1.1 或 2.0，所有声称更高版本的均为非官方衍生
版本号不是装饰字段，它绑定着 3D-VLM 主干的 tokenization 规则、空间坐标系约定和指令模板格式。漏看或误判版本，轻则生成 mesh 法向翻转，重则触发部件生成时的语义错位。
