sam3

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

SAM 3 (facebookresearch/sam3)

Overview

概述

Build, integrate, fine-tune, and evaluate Meta SAM 3 with reproducible commands and minimal setup friction.

通过可复现的命令和低摩擦的设置流程，构建、集成、微调并评估Meta SAM 3。

Quick Routing

快速导航

User intent	Action
Install SAM 3 and run first inference	Follow setup in `references/setup-and-inference.md`
Add SAM 3 to an existing Python app	Generate starter code with `scripts/create_inference_starter.py` and adapt API calls
Verify environment before setup/inference	Run `scripts/sam3_preflight_check.py`
Fine-tune on custom data	Use `references/training-and-eval.md` training flow and config guidance
Run SA-Co benchmarks or eval custom predictions	Use eval commands in `references/training-and-eval.md` and upstream `scripts/eval/*` docs
Debug runtime failures	Run the troubleshooting checklist in `references/setup-and-inference.md`

用户意图	操作
安装SAM 3并运行首次推理	遵循 `references/setup-and-inference.md` 中的设置步骤
将SAM 3添加到现有Python应用	使用 `scripts/create_inference_starter.py` 生成入门代码并适配API调用
在设置/推理前验证环境	运行 `scripts/sam3_preflight_check.py`
在自定义数据上微调	使用 `references/training-and-eval.md` 中的训练流程和配置指南
运行SA-Co基准测试或评估自定义预测结果	使用 `references/training-and-eval.md` 中的评估命令，以及上游 `scripts/eval/*` 文档
调试运行时故障	遵循 `references/setup-and-inference.md` 中的故障排查清单

Core Workflow

核心工作流

Confirm objective and modality.
Set up environment and checkpoint access.
Run a smoke test.
Execute the task path: inference, training, or evaluation.
Return reproducible commands and file paths.

确认目标和模态。
搭建环境并获取checkpoint访问权限。
运行冒烟测试。
执行任务流程：推理、训练或评估。
返回可复现的命令和文件路径。

1) Confirm objective and modality

1) 确认目标和模态

Identify whether the user needs image inference, video inference, fine-tuning, or benchmark evaluation.
Confirm whether CUDA is available and which GPU memory budget applies.
Confirm whether Hugging Face access to
```
facebook/sam3
```
is already approved.

确定用户需要的是图像推理、视频推理、微调还是基准测试评估。
确认CUDA是否可用，以及适用的GPU内存预算。
确认是否已获得Hugging Face对
```
facebook/sam3
```
的访问权限。

2) Set up environment and checkpoint access

2) 搭建环境并获取checkpoint访问权限

Use a clean environment:

bash

conda create -n sam3 python=3.12 -y
conda activate sam3
pip install torch==2.7.0 torchvision torchaudio --index-url https://download.pytorch.org/whl/cu126
git clone https://github.com/facebookresearch/sam3.git
cd sam3
pip install -e .

Authenticate with Hugging Face before first model load:

bash

hf auth login

Optionally run a preflight check before model download:

bash

python scripts/sam3_preflight_check.py --strict

For full setup and verification commands, read

references/setup-and-inference.md

使用干净的环境：

bash

conda create -n sam3 python=3.12 -y
conda activate sam3
pip install torch==2.7.0 torchvision torchaudio --index-url https://download.pytorch.org/whl/cu126
git clone https://github.com/facebookresearch/sam3.git
cd sam3
pip install -e .

首次加载模型前，通过Hugging Face进行身份验证：

bash

hf auth login

可选：在模型下载前运行预检检查：

bash

python scripts/sam3_preflight_check.py --strict

完整的设置和验证命令，请参阅

references/setup-and-inference.md

。

3) Run a smoke test

3) 运行冒烟测试

From this skill folder, generate a starter script:

bash

python scripts/create_inference_starter.py --mode image --output ./sam3_smoke.py

Edit placeholders and run from a SAM3 checkout.

从本技能文件夹中，生成入门脚本：

bash

python scripts/create_inference_starter.py --mode image --output ./sam3_smoke.py

编辑占位符内容，然后在SAM3代码目录中运行。

4) Execute the task path

4) 执行任务流程

Image and video inference: Use

references/setup-and-inference.md

to apply

Sam3Processor

and

build_sam3_video_predictor

patterns.

Fine-tuning: Use
```
references/training-and-eval.md
```
and start from a provided config in
```
sam3/train/configs
```
.

Benchmark evaluation: Use

references/training-and-eval.md

plus upstream dataset notes under

scripts/eval/gold

scripts/eval/silver

, and

scripts/eval/veval

图像和视频推理：使用

references/setup-and-inference.md

中的

Sam3Processor

和

build_sam3_video_predictor

模式。

微调：使用
```
references/training-and-eval.md
```
，并从
```
sam3/train/configs
```
中提供的配置开始。

基准测试评估：使用

references/training-and-eval.md

，以及

scripts/eval/gold

、

scripts/eval/silver

和

scripts/eval/veval

下的上游数据集说明。

5) Return reproducible output

5) 返回可复现的输出

Report exact commands run and any config overrides.
Include checkpoint source and authentication assumptions.
Include prompt text, frame index, and confidence threshold when reporting inference outputs.

报告执行的精确命令和任何配置覆盖项。
包含checkpoint来源和身份验证假设。
报告推理输出时，包含提示文本、帧索引和置信度阈值。

Guardrails

注意事项

Do not assume checkpoint access is granted; verify login and permission first.
Prefer official
```
sam3.model_builder
```
and predictor APIs over custom re-implementations.
Keep generated scripts editable and avoid machine-specific absolute paths.
If running on CPU, explicitly note expected performance limits before large jobs.

不要假设已获得checkpoint访问权限；请先验证登录状态和权限。
优先使用官方的
```
sam3.model_builder
```
和predictor API，而非自定义重实现。
保持生成的脚本可编辑，避免使用特定机器的绝对路径。
如果在CPU上运行，在执行大型任务前需明确说明预期的性能限制。

Resources

资源

Setup and inference guide:
```
references/setup-and-inference.md
```
Training and evaluation guide:
```
references/training-and-eval.md
```
Starter generator:
```
scripts/create_inference_starter.py
```
Preflight checker:
```
scripts/sam3_preflight_check.py
```

设置与推理指南：
```
references/setup-and-inference.md
```
训练与评估指南：
```
references/training-and-eval.md
```
入门代码生成器：
```
scripts/create_inference_starter.py
```
预检检查工具：
```
scripts/sam3_preflight_check.py
```