2026-07-08 20:48:01 +08:00
..
2026-07-08 20:48:01 +08:00
2026-07-08 20:48:01 +08:00
2026-07-08 20:48:01 +08:00
2026-07-08 20:48:01 +08:00
2026-07-08 20:48:01 +08:00
2026-07-08 20:48:01 +08:00
2026-07-08 20:48:01 +08:00

SAM3 生产推理服务(prod_server)

把 SAM3 以与老服务 SegmentAnything2/api.py 逐字一致的 HTTP 接口暴露出来的推理服务(SAM2.1 → SAM3 的 drop-in 升级)。交付物 = 一个自包含 Docker 镜像 sam3-server:cu128,端点 GET /health + POST /api/v1/segment,掩码以 polygons(cv2 简化多边形)返回。运行时零联网、生产不挂载任何目录。本目录的调用案例(client 脚本)除推理走服务外,渲染/IO/路径/文档结构与 demos/ 对齐。

points / bboxes 两路与老服务逐字一致;texts(开放词表,多短语)是 SAM3 相对老服务的增量——老服务(SAM2)无文本能力。三种 prompt points / bboxes / texts 平级,老客户端不传 texts 则行为完全不变。


无缝替代:改了什么、没改什么

老服务 SegmentAnything2 本服务 prod_server
模型 SAM 2.1(large/small,fp32) SAM3(sam3.pt,bf16 autocast)
框架/端口 FastAPI + uvicorn,容器 80 FastAPI + uvicorn,容器 80
端点 GET /health、POST /api/v1/segment 同名同路径
请求/响应字段 SegmentRequest/Response points/bboxes 逐字段一致;texts/threshold 为 SAM3 增量(可选)
坐标系 / 错误串 — 逐字一致
  • 老客户端只需改 URL/端口,请求体一行都不用动:model 仍可传 SAM-2.1-Large/SAM-2.1-Small(内部别名 → SAM-3),points/bboxes 格式完全不变。
  • 响应统一包络 {status:int, message:str, data:list|null};业务错误 HTTP 永远 200,对错看 status 字段(与老服务一致;只有缺必填字段这类参数错误才是 HTTP 422)。
  • 掩码数值会因模型升级而变化(这是预期),但形状、字段、坐标系、错误语义不变——这正是「无缝」的含义。
  • texts 是 SAM3 增量:老服务(SAM2)无文本能力;本服务在同一个 /api/v1/segment 上加可选 texts(开放词表短语列表)+ threshold。老客户端不传 texts 时,请求体与响应与老服务逐字一致——「无缝」对老客户端始终成立。

坐标系约定(必读 · 最容易踩坑)

所有坐标都是「绝对像素」,基于你本次请求发的那张图的原始分辨率;原点一律在左上角,y 轴向下。 没有 0~1 归一化,没有「行/列」写法。

量 请求字段 格式 单位 / 取值 关键约定
图片 image data:image/jpeg;base64,...(data URI) — 服务端强制转 RGB(alpha 通道丢弃);坐标基准 = 你发的这张图的分辨率
点 points[].point [x, y] 绝对像素 x=列(宽方向)在前,y=行(高方向)在后;原点左上、y 向下
点标签 points[].label 1 或 0 — 1=正点(前景)、0=负点(背景)
框 bboxes[] [x, y, w, h] 绝对像素 (x,y)=左上角,w,h=宽高 → xywh;服务端转 xyxy 喂模型
文本 texts[] ["a truck", "a bottle", ...] 开放词表短语 SAM3 增量;多短语一次查,每个短语各自 grounding,实例打所属短语
阈值 threshold float 默认 0.5 仅 texts 分支用;越低实例越多(更噪)
输出多边形 data[].polygons [[x,y], ...] 整数绝对像素 与输入同坐标系(左上原点);取首条外轮廓;approxPolyDP 简化
输出框 data[].box [x, y, w, h] 绝对像素 xywh 仅 texts 分支返回;与 bboxes 输入同约定
输出分数 data[].score float 0~1 仅 texts 分支返回;sigmoid(class)×sigmoid(presence)
输出短语 data[].text str — 仅 texts 分支返回;该实例所属的输入短语

