node-llama-cpp

环境要求

• Node.js 环境（需能使用 npm / npx）
• 支持 macOS、Linux 或 Windows 系统
• 模型需为 GGUF 格式文件
• 若平台无预编译二进制，需要 cmake 以便从源码构建（不需要 node-gyp 或 Python）

安装与启动步骤

1. 1免安装试用

   不写任何代码，直接在终端用 npx 启动内置 CLI 与模型对话，适合先验证环境是否可用。首次执行会联网拉取包。

   npx -y node-llama-cpp chat

   复制

2. 2安装依赖包

   在项目目录中把 node-llama-cpp 安装为依赖。包内自带 macOS、Linux、Windows 的预编译二进制。

   npm install node-llama-cpp

   复制

3. 3准备 GGUF 模型

   在项目下建 models 目录并放入 GGUF 模型文件。README 示例使用的是 Meta-Llama-3.1-8B-Instruct.Q4_K_M.gguf，路径需与代码一致。

4. 4编写调用脚本

   创建入口文件，用 getLlama 加载模型、创建上下文与 LlamaChatSession，再调用 session.prompt 提问。

   import {fileURLToPath} from "url";
   import path from "path";
   import {getLlama, LlamaChatSession} from "node-llama-cpp";
   
   const __dirname = path.dirname(fileURLToPath(import.meta.url));
   
   const llama = await getLlama();
   const model = await llama.loadModel({
       modelPath: path.join(__dirname, "models", "Meta-Llama-3.1-8B-Instruct.Q4_K_M.gguf")
   });
   const context = await model.createContext();
   const session = new LlamaChatSession({
       contextSequence: context.getSequence()
   });
   
   const q1 = "Hi there, how are you?";
   console.log("User: " + q1);
   
   const a1 = await session.prompt(q1);
   console.log("AI: " + a1);
   
   const q2 = "Summarize what you said";
   console.log("User: " + q2);
   
   const a2 = await session.prompt(q2);
   console.log("AI: " + a2);

   复制

5. 5运行脚本验证

   用 Node.js 执行你的入口文件，终端会先打印用户提问、再打印模型回答；首次加载模型会稍慢。

   node index.js

   复制

关键配置

如何确认成功

执行 npx -y node-llama-cpp chat 能进入终端对话，或脚本成功打印出 AI 的回复内容。

常见问题

注意事项

• 模型必须是 GGUF 格式，示例路径为 models/Meta-Llama-3.1-8B-Instruct.Q4_K_M.gguf。
• 示例代码使用 ESM 的 import 语法，node-llama-cpp 为 TypeScript 编写的库，提供类型安全 API。
• CLI 还支持更新 llama.cpp：用单条 CLI 命令下载并编译最新 release（详见官方构建文档）。