在宿主机/虚拟机安装

本文介绍如何让虚拟机里的应用使用宿主机的 NVIDIA GPU，既不需要 GPU 直通，也不需要 Kubernetes。做法是：在宿主机上启动一个 worker 进程，在虚拟机里把 client 动态库加载进应用，再把 client 指向 worker。这种模式称为 TensorFusion HyperGPU。

如果要把多台服务器的 GPU 池化并统一调度，请改看在虚拟机/服务器安装（K3S）。

工作方式

多个 client 可以连接同一个 worker。生产环境建议每个 client 对应一个 worker，资源限制和问题排查都互不影响。

前置条件

• 一台 x86-64 架构的 Linux 宿主机，装有 NVIDIA GPU 和 NVIDIA 驱动，nvidia-smi 能正常运行。建议驱动版本 570 或更高。
• 宿主机的 glibc 版本不低于 2.34（例如 Ubuntu 22.04、RHEL 9），并装有 RDMA 用户态库 libibverbs.so.1 和 librdmacm.so.1，worker 二进制依赖这两个库。安装命令：apt-get install -y libibverbs1 librdmacm1 或 dnf install -y libibverbs librdmacm。
• 一台或多台虚拟机，虚拟化平台不限（QEMU、MVisor、VMware、Hyper-V 等），能通过 TCP 或共享内存设备与宿主机通信。Linux 虚拟机需要 x86-64 架构，glibc 不低于 2.34。也支持 Windows 虚拟机。

第 1 步：下载 TensorFusion

在宿主机上下载并解压安装包：

curl -fLO https://cdn.tensor-fusion.ai/archive-lastest.zip
unzip archive-lastest.zip
cd archive-lastest

安装包的内容：

archive-lastest/
├── tensor-fusion-worker          # 在宿主机上运行
└── tensor-fusion-client/
    ├── linux/                    # libcuda.so、libnvidia-ml.so、libteleport.so
    └── windows/                  # nvcuda.dll、nvml.dll、teleport.dll

第 2 步：在宿主机启动 worker

1. 选择 client 与 worker 之间的通信协议：

   协议	传输方式	适用场景
   native	TCP	部署最简单。虚拟机和宿主机在同一内网、往返延迟在 0.8 ms 左右或更低时使用。
   shmem	共享内存	延迟最低，适合对延迟敏感的业务。虚拟机需要挂载 IVSHMEM 设备。

2. 按选定的协议启动 worker。

   nativeshmem

   监听 TCP 端口 12345：

   TF_ENABLE_LOG=1 ./tensor-fusion-worker -n native -p 12345

   创建一块名为 /my_shm、大小 256 MB 的共享内存，它在宿主机上对应文件 /dev/shm/my_shm：

   TF_ENABLE_LOG=1 ./tensor-fusion-worker -n shmem -m /my_shm -M 256

   worker 需要一直运行。生产环境用 systemd 之类的进程管理工具来托管。

worker 的命令行参数，即 ./tensor-fusion-worker -h 的输出：

Usage: tensor-fusion-worker [option]
Options
  -h, --help              Display this information.
  -v, --version           Display version information.
  -n, --net               Specified network protocol.
  -p, --port              Specified the port for server.
  -c, --controller-pipe   Specified the path of the controller pipe.
  -m, --shmem-file        Specified the file path of shared memory.
  -M, --shmem-size        Specified the size(MB) of shared memory.
  -R, --rdma-buffer-size  Specified the size(MB) of RDMA buffer.

-n 默认为 native。native 必须指定 -p，shmem 必须同时指定 -m 和 -M。

worker 的环境变量：

第 3 步：在虚拟机中安装 client

把安装包里的 tensor-fusion-client 目录复制到虚拟机。下面的示例假设它位于 /opt/tensor-fusion-client。

export LD_PRELOAD=/opt/tensor-fusion-client/linux/libteleport.so:/opt/tensor-fusion-client/linux/libcuda.so:/opt/tensor-fusion-client/linux/libnvidia-ml.so

各系统环境差别较大，请确认应用实际加载的是这几个库，而不是 NVIDIA 的原生库。设置 TF_ENABLE_LOG=1 后，client 启动时会打印日志。

client 的环境变量：

第 4 步：连接并验证

下面以装有 Python 和 CUDA 版 PyTorch 的 Linux 虚拟机为例。

