在 Kubernetes 安装

本文介绍如何在已有的 Kubernetes 集群上安装 TensorFusion，并把集群接入 TensorFusion 控制台。整个过程分三步：执行一条 Helm 命令，在控制台确认集群配置，在 vGPU 上部署一个小参数量的大模型并完成一次推理。

如果不希望集群连接控制台，请改看 Helm 快速安装。如果手里只有物理机或虚拟机，先用 K3s 搭建集群。

前置条件

• 一个 Kubernetes 集群，至少有一个 NVIDIA GPU 节点。其他厂商的加速卡见 Helm 快速安装。

• 每个 GPU 节点已安装 NVIDIA 驱动，容器运行时能挂载 GPU 设备。多数云厂商的托管 Kubernetes 已经配置好；自建节点需要安装 NVIDIA Container Toolkit。

• 每个 GPU 节点带有标签 nvidia.com/gpu.present=true。这个标签由 NVIDIA GPU Operator 或 GPU feature discovery 添加，TensorFusion 不会自动添加。用下面的命令检查，没有列出节点时手动打标签：

  kubectl get nodes -l nvidia.com/gpu.present=true
  kubectl label node <gpu-node-name> nvidia.com/gpu.present=true

• 本机已安装 kubectl 和 helm，账号有权限创建 Namespace、CRD、ClusterRole 和 MutatingWebhookConfiguration。

• 节点能从 Docker Hub 拉取镜像，集群能主动访问 app.tensor-fusion.ai。不需要开放任何入站访问。

第 1 步：安装 TensorFusion

1. 注册账号，打开 TensorFusion 控制台。

2. 在接入向导中选择 Connect existing Kubernetes，复制安装命令。命令里已经带上当前环境的接入令牌和 agent ID：

   helm upgrade --install --create-namespace --namespace tensor-fusion-sys \
     --repo https://download.tensor-fusion.ai \
     --set agent.enrollToken=<enroll-token> \
     --set agent.agentId=<org-id>:<environment-name> \
     tensor-fusion-sys tensor-fusion

   

3. 在目标集群上执行这条命令。

命令会安装以下内容：

agent 与控制台之间只有一条由集群主动发起的 WebSocket 连接。指标数据留在集群内的 GreptimeDB，不会上传。

需要调整 chart 参数时，参考 Helm values 参考。

在中国大陆安装

如果节点拉取 Docker Hub、quay.io、registry.k8s.io 的镜像不稳定，在命令末尾追加镜像加速的 values 文件：

  -f https://download.tensor-fusion.ai/values-cn.yaml

