import { createReadStream } from 'fs';
import { join } from 'path';
import { LlamaContext, LlamaModel } from 'llama-cpp-node';

interface BenchmarkConfig {
  modelPath: string;
  prompt: string;
  maxTokens: number;
  contextSize: number;
  threads: number;
}

async function runDecodeBenchmark(config: BenchmarkConfig) {
  const model = await LlamaModel.load({ modelPath: config.modelPath });
  const context = await model.createContext({
    contextSize: config.contextSize,
    threads: config.threads,
    gpuLayers: -1, // Offload all layers to VRAM
  });

  const session = context.createSession();
  const startTime = performance.now();
  let tokenCount = 0;

  await session.evaluate(config.prompt, {
    onToken: (tokens) => {
      tokenCount += tokens.length;
    }
  });

  const elapsed = (performance.now() - startTime) / 1000;
  const throughput = tokenCount / elapsed;

  console.log(`[BENCHMARK] Tokens: ${tokenCount} | Duration: ${elapsed.toFixed(2)}s | Throughput: ${throughput.toFixed(1)} t/s`);
  
  await session.dispose();
  await context.dispose();
  return throughput;
}

export { runDecodeBenchmark, BenchmarkConfig };

tation uses llama-cpp-node to measure raw decode speed. The onToken callback captures generation rate without blocking the event loop. By forcing full GPU offloading (gpuLayers: -1), the benchmark isolates VRAM bandwidth from PCIe transfer overhead.

Step 2: Memory Subsystem Analysis

Hardware selection must prioritize three metrics: memory type, bus width, and effective clock speed. Bandwidth is calculated as: Bandwidth = (Bus Width / 8) × Memory Clock × Transfers Per Cycle

GDDR6X uses PAM4 signaling to achieve 2 transfers per clock cycle, while HBM stacks use a 1024-bit bus with lower clocks but massive parallelism. When comparing cards, verify the effective bandwidth in the manufacturer's technical reference manual. Do not rely on marketing summaries. A 384-bit GDDR6X interface at 21 Gbps yields ~1,008 GB/s. A 320-bit interface at 19 Gbps yields ~760 GB/s. The 32% difference directly translates to decode speed variance.

Step 3: Runtime Configuration for Bandwidth Efficiency

Inference engines must be tuned to minimize redundant memory fetches. Key architectural decisions include:

• Quantization Strategy: Q4_K_M reduces weight size by ~75% compared to FP16, dramatically lowering bandwidth pressure per token. The accuracy trade-off is negligible for most conversational workloads. Avoid Q2 or Q3 quantization unless bandwidth is severely constrained, as accuracy degradation compounds with context length.
• Context Window Sizing: Larger contexts increase KV cache memory footprint, which competes with weight streaming for bandwidth. Set contextSize to the minimum required for your use case. For single-turn APIs, 2,048–4,096 tokens is optimal. For multi-turn agents, implement sliding window eviction to cap memory growth.
• Batch Size Limitation: Decode bandwidth does not scale linearly with batch size. Each additional sequence in a batch requires independent KV cache lookups, multiplying memory requests. Keep batch sizes ≤ 4 for interactive workloads. Use continuous batching or speculative decoding if higher throughput is required.

Step 4: PCIe and Topology Validation

Memory bandwidth is only accessible if the GPU can communicate with the host without bottlenecking. Verify PCIe lane allocation. Consumer motherboards often split x16 slots into x8/x8 or x8/x4/x4 configurations. An RTX 4090 running at PCIe 4.0 x8 loses ~50% of host-to-device bandwidth, which impacts model loading and offloading fallbacks. Use lspci or nvidia-smi to confirm link width and speed. For multi-GPU setups, ensure NVLink or PCIe switch topology matches the inference engine's tensor parallelism requirements.

Pitfall Guide

1. VRAM-First Sizing Fallacy

Explanation: Selecting GPUs based solely on capacity leads to purchasing cards with narrow memory buses. A 24GB card with 672 GB/s bandwidth will generate tokens 40% slower than a 16GB card with 1,000 GB/s bandwidth. Fix: Calculate required VRAM for your target model + context, then select the highest bandwidth option that meets or exceeds that threshold. Use bandwidth-to-VRAM ratio as the primary procurement metric.

2. Ignoring Memory Bus Width and Type

Explanation: Not all VRAM is equal. GDDR6, GDDR6X, and HBM2e have different latency profiles and bandwidth ceilings. A card with 24GB GDDR6 may underperform a 16GB GDDR6X card due to signaling efficiency. Fix: Cross-reference technical datasheets for effective bandwidth (GB/s), not just capacity. Prioritize GDDR6X for consumer builds and HBM for datacenter deployments.

3. Context Window Overprovisioning

