Merge pull request #6 from danielebarbaro/refactor/save

Enhancing Performance through Adaptive efConstruction and Streaming Serialization

Author: ezimuel

src/HNSW/Config.php

@@ -82,12 +82,14 @@ public function __construct(
         if ($M < 2) {
             throw new \InvalidArgumentException('M must be at least 2.');
         }
-        if ($efConstruction < $M) {
-            throw new \InvalidArgumentException('efConstruction must be ≥ M.');
+        $resolvedM0 = $M0 ?? ($M * 2);
+
+        if ($efConstruction < $resolvedM0) {
+            throw new \InvalidArgumentException("efConstruction must be ≥ M0 ({$resolvedM0}).");
         }
 
         $this->M = $M;
-        $this->M0 = $M0 ?? ($M * 2);
+        $this->M0 = $resolvedM0;
         $this->mL = $mL ?? (1.0 / log($M));
         $this->efConstruction = $efConstruction;
         $this->efSearch = $efSearch;

src/HNSW/Index.php

@@ -198,11 +198,25 @@ public function insert(Document $document): void
         }
 
         // Phase 2: from min(L, l) down to layer 0 — build connections.
+        //
+        // Adaptive efConstruction: scale with graph size so early inserts
+        // (where the graph is small and fewer candidates exist) use a lower
+        // beam width, ramping up to the configured maximum as the index grows.
+        // This avoids wasting cycles searching a sparse graph while preserving
+        // full recall quality at scale.
         for ($lc = min($this->maxLayer, $maxLayer); $lc >= 0; $lc--) {
             $mMax = $lc === 0 ? $this->config->M0 : $this->config->M;
 
-            // Find ef_construction nearest neighbours at this layer.
-            $W = $this->searchLayer($dv, [[$epDist, $ep]], $this->config->efConstruction, $lc);
+            // Compute adaptive efConstruction per-layer, ensuring it is at least
+            // the maximum desired degree for this layer (mMax). This guarantees
+            // that searchLayer() can return enough candidates to fill M0 on the
+            // base layer and M on upper layers, even during early inserts.
+            $efC = max(
+                $mMax,
+                min($this->config->efConstruction, (int) ($nodeId / 10))
+            );
+            // Find efConstruction nearest neighbours at this layer.
+            $W = $this->searchLayer($dv, [[$epDist, $ep]], $efC, $lc);
 
             // Select the best M neighbours using simple or heuristic strategy.
             $neighbours = $this->config->useHeuristic

src/Persistence/IndexSerializer.php

@@ -50,6 +50,10 @@ final class IndexSerializer
     /**
      * Write the HNSW graph state to $path.
      *
+     * Uses streaming fwrite() instead of buffer concatenation to avoid
+     * O(n²) memory copies. Each pack() result is written directly to
+     * disk, producing the same binary format with O(n) cost.
+     *
      * @param array{
      *   entryPoint: int|null,
      *   maxLayer: int,
@@ -64,27 +68,32 @@ public function writeHnsw(string $path, array $state): void
         $nodeCount = count($nodes);
         $ep        = $state['entryPoint'] ?? self::NULL_ENTRY_POINT;
 
-        $buf  = self::HNSW_MAGIC;
-        $buf .= pack('C', self::VERSION);
-        $buf .= pack('NNNN', $dim, $nodeCount, $ep, (int) $state['maxLayer']);
+        $fh = fopen($path, 'wb');
+        if ($fh === false) {
+            throw new \RuntimeException("Failed to open file for writing: {$path}");
+        }
 
-        foreach ($nodes as $nodeId => $node) {
-            $buf .= pack('NN', $nodeId, $node['maxLayer']);
-            if ($dim > 0) {
-                $buf .= pack('d*', ...$node['vector']);
-            }
-            for ($l = 0; $l <= $node['maxLayer']; $l++) {
-                $conns = $node['connections'][$l] ?? [];
-                $cnt   = count($conns);
-                $buf  .= pack('N', $cnt);
-                if ($cnt > 0) {
-                    $buf .= pack('N*', ...$conns);
+        try {
+            $this->checkedWrite($fh, self::HNSW_MAGIC);
+            $this->checkedWrite($fh, pack('C', self::VERSION));
+            $this->checkedWrite($fh, pack('NNNN', $dim, $nodeCount, $ep, (int) $state['maxLayer']));
+
+            foreach ($nodes as $nodeId => $node) {
+                $this->checkedWrite($fh, pack('NN', $nodeId, $node['maxLayer']));
+                if ($dim > 0) {
+                    $this->checkedWrite($fh, pack('d*', ...$node['vector']));
+                }
+                for ($l = 0; $l <= $node['maxLayer']; $l++) {
+                    $conns = $node['connections'][$l] ?? [];
+                    $cnt   = count($conns);
+                    $this->checkedWrite($fh, pack('N', $cnt));
+                    if ($cnt > 0) {
+                        $this->checkedWrite($fh, pack('N*', ...$conns));
+                    }
                 }
             }
-        }
-
-        if (file_put_contents($path, $buf) === false) {
-            throw new \RuntimeException("Failed to write hnsw.bin: {$path}");
+        } finally {
+            fclose($fh);
         }
     }
 
@@ -173,6 +182,8 @@ public function readHnsw(string $path): array
     /**
      * Write the BM25 inverted index to $path.
      *
+     * Streams directly to disk
+     *
      * @param array{
      *   totalTokens: int,
      *   docLengths: array<int, int>,
@@ -181,29 +192,34 @@ public function readHnsw(string $path): array
      */
     public function writeBm25(string $path, array $state): void
     {
-        $buf  = self::BM25_MAGIC;
-        $buf .= pack('C', self::VERSION);
-        $buf .= pack('N', $state['totalTokens']);
-
-        $docLengths = $state['docLengths'];
-        $buf .= pack('N', count($docLengths));
-        foreach ($docLengths as $nodeId => $length) {
-            $buf .= pack('NN', $nodeId, $length);
+        $fh = fopen($path, 'wb');
+        if ($fh === false) {
+            throw new \RuntimeException("Failed to open file for writing: {$path}");
         }
 
-        $invertedIndex = $state['invertedIndex'];
-        $buf .= pack('N', count($invertedIndex));
-        foreach ($invertedIndex as $term => $postings) {
-            $termBytes = (string) $term;
-            $buf .= pack('n', strlen($termBytes)) . $termBytes;
-            $buf .= pack('N', count($postings));
-            foreach ($postings as $postNodeId => $tf) {
-                $buf .= pack('NN', $postNodeId, $tf);
+        try {
+            $this->checkedWrite($fh, self::BM25_MAGIC);
+            $this->checkedWrite($fh, pack('C', self::VERSION));
+            $this->checkedWrite($fh, pack('N', $state['totalTokens']));
+
+            $docLengths = $state['docLengths'];
+            $this->checkedWrite($fh, pack('N', count($docLengths)));
+            foreach ($docLengths as $nodeId => $length) {
+                $this->checkedWrite($fh, pack('NN', $nodeId, $length));
             }
-        }
 
-        if (file_put_contents($path, $buf) === false) {
-            throw new \RuntimeException("Failed to write bm25.bin: {$path}");
+            $invertedIndex = $state['invertedIndex'];
+            $this->checkedWrite($fh, pack('N', count($invertedIndex)));
+            foreach ($invertedIndex as $term => $postings) {
+                $termBytes = (string) $term;
+                $this->checkedWrite($fh, pack('n', strlen($termBytes)) . $termBytes);
+                $this->checkedWrite($fh, pack('N', count($postings)));
+                foreach ($postings as $postNodeId => $tf) {
+                    $this->checkedWrite($fh, pack('NN', $postNodeId, $tf));
+                }
+            }
+        } finally {
+            fclose($fh);
         }
     }
 
@@ -278,4 +294,14 @@ public function readBm25(string $path): array
             'invertedIndex' => $invertedIndex,
         ];
     }
+
+    /**
+     * @param resource $fh
+     */
+    private function checkedWrite($fh, string $data): void
+    {
+        if (@fwrite($fh, $data) === false) {
+            throw new \RuntimeException("Failed to write data");
+        }
+    }
 }