易错点(务必照此):

  1. [x, y] 别写反:横坐标 x 在前、纵坐标 y 在后。写成 [y, x](行列)会偏到错误位置。
  2. 框是 xywh(左上角 + 宽高),不是 xyxy(左上 + 右下)。例:左上 (580,136)、宽 40、高 37 的框写 [580,136,40,37]。
  3. 点标签 1=正、0=负(注意不是反的;与老服务 api.py 注释一致)。
  4. 坐标基准随你发的图走:若你先把图 resize 再发,点/框坐标必须匹配 resize 后的尺寸。
  5. image 必须带 data URI 前缀 data:image/jpeg;base64,:服务按第一个逗号切分取后半段 base64。
  6. 输出只给「首条轮廓」:掩码若有多个不连通块,只返回其中一个的外轮廓;内部孔洞(RETR_EXTERNAL)不计入。要完整掩码请自行用 cv2.fillPoly(polygons) 还原(client 正是这么做的)。
  7. points / bboxes / texts 三者平级互斥:一条请求只用一种 prompt 类型;同传多种时按 points → bboxes → texts 顺序取首个。texts 是字符串列表 ["a truck", "a bottle", ...](与 points/bboxes 同为 list、平级),不是单个字符串。

运行环境

conda activate sam3          # 客户端与 demos 同环境:torch+cv2+PIL+numpy(渲染复用 demos/_common)

客户端调用前服务必须先起来(构建/启动见下文「构建与启动」)。调用本机服务时务必先关 proxy,否则 127.0.0.1 流量会被代理拦成 502 Bad Gateway:

unset http_proxy https_proxy HTTP_PROXY HTTPS_PROXY
export SAM3_SERVER=http://127.0.0.1:8080

运行约定:所有命令在仓库根目录 SAM3_Cloud/ 下执行(本 README 位于其 prod_server/ 子目录),形如 python3 prod_server/client_xxx.py --input assets/inputs/... --output assets/outputs/...。输入多媒体在 assets/inputs/,输出在 assets/outputs/(即 SAM3_Cloud/assets/,与本目录平级)。

构建与启动(容器)

已构建镜像:

ccr-29eug8s3-pub.cnc.bj.baidubce.com/public/sam3_serevr:v20260708_v1

镜像从源码构建(在 SAM3_Cloud/ 下):

bash prod_server/prepare_weights.sh                 # 权重入构建上下文 checkpoints/
docker build --build-arg HTTP_PROXY=http://192.168.16.68:18000 \
             --build-arg HTTPS_PROXY=http://192.168.16.68:18000 \
             --build-arg http_proxy=http://192.168.16.68:18000 \
             --build-arg https_proxy=http://192.168.16.68:18000 \
             -f prod_server/Dockerfile -t sam3-server:cu128 .

代理 build-arg 是本机出口(apt 直连、pip/uv 走代理、torch 走 --torch-backend=cu128)。镜像构建末尾会跑 import sam3; from app.main import app + 权重存在性自检,失败即 fail-fast。

启动 + 探活:

docker run -d --rm --gpus all -p 8080:80 sam3-server:cu128      # 宿主 8080 -> 容器 80
until curl -sf http://127.0.0.1:8080/health; do sleep 2; done   # /health 通了才可用(模型载完才开放端口)

冷启动 GPU 已热时约 10s,首次冷构建约 2.5 min。运行时零联网(权重在镜像内、HF_HUB_OFFLINE=1),可 --network=none 验证。


