簡介一套開箱即用的SAM2圖像分割完整跑通版本面向計(jì)算機(jī)視覺領(lǐng)域的研究者、開發(fā)者以及自動駕駛、醫(yī)學(xué)影像處理方向的技術(shù)人員解決從任意圖像到像素級分割掩膜的快速轉(zhuǎn)換難題。壓縮包共297個文件整體約344.72MB其中包含預(yù)訓(xùn)練模型權(quán)重、30個Python二次開發(fā)腳本、24個編譯緩存文件、多種模型調(diào)用示例、YAML環(huán)境配置、數(shù)據(jù)處理腳本以及詳細(xì)的README文檔還有配置環(huán)境的DOCX教程目錄按功能模塊組織非常便于檢索和按需取用。目前已有3596人學(xué)習(xí)下載示例程序覆蓋圖像預(yù)測、自動掩膜生成、視頻預(yù)測等典型場景搭配預(yù)訓(xùn)練權(quán)重即可開箱推理也可基于現(xiàn)有腳本快速改造。對希望將最新分割技術(shù)落地到科研實(shí)驗(yàn)或產(chǎn)品原型的團(tuán)隊(duì)而言這套資源能顯著縮短環(huán)境搭建與代碼調(diào)試周期同時提供完整的調(diào)用鏈路參考有效提升圖像分析的精度與效率。1. 從解壓到第一次出maskSAM2到底卡在哪一步拿到「segment-anything-2.zip」這類的壓縮包不少人的第一反應(yīng)是解壓、裝依賴、跑demo結(jié)果往往卡在一個很尷尬的位置環(huán)境裝好了權(quán)重也下下來了但一跑推理就報(bào)錯或者mask出來一團(tuán)黑。SAM2跟第一代最大的區(qū)別在于它在視頻分割上的能力大幅增強(qiáng)但代價是運(yùn)行時對顯存和模型加載邏輯更挑剔。這個標(biāo)題指向的其實(shí)不是一個「跑通聽天由命」的黑匣子而是一條可以穩(wěn)定復(fù)現(xiàn)的路徑把壓縮包里的項(xiàng)目代碼變成能在本地出分割結(jié)果的工具。這篇文章會把「跑通版本」這件事拆成四塊環(huán)境到底要裝到什么粒度、官方推理腳本怎么用才不出錯、prompt參數(shù)怎么調(diào)才能讓mask貼合目標(biāo)以及你大概率會踩的五個坑。適合剛拿到壓縮包不知道從哪下手的初階用戶也適合被各種load_state_dict報(bào)錯折磨過的熟手——后者可以直接跳到避坑章節(jié)對照排查。先說結(jié)論SAM2的項(xiàng)目跑通不難難的是環(huán)境版本和權(quán)重文件的對齊這兩件事做對了剩下的就是幾十行代碼的事。2. 環(huán)境準(zhǔn)備把版本對齊這件事做到位SAM2的代碼依賴一堆深度學(xué)習(xí)組件但真正決定你能否跑通的只有三個Python版本、PyTorch版本、權(quán)重文件與代碼倉庫的匹配關(guān)系。很多人翻車不是因?yàn)榇a寫錯而是因?yàn)閠orch版本太新或太老導(dǎo)致編譯擴(kuò)展或加載checkpoint時出現(xiàn)莫名奇妙的報(bào)錯。2.1 解壓后的目錄結(jié)構(gòu)先搞清楚你手里有什么拿到壓縮包解壓后常見做法是先看看目錄里有沒有checkpoints、configs、demo或segment_anything_2這類目錄。以官方倉庫常見的結(jié)構(gòu)為例代碼部分包含模型定義、數(shù)據(jù)加載和推理腳本權(quán)重通常不會直接塞在zip里因?yàn)閱蝹€checkpoint文件動不動幾個GB壓縮包一般只帶代碼骨架和配置。所以解壓第一步不是急著裝環(huán)境而是確認(rèn)你缺什么東西。unzip segment-anything-2.zip -d sam2_project cd sam2_project find . -maxdepth 2 -type d | sort # 期望看到的目錄層級示例 # ./checkpoints # 權(quán)重文件目錄可能為空 # ./configs # 模型配置yaml # ./demo # gradio演示或推理示例 # ./segment_anything_2 # 核心代碼包這段命令的意圖是讓你在動手前對項(xiàng)目結(jié)構(gòu)有數(shù)。如果checkpoints目錄不存在需要手動創(chuàng)建并下載對應(yīng)權(quán)重如果demo目錄缺失說明這個zip可能是裁剪版只保留了核心庫。邏輯說明SAM2的推理入口通常封裝在segment_anything_2包內(nèi)配置yaml里記錄了模型結(jié)構(gòu)參數(shù)這兩者必須和權(quán)重文件的訓(xùn)練配置一致否則加載時會出現(xiàn)層名匹配失敗。參數(shù)說明maxdepth 2限制只往下看兩層目錄避免輸出太長sort讓目錄名按字典序排列方便快速定位。如果你解壓后發(fā)現(xiàn)目錄結(jié)構(gòu)異常比如少了configs或核心包目錄那這個zip很可能不完整不要浪費(fèi)時間繼續(xù)下一步。2.2 依賴安裝的版本敏感點(diǎn)torch版本決定的坑SAM2的官方實(shí)現(xiàn)依賴torch、torchvision、opencv-python、pycocotools等庫但真正卡人的是GPU相關(guān)的那部分。項(xiàng)目代碼里有CUDA自定義算子主要是視頻分割用到的flash-attention類優(yōu)化聚合版本不同會導(dǎo)致編譯失敗或運(yùn)行時報(bào)錯。常見做法是先創(chuàng)建獨(dú)立conda環(huán)境再裝對應(yīng)版本的torch。conda create -n sam2 python3.10 -y conda activate sam2 # 安裝PyTorch注意cuda版本要和本機(jī)驅(qū)動匹配 pip install torch2.1.0 torchvision0.16.0 --index-url https://download.pytorch.org/whl/cu121 # 安裝項(xiàng)目依賴 cd sam2_project pip install -e . # 如果你有setup.py # 或 pip install -r requirements.txt邏輯說明Python 3.10是穩(wěn)妥選擇SAM2的代碼基于新語法特性寫的3.8以下大概率直接語法報(bào)錯3.12以上又可能遇到某些依賴沒有預(yù)編譯wheel的問題。torch 2.1.0配合cu121是過去驗(yàn)證過的組合因?yàn)镾AM2的官方release時間線正好落在torch 2.x早期版本區(qū)間太新的torch比如2.4改了部分API行為可能導(dǎo)致自定義算子加載失敗。參數(shù)說明-e表示可編輯安裝適合跑通后修改源碼調(diào)試如果你不需要改源碼直接pip install .會更快。requirements.txt里如果鎖定了某些庫的版本號建議優(yōu)先以它為準(zhǔn)手動安裝torch只是為了提前確認(rèn)CUDA兼容性。注意不要用CPU版本的torch跑SAM2除非你只是想看代碼結(jié)構(gòu)——視頻分割在CPU上跑一個片段可能要等十分鐘。3. 用最小推理腳本跑通第一次靜態(tài)圖分割環(huán)境裝好、權(quán)重下載完畢之后下一個目標(biāo)是讓模型對一張圖輸出mask。這里的關(guān)鍵是準(zhǔn)備好輸入數(shù)據(jù)格式以及把模型加載、圖像預(yù)處理、推理調(diào)用這三步串聯(lián)起來。3.1 輸入數(shù)據(jù)準(zhǔn)備不該被忽略的預(yù)處理細(xì)節(jié)SAM2雖然號稱「開箱即用」但對輸入圖像有隱性要求尺寸、通道數(shù)、數(shù)值范圍都要符合模型的預(yù)期。官方代碼里通常有個預(yù)處理管道但你在自定義腳本里調(diào)用時要自己處理Resize和歸一化。import cv2 import numpy as np def preprocess_image(image_path, target_size1024): # 讀取圖像SAM2默認(rèn)期望BGR轉(zhuǎn)RGB image cv2.imread(image_path) image cv2.cvtColor(image, cv2.COLOR_BGR2RGB) h, w image.shape[:2] # 等比縮放長邊縮到target_size scale target_size / max(h, w) new_h, new_w int(h * scale), int(w * scale) image cv2.resize(image, (new_w, new_h), interpolationcv2.INTER_LINEAR) return image, (new_h, new_w), (h, w)邏輯說明SAM2的圖像編碼器用的是Transformer結(jié)構(gòu)輸入尺寸需要被編碼器內(nèi)部的position embedding處理雖然不是嚴(yán)格固定到1024x1024但把長邊縮放到1024是官方demo的常見取值這樣mask輸出質(zhì)量有保障。另一個潛在坑是顏色通道OpenCV默認(rèn)讀取是BGR格式直接丟給模型會導(dǎo)致分割結(jié)果完全錯誤雖然視覺上圖像看起來正常但模型學(xué)到的顏色分布是RGB通道顛倒會嚴(yán)重影響特征提取。參數(shù)說明target_size1024是模型訓(xùn)練時的標(biāo)準(zhǔn)輸入分辨率如果你的圖像太大比如4000x3000直接resize到1024會損失細(xì)節(jié)我一般會先看目標(biāo)物體大小如果物體很小先在原圖上裁剪出感興趣區(qū)域再縮放效果比直接全圖縮放好很多。INTER_LINEAR是線性插值對自然圖像足夠用不需要換更高級的插值方法。3.2 加載權(quán)重與推理腳本從模型初始化到mask輸出權(quán)重文件的加載是另一個高發(fā)報(bào)錯點(diǎn)。SAM2的模型類會從config文件讀取結(jié)構(gòu)參數(shù)然后用torch.load讀取checkpoint里的state_dict。如果config和權(quán)重不對齊最常見的報(bào)錯是size mismatch或Missing key(s) in state_dict。# 假設(shè)權(quán)重放在checkpoints目錄下 mkdir -p checkpoints # 需要從官方地址下載sam2.pt權(quán)重文件放到checkpoints目錄import torch from segment_anything_2 import build_sam2, Sam2Predictor def load_model(devicecuda): config_path configs/sam2/sam2_hiera_l.yaml checkpoint_path checkpoints/sam2_hiera_l.pt # 構(gòu)建模型 model build_sam2(config_path, checkpoint_path, devicedevice) predictor Sam2Predictor(model) return predictor # 推理拿到mask def segment_image(predictor, image): predictor.set_image(image) # 輸入點(diǎn)提示目標(biāo)中心位置類型為前景點(diǎn) point_prompt np.array([[500, 300]]) point_label np.array([1]) masks, scores, _ predictor.predict( point_coordspoint_prompt, point_labelspoint_label, multimask_outputTrue, ) return masks, scores邏輯說明build_sam2內(nèi)部會根據(jù)yaml文件里的模型層次配置構(gòu)建網(wǎng)絡(luò)結(jié)構(gòu)然后加載checkpoint。這里強(qiáng)調(diào)devicecuda是因?yàn)镾AM2的模型參數(shù)量在百萬級別CPU推理不是不能跑但一次前向要等很久調(diào)試效率極低。Sam2Predictor是官方封裝好的推理接口set_image內(nèi)部完成了圖像編碼器的前向計(jì)算之后每次predict都復(fù)用這個特征所以如果你要同時對一張圖做多次不同prompt的分割調(diào)用一次set_image就夠不用重復(fù)編碼。參數(shù)說明multimask_outputTrue時模型會返回3個候選maskscores是每個mask的置信度如果設(shè)為False則只返回最優(yōu)的一個。點(diǎn)提示的坐標(biāo)坐標(biāo)系是原始圖像尺寸——注意不是resize后的尺寸因?yàn)镾am2Predictor內(nèi)部會做坐標(biāo)變換所以你在調(diào)用predict時傳入的坐標(biāo)是原圖像上的坐標(biāo)。point_label為1表示前景點(diǎn)為0表示背景點(diǎn)這直接影響分割結(jié)果的語義。4. 交互式提示設(shè)計(jì)與參數(shù)調(diào)優(yōu)讓mask貼合目標(biāo)跑通demo只是起點(diǎn)真實(shí)場景里你往往需要分割特定物體或者修正模型第一次分割的偏差。SAM2的交互式設(shè)計(jì)允許你用點(diǎn)和框來引導(dǎo)模型但其中的參數(shù)選擇會影響最終mask邊界是否干凈。4.1 點(diǎn)提示與框提示的組合策略何時用點(diǎn)、何時用框SAM2對點(diǎn)提示和框提示的響應(yīng)模式不同點(diǎn)提示適合指定「要什么」或「不要什么」框提示則相當(dāng)于給模型一個空間范圍約束。實(shí)際使用中框提示的穩(wěn)定性遠(yuǎn)高于點(diǎn)提示——如果你只給一個前景點(diǎn)模型可能把與目標(biāo)顏色相近的背景也分割進(jìn)來但給一個緊貼目標(biāo)的框模型會在框內(nèi)尋找精確邊界。# 框提示示例框住目標(biāo)物體 box_prompt np.array([[100, 150], [600, 700]]) # [左上角x,y], [右下角x,y] masks, scores, _ predictor.predict( point_coordsNone, point_labelsNone, boxbox_prompt, multimask_outputTrue, )邏輯說明當(dāng)point_coords傳None時模型只依賴框提示做分割。官方文檔里強(qiáng)調(diào)box坐標(biāo)格式是[x1, y1, x2, y2]并且同樣是原始圖像坐標(biāo)系。傳入坐標(biāo)必須確保x2 x1且y2 y1否則模型內(nèi)部會對坐標(biāo)進(jìn)行重排序或直接報(bào)錯。實(shí)際使用中我傾向先用目標(biāo)檢測器得到一個初始框再傳給SAM2這比手工點(diǎn)選更可復(fù)現(xiàn)。參數(shù)說明如果同時提供點(diǎn)提示和框提示模型會優(yōu)先遵循框的空間約束點(diǎn)提示用于細(xì)化前景/背景語義。一個常用技巧是在框的基礎(chǔ)上額外尺子一個前景點(diǎn)目標(biāo)中心這樣既限制了范圍又明確了目標(biāo)類別。另外multimask_outputTrue在框提示模式下得到的3個候選mask往往差異較大建議對每個mask算一下面積取面積最接近框面積的一半的那個。4.2 mask閾值與后處理從模型概率到干凈邊界模型輸出的mask是一張與輸入圖像同尺寸的概率圖每個像素值在0~1之間表示屬于目標(biāo)的概率。直接拿 0.5判閾值有時會得到毛糙的邊緣或者細(xì)小的孤立噪點(diǎn)。官方Sam2Predictor返回的mask已經(jīng)做過sigmoid但未經(jīng)形態(tài)學(xué)后處理。def postprocess_mask(mask_prob, threshold0.0): # mask_prob 形狀 (H, W)值范圍0~1 binary_mask (mask_prob threshold).astype(np.uint8) # 去除小連通域 num_labels, labels, stats, _ cv2.connectedComponentsWithStats(binary_mask, connectivity8) for i in range(1, num_labels): if stats[i, cv2.CC_STAT_AREA] 500: binary_mask[labels i] 0 # 閉運(yùn)算填充孔洞 kernel cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (5, 5)) binary_mask cv2.morphologyEx(binary_mask, cv2.MORPH_CLOSE, kernel) return binary_mask邏輯說明為什么threshold設(shè)為0.0而不是0.5因?yàn)镾AM2訓(xùn)練時用了focal loss模型對正樣本的輸出概率往往偏低即使目標(biāo)區(qū)域概率只有0.3它仍然是模型認(rèn)定的前景直接按0.5截?cái)鄷G掉大量真實(shí)目標(biāo)像素。這是很多人覺得SAM2分割效果比預(yù)期差的一個重要原因。去掉小連通域是為了避免模型在非目標(biāo)區(qū)域產(chǎn)生零星誤判。參數(shù)說明connectedComponentsWithStats返回每個連通域的面積信息500是過濾閾值如果你的目標(biāo)物體本身很小這個值要調(diào)低到50甚至10。閉運(yùn)算的kernel大小5,5對大多數(shù)自然圖像夠用如果mask邊界鋸齒嚴(yán)重可以加大到 (7,7)但注意閉運(yùn)算會輕微膨脹邊界對精細(xì)分割任務(wù)反而有副作用。這一步的后處理在可視化或生成標(biāo)注時非常關(guān)鍵。5. SAM2跑通的常見問題與排查路徑這一章匯總了跑通過程中最常見的五個攔路虎每條都是先現(xiàn)象、后原因、再解決方便你對照排查。5.1weights[key] size mismatch權(quán)重層尺寸不匹配現(xiàn)象加載checkpoint時報(bào)size mismatch for ...比如某個卷積層的weight維度對不上。原因權(quán)重文件對應(yīng)的config與你現(xiàn)在傳入的yaml配置不一致。最常見的場景是你拿了大模型hiera_l的權(quán)重但config里寫的是小模型hiera_t的結(jié)構(gòu)導(dǎo)致每一層的維度都差了一截。解決重新檢查config路徑和權(quán)重文件名是否配套。官方幾種配置分別對應(yīng)不同的模型規(guī)模你需要在configs/sam2/目錄下找到與權(quán)重匹配的那個yaml。如果文件名一樣但還報(bào)錯檢查下載的權(quán)重是否完整——某些網(wǎng)盤下載的zip會損壞用torch.load時改成mmapTrue有時能跳過加載階段。5.2CUDA out of memory顯存溢出現(xiàn)象調(diào)用predict時拋RuntimeError: CUDA out of memory。原因SAM2的Hiera模型參數(shù)量大圖像編碼器單次前向占用顯存較高分辨率大或batch設(shè)多了顯存直接爆。解決先把圖像縮到1024以內(nèi)前文預(yù)處理模塊已經(jīng)做了如果還爆把模型切成sam2_hiera_t那個資源占用最低的版本。另外PyTorch的顯存分配器會保留空閑緩存你可以在set_image后調(diào)用torch.cuda.empty_cache()清理。如果顯卡只有4GB顯存建議直接用CPU跑靜態(tài)圖分割雖然慢但至少能出結(jié)果。5.3KeyError: resolution或加載checkpoint報(bào)缺鍵現(xiàn)象加載模型時提示某個key不存在比如resolution或prompt_encoder。原因你拿到的checkpoint不是SAM2的而是第一代SAM的。兩代的state_dict命名有差異特別是prompt encoder和memory bank相關(guān)層的命名完全不同。解決確認(rèn)zip包里的權(quán)重文件來源如果是從網(wǎng)盤里整合的很可能是把一代替換成了二代。你可以用torch.load打印state_dict的鍵名看一下有沒有image_encoder.trunk開頭的鍵如果只有image_encoder而沒有trunk那就是拿錯了版本。這個檢查十秒鐘就能定位。5.4 分割結(jié)果全黑或全白圖像預(yù)處理問題現(xiàn)象模型能跑通但輸出的mask是全黑的無目標(biāo)或全白的全目標(biāo)。原因90%的情況是圖像顏色通道沒轉(zhuǎn)——cv2.imread讀進(jìn)來是BGR直接丟給模型導(dǎo)致特征極度錯亂。另一個可能是你把圖像做歸一化時像素值被縮放到0~1后又被減均值除方差但SAM2內(nèi)部已經(jīng)做了歸一化你重復(fù)操作會把分布徹底打亂。解決嚴(yán)格按官方demo的預(yù)處理來——讀取圖像、轉(zhuǎn)RGB、resize到1024、轉(zhuǎn)float和/255.0不要額外加歸一化。5.5 視頻分割跑起來特別慢未啟用記憶機(jī)制現(xiàn)象對視頻逐幀調(diào)predict每幀都要1秒以上一個10秒視頻跑半天。原因直接把靜態(tài)圖的推理邏輯套在視頻上每幀獨(dú)立分割沒有利用SAM2的視頻記憶組件。SAM2的視頻分割應(yīng)該用專門的Sam2VideoPredictor它支持跨幀的特征記憶和傳播后續(xù)幀只需要處理變化部分速度提升一個量級。解決換用segment_anything_2/video/predictor.py里的接口并傳入幀序列逐幀傳入add_new_frame或直接批量預(yù)測。這一條是很多從SAM一代遷移過來的老手最容易忽視的。6. 進(jìn)階用視頻分割做半自動標(biāo)注時的引用幀選擇如果你的目標(biāo)是從壓縮包跑到實(shí)際場景——比如用SAM2做數(shù)據(jù)標(biāo)注、視頻目標(biāo)跟蹤需要再深入一點(diǎn)的是「引用幀」的選取。視頻分割里你在一幀上打點(diǎn)提示作為引用模型會把分割結(jié)果傳播到前后幀引用幀選得好整個序列的mask質(zhì)量會穩(wěn)定選得差則反饋放大錯誤。from segment_anything_2.video import Sam2VideoPredictor predictor Sam2VideoPredictor(config_path, checkpoint_path, devicecuda) with torch.inference_mode(): state predictor.init_state(video_pathyour_video.mp4) # 在中間幀添加提示 frame_idx len(state[images]) // 2 # 選擇視頻中間幀 predictor.add_new_points_or_box( inference_statestate, frame_idxframe_idx, obj_id0, pointsnp.array([[400, 300]]), labelsnp.array([1]), ) # 前向傳播 for idx in range(len(state[images])): masks, scores, _ predictor.propagate_in_video(state, start_frame_idxframe_idx, reverseFalse)邏輯說明引用幀的選擇原則是「目標(biāo)姿態(tài)最典型、遮擋最少的一幀」。常見做法是取視頻中目標(biāo)居中、面積最大的那一幀而不是第一幀。因?yàn)榈谝粠繕?biāo)可能剛進(jìn)入畫面被邊緣截?cái)嗄Ｐ蛯W(xué)到的特征不完整傳播后誤差累積。中間幀通常目標(biāo)完整且運(yùn)動速度適中便于模型提取穩(wěn)定的外觀特征。參數(shù)說明obj_id表示當(dāng)前追蹤的目標(biāo)ID同時追蹤多個目標(biāo)時用不同ID區(qū)分add_new_points_or_box是在指定幀上添加提示信息這個函數(shù)是視頻分割的核心交互接口。propagate_in_video會從start_frame_idx開始向后逐幀傳播mask如果你需要雙向傳播先正向跑一遍再從引用幀反向跑一遍。踩過這個坑之后我的習(xí)慣是拿到視頻先抽幀預(yù)覽一遍挑目標(biāo)最清晰的那幀做提示而不是隨手點(diǎn)第一幀。這樣下來一張mask的精度能提升不少后處理的時間反而省了。另外如果是長時間視頻幾分鐘建議分段處理每段單獨(dú)選引用幀避免模型在長時序中丟失目標(biāo)外觀。希望這篇文章能讓你在解壓zip之后少走幾個彎路快速跑通SAM2并做出能用的分割結(jié)果用模型做標(biāo)注也好、做分析也好一步到位。本文還有配套的精品資源點(diǎn)擊獲取