Fix family download metadata and counted download flows

README.md

@@ -143,6 +143,9 @@ The optimization reduces output-head work, not the context-processing backbone.
 
 ## 5. Minimal Inference
 
+The root [meta.yaml](meta.yaml) catalogs model variants and their configuration hashes. Include it when downloading a variant; the repository and existing model paths are unchanged. You can also use [download_model.py](download_model.py) with `--variant 9B-3000 --local-dir ./APUS-OpenJev-v1`; it selects and checks the variant at one fixed Hub revision. Hub download statistics count requests to selected metadata files, not unique users or completed weight transfers. Older subfolder-only clients can bypass this metadata.
+
+
 The repository is a model-family bundle. Choose a subdirectory containing complete BF16 weights and the reference runtime:
 
 | Variant | Model directory | Suggested use |
@@ -158,7 +161,7 @@ Use a CUDA-capable PyTorch environment. Select the model directory to download:
 python -m pip install huggingface_hub
 hf auth login
 hf download apus-ailab/APUS-OpenJev-v1 \
-  --include "9B-3000/*" --local-dir ./APUS-OpenJev-v1
+  --include "meta.yaml" "9B-3000/*" --local-dir ./APUS-OpenJev-v1
 cd ./APUS-OpenJev-v1/9B-3000
 python -m pip install -r requirements.txt
 python examples.py . --device cuda:0 --effort high

README.zh-CN.md

@@ -143,6 +143,9 @@ tags:
 
 ## 5. 最小推理示例
 
+根目录 [meta.yaml](meta.yaml) 提供模型版本及配置哈希；下载指定版本时请同时保留它，仓库与原模型路径不变。也可运行 [download_model.py](download_model.py)，参数为 `--variant 9B-3000 --local-dir ./APUS-OpenJev-v1`，在同一固定 Hub revision 选择并校验模型。Hub 下载统计按指定元数据文件的请求计数，不等同独立用户或完整权重下载；旧版仅下载子目录的客户端可能绕过此元数据。
+
+
 本仓库集中保存一个模型系列。请选择包含完整BF16权重和参考runtime的具体子目录：
 
 | 版本 | 模型目录 | 建议用途 |
@@ -158,7 +161,7 @@ tags:
 python -m pip install huggingface_hub
 hf auth login
 hf download apus-ailab/APUS-OpenJev-v1 \
-  --include "9B-3000/*" --local-dir ./APUS-OpenJev-v1
+  --include "meta.yaml" "9B-3000/*" --local-dir ./APUS-OpenJev-v1
 cd ./APUS-OpenJev-v1/9B-3000
 python -m pip install -r requirements.txt
 python examples.py . --device cuda:0 --effort high

bundle-manifest.json

@@ -28,9 +28,11 @@
     "assets/equations/projection-cost.svg",
     "assets/latency-vllm.svg",
     "deployment/serve_vllm.py",
+    "download_model.py",
     "effort-tradeoff-data.json",
     "equations-source.json",