公共模块

  • demos/_common.py(复用,不重复实现):渲染 + IO——overlay_masks(半透明掩码 + 框 + #编号)、draw_points(蓝正红负)、save_image / load_image、in_path / out_path(资产路径)。与 demos 同源、零漂移。
  • prod_server/_client_common.py(服务交互):file_to_data_uri(图→data URI)、post(HTTP POST)、polygons_to_mask(服务 polygons→bool 掩码,cv2.fillPoly 还原首条轮廓)。客户端像 demos 一样在 sam3 env 下跑(import 触发 torch/cv2,但不加载模型——模型单例懒加载)。

能力 1 | 点交互分割(points) · 走服务

兼容经典 SAM click-to-segment:正点(前景)/负点(背景)交互分割单个实例。结构镜像 demos/02_interactive_points.py——先画一张点位置图,再出结果图。

  • 输入:image(data URI,必填)+ model(默认 SAM-3;老服务名 SAM-2.1-Large/SAM-2.1-Small 作别名)+ points([{"point":[x,y],"label":1|0}, ...],xy 绝对像素,1=正/0=负)
  • 输出:data=[{"polygons":[[x,y], ...]}],恒 1 条;polygons 是掩码首条轮廓的简化多边形,xy 整数绝对像素;无轮廓时 []
  • 入口:POST /api/v1/segment(服务内部 predict_inst(..., multimask_output=False),直接返单掩码;demos 02 是 3 候选取 IoU 最高——服务已替你选好)
  • 模型:SAM3 sam3.pt,服务端 enable_inst_interactivity=True

1.1 街景(正点在人上、负点在背景) · test_image.jpg

点位置(蓝=正 [544,472]、红=负 [459,306]):

python3 prod_server/client_segment_points.py \
    --input assets/inputs/test_image.jpg \
    --points-out assets/outputs/server_02_testimage_points.jpg \
    --output      assets/outputs/server_02_testimage_result.jpg

点位置 · test_image(蓝正红负)

分割结果(服务返 110 点多边形,本地 fillPoly 还原 + overlay_masks 叠加):

点分割结果 · test_image

对应的原始请求/响应(坐标均为 test_image 1280×720 的绝对像素):

// 请求
{"image":"data:image/jpeg;base64,/9j/4AAQ...","model":"SAM-3",
 "points":[{"point":[544,472],"label":1},{"point":[459,306],"label":0}]}
// 响应(polygons 共 110 点,只显示前 4 个)
{"status":200,"message":"success",
 "data":[{"polygons":[[540,307],[530,311],[525,317],[521,326] /* …共 110 点… */]}]}

默认 --pos 544 472 --neg 459 306 是 test_image 上一个人的点;换图请自带 --pos/--neg 坐标。


能力 2 | 框 prompt 分割(bboxes) · 走服务

用矩形框指定目标;传 N 个框返回 N 条结果。结构镜像 demos/01_box_prompt.py——出一张**掩码 + 框 + #编号**的结果图。

  • 输入:image + model + bboxes([[x,y,w,h], ...],xywh 像素,服务端转 xyxy)
  • 输出:data 有 N 条,每条 {"polygons":[[x,y], ...]},顺序对应输入框
  • 入口:POST /api/v1/segment(bboxes 分支)
  • 模型:SAM3 sam3.pt

2.1 杂货(塑料袋) · groceries.jpg

python3 prod_server/client_segment_bbox.py \
    --input assets/inputs/groceries.jpg \
    --box 580 136 40 37 \
    --output assets/outputs/server_01_groceries_box.jpg

框分割结果 · groceries(掩码 + 绿框 #0)

对应的原始请求/响应(groceries 800×534,框 [580,136,40,37] xywh):

// 请求
{"image":"data:image/jpeg;base64,/9j/4AAQ...","model":"SAM-3","bboxes":[[580,136,40,37]]}
// 响应(polygons 共 56 点,只显示前 4 个)
{"status":200,"message":"success",
 "data":[{"polygons":[[582,138],[581,139],[581,143],[580,144] /* …共 56 点… */]}]}

服务不返回 score,故结果图编号只画 #0、无分数(demos 01 的分数是本地 grounding 产物,服务契约里没有)。默认 --box 580 136 40 37 是 groceries 上一个塑料袋的框;换图请自带 --box xywh。


能力 3 | 开放词表分割(texts → mask + box) · 走服务

SAM3 核心能力(老 SAM2 服务没有):给一个/多个开放词表文本短语,检测并分割图中所有匹配实例,输出每个实例的 mask、包围框、置信度分数、所属短语。结构镜像 demos/00_text_grounding.py——出一张掩码 + 框 + #编号 + 分数的结果图。

  • 输入:image(data URI,必填)+ model(默认 SAM-3;老服务名作别名)+ texts(["a truck", "a bottle", ...],开放词表短语列表,与 points/bboxes 平级)+ threshold(默认 0.5,越低实例越多)
  • 输出:data=[{"text": <短语>, "polygons":[[x,y],...], "box":[x,y,w,h], "score":float}, ...],跨所有短语的实例平铺;每条带所属 text;box 为 xywh 绝对像素;无匹配时 data=[]
  • 入口:POST /api/v1/segment(texts 分支;服务端 set_image 只算一次,按短语循环 set_text_prompt 各自 grounding,实例打 text 归属后累积)
  • 模型:SAM3 sam3.pt,build_sam3_image_model

3.1 卡车(单实例,score 0.83) · truck.jpg

python3 prod_server/client_segment_text.py \
    --input assets/inputs/truck.jpg --texts "a truck" \
    --output assets/outputs/server_00_truck.jpg

文本分割结果 · truck(掩码 + 框 #0 0.83)

对应的原始请求/响应(truck 1800×1200):

// 请求
{"image":"data:image/jpeg;base64,/9j/4AAQ...","model":"SAM-3","texts":["a truck"],"threshold":0.5}
// 响应(1 个实例;polygons 共 67 点,只显示前 4 个)
{"status":200,"message":"success",
 "data":[{"text":"a truck","score":0.832,
          "box":[85.98,281.91,1624.62,567.77],
          "polygons":[[85,721],[97,731],[128,732],[146,740] /* …共 67 点… */]}]}

3.2 杂货(多实例:5 个塑料袋) · groceries.jpg

python3 prod_server/client_segment_text.py \
    --input assets/inputs/groceries.jpg --texts "a plastic bag" --threshold 0.5 \
    --output assets/outputs/server_00_groceries.jpg

文本分割结果 · groceries(5 个塑料袋)

// 请求
{"image":"data:image/jpeg;base64,/9j/4AAQ...","model":"SAM-3","texts":["a plastic bag"],"threshold":0.5}
// 响应(5 个实例,均 text="a plastic bag";首条 score 0.58、box≈[580,138,40,39]、55 点)
{"status":200,"message":"success",
 "data":[{"text":"a plastic bag","score":0.578,"box":[579.62,137.69,39.77,39.32],"polygons":[ /* … */ ]} /* …共 5 条… */]}

3.3 多短语(一次查多类:5 塑料袋 + 9 包装) · groceries.jpg

texts 是列表,一次请求查多个类别,每个实例带所属 text:

python3 prod_server/client_segment_text.py \
    --input assets/inputs/groceries.jpg --texts "a plastic bag" "a package" --threshold 0.5 \
    --output assets/outputs/server_00_groceries_multi.jpg

文本分割结果 · groceries 多短语(5 塑料袋 + 9 包装)

// 请求(列表里两个短语)
{"image":"data:image/jpeg;base64,/9j/4AAQ...","model":"SAM-3","texts":["a plastic bag","a package"],"threshold":0.5}
// 响应:14 条实例平铺,5 条 text="a plastic bag" + 9 条 text="a package"
{"status":200,"message":"success","data":[{"text":"a plastic bag", /* … */ },{"text":"a package", /* … */ } /* …共 14 条… */]}

服务按短语循环 grounding:每个短语等价于独立跑一次 set_text_prompt(vision 特征只算一次复用),故多短语的实例天然带所属短语标签。结果图按实例序上色(#i),同短语不一定同色。


错误与边界

业务错误(HTTP 仍 200,看 body.status):

// 未知 model(含 SAM-3.1,它是 multiplex 专用,segment 不接受)
// 请求: {"image":"...","model":"SAM-9-X","points":[{"point":[544,472],"label":1}]}
{"status":500, "message":"Model SAM-9-X not found", "data":null}

// points / bboxes / texts 都不传(兜底错误;错误串为保老客户端 drop-in 字节一致,逐字保留、未改写含 texts)
// 请求: {"image":"...","model":"SAM-3"}
{"status":500, "message":"points and boxes cannot be both None", "data":null}

参数错误(HTTP 422,pydantic 校验,如缺必填 image):

curl -s -o /dev/null -w '%{http_code}\n' -X POST http://127.0.0.1:8080/api/v1/segment \
  -H 'Content-Type: application/json' -d '{"model":"SAM-3","points":[{"point":[544,472],"label":1}]}'
# 422

points / bboxes / texts 三者平级互斥,同传时按 points → bboxes → texts 顺序取首个(与老服务 points/bboxes 优先级一致,texts 作为第三 peer 追加)。 texts 分支返跨短语实例平铺,每条带 text/box/score(points/bboxes 分支只返 polygons,不带)。threshold 越低实例越多(更噪)。 并发:模块级 GLOBAL_LOCK 串行保护 set_image + predict(SAM 模型非线程安全),uvicorn 单 worker——吞吐为单请求串行,与老服务一致。


复现说明(闭环)

从 SAM3_Cloud/ 根目录,一条龙可复现全部产物:

# 0) 关 proxy(调本机服务必需)
unset http_proxy https_proxy HTTP_PROXY HTTPS_PROXY
export SAM3_SERVER=http://127.0.0.1:8080

# 1) 构建 + 启动 + 探活
bash prod_server/prepare_weights.sh
docker build --build-arg HTTPS_PROXY=http://192.168.16.68:18000 \
             --build-arg https_proxy=http://192.168.16.68:18000 \
             -f prod_server/Dockerfile -t sam3-server:cu128 .
docker run -d --rm --gpus all -p 8080:80 sam3-server:cu128
until curl -sf http://127.0.0.1:8080/health; do sleep 2; done

# 2) 调用(渲染复用 demos/_common,sam3 env 下跑)
python3 prod_server/client_segment_points.py          # → server_02_testimage_{points,result}.jpg
python3 prod_server/client_segment_bbox.py            # → server_01_groceries_box.jpg
python3 prod_server/client_segment_text.py            # → server_00_truck.jpg(开放词表 texts → mask+box+score)

校验口径:/health 返回 status:200;点交互返 110 点多边形(同一个人,与 demos/02 结果掩码 IoU≈0.97)、框 prompt 返 56 点多边形;文本 prompt(texts)truck 返 1 实例(score≈0.83)、groceries "a plastic bag" 返 5 实例、多短语 ["a plastic bag","a package"] 返 14 实例(5+9,跨短语平铺、每条带 text)。所有坐标落在图片像素范围内;六张 assets/outputs/server_* 落地。server_0{0,1,2}_* 与 demos 的 0{0,1,2}_* 并排,可直观对比「本地推理 vs 服务推理」。