这个文件把 operator、agent、GreptimeDB、Vector、Alertmanager 和 webhook 证书工具的镜像换成国内镜像仓库的地址。hypervisor、vGPU provider、client、worker 这几个镜像不在其中，仍然从 Docker Hub 的 tensorfusion/* 拉取。可以在容器运行时里配置镜像加速，或者用节点能访问的镜像地址覆盖 cluster.hypervisorImage 和 providerConfigs.nvidia.images.*。

第 2 步：在控制台创建集群

控制台显示 agent 已连接后，填写集群表单，点击 Preview and Deploy，检查生成的资源清单，再点击 Confirm Deploy。控制台通过 agent 把 TensorFusionCluster 和调度配置应用到你的集群。

第 3 步：验证安装

1. 检查系统 Pod：

   kubectl get pods -n tensor-fusion-sys
   kubectl get pods -n greptimedb

   tensor-fusion-sys-controller-* 处于 Running 状态，每个 GPU 节点对应一个 hypervisor-<node-name> Pod。

2. 检查 TensorFusion 是否已发现 GPU：

   kubectl get tensorfusioncluster,gpupool
   kubectl get gpunode,gpu

   集群和资源池的 Phase 变为 Running，每张物理 GPU 对应一个 GPU 资源，并显示它的 TFLOPS 和 VRAM。

   如果没有 hypervisor Pod，或者看不到 GPU 资源，参考没有 hypervisor Pod。

3. 部署一个小参数量的大模型作为测试负载。应用下面的 Deployment，它用 vLLM 在一张 GPU 的一部分资源上运行 Qwen3-0.6B。控制台的 Deploy Inference App 按钮也可以帮你启动一个测试应用：

   

   # qwen3-demo.yaml
   apiVersion: apps/v1
   kind: Deployment
   metadata:
     name: qwen3-demo
     namespace: default
   spec:
     replicas: 1
     progressDeadlineSeconds: 3600
     selector:
       matchLabels:
         app: qwen3-demo
     template:
       metadata:
         labels:
           app: qwen3-demo
           tensor-fusion.ai/enabled: "true"
         annotations:
           tensor-fusion.ai/tflops-request: "10"
           tensor-fusion.ai/tflops-limit: "30"
           tensor-fusion.ai/vram-request: "4Gi"
           tensor-fusion.ai/vram-limit: "5Gi"
       spec:
         containers:
           - name: app
             image: vllm/vllm-openai:v0.11.0
             command:
               - vllm
               - serve
               - Qwen/Qwen3-0.6B
               - --served-model-name
               - qwen3-0.6b
               - --port
               - "8000"
               - --dtype
               - half
               - --max-model-len
               - "2048"
               - --gpu-memory-utilization
               - "0.7"
               - --max-num-seqs
               - "32"
             env:
               - name: VLLM_USE_FLASHINFER_SAMPLER
                 value: "0"
             ports:
               - name: http
                 containerPort: 8000
             readinessProbe:
               httpGet:
                 path: /health
                 port: 8000
               periodSeconds: 5
               failureThreshold: 120
             volumeMounts:
               - name: dshm
                 mountPath: /dev/shm
         volumes:
           - name: dshm
             emptyDir:
               medium: Memory
               sizeLimit: 2Gi

   kubectl apply -f qwen3-demo.yaml

   标签 tensor-fusion.ai/enabled: "true" 表示这个 Pod 交给 TensorFusion 管理。注解向一张 GPU 申请 10 TFLOPS 算力和 4 GiB 显存，上限为 30 TFLOPS 和 5 GiB。不写其他注解时，Pod 调度到默认资源池的 GPU 节点上，以 soft 隔离模式共享 GPU。这张 GPU 至少要有 4 GiB 尚未分配的显存。

   vLLM 启动时会按固定比例预留它看到的显存。--gpu-memory-utilization 0.7 把预留量控制在 5 GiB 上限的 70%，--max-model-len 和 --max-num-seqs 按小规模测试设置服务规格。VLLM_USE_FLASHINFER_SAMPLER=0 让 vLLM 使用内置的采样器。

4. 等待模型服务就绪：

   kubectl rollout status deployment/qwen3-demo --timeout=30m
   kubectl get pod -l app=qwen3-demo -o wide

   首次启动要拉取几个 GB 的 vLLM 镜像，并从 Hugging Face 下载模型权重，可能需要几分钟。模型加载进显存、/health 可以访问之后，Pod 才会变为 Ready。可以用 kubectl logs -f deployment/qwen3-demo 查看进度。

   如果节点访问不了 Hugging Face，给容器加上环境变量 HF_ENDPOINT，值为镜像站地址。

5. 进入容器检查 vGPU：

   kubectl exec deploy/qwen3-demo -- nvidia-smi

   nvidia-smi 显示的总显存约为 5120 MiB，也就是显存上限，而不是整张卡的显存。进程列表里能看到 vLLM 进程和它预留的显存。

6. 向模型发送一次对话请求：

   kubectl port-forward deploy/qwen3-demo 8000:8000 &
   
   curl -s http://127.0.0.1:8000/v1/chat/completions \
     -H 'Content-Type: application/json' \
     -d '{
       "model": "qwen3-0.6b",
       "max_tokens": 80,
       "messages": [{"role": "user", "content": "Give me a short introduction to large language model."}],
       "chat_template_kwargs": {"enable_thinking": false}
     }'
   
   kill %1   # 停止端口转发

   返回的是 OpenAI 格式的 JSON。choices[0].message.content 是 Qwen3-0.6B 生成的回答，usage.completion_tokens 大于 0。这一步才是真正的验证：Pod 处于 Running 不代表 GPU 链路可用，而一次完整的推理说明模型已经加载进 vGPU 的显存，每个 token 都是经过 TensorFusion 计算出来的。

7. 删除测试负载：

   kubectl delete deployment qwen3-demo

卸载

卸载脚本会删除 TensorFusion 创建的全部内容：所有 TensorFusion 自定义资源和 CRD、controller、webhook、tensor-fusion-sys 和 greptimedb 两个命名空间及其中的 PVC，以及节点上的 TensorFusion 标签。nvidia.com/gpu.present 这类厂商标签会保留。正在使用 TensorFusion vGPU 的业务会失去 GPU，卸载前先迁移或停止这些业务。

curl -sfLO https://raw.githubusercontent.com/NexusGPU/tensor-fusion/main/scripts/uninstall.sh
bash uninstall.sh --help   # 查看参数和删除范围
bash uninstall.sh

脚本对当前 kubectl context 指向的集群执行，不会二次确认。它会等待资源删除完成，可能需要几分钟。

下一步

• 创建 AI 应用：估算资源，把自己的应用跑在 vGPU 上。
• 工作负载注解参考：全部 Pod 注解。
• 生产级部署指南：高可用和外部 GreptimeDB。
• CRD 参考：各资源的定义。