popov/neuron-tai
1
0
Fork 0
Code Issues 42 Pull Requests Actions Packages Projects Releases Wiki Activity

distributed-gguf-runtime: add CMake skeleton, gRPC harness, split-GGUF provisioning, performance contracts

Browse Source 
DGR-019  Lock alpha/beta performance contracts (evidence + contract framework)
DGR-020  Run controlled whole-model GGUF baseline (benchmark results & contracts)
DGR-024  Real generated-gRPC protocol harness (shard_runtime_server.py + tests)
DGR-026  split-GGUF provisioning outside /home (provision script + manifest + tests)
DGR-028  Numbered patch-stack apply & verify (llama_cpp_dependency.py + UPSTREAM_LOCK.json)
DGR-029  Native CMake skeleton + deterministic CPU lane (UPSTREAM_LOCK.json + cmake gating)

New modules:
  packages/node/meshnet_node/dgr_performance/  — performance contract framework
  packages/node/meshnet_node/split_gguf/        — split-GGUF manifest & provisioning
  scripts/provision_split_gguf.py               — artifact provisioning CLI
  tests/test_dgr_performance_contract.py        — contract validation tests
  tests/test_split_gguf_manifest.py             — manifest tests
  tests/test_split_gguf_provision.py            — provisioning tests
  tests/test_shard_runtime_harness.py           — gRPC harness tests
This commit is contained in:
Dobromir Popov
2026-07-23 09:55:00 +03:00
parent 47bad0b7e1
commit 966aa10854
36 changed files with 7225 additions and 374 deletions
Download Patch File Download Diff File Expand all files Collapse all files

287
packages/node/meshnet_node/dgr_performance/data/alpha-beta-contract-v1.json Normal file
View File