Explanation: Setting contextSize to 8,192 or 16,384 tokens by default inflates KV cache memory usage. The additional cache entries compete with weight streaming for bandwidth, reducing decode speed by 15–30%. Fix: Profile actual prompt/response lengths in your workload. Configure context windows to 1.5× the 95th percentile length. Implement cache eviction policies for long-running sessions.

4. PCIe Lane Sharing Bottlenecks

Explanation: Motherboards with multiple M.2 slots or secondary GPUs often downgrade primary PCIe slots to x8 or x4. This restricts host-to-GPU transfer rates, causing stalls during model loading and CPU offloading fallbacks. Fix: Verify slot configuration in BIOS/UEFI. Use lspci -vv | grep -i width to confirm active link width. Reserve x16 slots exclusively for primary inference accelerators.

5. Thermal Throttling and Sustained Bandwidth

Explanation: Consumer GPUs with blower or compact coolers throttle memory clocks under sustained decode loads. Bandwidth drops 10–20% after 10–15 minutes of continuous generation, causing unpredictable latency spikes. Fix: Monitor nvidia-smi for memory clock throttling. Implement workload pacing or deploy cards with vapor chamber/flow-through cooling for production environments.

6. Quantization Mismatch

Explanation: Using FP16 or Q8_0 quantization on bandwidth-constrained hardware forces the memory subsystem to stream double the data per token. This negates the benefits of high-bandwidth VRAM and increases power draw. Fix: Default to Q4_K_M or Q5_K_M for 7B–13B models. Reserve higher precision for embedding models or tasks requiring strict numerical stability.

7. Assuming Linear Batch Scaling

Explanation: Increasing batch size from 1 to 8 does not multiply throughput by 8. Memory bandwidth becomes the hard ceiling, and KV cache allocation causes diminishing returns after batch size 4. Fix: Benchmark batch sizes incrementally. Cap interactive batches at 2–4. Use continuous batching frameworks (vLLM, TGI) for API servers to maximize bandwidth utilization without manual tuning.

Production Bundle

Action Checklist

• Verify target model VRAM requirement + 20% overhead for KV cache
• Cross-reference GPU technical datasheets for effective memory bandwidth (GB/s)
• Run baseline decode benchmark with full GPU offloading enabled
• Configure context window to 1.5× observed 95th percentile token length
• Validate PCIe link width and speed using system diagnostics
• Apply Q4_K_M or Q5_K_M quantization for 7B–13B parameter models
• Monitor memory clock stability under sustained decode load for 15+ minutes
• Implement batch size caps and continuous batching for API endpoints

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Interactive Chat API	16–24GB GDDR6X, ≥900 GB/s	Balances capacity for context with high decode throughput	Moderate hardware cost, low latency
Batch Embedding Generation	24–48GB GDDR6, compute-focused	Prefill phase is compute-bound; bandwidth less critical	Lower bandwidth tolerance acceptable
Multi-Agent Orchestration	40–80GB HBM, ≥1.5 TB/s	High concurrency requires massive KV cache + streaming speed	High capital expenditure, scales linearly
Edge/On-Device Deployment	8–12GB LPDDR5X, optimized quantization	Power constraints limit bandwidth; Q3_K_M reduces footprint	Low cost, requires aggressive optimization

Configuration Template

# inference-config.yaml
model:
  path: "/models/llama-3-8b-instruct-q4_k_m.gguf"
  gpu_layers: -1
  context_size: 2048
  batch_size: 2
  threads: 8

performance:
  max_tokens: 512
  temperature: 0.7
  top_p: 0.9
  cache_eviction: sliding_window
  cache_window_size: 1024

monitoring:
  enable_throughput_logging: true
  log_interval_seconds: 5
  thermal_threshold_celsius: 85
  throttle_on_memory_clock_drop: true

hardware:
  require_min_bandwidth_gbs: 900
  verify_pcie_width: "x16"
  allow_cpu_offload: false

Quick Start Guide

1. Install Runtime: Deploy llama-cpp-node or llama-cpp-python with CUDA/Metal acceleration enabled. Verify GPU detection with nvidia-smi or metalinfo.
2. Download Quantized Model: Fetch a Q4_K_M GGUF variant of your target model. Ensure file integrity with SHA-256 checksums.
3. Apply Configuration: Copy the provided YAML template, adjust context_size and batch_size to match your workload profile, and set gpu_layers: -1.
4. Run Baseline Benchmark: Execute the TypeScript benchmark script. Record tokens-per-second and verify memory clock stability.
5. Deploy to Service: Wrap the inference engine in a FastAPI or Express server. Implement request queuing and batch aggregation. Monitor throughput metrics and adjust context windows based on real-world token distribution.