MLX-LM 離線模型產物：Revision 固定、Manifest 與冷環境驗收

mkdir pypy-model-delivery
cd pypy-model-delivery
uv venv --python 3.12 .venv
uv pip install --python .venv/bin/python 'mlx-lm==0.32.2' 'huggingface-hub==2.3.0'

import json
import platform
import shutil
from importlib.metadata import distributions
from pathlib import Path
from huggingface_hub import snapshot_download

REPO = "mlx-community/SmolLM2-135M-Instruct-8bit"
REV = "0f0d9b8218915bc34d401e1a340b8c049d300d5e"
root = Path("release")
root.mkdir(exist_ok=False)
snapshot = snapshot_download(repo_id=REPO, revision=REV)
# 讀取快取，但不修改它；將連結目標實體複製到交付區。
shutil.copytree(snapshot, root / "model", symlinks=False)
provenance = {"repo_id": REPO, "revision": REV}
(root / "provenance.json").write_text(json.dumps(provenance, indent=2))
runtime = {
    "python": platform.python_version(), "macos": platform.mac_ver()[0],
    "architecture": platform.machine(),
    "packages": dict(sorted((d.metadata["Name"], d.version)
                            for d in distributions())),
}
(root / "runtime.json").write_text(json.dumps(runtime, indent=2))
print("materialized:", root.resolve())

.venv/bin/python prepare.py

import hashlib
import json
import re
import sys
from pathlib import Path, PurePosixPath


def read_json(path):
    return json.loads(path.read_text(encoding="utf-8"))


def digest(path):
    with path.open("rb") as source:
        return hashlib.file_digest(source, "sha256").hexdigest()


def inventory(root):
    if root.is_symlink() or not root.is_dir():
        raise ValueError("release root must be a real directory")
    result = {}
    for path in sorted(root.rglob("*")):
        if path.is_symlink():
            raise ValueError(f"symlink: {path.name}")
        if path.is_dir():
            continue
        if not path.is_file():
            raise ValueError("non-regular file")
        name = path.relative_to(root).as_posix()
        if name != "manifest.json":
            result[name] = {"bytes": path.stat().st_size, "sha256": digest(path)}
    return result


def structure(root):
    model = root / "model"
    for name in ("config.json", "tokenizer.json", "tokenizer_config.json"):
        value = read_json(model / name)
        if not isinstance(value, dict) or not value:
            raise ValueError(f"invalid {name}")
    config = read_json(model / "tokenizer_config.json")
    if not config.get("chat_template") and not (model / "chat_template.jinja").is_file():
        raise ValueError("missing chat template")
    weights = {p.name for p in model.glob("*.safetensors")}
    if not weights or any((model / n).stat().st_size == 0 for n in weights):
        raise ValueError("missing or empty weights")
    index = model / "model.safetensors.index.json"
    if index.exists():
        mapping = read_json(index)["weight_map"]
        if not isinstance(mapping, dict) or not mapping:
            raise ValueError("empty weight_map")
        shards = set(mapping.values())
        if any(not isinstance(n, str) or PurePosixPath(n).name != n
               or "\\" in n or not n.endswith(".safetensors") for n in shards):
            raise ValueError("invalid shard path")
        if shards != weights:
            raise ValueError("shard inventory differs from index")
    origin = read_json(root / "provenance.json")
    if not isinstance(origin.get("repo_id"), str) or not origin["repo_id"]:
        raise ValueError("missing repo ID")
    if not re.fullmatch(r"[0-9a-f]{40}", origin.get("revision", "")):
        raise ValueError("revision must be a full commit SHA")
    runtime = read_json(root / "runtime.json")
    if not all(runtime.get(k) for k in ("python", "macos", "architecture", "packages")):
        raise ValueError("missing runtime record")


def seal(root):
    files = inventory(root)
    structure(root)
    with (root / "manifest.json").open("x", encoding="utf-8") as target:
        json.dump({"schema": 1, "files": files}, target, indent=2, sort_keys=True)


def verify(root):
    actual = inventory(root)
    manifest = read_json(root / "manifest.json")
    if type(manifest.get("schema")) is not int or manifest["schema"] != 1:
        raise ValueError("unsupported manifest schema")
    if not isinstance(manifest.get("files"), dict) or actual != manifest["files"]:
        raise ValueError("missing, extra or modified artifact files")
    structure(root)
    return manifest


if __name__ == "__main__":
    action, directory = sys.argv[1:]
    if action not in {"seal", "verify"}:
        raise SystemExit("use seal or verify")
    (seal if action == "seal" else verify)(Path(directory))
    print(f"{action}: OK")

.venv/bin/python artifact.py seal release
.venv/bin/python artifact.py verify release

import json
import os
import sys
from pathlib import Path
from artifact import digest, verify

# 必須由啟動命令設定，且在 import MLX / Hub 之前檢查。
assert os.environ.get("HF_HUB_OFFLINE") == "1"
assert os.environ.get("TRANSFORMERS_OFFLINE") == "1"
cache = Path(os.environ["HF_HOME"])
assert not cache.exists() or not any(cache.iterdir()), "HF_HOME is not empty"
attempts = []


def no_python_network(event, args):
    if event in {"socket.connect", "socket.getaddrinfo"}:
        attempts.append(event)
        raise OSError("network forbidden in artifact smoke test")


sys.addaudithook(no_python_network)
from mlx_lm import generate, load
from mlx_lm.sample_utils import make_sampler

root = Path(sys.argv[1]).resolve(strict=True)
verify(root)
model, tokenizer = load(
    str(root / "model"), trust_remote_code=False,
    tokenizer_config={"local_files_only": True, "trust_remote_code": False})
prompt = tokenizer.apply_chat_template(
    [{"role": "user", "content": "Say hello to Pypy."}],
    tokenize=False, add_generation_prompt=True)
answer = generate(model, tokenizer, prompt=prompt, max_tokens=16,
                  sampler=make_sampler(temp=0), verbose=False)
assert answer.strip() and not attempts
print(json.dumps({"loaded": True, "answer": answer,
                  "python_network_attempts": attempts,
                  "manifest_sha256": digest(root / "manifest.json")}))

uv pip freeze --python .venv/bin/python > runtime-requirements.txt
uv venv --python 3.12 cold-venv
uv pip install --offline --no-deps --python cold-venv/bin/python -r runtime-requirements.txt
mkdir cold-room
cp -R release cold-room/release
HF_HOME="$PWD/cold-room/hf-home" HF_HUB_CACHE="$PWD/cold-room/hf-home/hub" HF_HUB_OFFLINE=1 TRANSFORMERS_OFFLINE=1 cold-venv/bin/python smoke.py cold-room/release

import shutil
from pathlib import Path
import pytest
from artifact import verify


@pytest.mark.parametrize("case", ["modified", "missing", "extra"])
def test_bad_delivery(tmp_path, case):
    root = tmp_path / "release"
    shutil.copytree(Path("release"), root)
    weight = root / "model/model.safetensors"
    if case == "modified":
        weight.chmod(0o600)  # 只改測試複本；Hub 檔案可能原本是唯讀。
        with weight.open("r+b") as target:
            first = target.read(1)
            target.seek(0)
            target.write(bytes([first[0] ^ 1]))
    elif case == "missing":
        weight.unlink()
    else:
        (root / "unexpected.txt").write_text("not in this release")
    with pytest.raises(ValueError):
        verify(root)

uv pip install --python .venv/bin/python pytest
.venv/bin/python -m pytest -q test_delivery.py