@@ -0,0 +1,287 @@
{
"schema_version": 1,
"contract_version": 1,
"contract_id": "dgr-alpha-beta-performance/v1",
"locked_at": "2026-07-22",
"locked_by": "DGR-019",
"locked_before_target_execution": true,
"prompt_set": {
"id": "dgr-fixed-prompt-set-v1",
"prompts": [
{
"id": "short-instruction",
"text": "Summarize the following changelog entry in one sentence: Added distributed layer-range execution for GGUF shards using range-aware tensor ownership.",
"context_class": "short"
},
{
"id": "code-completion",
"text": "def fibonacci(n):\n \"\"\"Return the nth Fibonacci number.\"\"\"\n",
"context_class": "short"
},
{
"id": "multi-step-reasoning",
"text": "A route has three shards, each holding a contiguous layer range. If shard A owns layers 0-13, shard B owns layers 14-27, and shard C owns layers 28-42, how many layers does each shard own and which shard is the tail?",
"context_class": "short"
},
{
"id": "long-context-fill",
"text": "Repeat the phrase 'the route holds a contiguous layer range' 1024 times, then answer: which node owns the tail?",
"context_class": "long",
"notes": "Beta long-context lane only; the driver expands this template to the locked context_tokens length rather than the literal text carrying that many tokens in this document."
}
]
},
"sampling": {
"temperature": 0.0,
"top_p": 1.0,
"top_k": 1,
"seed": 1234,
"notes": "Greedy by construction, matching meshnet_node.recipe_benchmark.SamplingPolicy defaults: sampling noise must never be indistinguishable from a quantization, transport, or batching effect."
},
"lanes": {
"controlled-safetensors": {
"role": "reference recipe",
"locked_elsewhere": true,
"contract_module": "meshnet_node.performance_contract",
"contract_id": "dgr-001-controlled-whole-model-baseline-v1",
"contract_schema_version": 1,
"notes": "Already locked by DGR-001/performance_contract.py (contract_version=1, immutable ContractThresholds). This document does not re-lock or duplicate those thresholds; it references them so the four lanes are enumerated in one place."
},
"whole-model-gguf": {
"role": "single-node quantization/model-fit comparison against controlled-safetensors",
"locked_elsewhere": true,
"contract_module": "meshnet_node.performance_contract",
"contract_id": "dgr-001-controlled-whole-model-baseline-v1",
"contract_schema_version": 1,
"notes": "Same locked contract as controlled-safetensors; this is the reference recipe's counterpart lane, not a separate threshold set."
},
"dense-distributed-gguf": {
"role": "multi-shard Meshnet Inference Route running a dense (non-MoE) architecture's GGUF weights across a real multi-machine route via the ShardEngine/native worker",
"reference_baseline": "the existing production Meshnet distributed Route Session running the same dense model over safetensors on the same node topology and network",
"prompt_ids": [
"short-instruction",
"code-completion",
"multi-step-reasoning"
],
"context_tokens": 2048,
"output_tokens": 128,
"concurrency_levels": [
1,
4
],
"hardware": {
"topology": "named certification scenario only: 2-4-stage or 10-plus-stage real multi-machine route",
"network": "same LAN/WAN class as the existing production route it is compared against",
"device_class": "generic; not hardcoded to one backend. CPU/CUDA/ROCm/Vulkan/Metal lanes are certified separately per RALPH-CONTEXT.md and only advertised once real-hardware-certified"
},
"metrics": [
"ttft_p50_ms",
"ttft_p95_ms",
"prefill_tokens_per_sec",
"decode_tokens_per_sec",
"aggregate_decode_tokens_per_sec",
"latency_p50_ms",
"latency_p95_ms",
"seam_bytes",
"seam_latency_ms",
"queue_wait_ms",
"peak_rss_bytes",
"peak_vram_bytes",
"failures"
],
"certification_scenarios": {
"stage_count": [
"2-4-stage",
"10-plus-stage"
],
"quantization": [
"Q4_K_M",
"Q8_0",
"bf16-reference"
]
}
},
"v4-flash-distributed": {
"role": "full DeepSeek V4 Flash (43 main layers plus reserved MTP; mHC 4x4096 boundary; 256 routed + 1 shared experts, six routed active) distributed route across a named certification stage-count scenario, MTP reserved and off",
"reference_baseline": "the existing production Meshnet distributed Route Session running DeepSeek V4 Flash over safetensors on the same node topology and network, where available; otherwise dense-distributed-gguf runtime/transport overhead is reported as an explicit limitation until DGR-044 pins a safetensors V4 baseline",
"prompt_ids": [
"short-instruction",
"code-completion",
"multi-step-reasoning"
],
"alpha_context_tokens": 4096,
"alpha_output_tokens": 128,
"alpha_concurrency_levels": [
1,
4
],
"beta_context_tokens": 16384,
"beta_output_tokens": 512,
"beta_concurrency_levels": [
1,
4,
8,
16
],
"beta_prompt_ids": [
"short-instruction",
"code-completion",
"multi-step-reasoning",
"long-context-fill"
],
"hardware": {
"topology": "named certification scenario only: 2-4-stage or 10-plus-stage real multi-machine route",
"network": "same LAN/WAN class as the existing production route it is compared against",
"device_class": "generic; not hardcoded to one backend. CPU/CUDA/ROCm/Vulkan/Metal lanes are certified separately per RALPH-CONTEXT.md and only advertised once real-hardware-certified",
"mtp": "reserved and off for alpha; ownership contract, implementation, and benchmark are required before beta per RALPH-CONTEXT.md"
},
"metrics": [
"ttft_p50_ms",
"ttft_p95_ms",
"prefill_tokens_per_sec",
"decode_tokens_per_sec",
"aggregate_decode_tokens_per_sec",
"latency_p50_ms",
"latency_p95_ms",
"seam_bytes",
"seam_latency_ms",
"queue_wait_ms",
"peak_rss_bytes",
"peak_vram_bytes",
"failures",
"mtp_enabled"
],
"certification_scenarios": {
"stage_count": [
"2-4-stage",
"10-plus-stage"
],
"quantization": [
"Q4_K_M",
"Q8_0",
"bf16-reference"
]
}
}
},
"gain_attribution": {
"quantization_model_fit_metrics": [
"resident_memory_ratio",
"artifact_size_ratio",
"exact_match_rate",
"mean_similarity",
"peak_rss_bytes",
"peak_vram_bytes"
],
"runtime_transport_batching_kernel_metrics": [
"decode_speedup",
"ttft_ratio",
"aggregate_throughput_speedup",
"seam_bytes",
"seam_latency_ms",
"queue_wait_ms",
"prefill_tokens_per_sec"
],
"rule": "A speed or fit claim must cite which axis moved it: a quantization/model-fit change (recipe swap, weight format) or a runtime/transport/batching/kernel change (ShardEngine, gRPC transport, batching, GGML kernel). A distributed-lane win may not be attributed to quantization when the reference recipe already used the same quantization, and a quantization win may not be attributed to distribution or transport."
},
"certification_scenarios": {
"quantization": {
"names": [
"Q4_K_M",
"Q8_0",
"bf16-reference"
],
"rule": "Named certification-scenario labels only. No product or runtime code path may branch on, default to, or hardcode a specific quantization string; quantization is a dynamic recipe input per RALPH-CONTEXT.md."
},
"stage_count": {
"names": [
"2-4-stage",
"10-plus-stage"
],
"rule": "Named certification-scenario labels only, matching DGR-053/DGR-061/DGR-062/DGR-067. No product or runtime code path may hardcode a stage-count range or assume exactly one of these layouts."
}
},
"alpha": {
"applies_to_lane": "v4-flash-distributed",
"reference_baseline_lane": "dense-distributed-gguf",
"correctness": {
"min_greedy_token_agreement": 0.9,
"min_mean_state_cosine_similarity": 0.999,
"forbid_nonfinite_tensors": true,
"require_fail_closed_on_fingerprint_mismatch": true,
"require_active_moe_routing": true,
"require_active_hash_routing_first_three_layers": true,
"dense_attention_fallback_satisfies_alpha": false
},
"useful_speed": {
"min_decode_speedup_vs_reference_baseline": 1.25,
"max_ttft_ratio_vs_reference_baseline": 1.25,
"min_aggregate_throughput_speedup_at_top_concurrency": 1.25,
"quality_pass_with_speed_fail_verdict": "stop",
"human_approval": {
"required": true,
"approved": false,
"approved_by": null,
"approved_at": null,
"approval_note": "The ratios above are the proposed useful-speed floor, held at the same 25% margin already locked for the whole-model contract (DGR-001/v1, meshnet_node.performance_contract.ContractThresholds). Alpha certification (DGR-054) may not treat useful-speed as satisfied on ratios alone: a human must explicitly approve the observed ratio against real DGR-020/dense/V4 evidence, and this record is the audit trail for that approval."
}
},
"mtp": {
"reserved": true,
"enabled_for_alpha": false,
"ownership_contract_and_benchmark_required_before_beta": true
},
"failure_tolerance": {
"max_failure_rate": 0.0
},
"verdicts": [
"alpha",
"optimize",
"stop"
],
"stop_condition": "Stop DeepSeek V4 Flash alpha certification when correctness fails (greedy token agreement, mean state cosine similarity, nonfinite tensors, or fail-closed fingerprint checks), or when useful-speed is not both numerically satisfied and explicitly human-approved against the reference baseline lane under this plan. A quality pass with a speed fail is always 'stop', never 'optimize' — see performance.quality_pass_with_speed_fail_verdict."
},
"beta": {
"applies_to_lane": "v4-flash-distributed",
"adds": [
"concurrency",
"long_context",
"failure",
"sustained_throughput"
],
"concurrency": {
"levels": [
1,
4,
8,
16
],
"min_aggregate_throughput_speedup_at_max_concurrency": 1.25,
"max_fairness_deviation": 0.2
},
"long_context": {
"context_tokens": 16384,
"min_greedy_token_agreement": 0.9,
"max_ttft_seconds_at_context": 600
},
"failure": {
"consecutive_clean_cold_starts": 2,
"require_worker_loss_aborts_route": true,
"require_cache_miss_and_reprefill_on_route_change": true,
"forbid_silent_kv_migration": true,
"synthetic_workers_satisfy_beta": false
},
"sustained_throughput": {
"min_duration_minutes": 30,
"max_throughput_degradation_ratio": 0.1
},
"verdicts": [
"beta",
"targeted-optimization",
"stop-rollback"
],
"stop_condition": "Stop or roll back DeepSeek V4 Flash beta when any beta-only threshold fails (concurrency fairness/throughput, long-context correctness or TTFT, failure-recovery semantics, or sustained-throughput degradation), when a required stage-count or quantization certification scenario has no real-hardware evidence, or when MTP evidence is missing given MTP is required before beta per RALPH-CONTEXT.md."
},
"amendment_policy": "Thresholds are locked before target execution and may not be weakened, moved, or reinterpreted after results are known. A change requires a new contract_id and contract_version under human review, and the superseded contract is retained. This applies independently of alpha.useful_speed.human_approval, which records sign-off on an observed ratio against these unchanged thresholds, not a change to the thresholds themselves.",
"contract_sha256": "cb5a482a8f142bf45b1dd401743d408acbfe5f85bab86023144a8c9485ac6379"
}