-    "latency-vllm-data.json"
+    "latency-vllm-data.json",
+    "meta.yaml"
   ],
   "files": [
     {
@@ -590,13 +592,13 @@
     },
     {
       "path": "README.md",
-      "bytes": 18803,
-      "sha256": "47b45662d3356a3324062b84cb6bd381621865241744cbe9ff0c0928fb8f948d"
+      "bytes": 19342,
+      "sha256": "93fdbfe97a697fb5576b7e12fd9e2871656a99b5994b56e6eb9e2e2cf77dcbae"
     },
     {
       "path": "README.zh-CN.md",
-      "bytes": 14045,
-      "sha256": "0a733d01ed54e3f9dca9210c5384d46a62128a746d5c78b20474f0c7d76e7bfb"
+      "bytes": 14539,
+      "sha256": "bdc3560df8a90a75f6ce4cc996aaddae5f9801134760279f2b7efbc05f995448"
     },
     {
       "path": "TECHNICAL_REPORT.md",
@@ -685,8 +687,13 @@
     },
     {
       "path": "deployment/serve_vllm.py",
-      "bytes": 3535,
-      "sha256": "7d8fac3021a9f9949e73364013989d861dcb6fd4c44ee338239822584d32ecf8"
+      "bytes": 5319,
+      "sha256": "2dab173e233c3b96c49a6fc416204a7800e0887aae53bb60e28e9f8ecfa4b777"
+    },
+    {
+      "path": "download_model.py",
+      "bytes": 2894,
+      "sha256": "3a5abe26075c47d10ee1854c60365b651be5d7caad8523896fd27c1b881a53a2"
     },
     {
       "path": "effort-tradeoff-data.json",
@@ -703,6 +710,11 @@
       "bytes": 3456,
       "sha256": "3165a4510d2d294934b0374d1f6e9a53303f5fa734daf662eb8a3aa69581fab0"
     },
+    {
+      "path": "meta.yaml",
+      "bytes": 811,
+      "sha256": "937aaa3208cf803e03295a64b788e3c4f99299c5d1f5b6341701e90e93250989"
+    },
     {
       "path": "subset-chart-data.json",
       "bytes": 58611,

deployment/serve_vllm.py

@@ -1,6 +1,7 @@
 """Download APUS-OpenJev-v1 merged 9B weights and launch standard vLLM serving."""
 
 import argparse
+import hashlib
 import json
 import os
 from pathlib import Path
@@ -48,6 +49,45 @@ def engine_command(model, host, port):
     ]
 
 
+def select_catalog_model(repo, revision):
+    from huggingface_hub import hf_hub_download
+    from huggingface_hub.errors import EntryNotFoundError
+
+    try:
+        path = hf_hub_download(repo_id=repo, filename="meta.yaml", revision=revision)
+    except EntryNotFoundError:
+        # Preserve explicit older revisions published before the family catalog.
+        path = hf_hub_download(
+            repo_id=repo, filename="bundle-manifest.json", revision=revision
+        )
+        manifest = json.loads(Path(path).read_text())
+        if manifest.get("repo_id") != repo:
+            raise ValueError("Unexpected legacy family manifest")
+        matches = [
+            item for item in manifest["files"]
+            if item.get("path") == MODEL_SUBFOLDER + "/config.json"
+        ]
+        if len(matches) != 1:
+            raise ValueError("Missing or duplicate legacy config identity")
+        entry = {
+            "subfolder": MODEL_SUBFOLDER,
+            "config_sha256": matches[0]["sha256"],
+        }
+    else:
+        catalog = json.loads(Path(path).read_text())
+        if (
+            catalog.get("schema") != "apus-openjev-family.v1"
+            or catalog.get("repo_id") != repo
+        ):
+            raise ValueError("Unexpected model-family catalog")
+        entry = catalog["variants"][MODEL_SUBFOLDER]
+    if entry.get("subfolder") != MODEL_SUBFOLDER or not re.fullmatch(
+        r"[0-9a-f]{64}", entry.get("config_sha256", "")
+    ):
+        raise ValueError("Unexpected model variant identity")
+    return entry
+
+
 def main():
     parser = argparse.ArgumentParser(description=__doc__)
     parser.add_argument(
@@ -88,6 +128,7 @@ def main():
     revision = HfApi().model_info(MODEL_REPO, revision=args.revision).sha
     if not revision or not re.fullmatch(r"[0-9a-f]{40}", revision):
         parser.error("The Hub did not return an immutable model commit SHA")
+    entry = select_catalog_model(MODEL_REPO, revision)
     snapshot = snapshot_download(
         repo_id=MODEL_REPO, revision=revision, allow_patterns=[f"{MODEL_SUBFOLDER}/*"]
     )
@@ -96,6 +137,8 @@ def main():
         parser.error(
             "Downloaded subfolder is missing config.json or merged safetensors weights"
         )
+    if hashlib.sha256((model / "config.json").read_bytes()).hexdigest() != entry["config_sha256"]:
+        parser.error("Downloaded model config does not match family catalog")
     if (model / "adapter_config.json").exists():
         parser.error("Expected merged weights, not an adapter-only directory")
     print(

download_model.py

@@ -0,0 +1,78 @@
+"""Download one APUS-OpenJev variant using its verified family catalog.
+
+The Hub's meta.yaml is JSON (a YAML 1.2 subset), so no YAML dependency is needed.
+Only the requested model subdirectory is downloaded. Requires huggingface_hub.
+"""
+
+import argparse
+import hashlib
+import json
+from pathlib import Path
+import re
+
+REPO_ID = "apus-ailab/APUS-OpenJev-v1"
+VARIANTS = ("4B-5949", "9B-3000", "9B-5949")
+SCHEMA = "apus-openjev-family.v1"
+
+
+def download_variant(*, local_dir, variant="9B-3000", revision="main"):
+    """Resolve once, validate the catalog, download and verify the model config."""
+    if variant not in VARIANTS:
+        raise ValueError("Unknown model variant")
+
+    from huggingface_hub import HfApi, hf_hub_download, snapshot_download
+
+    commit = HfApi().model_info(REPO_ID, revision=revision).sha
+    if not isinstance(commit, str) or not re.fullmatch(r"[0-9a-f]{40}", commit):
+        raise ValueError("Hub did not return an immutable commit SHA")
+    catalog_path = hf_hub_download(REPO_ID, "meta.yaml", revision=commit)
+    catalog = json.loads(Path(catalog_path).read_text(encoding="utf-8"))
+    if (
+        not isinstance(catalog, dict)
+        or catalog.get("schema") != SCHEMA
+        or catalog.get("repo_id") != REPO_ID
+        or not isinstance(catalog.get("variants"), dict)
+    ):
+        raise ValueError("Invalid model family catalog")
+    entry = catalog["variants"].get(variant)
+    if not isinstance(entry, dict) or entry.get("subfolder") != variant:
+        raise ValueError("Catalog subfolder does not match the selected variant")
+    expected_sha = entry.get("config_sha256")
+    if not isinstance(expected_sha, str) or not re.fullmatch(
+        r"[0-9a-f]{64}", expected_sha
+    ):
+        raise ValueError("Catalog config_sha256 is invalid")
+
+    snapshot = snapshot_download(
+        repo_id=REPO_ID,
+        revision=commit,
+        allow_patterns=[f"{variant}/*"],
+        local_dir=str(local_dir),
+    )
+    model_path = Path(snapshot) / variant
+    actual_sha = hashlib.sha256((model_path / "config.json").read_bytes()).hexdigest()
+    if actual_sha != expected_sha:
+        raise ValueError("Downloaded config.json does not match the family catalog")
+    return {
+        "repo_id": REPO_ID,
+        "revision": commit,
+        "variant": variant,
+        "model_path": str(model_path.resolve()),
+        "config_sha256": actual_sha,
+    }
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--variant", choices=VARIANTS, default="9B-3000")
+    parser.add_argument("--revision", default="main")
+    parser.add_argument("--local-dir", type=Path, required=True)
+    args = parser.parse_args(argv)
+    result = download_variant(
+        local_dir=args.local_dir, variant=args.variant, revision=args.revision
+    )
+    print(json.dumps(result, indent=2))
+
+
+if __name__ == "__main__":
+    main()

meta.yaml

@@ -0,0 +1,25 @@
+{
+  "schema": "apus-openjev-family.v1",
+  "repo_id": "apus-ailab/APUS-OpenJev-v1",
+  "description": "Select a complete model subdirectory; this is family metadata, not a Transformers model config.",
+  "variants": {
+    "4B-5949": {
+      "subfolder": "4B-5949",
+      "config_sha256": "4b53bdb886bb68d228841409c2db2f5d7eb670c28ae4376849f58d3bd014968d",
+      "checkpoint": 5949,
+      "dtype": "bfloat16"
+    },
+    "9B-3000": {
+      "subfolder": "9B-3000",
+      "config_sha256": "b1d02fb6b40aeba43105ca558b2532f31d062e0bd95bce564d9996c0a34b4211",
+      "checkpoint": 3000,
+      "dtype": "bfloat16"
+    },
+    "9B-5949": {
+      "subfolder": "9B-5949",
+      "config_sha256": "b1d02fb6b40aeba43105ca558b2532f31d062e0bd95bce564d9996c0a34b4211",
+      "checkpoint": 5949,
+      "dtype": "bfloat16"
+    }
+  }
+}