QVAC Python快速教程:无需Node.js,3步加载并推理你的第一个本地AI模型
QVAC Python快速教程:无需Node.js,3步加载并推理你的第一个本地AI模型
QVAC 是一个开源的本地 AI SDK,让你在设备端直接运行 AI 模型——不依赖云端、不需要 API Key。本教程使用 Python 客户端 tetherto-qvac-sdk,带你用 3 步完成安装、加载本地 LLM 模型并运行流式推理,全程无需 Node.js。
为什么选择 QVAC 跑本地AI
- 🏠 Local-first:模型在本地设备推理,离线也能跑,数据不出设备
- 🔒 隐私可控:无云端、无第三方 API,彻底告别 API Key
- 🧩 一个 SDK 覆盖全部 AI:LLM、语音识别、TTS、OCR、翻译、图像/视频生成、Embedding、RAG
- 🌍 跨平台:Linux、macOS、Windows、Android、iOS,同一套代码
- ⚡ Python 即装即用:自带 worker 的自包含 wheel,零额外配置
第 1 步:一行命令安装 QVAC Python SDK
要求 Python 3.10+。最快的安装方式是自包含 wheel——它会直接打包 QVAC worker(@qvac/sdk 运行时)和 Bare runtime,安装后 Client() 即可零配置启动,完全不需要 Node.js:
pip install tetherto-qvac-sdk
💡 自包含的按平台 wheel(darwin-arm64、linux-x64/arm64、win32-x64)发布在官方 Release 资源中,安装时用
pip install -f <release资源地址>指定即可,完整命令见 packages/sdk-python/README.md。纯 Python 依赖(pydantic、bare-rpc、compact-encoding)会自动从 PyPI 拉取。
数据科学同学可以顺手加上 notebook 扩展,获得同步 API 和 numpy/pandas 返回:
pip install "tetherto-qvac-sdk[notebook]"
第 2 步:加载你的第一个本地AI模型
QVAC 内置了模型目录,模型以常量形式提供,首次使用时通过 P2P 网络从 registry 拉取并缓存到本地。我们选 LLAMA_3_2_1B_INST_Q4_0(约 773 MB 的 Llama-3.2-1B 指令模型),它是入门推理的理想选择。
下面是完整的「三步」示例,可直接保存运行:
import asyncio
from tetherto.qvac_sdk import Client, load_model, completion, unload_model
from tetherto.qvac_sdk.models import LLAMA_3_2_1B_INST_Q4_0
async def main():
# 1️⃣ 创建客户端(自包含 wheel 下零配置,自动找到 worker)
async with Client() as client:
t = client.transport
# 2️⃣ 加载本地AI模型(首次自动下载并缓存)
model_id = await load_model(t, model_src=LLAMA_3_2_1B_INST_Q4_0)
# 3️⃣ 运行推理:流式接收生成内容
run = completion(
t,
model_id=model_id,
history=[{"role": "user",
"content": "用一句话解释量子计算"}],
)
async for event in run.events:
if event.type == "contentDelta":
print(event.text, end="", flush=True)
print()
# 用完卸载,释放内存
await unload_model(t, model_id)
asyncio.run(main())
运行后终端会实时打印模型的回答。模型加载的内部流程如图所示:客户端请求 → 解析来源 → 下载/复用缓存 → 加载原生插件 → 注册模型并返回 modelId。
两个实用小贴士:
- 用
on_progress=回调打印下载进度,参考 packages/sdk-python/examples/quickstart.py - 用环境变量
QVAC_CACHE_DIR或Client(config={"cacheDirectory": "..."})指定模型缓存目录,方便多台机器共享缓存
第 3 步:跑通之后,还能做什么
QVAC Python SDK 的公共 API 从 tetherto.qvac_sdk 平铺导出,加载其他模型后几乎零成本切换能力:
| 能力 | 方法 | 参考示例 |
|---|---|---|
| 语音转文字(Whisper) | transcribe |
examples/transcription.py |
| 文字转语音(TTS) | text_to_speech |
examples/text_to_speech.py |
| OCR 文字识别 | ocr_stream |
examples/ocr.py |
| 翻译 | translate |
examples/translation.py |
| Embedding 向量化 | embed |
examples/embeddings.py |
| 图像/视频生成 | diffusion_stream |
examples/ |
| RAG 检索增强 | model_registry_* |
examples/rag_sqlite.py |
在 Jupyter 里开发更方便——SyncClient 让每个调用都是同步阻塞的,embed 直接返回 numpy 数组:
from tetherto.qvac_sdk.notebook import SyncClient
from tetherto.qvac_sdk.models import EMBEDDINGGEMMA_300M_Q4_0
with SyncClient() as client:
m = client.load_model(model_src=EMBEDDINGGEMMA_300M_Q4_0)
vec = client.embed(m, "hello") # 1-D numpy 数组
每个主要能力都有可独立运行的示例脚本,用法详见 examples/README.md。
相关资料
- Python SDK 完整文档:packages/sdk-python/README.md
- 包定义与可选依赖:packages/sdk-python/pyproject.toml
- 全部官方示例:packages/sdk-python/examples/
- 模型加载流程架构图:docs/architecture/puml/images/08-model-loading-flow.png
- 项目总览与 Quickstart:README.md
🚀 从 pip install 到本地模型出字只需三分钟——现在就试试在你的设备上跑第一个本地AI模型吧!


