TensorFlow Models CircularNet 部署实战：克隆 waste_identification_ml 仓库并初始化推理客户端环境

本文以 TensorFlow Models 仓库中 waste_identification_ml（CircularNet 垃圾识别项目）的官方部署文档为骨架，完整讲解 CircularNet 部署流程的第一步：在云端 GPU 实例或 NVIDIA 边缘设备上克隆仓库、进入部署目录并执行依赖安装脚本。读完后，你将能够独立完成环境初始化，并理解 requirements.sh 脚本内部的每一步行为及其与后续 Triton 推理服务启动步骤的衔接关系。

部署目标与两条环境路线

在克隆仓库之前，需要先明确 CircularNet 部署的整体形态。根据部署入口文档 circularnet-docs/content/deploy-cn/_index.md：CircularNet 可以部署在任意云厂商或推荐的边缘设备上，但官方文档给出的标准路线是在 Google Cloud 或 NVIDIA 设备上创建并运行一个 Triton 推理服务器。该服务器的设计目标是高效处理图片或视频输入：将输入拆分为帧，并对每一帧执行模型预测。

官方提供两条前置环境路线（详见 before-you-begin.md），克隆仓库的操作在两种终端环境下完全一致：

路线	终端	关键配置
Google Cloud	VM 实例的 SSH-in-browser 窗口	挂载 1 块 NVIDIA T4 GPU 的 Compute Engine 实例，机器类型 n1-standard-8（8 vCPU、30 GB 内存），镜像选择“Deep Learning on Linux，预装 CUDA 11.3 的 Debian 11 + Python 3.10”，启动盘 300 GB 平衡持久盘，防火墙放行 HTTP/HTTPS
NVIDIA 边缘设备	设备终端	参考如 NVIDIA Jetson 的开发者指南完成基础配置，确保设备联网以完成依赖包下载

两条路线的唯一区别在于你打开的是“SSH-in-browser 窗口”还是“设备终端”，后文所有命令均可直接复用。

克隆仓库并安装依赖（官方四步法）

以下命令来自官方文档 clone-repo.md，在 SSH-in-browser 窗口或边缘设备终端中依次执行：

第 1 步：安装 Git

sudo apt-get install git

第 2 步：克隆包含 CircularNet 的 TensorFlow Models 仓库

git clone --depth 1 https://github.com/tensorflow/models.git

这里使用 --depth 1 浅克隆，只拉取最新一次提交而不包含完整历史。CircularNet 项目位于该仓库的 official/projects/waste_identification_ml 子目录下，浅克隆能显著减少一次性的网络下载量与磁盘占用——对于 300 GB 启动盘的云端 VM 或容量更小的 Jetson 设备都是一个实用的选择。

第 3 步：进入 waste_identification_ml 项目的 client 目录

cd models/official/projects/waste_identification_ml/Deploy/detr_cloud_deployment/client/

注意路径中的实际目录名为 Deploy（大写 D）与 detr_cloud_deployment，与仓库结构一一对应，该目录下当前包含推理客户端的全部脚本。

第 4 步：运行依赖安装脚本

sh requirements.sh

第 5 步：返回根目录（官方文档以 cd\ 表示回退操作，即返回用户主目录/仓库根目录）。

完成后，环境初始化结束，下一步即启动 Triton 推理服务器，官方文档将其指引至 start-server.md。

深入 requirements.sh：环境初始化脚本到底做了什么

sh requirements.sh 这一行命令背后，是一个位于 client/requirements.sh 的完整环境编排脚本。结合源码，可以逐段确认它的实际行为：

1. Shell 自检与回退执行：脚本开头检查 BASH_VERSION，若非在 bash 下执行则 exec /bin/bash "$0" "$@" 重新拉起自身。这正是文档可以放心使用 sh requirements.sh 的原因——即使被 dash/sh 启动，脚本也会自动切换到 bash 运行，依赖 bash 语法的逻辑不会失效。
2. 系统依赖准备：执行 sudo apt-get update -y，随后检查 docker 命令是否存在；未安装时通过官方安装脚本安装 Docker，已安装则跳过。Docker 是后续运行 Triton 推理服务器的载体（见后文）。
3. Python 虚拟环境：安装 python3-venv 与 python3-pip，用 python3.10 -m venv myenv 创建虚拟环境 myenv 并激活。这与前置条件中“Deep Learning VM with CUDA 11.3、Debian 11、Python 3.10”的镜像要求直接对应。
4. 安装 Python 依赖：执行 pip install -r requirements.txt，按 client/requirements.txt 的清单安装客户端所需的全部包。
5. 仓库存在性兜底：若当前目录不存在 models 目录，脚本会再次执行 git clone --depth 1 克隆仓库，否则跳过。这是一个容错分支——正常情况下你在第 2 步已经克隆过仓库，此分支不会触发。
6. 清理现场：脚本末尾 deactivate 退出虚拟环境，并打印 “Environment setup is complete.” 作为完成信号。

