QVAC SDK 完全指南：290⭐ 开源本地 AI 应用 SDK，跨平台 P2P 推理一包搞定
AI 推理的部署模式正在从「云端优先」转向「本地优先」。不管是隐私敏感的企业场景、无网络的离岸开发环境，还是不想被 SaaS 锁定的独立开发者，都需要一个能在本地跑通 LLM、语音、OCR 和 RAG 的统一 SDK。但本地 AI 碎片化严重——llama.cpp 只管推理，Whisper 只管语音，ONNX Runtime 只管模型转换……
QVAC（tetherto/qvac, 290⭐, Apache-2.0, TypeScript）是一套开源跨平台本地 AI 应用 SDK，覆盖 LLM 推理、文本嵌入、翻译、语音识别、TTS、OCR、图片生成、RAG 和 P2P 推理委派。更关键的是它的全栈架构：一个 npm install @qvac/sdk 就拿到了整个本地 AI 工具箱。
核心架构：Local-First + P2P 双引擎
QVAC 以 JavaScript SDK 为核心入口，运行在 Node.js、Bare 运行时和 Expo 移动端。它的架构分为三层：
应用层（SDK） — 统一的 @qvac/sdk 包，暴露 loadModel()、completion()、embed()、transcribe() 等顶层 API。全部 TypeScript 类型安全。
能力层（Addons） — 每项 AI 能力对应一个独立 C++ 或 JS addon：lib-infer-llamacpp-llm 做 LLM 推理，transcription-whispercpp 做语音转文字，diffusion-cpp 做图片生成。按需加载，不用的不占用系统资源。
基础设施层 — Hyperdrive 分布式文件系统用于模型分发，Holepunch P2P 栈用于节点发现和推理委派。模型可以从本地文件系统加载，也可以从 P2P 网络的 peer 下载。
这种分层设计的一个直接好处是：你可以在 MacBook 上本地推理 Llama 3.2 1B，同时通过 P2P 把更重的任务委派给办公室的 GPU 服务器。
安装与快速启动
QVAC SDK 是一个标准 npm 包，一行命令安装：
mkdir qvac-app && cd qvac-app npm init -y && npm pkg set type=module npm install @qvac/sdk
没有 Python 依赖，没有 Docker 容器。安装后的 node_modules/@qvac/sdk 包含完整的 TypeScript 类型定义和平台原生二进制。如果你用的是 Windows，需要确保系统已安装最新的 Visual C++ Redistributable（QVAC 的 C++ addon 依赖它）。
功能详解
1. LLM 推理（Completion）
加载模型 → 生成文本 → 卸载模型，三步构成一个完整的推理生命周期：
import { loadModel, LLAMA_3_2_1B_INST_Q4_0, completion, unloadModel } from "@qvac/sdk";
const modelId = await loadModel({
modelSrc: LLAMA_3_2_1B_INST_Q4_0,
modelType: "llm",
onProgress: (p) => console.log(p),
});
const result = completion({
modelId,
history: [{ role: "user", content: "用一句话解释量子计算" }],
stream: true,
});
for await (const token of result.tokenStream) {
process.stdout.write(token);
}
await unloadModel({ modelId });
LLAMA_3_2_1B_INST_Q4_0 是 SDK 内置的模型常量，指向一个约 700MB 的量化模型。QVAC 支持 Hugging Face 上所有 GGUF 格式模型——只需传入模型 URL 或本地路径即可。流式输出通过 for await 逐 token 消费，与 OpenAI 的 stream API 体验一致。
2. 向量嵌入与语义搜索
QVAC 的文本嵌入能力通过 qvac-fabric-llm.cpp 后端实现，支持生成兼容格式的文本向量，用于语义搜索和 RAG 场景。调用方式与 Completion 类似——先加载嵌入模型，再传入文本数组获取向量数组。
3. 语音识别（Whisper）
本地转写无需调用 OpenAI API，隐私数据不出设备。QVAC 集成了 Whisper 转录能力组件，支持标准的音频文件输入（WAV、MP3、FLAC），语言可指定为中文或自动检测。也支持 NVIDIA Parakeet 作为备选引擎。
4. P2P 推理委派
这是 QVAC 最独特的特性——把推理任务通过网络委派给其他节点。不同设备上运行 QVAC SDK 的 node 通过 Holepunch P2P 栈（Noise Protocol 加密 + QUIC UDP 隧道）自动发现彼此，NAT 穿透通过 blind relay 节点实现。这意味着两台不同内网中的设备也能建立直接连接，共享推理负载。
5. RAG 检索增强生成
QVAC 的内置 RAG 工作流包含文档摄入、向量存储和语义检索三个环节。支持常见的文档格式（Markdown、TXT、PDF），分块策略和检索参数均可配置。完整的 API 参考见官方 SDK 文档。
6. 多模态扩展
通过插件系统，QVAC 还支持图片生成（diffusion-cpp，基于 SDXL / Stable Diffusion）、OCR（ONNX 运行时）和 TTS（Chatterbox 神经网络模型）。OCR 和 TTS 在 CPU 上即可运行，M1+ 芯片会利用 Apple Neural Engine 自动加速。
排错指南
loadModel 一直卡在进度条不动：检查网络连接——内置的模型下载源可能需要科学上网。也可以用 DL_FILESYSTEM 环境变量指定本地模型目录，绕过在线下载。
P2P 连接建立失败：确认双方 QVAC 版本一致，检查防火墙是否放行 UDP 端口。Blind relay 默认使用 Tether 公共 relay，企业环境可自建 relay 节点。
npm install @qvac/sdk 报 node-gyp 错误：确保系统安装了 C++ 编译工具链（macOS: xcode-select --install，Ubuntu: build-essential，Windows: Visual Studio Build Tools）。
总结
QVAC 用一个 npm 包整合了本地 AI 开发需要的大部分能力——LLM、嵌入、语音、OCR、RAG 和 P2P 推理委派都藏在 @qvac/sdk 的 API 后面。Apache-2.0 许可证意味着你可以随意修改和商用。
如果你的场景是「在用户的手机上跑 LLM」「构建私有的企业 AI 助手」「或者办公室内多设备共享推理负载」，QVAC 是一个值得投入时间了解的选择。
相关链接：