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)无文本能力。三种 promptpoints/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 分支返回;该实例所属的输入短语 |
易错点(务必照此):
[x, y]别写反:横坐标 x 在前、纵坐标 y 在后。写成[y, x](行列)会偏到错误位置。- 框是
xywh(左上角 + 宽高),不是xyxy(左上 + 右下)。例:左上(580,136)、宽40、高37的框写[580,136,40,37]。 - 点标签
1=正、0=负(注意不是反的;与老服务api.py注释一致)。 - 坐标基准随你发的图走:若你先把图 resize 再发,点/框坐标必须匹配 resize 后的尺寸。
image必须带 data URI 前缀data:image/jpeg;base64,:服务按第一个逗号切分取后半段 base64。- 输出只给「首条轮廓」:掩码若有多个不连通块,只返回其中一个的外轮廓;内部孔洞(
RETR_EXTERNAL)不计入。要完整掩码请自行用cv2.fillPoly(polygons)还原(client 正是这么做的)。 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 一样在sam3env 下跑(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
分割结果(服务返 110 点多边形,本地 fillPoly 还原 + overlay_masks 叠加):
对应的原始请求/响应(坐标均为 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 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 上一个塑料袋的框;换图请自带--boxxywh。
能力 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 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
// 请求
{"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
// 请求(列表里两个短语)
{"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 服务推理」。