1. 在虚拟机中开启日志并加载 client：

   export TF_ENABLE_LOG=1
   export LD_PRELOAD=/opt/tensor-fusion-client/linux/libteleport.so:/opt/tensor-fusion-client/linux/libcuda.so:/opt/tensor-fusion-client/linux/libnvidia-ml.so

2. 按 worker 使用的协议设置连接信息。

   nativeshmem

   格式为 native+<宿主机 IP>+<端口>+<版本号>。假设 worker 所在宿主机的 IP 是 192.168.1.100，端口是 12345：

   export TENSOR_FUSION_OPERATOR_CONNECTION_INFO=native+192.168.1.100+12345+0

   虚拟机必须能访问这个 IP 和端口。

   把 worker 创建的共享内存作为 IVSHMEM 设备挂给虚拟机。以 QEMU 为例，对应用 -m /my_shm -M 256 启动的 worker：

   qemu-system-x86_64 \
     -m 8192 \
     -hda centos8.4.qcow2 \
     -vnc :1 \
     -enable-kvm \
     -cpu host \
     -object memory-backend-file,id=shm0,mem-path=/dev/shm/my_shm,size=256M,share=on \
     -device ivshmem-plain,memdev=shm0 \
     -smp 4

   在虚拟机里找到 IVSHMEM 设备的 PCI 地址：

   lspci -vv | grep -i Inter-VM

   00:04.0 RAM memory: Red Hat, Inc. Inter-VM shared memory (rev 01)

   这里的地址是 00:04.0。连接信息的格式为 shmem+<设备资源文件>+<大小（MB）>+<版本号>，资源文件是该设备在 /sys 下的 resource2 文件：

   export TENSOR_FUSION_OPERATOR_CONNECTION_INFO=shmem+/sys/devices/pci0000:00/0000:00:04.0/resource2+256+0

   大小必须与 worker 的 -M 参数一致。映射 IVSHMEM 资源文件通常需要 root 权限。

3. 用 PyTorch 和 Qwen3-0.6B 跑一次推理：

   pip install modelscope packaging transformers accelerate
   
   cat << 'EOF' > test-qwen.py
   from modelscope import AutoModelForCausalLM, AutoTokenizer
   
   model_name = "Qwen/Qwen3-0.6B"
   
   tokenizer = AutoTokenizer.from_pretrained(model_name)
   model = AutoModelForCausalLM.from_pretrained(
       model_name,
       torch_dtype="auto",
       device_map="cuda:0"
   )
   
   prompt = "Give me a short introduction to large language model."
   messages = [
       {"role": "user", "content": prompt}
   ]
   text = tokenizer.apply_chat_template(
       messages,
       tokenize=False,
       add_generation_prompt=True,
       enable_thinking=True
   )
   model_inputs = tokenizer([text], return_tensors="pt").to(model.device)
   generated_ids = model.generate(
       **model_inputs,
       max_new_tokens=32768
   )
   output_ids = generated_ids[0][len(model_inputs.input_ids[0]):].tolist()
   try:
       # rindex finding 151668 (</think>)
       index = len(output_ids) - output_ids[::-1].index(151668)
   except ValueError:
       index = 0
   
   thinking_content = tokenizer.decode(output_ids[:index], skip_special_tokens=True).strip("\n")
   content = tokenizer.decode(output_ids[index:], skip_special_tokens=True).strip("\n")
   
   print("thinking content:", thinking_content)
   print("content:", content)
   EOF
   
   python3 test-qwen.py

   在中国大陆可以先给 pip 配置镜像源加速下载：pip config set global.index-url https://pypi.mirrors.ustc.edu.cn/simple。

4. 检查结果：

   • 虚拟机里的脚本打印出模型的回答。
   • 在宿主机上运行 nvidia-smi，能看到 worker 进程和它占用的显存。

脚本报错时，查看虚拟机里的 client 日志和宿主机上的 worker 日志。设置了 TF_ENABLE_LOG=1 后两边都会输出日志。

下一步

• 在虚拟机/服务器安装（K3S）：把多台服务器的 GPU 池化，由 TensorFusion 统一调度。
• TensorFusion 架构：client、worker 与 TensorFusion 其他组件如何协作。
• GPU Go：在笔记本或工作站上使用远程 GPU。