node-llama-cpp

在您的本地机器上运行 AI 模型

_{提供预编译的绑定，并支持回退到使用 CMake 从源码构建}

✨ gpt-oss 已发布！ ✨

特性

• 在本地机器上运行大语言模型
• 支持 Metal、CUDA 和 Vulkan 显卡加速
• 提供预编译二进制文件，同时支持不依赖 node-gyp 或 Python 的源码构建
• 自动适配您的硬件配置，无需任何额外设置
• 完整的工具集，满足您在项目中使用大语言模型的所有需求
• 可通过命令行与模型对话，无需编写代码
• 始终保持与最新版 llama.cpp 同步。只需一条命令即可下载并编译最新版本
• 能够强制模型以可解析的格式生成输出，例如 JSON 格式，甚至可以指定特定的 JSON 模式
• 允许为模型提供可按需调用的函数，用于获取信息或执行操作
• 支持嵌入和重排序功能
• 具有防止特殊标记注入攻击的安全机制
• 提供出色的开发体验，全面支持 TypeScript，并配有完整的文档
• 更多功能……

文档

• 入门指南
• API 参考
• CLI 使用帮助
• 博客
• 变更日志
• 路线图

无需安装即可试用

您可以在终端中使用一条命令与模型对话：

npx -y node-llama-cpp chat

安装

npm install node-llama-cpp

此包为 macOS、Linux 和 Windows 提供了预编译的二进制文件。如果您的平台没有可用的二进制文件，则会自动下载 llama.cpp 的最新版本，并使用 CMake 进行编译。若要禁用此行为，请将环境变量 NODE_LLAMA_CPP_SKIP_DOWNLOAD 设置为 true。

使用示例

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 = "你好，最近怎么样？";
console.log("用户：" + q1);

const a1 = await session.prompt(q1);
console.log("AI：" + a1);


const q2 = "请总结一下你刚才说的话";
console.log("用户：" + q2);

const a2 = await session.prompt(q2);
console.log("AI：" + a2);

更多示例请参阅 入门指南

贡献

如需参与 node-llama-cpp 的开发，请阅读 贡献指南。

致谢

• llama.cpp：ggml-org/llama.cpp

如果您喜欢这个仓库，请给它点个赞 ✨                                                    

node-llama-cpp 快速上手指南

node-llama-cpp 是一个强大的 Node.js 库，允许你在本地机器上运行大型语言模型（LLM）。它基于 llama.cpp，支持 Metal (macOS)、CUDA (NVIDIA) 和 Vulkan，并能自动适配你的硬件。无需配置复杂的构建环境，开箱即用。

环境准备

• 操作系统：macOS、Linux 或 Windows。
• Node.js：建议安装最新的 LTS 版本。
• 前置依赖：
  • 该包默认提供预编译二进制文件，无需安装 Python、node-gyp 或 CMake 即可直接使用。
  • 仅当你的平台没有预编译文件时，它才会尝试使用 cmake 从源码构建（此时才需要安装 CMake）。
• 模型文件：你需要准备一个 .gguf 格式的模型文件（例如从 Hugging Face 下载）。

安装步骤

使用 npm 安装核心库：

npm install node-llama-cpp

提示：如果你在中国大陆遇到下载预编译二进制文件速度慢的问题，可以尝试配置网络代理，或者设置环境变量跳过自动下载（需手动处理），但在大多数网络环境下可直接安装。

基本使用

以下是一个最简单的聊天示例。请确保你已经在项目目录下准备了模型文件（例如 Meta-Llama-3.1-8B-Instruct.Q4_K_M.gguf）。

1. 创建一个 TypeScript 或 JavaScript 文件（例如 index.ts）。
2. 填入以下代码：

import {fileURLToPath} from "url";
import path from "path";
import {getLlama, LlamaChatSession} from "node-llama-cpp";

const __dirname = path.dirname(fileURLToPath(import.meta.url));

// 初始化 Llama 实例
const llama = await getLlama();

// 加载模型 (请替换为你本地的 .gguf 模型路径)
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);

3. 运行你的代码（确保你的 package.json 中设置了 "type": "module" 或使用 .mjs 后缀）：

node index.ts
# 或者如果使用 tsx
npx tsx index.ts

免安装体验 (CLI)

如果你只想快速测试某个模型而不想写代码，可以直接使用 npx 运行命令行工具：

npx -y node-llama-cpp chat

运行后按照提示选择或输入模型路径即可开始终端聊天。