OpenMOSS-Team
/

MOSS-Audio-Tokenizer-v2

@@ -1,215 +0,0 @@
-# Hugging Face 合规性检查总结
-检查日期：2026-06-05 UTC
-检查对象：本地仓库 `MOSS-Audio-Tokenizer-V2`，远程地址为 `https://huggingface.co/OpenMOSS-Team/MOSS-Audio-Tokenizer-V2`。
-结论：本地仓库整体已经是标准 Hugging Face Transformers 自定义模型仓库形态，权重使用 safetensors + Git LFS 分片，`config.json` 的 `auto_map` 和远程代码加载入口也能通过本地验证。没有发现会直接阻断上传或 `AutoConfig`/模型类动态导入的问题。2026-06-05 已完成一轮整改，补齐了主要发布质量问题；剩余事项主要是远程页面状态、可选 metadata 和更完整的结构化评测信息核验。
-## 整改状态
-已完成：
-- 添加根目录 `LICENSE`，使用 Apache-2.0 全文。
-- 删除 README license 部分的待办注释。
-- README 补充 Model Details、Intended Use、Training Data And Procedure、Evaluation、Limitations、Requirements。
-- README 示例保留 `demo/demo_gt.wav`，并说明可替换为自有音频；当前本地已有 `demo/demo_gt.wav`。
-- README 增加 production 使用 `trust_remote_code=True` 时 pin commit revision 的建议。
-- README repository layout 补充分片权重、index 和 demo 音频。
-- `.gitignore` 增加 `!dev/huggingface_compliance_audit.md`，使本审计文档可被 Git 跟踪；同时忽略 quickstart 生成的 `demo/demo_rec*.wav`。
-## 检查依据
-本次按 Hugging Face 官方文档的以下方向检查：
-- Model Cards: `README.md` 是模型卡，应包含 YAML metadata 和正文说明；模型卡应描述模型、用途/限制、训练信息、数据、评测结果等。参考：<https://huggingface.co/docs/hub/model-cards>
-- Model Card metadata: 建议显式写 `library_name`；可写 `pipeline_tag`、`license`、`datasets`、`model-index` 等以提高可发现性。参考：<https://huggingface.co/docs/hub/model-cards>
-- Custom Transformers model: 自定义模型需要配置类 `model_type`、模型类 `config_class`、`auto_map`，并通过 `trust_remote_code=True` 加载。参考：<https://huggingface.co/docs/transformers/custom_models>
-- 大文件和仓库结构：建议文件数少于 100k、单目录条目少于 10k、单文件分片小于 200GB、一次 commit 尽量少于 100 个大文件操作。参考：<https://huggingface.co/docs/hub/en/storage-limits>
-- 权重安全格式：safetensors 相比 pickle 更安全；pickle 权重存在任意代码执行风险。参考：<https://huggingface.co/docs/safetensors/en/index>、<https://huggingface.co/docs/hub/security-pickle>
-## 本地证据
-### 仓库结构
-`git ls-files` 当前跟踪的文件为：
-- `.gitattributes`
-- `README.md`
-- `__init__.py`
-- `config.json`
-- `configuration_moss_audio_tokenizer.py`
-- `modeling_moss_audio_tokenizer.py`
-- `model-00001-of-00003.safetensors`
-- `model-00002-of-00003.safetensors`
-- `model-00003-of-00003.safetensors`
-- `model.safetensors.index.json`
-结构判断：符合 Hugging Face model repo 的基本结构。自定义 Transformers remote-code 文件、config、模型权重和权重索引均在根目录，用户可以通过 `AutoModel.from_pretrained(repo_id, trust_remote_code=True)` 获取。
-注意：当前 `.gitignore` 保留 `dev/*`，但已增加 `!dev/huggingface_compliance_audit.md`，因此本文件可以被 Git 跟踪。`.gitignore` 还忽略 quickstart 生成的 `demo/demo_rec*.wav`。
-### 模型卡 README
-已符合：
-- `README.md` 顶部已有 YAML metadata。
-- 已声明 `license: apache-2.0`。
-- 已声明 `library_name: transformers`。这点很重要，因为 Hugging Face 对 2024-08 之后创建的模型仓库不再总是从 `config.json` 自动推断为 Transformers。
-- 已提供与 audio tokenizer 相关的 tags：`audio`、`audio-tokenizer`、`neural-codec`、`moss-tts-family`、`speech-tokenizer`、`trust-remote-code` 等。
-- 已包含 quickstart、streaming 使用示例、RVQ 层数控制、citation 和 license 说明。
-- README 示例明确使用 `trust_remote_code=True`，与 custom model 要求一致。
-仍可改进或待核验：
-- YAML metadata 仍未添加 `pipeline_tag`。音频 tokenizer 不一定有完全匹配的官方 pipeline；如果 Hugging Face metadata UI 接受，可以考虑 `feature-extraction`，否则保留现有自定义 tags。
-- YAML metadata 没有 `datasets`。README 已补训练数据说明；如果训练数据有公开 Hub dataset id，可再补 `datasets` metadata。
-- 没有 `model-index` 或结构化 eval metadata。若论文中有重建质量、ASR/TTS 下游指标，建议加入正文表格；如果有可结构化指标，再加 `model-index`。
-- 远程页面 metadata 是否正确渲染仍需有权限账号确认。
-### config 和 AutoClass
-已符合：
-- `config.json` 包含：
-  - `model_type: "moss-audio-tokenizer"`
-  - `architectures: ["MossAudioTokenizerModel"]`
-  - `auto_map.AutoConfig: "configuration_moss_audio_tokenizer.MossAudioTokenizerConfig"`
-  - `auto_map.AutoModel: "modeling_moss_audio_tokenizer.MossAudioTokenizerModel"`
-- `configuration_moss_audio_tokenizer.py` 中 `MossAudioTokenizerConfig.model_type` 与 `config.json` 一致。
-- `modeling_moss_audio_tokenizer.py` 中 `MossAudioTokenizerPreTrainedModel.config_class = MossAudioTokenizerConfig`。
-- `modeling_moss_audio_tokenizer.py` 设置了 `main_input_name = "input_values"`、`input_modalities = "audio"` 和 `_no_split_modules`，对 Transformers 加载/设备切分是正面信号。
-本地验证通过：
-```bash
-python -c "from transformers import AutoConfig; c=AutoConfig.from_pretrained('.', trust_remote_code=True); print(type(c).__name__, c.model_type, c.architectures, c.auto_map)"
-```
-输出要点：
-```text
-MossAudioTokenizerConfig moss-audio-tokenizer ['MossAudioTokenizerModel'] {'AutoConfig': 'configuration_moss_audio_tokenizer.MossAudioTokenizerConfig', 'AutoModel': 'modeling_moss_audio_tokenizer.MossAudioTokenizerModel'}
-```
-模型类动态导入也通过：
-```bash
-python -c "from transformers.dynamic_module_utils import get_class_from_dynamic_module; cls=get_class_from_dynamic_module('modeling_moss_audio_tokenizer.MossAudioTokenizerModel', '.'); print(cls.__name__, cls.config_class.__name__)"
-```
-输出要点：
-```text
-MossAudioTokenizerModel MossAudioTokenizerConfig
-```
-当前状态：
-- README 已补 “Requirements” 小节，说明 Python、PyTorch、Transformers、`torchaudio` 和可选 `flash-attn`。
-- README 已说明 `config.json` 中的 `transformers_version` 为 `4.56.0.dev0`，建议使用支持 custom remote-code models 的近期 Transformers build。
-- README 已加入 production 使用 `trust_remote_code=True` 时 pin reviewed commit hash 的建议。
-### 权重、LFS 和仓库大小
-已符合：
-- `.gitattributes` 对 `*.safetensors` 设置了 `filter=lfs diff=lfs merge=lfs -text`。
-- `git lfs ls-files` 列出了三个 safetensors 分片：
-  - `model-00001-of-00003.safetensors`
-  - `model-00002-of-00003.safetensors`
-  - `model-00003-of-00003.safetensors`
-- `git cat-file -s HEAD:model-00001-of-00003.safetensors` 为 135 字节，说明 Git 对象里是 LFS pointer，不是把 3.9GB 权重作为普通 Git blob 提交。
-- 第一个 LFS pointer 内容记录了真实大小 `3978639168` 字节。
-- 另外两个分片的 Git blob size 分别为 135 和 134 字节，也符合 LFS pointer 预期。
-- `model.safetensors.index.json` metadata:
-  - `total_parameters: 2123701248`
-  - `total_size: 8494804992`
-  - `weight_map` 条目数：2094
-- `weight_map` 分片分布：
-  - `model-00001-of-00003.safetensors`: 898 entries
-  - `model-00002-of-00003.safetensors`: 1010 entries
-  - `model-00003-of-00003.safetensors`: 186 entries
-- 三个分片大小约 3.98GB、3.99GB、0.52GB，远低于 Hugging Face 对大文件建议的 200GB 分片线，也低于 500GB 单文件硬限制。
-- 仓库跟踪文件数量只有 10 个，远低于 100k 文件建议，也不存在单目录 10k 条目问题。
-需要改进或待核验：
-- 只能确认本地当前分支的 LFS pointer。远程仓库历史中是否有旧的大 LFS 版本、未清理 PR ref、重复上传，需要在 Hugging Face repo Settings 的 “List LFS files” 或通过有权限的 API 再查。
-- 如果后续更新权重，建议保持分片数量少、每次 commit 的大文件操作不超过 50-100 个。
-### 安全性
-已符合：
-- 权重使用 safetensors，没有发现 `.bin`、`.pt`、`.pth`、`.pkl`、`.pickle` 等 pickle 风险权重文件。
-- 自定义代码 import 扫描未发现明显高风险模式：`subprocess`、`requests`、`urllib`、`socket`、`pickle`、`torch.load`、`eval(`、`exec(` 等。
-- `flash_attn` 是 try/except 可选依赖；缺失时会回退，不会阻断基础导入。
-当前状态：
-- README 已说明 repo 使用 custom Transformers remote code，并建议生产环境 pin reviewed commit hash。
-- 如果未来增加依赖，仍应避免在模型 import 或 forward 过程中做网络访问、文件系统副作用、shell 调用。
-### 远程页面状态
-待核验：
-- 浏览器/匿名 API 访问 `https://huggingface.co/OpenMOSS-Team/MOSS-Audio-Tokenizer-V2` 返回 401，当前无法匿名确认远程页面实际渲染、文件列表、模型卡 metadata 解析结果、LFS 文件列表或下载统计。
-- 本地 `git remote -v` 确认 origin 指向该 Hugging Face repo。
-建议有权限的人在 Hugging Face 页面上手动确认：
-- README metadata 是否被页面正确解析。
-- `Files and versions` 中是否有 3 个 safetensors 分片和 index。
-- 页面是否显示 `Safetensors`、`Transformers`、license、任务标签。
-- `Security`/file scan 是否正常，无 pickle 或 malware 警告。
-- LFS storage 页面是否没有多余历史大文件。
-## 优先级建议
-### P0：阻断项
-本地未发现明确 P0 阻断项。`AutoConfig` 和模型类动态导入通过，权重以 LFS pointer 形式跟踪。
-### P1：已完成
-- 已删除 README 中的 license 待办注释。
-- 已添加根目录 `LICENSE` 文件，放 Apache-2.0 全文。
-- 已补 README 标准模型卡小节：intended use、limitations、training data、training procedure、evaluation results、ethical considerations。
-- 已加 “Requirements” 小节，写清 Python、Transformers、PyTorch、`torchaudio`、可选 `flash-attn`。
-- 已确认并保留 `demo/demo_gt.wav` 示例音频，README 说明可替换为自有音频。
-### P2：增强可发现性和可维护性
-- 如 Hugging Face metadata UI 校验通过，增加 `pipeline_tag: feature-extraction`。
-- 如有论文指标，加入 eval 表格；可结构化时再加入 `model-index`。
-- 如训练数据有公开 Hub dataset id，补 `datasets` metadata；否则正文解释数据范围和不可公开原因。
-- 用有权限账号确认远程页面和 LFS storage 状态。
-## 推荐的 README metadata 方向
-以下仅是方向，`pipeline_tag` 需要以 Hugging Face metadata UI 的校验结果为准：
-```yaml
----
-license: apache-2.0
-library_name: transformers
-pipeline_tag: feature-extraction
-tags:
-  - audio
-  - audio-tokenizer
-  - neural-codec
-  - speech-tokenizer
-  - trust-remote-code
-  - arxiv:2602.10934
----
-```
-如果 `pipeline_tag: feature-extraction` 不适合该 tokenizer，就不要强行添加；保留自定义 tags，并在正文明确这是 audio tokenizer / neural codec。
-## 最终判断
-按本地证据看，这个仓库已经基本符合 Hugging Face 模型仓库和 Transformers custom remote-code 的关键规范：模型卡存在、metadata 基本可用、config/auto_map 正确、权重是 safetensors、LFS tracking 正确、分片和索引一致、文件数量和分片大小都在建议范围内。
-主要发布质量问题已经整改：LICENSE、README 待办注释、模型卡补充、依赖版本说明和 remote-code 安全建议都已加入。剩余风险主要是远程页面因为匿名访问 401，需要有权限账号再做最后确认；另外 `pipeline_tag`、`datasets`、`model-index` 是否补充取决于 Hugging Face metadata 校验结果和可公开的训练/评测信息。