requirements.txt 依赖清单解析

从依赖版本可以看出客户端的完整能力面（以下版本号以仓库当前 requirements.txt 为准）：

• 推理通信：tritonclient[all]==2.65.0 —— Triton 官方客户端库，是 client 目录中推理脚本与推理服务器通信的基础；
• 图像处理与目标跟踪：opencv-python==4.13.0.92、scikit-image==0.25.2、pillow==12.0.0、supervision==0.26.1、trackpy==0.7、cuml-cu12==25.12.* —— 覆盖图片/视频读帧、检测框后处理与跨帧跟踪；
• GPU 加速栈：cupy-cuda12x[cuda_dlls]、cupy-cuda12x[ctk]、cuml-cu12（RAPIDS cuML），并通过 --extra-index-url https://pypi.nvidia.com 指定 NVIDIA 的 PyPI 索引以获取 CUDA 相关包；
• 云端数据链路：google-cloud-bigquery==3.40.1、pandas-gbq==0.33.0、google-cloud-storage==3.9.0、google-auth —— 对应客户端将推理结果写入 BigQuery、从 Cloud Storage 读取数据的能力（与前置条件中需启用 BigQuery API、Cloud Storage API 相互印证）；
• 基础工具：natsort、absl-py、pandas、scikit-learn、webcolors、ffmpeg-python（视频帧处理）。

如果 pip install 阶段失败，优先排查三点：Python 版本是否为 3.10（脚本硬编码了 python3.10）、网络能否访问 NVIDIA 的 extra index、以及 CUDA 11.3 镜像是否安装成功。

与下一步“启动服务器”的衔接

克隆与环境初始化完成后，整个部署链路就走到了服务端环节。官方文档 start-server.md 指引你进入同级目录的 server/ 并执行 bash triton_inference_server.sh。为了说明为何 requirements.sh 中要预先安装 Docker 与 screen，可以结合 server/triton_inference_server.sh 的实现确认其职责链：

• 清理旧的 model_repository 目录，并从 Cloud Storage 下载、解压最新 CircularNet 模型包（脚本中以关联数组定义模型名与下载地址，其中模型标签为 CircularNet_Segmentation_Model_v1，实际下载的压缩包为 CircularNet_model_v2.zip）；
• 检测并安装 screen；
• 通过 screen -dmS server 创建一个名为 server 的分离会话，在其中以 --gpus all 启动 Triton 官方容器 nvcr.io/nvidia/tritonserver:25.05-py3，映射 8000（gRPC 推理端口）、8001（HTTP）、8002（指标）三个端口，并将模型仓库挂载到容器的 /models。

也就是说，clone-repo 这一步准备的 Docker 运行时、Python 3.10 虚拟环境与 Triton 客户端依赖，分别服务于“服务器容器化运行”与“客户端发起推理”两个后续环节。服务器就绪后，客户端脚本会利用 tritonclient 向 8000 端口发送图片帧进行推理，具体操作见官方文档 start-client.md。

完成自检清单

执行完克隆与依赖安装后，建议按以下依据逐项确认环境就绪：

1. 仓库结构完整：models/official/projects/waste_identification_ml/Deploy/detr_cloud_deployment/ 下同时存在 client/ 与 server/ 两个子目录，且 client/ 中能看到 requirements.sh、requirements.txt、run_images.sh、triton_server_inference.py、inference_pipeline.py 等文件；
2. 依赖安装成功：requirements.sh 运行结束时输出 “Environment setup is complete.”，且当前目录生成了 myenv 虚拟环境目录；
3. Docker 可用：docker --version 能正常返回版本信息，这是下一步启动 Triton 容器的前提；
4. 进入下一步：返回仓库根目录后，按 start-server.md 启动服务器，并在 screen -r server 会话中确认模型显示 READY 状态。

需要再次强调的适用前提：上述流程面向仓库当前版本对应的环境（Python 3.10 + CUDA 11.3 + Triton 25.05-py3 容器），官方部署文档明确提示“部署 CircularNet 模型需要具备管理基础设施、执行命令、以及在云端或边缘设备上建立连接设置与权限的技术能力”。如果在 Jetson 等边缘设备上执行，还需确认系统架构与 NVIDIA 索引中的包版本匹配，这是云端 T4 路线之外的唯一差异点。