QVAC Python快速教程:无需Node.js,3步加载并推理你的第一个本地AI模型

原创2026-10-31 15:20:371,922 阅读

QVAC Python快速教程:无需Node.js,3步加载并推理你的第一个本地AI模型

QVAC 是一个开源的本地 AI SDK,让你在设备端直接运行 AI 模型——不依赖云端、不需要 API Key。本教程使用 Python 客户端 tetherto-qvac-sdk,带你用 3 步完成安装、加载本地 LLM 模型并运行流式推理,全程无需 Node.js。

QVAC 本地AI SDK 演示

为什么选择 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

QVAC 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。

QVAC 模型加载流程

两个实用小贴士:

  • 用 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。

相关资料

🚀 从 pip install 到本地模型出字只需三分钟——现在就试试在你的设备上跑第一个本地AI模型吧!

登录后查看全文
qvac