1.HuggingFace的pipeline作用
pipeline 是 HuggingFace 的一个高级封装，用来把模型 + 预处理 + 推理 + 后处理 组合成一个“可直接调用的工具”。
它让你不用管模型内部细节，直接通过统一接口调用。
比如SAM3就提供了"mask-generation"这个功能，一行代码直接调用SAM3得到输出。
pipeline的缺点：
🚫 1. 不能高度自定义
🚫 2. 参数固定，不易扩展
🚫 3. 不适合生产部署
速度慢、无法精准管理 GPU 资源
pipeline 强在简单，但弱在灵活。
如果项目需要灵活多变的功能需求，那就不适合 pipeline。
2.公共方法写法
def _segment_instance_service( *, image_bytes, text=None, input_boxes=None, input_boxes_labels=None, return_geojson=False, threshold=0.25, mask_threshold=0.25 ):
,强制后面的所有参数必须使用关键字传参（keyword-only arguments）
也就是说， 后面的参数：
不能用位置传参
只能写成 key=value 的方式
公共方法写法一般参数较多，用位置传参（即位置一一对应，少传多传乱传都会报错出bug）容易出错，key=value方式传参更更好，更易读
3.Python 中的私有函数约定
以 下划线 _ 开头，就是 Python 的非强制私有约定：
def _image_interact_service(...):
这是模块内部使用的函数
外部模块不应该调用
IDE、文档工具会把它当成“内部 API”隐藏
from module import * 不会导入它
4.service 层做json结构校验
🧱 最推荐的做法：在 service 层 做结构校验
controller(API 路由层) 只负责解析 JSON 字符串 → Python 对象
将输入规范与示例写给AI即可，生成的校验代码很可靠。
