code-HFD / src /psi /runtime /qa_private_kv.py
Tinghong-Ye22's picture
Add files using upload-large-folder tool
06f9561 verified
Raw History Blame Contribute Delete
3.65 kB
"""Private QA-branch contracts for the isolated SWA checkpoint.
The formal action model deliberately does not import or apply this adapter:
its forward path has no video tensors or answer-text loss. This module gives
the future multimodal runtime a strict, cheap validation boundary and avoids
the dangerous alternative of silently treating an incompatible QA checkpoint
as an action checkpoint.
"""
from __future__ import annotations
import hashlib
from dataclasses import dataclass
from pathlib import Path
from typing import Any, Mapping
QA_LORA_SHA256 = "259d4df38622f10effb532e7f5213b322252b564eb3dc6a97508c220a972a681"
@dataclass(frozen=True)
class QAPrivateKVConfig:
"""Configuration for a side QA branch, never for the action KV."""
enabled: bool = False
checkpoint: str = ""
expected_sha256: str = QA_LORA_SHA256
layers: int = 8
rank: int = 16
alpha: float = 16.0
targets: str = "full"
max_pending_packets: int = 2
def validate(self) -> "QAPrivateKVConfig":
if self.layers <= 0 or self.rank <= 0:
raise ValueError("QA LoRA layers and rank must be positive")
if self.alpha <= 0:
raise ValueError("QA LoRA alpha must be positive")
if self.targets not in {"qv", "attention", "full"}:
raise ValueError(f"Unsupported QA LoRA target profile: {self.targets}")
if self.max_pending_packets < 1:
raise ValueError("max_pending_packets must be positive")
if self.enabled and not self.checkpoint:
raise ValueError("An enabled private QA branch requires a checkpoint")
return self
def sha256_file(path: str | Path, *, chunk_bytes: int = 1 << 20) -> str:
"""Hash a checkpoint without loading it into memory."""
digest = hashlib.sha256()
with Path(path).expanduser().open("rb") as handle:
while True:
chunk = handle.read(chunk_bytes)
if not chunk:
break
digest.update(chunk)
return digest.hexdigest()
def validate_qa_checkpoint(
path: str | Path,
*,
expected_sha256: str | None = QA_LORA_SHA256,
) -> dict[str, Any]:
"""Validate existence, digest and flat LoRA tensor-key contract.
Loading is intentionally deferred to the actual multimodal runtime. The
returned metadata is sufficient for startup checks and provenance logs.
"""
resolved = Path(path).expanduser().resolve()
if not resolved.is_file():
raise FileNotFoundError(f"QA LoRA checkpoint is missing: {resolved}")
digest = sha256_file(resolved)
if expected_sha256 and digest != expected_sha256:
raise RuntimeError(
"QA LoRA checkpoint SHA256 mismatch: "
f"expected={expected_sha256} actual={digest} path={resolved}"
)
tensor_count = None
try:
import torch
state = torch.load(resolved, map_location="cpu", weights_only=True)
if not isinstance(state, Mapping):
raise TypeError(f"expected mapping, got {type(state).__name__}")
keys = tuple(str(key) for key in state)
if not keys or any(
not (key.endswith(".down.weight") or key.endswith(".up.weight"))
for key in keys
):
raise ValueError("expected flat '<index>.down/up.weight' LoRA keys")
tensor_count = len(keys)
except ImportError:
# The validator remains usable in a CPU-only metadata environment.
pass
return {
"path": str(resolved),
"sha256": digest,
"tensor_count": tensor_count,
"private_kv": True,
"writes_main_action_kv": False,
}