fix: add helpful messages about solutions to CUDA issues

Author: giladgd

docs/guide/CUDA.md

@@ -156,6 +156,11 @@ ldd ./node_modules/@node-llama-cpp/linux-x64-cuda/bins/linux-x64-cuda/libggml-cu
 
 ::::
 
+### Fix the `ggml_cuda_init: failed to initialize CUDA: (null)` Error {#fix-failed-to-initialize-cuda-null}
+This error usually happens when the NVIDIA drivers installed on your machine are incompatible with the version of CUDA you have installed.
+
+To fix it, update your NVIDIA drivers to the latest version from the [NVIDIA Driver Downloads](https://www.nvidia.com/en-us/drivers/) page.
+
 
 ## Using `node-llama-cpp` With CUDA
 It's recommended to use [`getLlama`](../api/functions/getLlama) without specifying a GPU type,

src/bindings/Llama.ts

@@ -11,7 +11,10 @@ import {LlamaGrammar, LlamaGrammarOptions} from "../evaluator/LlamaGrammar.js";
 import {ThreadsSplitter} from "../utils/ThreadsSplitter.js";
 import {getLlamaClasses, LlamaClasses} from "../utils/getLlamaClasses.js";
 import {BindingModule} from "./AddonTypes.js";
-import {BuildGpu, BuildMetadataFile, LlamaGpuType, LlamaLocks, LlamaLogLevel, LlamaLogLevelGreaterThanOrEqual, LlamaNuma} from "./types.js";
+import {
+    BuildGpu, BuildMetadataFile, LlamaGpuType, LlamaLocks, LlamaLogLevel,
+    LlamaLogLevelGreaterThan, LlamaLogLevelGreaterThanOrEqual, LlamaNuma
+} from "./types.js";
 import {MemoryOrchestrator, MemoryReservation} from "./utils/MemoryOrchestrator.js";
 
 export const LlamaLogLevelToAddonLogLevel: ReadonlyMap<LlamaLogLevel, number> = new Map([
@@ -41,6 +44,7 @@ export class Llama {
     /** @internal */ public readonly _swapOrchestrator: MemoryOrchestrator;
     /** @internal */ public readonly _debug: boolean;
     /** @internal */ public readonly _threadsSplitter: ThreadsSplitter;
+    /** @internal */ public _hadErrorLogs: boolean = false;
     /** @internal */ private readonly _gpu: LlamaGpuType;
     /** @internal */ private readonly _numa: LlamaNuma;
     /** @internal */ private readonly _buildType: "localBuild" | "prebuilt";
@@ -470,6 +474,9 @@ export class Llama {
 
         this._previousLog = message;
         this._previousLogLevel = level;
+
+        if (!this._hadErrorLogs && LlamaLogLevelGreaterThan(level, LlamaLogLevel.error))
+            this._hadErrorLogs = true;
     }
 
     /** @internal */

src/bindings/types.ts

@@ -117,14 +117,23 @@ export const LlamaVocabularyTypeValues = Object.freeze([
 ] as const);
 
 /**
- *Check if a log level is higher than another log level
+ * Check if a log level is higher than another log level
+ * @example
+ * ```ts
+ * LlamaLogLevelGreaterThan(LlamaLogLevel.error, LlamaLogLevel.info); // true
+ * ```
  */
 export function LlamaLogLevelGreaterThan(a: LlamaLogLevel, b: LlamaLogLevel): boolean {
     return LlamaLogLevelValues.indexOf(a) < LlamaLogLevelValues.indexOf(b);
 }
 
 /**
- *Check if a log level is higher than or equal to another log level
+ * Check if a log level is higher than or equal to another log level
+ * @example
+ * ```ts
+ * LlamaLogLevelGreaterThanOrEqual(LlamaLogLevel.error, LlamaLogLevel.info); // true
+ * LlamaLogLevelGreaterThanOrEqual(LlamaLogLevel.error, LlamaLogLevel.error); // true
+ * ```
  */
 export function LlamaLogLevelGreaterThanOrEqual(a: LlamaLogLevel, b: LlamaLogLevel): boolean {
     return LlamaLogLevelValues.indexOf(a) <= LlamaLogLevelValues.indexOf(b);

src/cli/commands/inspect/commands/InspectGpuCommand.ts

@@ -153,6 +153,9 @@ export const InspectGpuCommand: CommandModule<object, InspectGpuCommand> = {
             } else {
                 console.info(`${chalk.yellow("CUDA:")} ${chalk.green("available")}`);
                 gpusToLogVramUsageOf.push("cuda");
+
+                if (llama._hadErrorLogs)
+                    console.info(chalk.yellow("To resolve errors related to CUDA, see the CUDA guide: ") + documentationPageUrls.CUDA);
             }
         }
 
@@ -165,6 +168,11 @@ export const InspectGpuCommand: CommandModule<object, InspectGpuCommand> = {
             } else {
                 console.info(`${chalk.yellow("Vulkan:")} ${chalk.green("available")}`);
                 gpusToLogVramUsageOf.push("vulkan");
+
+                if (llama._hadErrorLogs)
+                    console.info(
+                        chalk.yellow("To resolve errors related to Vulkan, see the Vulkan guide: ") + documentationPageUrls.Vulkan
+                    );
             }
         }