Ziyi-Wang/sam3-local-transfer

SAM3 本机版本传输包

这是从现有运行机器整理的 SAM3 完整模型与运行参考，方便在另一台机器上接续使用。

模型来自 facebook/sam3，固定版本为 3c879f39826c281e95690f02c7821c4de09afae7。根目录保留本机使用的完整权重、配置、processor和tokenizer文件，原始文件保持原样。本机通过 Transformers 的 Sam3Model 从官方 Sam3VideoModel 权重中加载图像检测部分；完整checkpoint仍包含原来保存的全部张量。

包含哪些内容

• model.safetensors、config.json：完整原始模型。
• processor配置与全部tokenizer资源：可直接从本地目录加载。
• runtime/fixed999/：本机图像分割脚本及常驻SAM服务代码的副本，只处理保存的图片，不需要相机或机器人。
• runtime/requirements-exact.txt：本机相关Python包版本。
• runtime/environment/installed-packages.txt：原环境包版本参考。
• runtime/sam-python-cache.tar.gz：现有SAM启动依赖缓存的无损归档，包含本机Torch、Transformers等模块及原有元数据；可用于保存本机实现和同平台复现。
• runtime/third_party_licenses/、LICENSE、UPSTREAM_README.md：原模型与相关组件的许可和来源说明。
• transfer_manifest.json、MANIFEST.sha256：版本、大小与完整性校验。

Python为3.10；本机主要版本为Torch 2.5.1+cu118、torchvision 0.20.1+cu118和Transformers 5.15.0。接收机器需要准备兼容的Python环境、系统库和GPU驱动。依赖缓存是本机模块快照，不能当成完整Conda环境直接搬用；它保留原有元数据，实际运行版本以清单中记录的版本为准。

下载

仓库为私有仓库。使用有读取权限的HF账号登录后下载；授权信息保留在接收机器，不需要写进脚本。

python -m pip install huggingface_hub
hf auth login
hf download Ziyi-Wang/sam3-local-transfer --local-dir ./sam3-local-transfer
cd sam3-local-transfer
python verify_transfer.py

准备环境

可以新建Python 3.10环境，按本机版本安装：

python -m pip install torch==2.5.1+cu118 torchvision==0.20.1+cu118 --index-url https://download.pytorch.org/whl/cu118
python -m pip install -r runtime/requirements-exact.txt --extra-index-url https://download.pytorch.org/whl/cu118

包管理器会按当前平台解析传递依赖。安装时需要可访问对应软件源；模型下载完成后，下面的模型加载与分割使用本地文件。

若需要对照本机启动缓存，可以将其解压到新目录：

mkdir sam-runtime-reference
tar -xzf runtime/sam-python-cache.tar.gz -C sam-runtime-reference

里面的二进制模块与原Linux x86_64/Python3.10环境相关。标准安装环境可直接运行下例；需要对照或使用保存的Transformers实现时，可在个人环境中参考该归档进行适配。不要覆盖其他项目的Python环境。

对保存的图片做分割

准备一张PNG图片。输出目录使用尚不存在的新目录：

PYTHONPATH="$PWD/runtime${PYTHONPATH:+:$PYTHONPATH}" \
  python -m fixed999.sam_perception \
  --model-dir "$PWD" \
  --image /path/to/image.png \
  --out /path/to/new_result \
  --prompt "tennis ball" \
  --device cuda

可重复提供 --prompt，也可用 --device cpu 运行。脚本生成实例mask、叠加图及包含模型来源、阈值与耗时的 report.json。默认score阈值为0.55，mask阈值为0.5，沿用打包时原脚本。

也可以直接使用Transformers：

from transformers import Sam3Model, Sam3Processor

processor = Sam3Processor.from_pretrained(".", local_files_only=True, token=False)
model = Sam3Model.from_pretrained(
    ".", local_files_only=True, token=False, use_safetensors=True
)

常驻服务入口是 python -m fixed999.perception_session --socket /path/to/sam.sock --model-dir /path/to/model --device cuda，同样需要将 runtime 加入PYTHONPATH。服务处理status/run/stop请求，协议见随包源码。

来源与验证

模型文件按原样保留，转存没有量化、裁剪或重新保存权重。传输清单记录文件SHA256，下载后可用校验脚本逐项确认。打包过程读取文件并检查safetensors结构，没有启动新GPU推理，也没有操作现有相机、机械臂或SAM常驻服务。另一台机器的运行效果需在其环境中确认。

本包中的SAM模型、权重和相关材料遵循随附的SAM License；其他组件沿用各自许可证。