Llama Sidecar

English | 简体中文

一个围绕 llama.cpp 的 llama-server 和 llama-cli 封装的轻量 TypeScript 工具。

llama-sidecar 可以帮助 Node.js 应用：

• 在安装阶段下载匹配的 llama-server 二进制
• 在安装阶段下载匹配的 llama-cli 二进制
• 通过代码启动和停止 llama-server
• 通过方法调用 llama-cli 并返回生成结果
• 用类型化参数代替手写命令行 argv
• 在某些参数暂未封装时，通过 args 透传原始参数

当前状态

这个包现在已经可用，但整体还在持续演进中。

目前内置下载器支持的平台是：

• macOS arm64
• macOS x64

如果你已经有自己的 llama-server，可以设置 LLAMA_SERVER_PATH；如果你已经有自己的 llama-cli，可以设置 LLAMA_CLI_PATH。包会优先使用你指定的二进制文件，而不是内置下载版本。

安装

pnpm add llama-sidecar

安装时会执行 postinstall，自动把 llama-server 和 llama-cli 下载到包目录中。

如果你想手动下载，也可以执行：

pnpm exec llama-sidecar-download

你也可以通过 npm config 固定下载指定的 llama.cpp release：

npm_config_llama_sidecar_version=b612 pnpm add llama-sidecar

或者写到 .npmrc：

llama_sidecar_version=b612
llama_sidecar_github_mirror=https://your-mirror.example.com

快速开始

import { LlamaServer } from 'llama-sidecar'

const server = await LlamaServer.create()

const { url, pid } = await server.start({
  model: './models/Qwen3.5-0.8B.gguf',
  port: 8080,
  startupTimeout: 30_000,
})

console.log(url, pid)

await server.stop()

使用示例

启动本地模型

import { LlamaServer } from 'llama-sidecar'

const server = await LlamaServer.create()

await server.start({
  cwd: process.cwd(),
  model: './models/Qwen3.5-0.8B/Qwen3.5-0.8B-UD-IQ2_XXS.gguf',
  ctxSize: 8192,
  nGpuLayers: 'auto',
  chatTemplateKwargs: {
    enable_thinking: false,
  },
})

直接从 Hugging Face 启动

import { LlamaServer } from 'llama-sidecar'

const server = await LlamaServer.create()

await server.start({
  hfRepo: 'mradermacher/tinyllama-15M-GGUF',
  hfFile: 'tinyllama-15M.IQ4_XS.gguf',
  port: 8210,
})

透传原始 llama-server 参数

当 llama.cpp 新增了参数，而 llama-sidecar 还没来得及提供类型字段时，可以直接使用 args：

await server.start({
  model: './models/model.gguf',
  args: ['--no-context-shift', '--metrics'],
})

调用 llama-cli 并返回结果

import { llamaChat } from 'llama-sidecar'

const chat = await llamaChat.create()

const result = await chat.chat({
  model: './models/Qwen3.5-0.8B.gguf',
  prompt: '用一句话介绍你自己',
  args: ['--simple-io'],
})

console.log(result.output)

API

LlamaServer.create()

创建实例，并在创建时验证 llama-server 二进制是否可运行。

llamaChat.create()

创建实例，并在创建时验证 llama-cli 二进制是否可运行。

chat.chat(options)

执行一次 llama-cli 调用，并把捕获到的输出作为方法返回值交给你，而不是直接打印到当前终端。

返回值：

{
  output: string
  stdout: string
  stderr: string
  exitCode: number
}

server.start(options)

启动 llama-server，只有在进程真正输出 ready 日志后才会 resolve。

返回值：

{
  url: string
  pid: number | undefined
}

几个比较重要的 sidecar 自身参数：

• cwd：用于解析相对路径，不会透传给 llama-server
• log：把 llama-server 的 stderr 转发到当前进程 stderr
• startupTimeout：在规定时间内没有 ready 就判定启动失败
• args：在类型化参数后追加原始 argv

server.stop(timeout?)

优雅停止服务。会先发 SIGTERM，如果超时仍未退出，再升级为 SIGKILL。

server.restart(options)

如果当前进程正在运行，会先停止，再按新的参数重新启动。

server.version()

返回 llama-server --version 输出中的最后两行。

server.help()

返回 llama-server --help 的输出内容。

状态访问器

• server.pid：当前子进程 pid
• server.status：stopped、starting、running、stopping 之一
• server.isRunning：当前是否已经完成启动且进程仍然存活

路径解析规则

在真正启动 llama-server 之前，常见的路径类参数会先基于 cwd 转成绝对路径。

包括但不限于：

• model
• lora
• loraScaled
• controlVector
• controlVectorScaled
• jsonSchemaFile
• mmproj
• slotSavePath
• mediaPath

如果 host 以 .sock 结尾，也会按 cwd 解析成绝对路径。

环境变量

• LLAMA_SERVER_PATH：指定现成的 llama-server 路径
• LLAMA_CLI_PATH：指定现成的 llama-cli 路径
• HF_TOKEN：访问需要鉴权的 Hugging Face 模型时由 llama-server 使用
• npm_config_llama_sidecar_version：安装时固定下载某个 release
• npm_config_llama_sidecar_github_mirror：安装时使用下载镜像

常见问题

llama-server binary file not found or not executable

可以先执行：

pnpm exec llama-sidecar-download

或者显式指定二进制路径：

export LLAMA_SERVER_PATH=/absolute/path/to/llama-server

启动卡住或超时

建议依次检查：

• 开启 log: true，先看 llama-server stderr 输出
• 适当增大 startupTimeout
• 确认模型路径是不是相对于 cwd 写对了
• 先执行 await server.help() 或 await server.version()，确认二进制本身可用

需要透传暂未支持的 llama-server 参数

直接使用 args，把原始 argv 传进去即可。

本地开发

pnpm install
pnpm test -- --run
pnpm build