ModelScope Pipelines 模块 API 全解析：pipeline() 工厂、Pipeline 基类与六大领域流水线

ModelScope Pipelines 模块 API 全解析pipeline() 工厂、Pipeline 基类与六大领域流水线【免费下载链接】modelscopeModelScope: bring the notion of Model-as-a-Service to life.项目地址: https://gitcode.com/GitHub_Trending/mo/modelscopeModelScope 的modelscope.pipelines模块是该框架将模型即服务Model-as-a-Service落地到推理侧的核心 API 层它把模型加载、预处理、前向推理、后处理封装成开箱即用的 Pipeline 对象。本文以仓库文档 modelscope.pipelines.rst 为主线完整梳理该模块的 API 文档结构——builder工厂函数、base基类以及 cv、nlp、multi-modal、audio、science 六大领域流水线——并结合源码解读pipeline()的调用链、Pipeline基类的执行流程与注册机制帮助你掌握从一个任务名 一个模型到可落地的推理服务的完整路径。模块总览modelscope.pipelines的组织结构modelscope.pipelines是 ModelScope 推理管线的顶层包。从文档索引可以看到它的 API 结构由以下部分组成modelscope.pipelines.basePipeline 抽象基类体系包含Pipeline与DistributedPipeline两个核心类modelscope.pipelines.builder流水线构建工厂提供pipeline()与build_pipeline()两个入口函数modelscope.pipelines.cv计算机视觉领域流水线约 60 个 Pipeline 类modelscope.pipelines.nlp自然语言处理领域流水线约 30 个 Pipeline 类modelscope.pipelines.multi-modal多模态流水线覆盖图文、视频-文本等任务modelscope.pipelines.audio语音与音频流水线modelscope.pipelines.science科学计算类流水线。包入口 modelscope/pipelines/init.py 只做了三件事导入audio、cv、multi_modal、nlp四个领域子包导出Pipeline基类并导出builder.pipeline工厂函数。因此用户侧最常见的用法是from modelscope.pipelines import pipeline通过工厂函数拿到具体任务的 Pipeline 实例。其余各子模块的独立 API 文档如 modelscope.pipelines.cv.rst、modelscope.pipelines.nlp.rst、modelscope.pipelines.builder.rst、modelscope.pipelines.base.rst 等构成了该页toctree的下一级导航Sphinx 会通过automodule自动提取各模块的 docstring 生成 API 参考。builderpipeline() 工厂函数与 build_pipeline()modelscope.pipelines.builder.rst 定义了本模块最核心的两个编程接口build_pipeline与pipeline。对应的实现位于 modelscope/pipelines/builder.py。pipeline()最常用的入口pipeline()是一个工厂方法根据任务名和模型返回对应的Pipeline实例。其完整签名如下def pipeline(task: str None, model: Union[str, List[str], Model, List[Model]] None, preprocessorNone, config_file: str None, pipeline_name: str None, framework: str None, device: str None, model_revision: Optional[str] DEFAULT_MODEL_REVISION, ignore_file_pattern: List[str] None, trust_remote_code: bool False, **kwargs) - Pipeline:各参数的作用与注意事项参数类型说明taskstr任务名决定返回哪个 Pipeline 类取值参见Tasks常量如text-classification、image-classification。与pipeline_name至少提供一个。modelstr/List[str]/Model/List[Model]模型名称ModelScope Hub 仓库名或本地目录或模型对象。传入多个模型时支持多模型 Pipeline如audio-kws任务可传[damo/audio-tts, damo/auto-tts2]。preprocessorPreprocessor可选显式指定预处理器对象否则从模型目录自动加载。config_filestr可选配置文件路径用于显式指定 Pipeline 构建配置。pipeline_namestr可选Pipeline 类名或注册别名用于绕过任务名直接指定流水线类型。frameworkstr可选框架类型torch / tf用于在回退到 transformers pipeline 时指定。devicestr推理设备支持cpu、gpu、cuda、gpu:X、cuda:X。缺省时默认gpu。model_revisionstr模型版本号从 Hub 拉取模型时使用多模型时要求所有模型版本一致默认取DEFAULT_MODEL_REVISION。ignore_file_patternstr/List下载模型时忽略的文件模式如精确文件名或扩展名用于跳过不需要的大文件。trust_remote_codebool是否允许执行模型配置中声明的远程代码/插件默认False这是重要的安全开关。源码 docstring 给出了四种典型用法 # 使用任务默认模型 p pipeline(image-classification) # 通过模型名创建自动从 Hub 下载 p pipeline(text-classification, modeldamo/distilbert-base-uncased) # 通过模型对象创建 resnet Model.from_pretrained(Resnet) p pipeline(image-classification, modelresnet) # 通过多个模型名创建多模型流水线 p pipeline(audio-kws, model[damo/audio-tts, damo/auto-tts2])pipeline() 的内部决策链从 builder.py 的实现可以还原pipeline()的完整决策逻辑合法性检查task与pipeline_name均为空时直接抛出ValueError(task or pipeline_name is required)。模型信任检查通过check_model_from_owner_group(model_id)判断模型是否来自可信官方组织若可信则自动放大trust_remote_code。确定 pipeline_name未指定pipeline_name且model是 Hub 路径时先调用read_config读取模型仓库的configuration.json优先取cfg.safe_get(pipeline, {}).get(type)作为流水线类型若配置未声明且任务是text_generation/chat则会走 LLM 分支默认llm_frameworkswift并通过external_engine_for_llm_checker判断是否切换到llm流水线见external_engine_for_llm_checker与 llm_pipeline.py 相关的LLMAdapterRegistrymodel是Model对象时从first_model.pipeline配置解析结果获取流水线信息都没命中时调用get_default_pipeline_info(task)查表DEFAULT_MODEL_FOR_PIPELINE该表由add_default_pipeline_info注册返回任务对应的默认 Pipeline 与默认模型。模型落地normalize_model_input会把 Hub 模型 id 通过snapshot_download下载为本地目录保证后续Model.from_pretrained拿到的是合法本地路径对于模型列表会逐一下载。插件与安全解析模型配置中的plugins与allow_remote字段若存在插件声明但用户未显式设置trust_remote_codeTrue会抛出RuntimeError拒绝加载防止执行恶意远程代码。降级回退若 ModelScope 自身找不到合适的 Pipelineembedding 类任务尝试sentence_transformers_pipeline安装了 transformers 时尝试hf_pipeline回退。组装并构建把model、device缺省gpu、kwargs、显式preprocessor合并为ConfigDict最终调用build_pipeline(cfg, task_nametask)。build_pipeline()注册表驱动的构建def build_pipeline(cfg: ConfigDict, task_name: str None, default_args: dict None): return build_from_cfg(cfg, PIPELINES, group_keytask_name, default_argsdefault_args)它基于PIPELINES Registry(pipelines)注册表按task_name分组查找 Pipeline 类并用配置实例化。这也是自定义流水线的入口只要用PIPELINES.register_module(group_key..., module_name...)注册的类都能被pipeline()统一调度详见下文注册机制。basePipeline 基类与 DistributedPipelinemodelscope.pipelines.base.rst 中列出两个类实现在 modelscope/pipelines/base.py。Pipelinepreprocess → forward → postprocess 三段式抽象Pipeline是一个ABC抽象基类构造函数接受config_file、model、preprocessor、device、auto_collate、device_map等参数。其构造期会完成设备校验verify_device、单/多模型初始化initiate_single_model/initiate_multiple_models、配置加载、预处理器加载缺省时用Preprocessor.from_pretrained(model_dir)、框架识别_get_framework读取各模型configuration.json的framework字段。每个具体 Pipeline 只需实现三个抽象接口方法职责preprocess(inputs, **preprocess_params)将原始输入文本、图片、音频、MsDataset等转换为模型可消费的特征基类默认委托给self.preprocessor。forward(inputs, **forward_params)调用self.model执行前向推理基类默认实现self.model(inputs)。postprocess(inputs, **post_params)将模型原始输出整理为标准输出字典对应OutputKeys基类默认raise NotImplementedError必须由子类实现。call的统一调度流程用户直接pipeline_obj(input)即可触发推理。基类__call__base.py会做如下事情首次调用前执行prepare_model()把 PyTorch 模型切到eval()并搬移到目标设备若开启compileTruetorch 2.0 编译则在此时通过compile_model编译。通过_sanitize_parameters(**kwargs)把调用参数拆分为preprocess_params、forward_params、postprocess_params三组分别注入三段流程。根据输入类型分流list逐元素调用_process_single若显式传入batch_size则走_process_batch做分批前向批内通过_batch拼接张量、_collate_fn整理数据MsDataset走_process_iterator生成器逐个 yield 结果天然支持流式处理大数据集其他单条输入直接_process_single。_process_single内部按预处理 → 设备上下文device_placement→torch.no_grad()→ collate → forward → postprocess的顺序执行并在进入前调用_check_input、退出前调用_check_output依据TASK_INPUTS/TASK_OUTPUTS校验输入输出键是否合规。此外Pipeline还内置了对LLMPipeline的特殊处理当输入是角色列表时会被包装为{messages: input}以便适配对话式 LLM 的 messages 语义。DistributedPipeline多卡模型推理DistributedPipeline用于加载跨多 GPU 切分的模型如 Megatron 训练出的巨型模型其工作流程在类 docstring 中有明确说明从configuration.json读取全局配置将 multiprocessing 启动方式设置为spawn按world_size打开一个多进程池实例化各模型分片调用子类实现的_instantiate_one设置master_ip默认127.0.0.1与自动分配的master_port并写入MASTER_ADDR/MASTER_PORT环境变量推理时主进程做 preprocess随后forward通过model_pool.map(_forward_one, ...)把输入广播给所有分片收集结果再在主进程 postprocess。world_size的解析逻辑为优先取megatron.world_size缺省回退到model.world_size。注意DistributedPipeline不调用super().__init__而是用类方法自行初始化模型两个抽象类方法_instantiate_one与_forward_one必须由派生类实现并将模型句柄保存在类字段中。六大领域流水线清单cv计算机视觉流水线60 个modelscope.pipelines.cv.rst 列出的 CV Pipeline 覆盖检测、分割、识别、生成、增强等全谱系任务包括但不限于检测类FaceDetectionPipeline、RetinaFaceDetectionPipeline、MtcnnFaceDetectionPipeline、MogFaceDetectionPipeline、CardDetectionPipeline、LicensePlateDetectionPipeline、OCRDetectionPipeline、RealtimeObjectDetectionPipeline、ImageDetectionPipeline、EasyCVDetectionPipeline、MaskDINOInstanceSegmentationPipeline等识别/分类类GeneralImageClassificationPipeline、ImageClassificationPipeline、AnimalRecognitionPipeline、GeneralRecognitionPipeline、TinynasClassificationPipeline、LiveCategoryPipeline、FaceRecognitionPipeline、MaskFaceRecognitionPipeline、ArcFaceRecognitionPipeline、FaceAttributeRecognitionPipeline、FacialExpressionRecognitionPipeline、ProductRetrievalEmbeddingPipeline、VopRetrievalPipeline等关键点/人体类Body2DKeypointsPipeline、Hand2DKeypointsPipeline、Face2DKeypointsPipeline、HumanWholebodyKeypointsPipeline、HandStaticPipeline等图像生成/编辑类Image2ImageGenerationPipeline、ImageCartoonPipeline、ImageColorizationPipeline、DDColorImageColorizationPipeline、ImageDeblurPipeline、ImageDenoisePipeline、ImageInpaintingPipeline、ImageMattingPipeline、ImageStyleTransferPipeline、ImageSkychangePipeline、ImageSuperResolutionPipeline、VideoFrameInterpolationPipeline、VideoStabilizationPipeline等分割/显著性类ImageSemanticSegmentationPipeline、ImageInstanceSegmentationPipeline、ImagePanopticSegmentationPipeline、ImagePanopticSegmentationEasyCVPipeline、ImageSalientDetectionPipeline、ShopSegmentationPipeline、ReferringVideoObjectSegmentationPipeline、VideoObjectSegmentationPipeline、TextDrivenSegmentationPipeline、EasyCVSegmentationPipeline等视频/3D 类VideoCategoryPipeline、VideoSuperResolutionPipeline、ActionDetectionPipeline、ActionRecognitionPipeline、MovieSceneSegmentationPipeline、ImageMultiViewDepthEstimationPipeline、PointCloudSceneFlowEstimationPipeline、VirtualTryonPipeline、ImageReidPersonPipeline、VisionMiddlewarePipeline、CMDSSLVideoEmbeddingPipeline、HICOSSLVideoEmbeddingPipeline等。nlp自然语言处理流水线30 个modelscope.pipelines.nlp.rst 列出的 NLP Pipeline 覆盖理解与生成两大方向分类/情感类TextClassificationPipeline、FasttextSequenceClassificationPipeline、ZeroShotClassificationPipeline、SentimentClassification相关任务对应于此序列标注类NamedEntityRecognitionPipeline、TokenClassificationPipeline、WordSegmentationPipeline、WordSegmentationThaiPipeline、InformationExtractionPipeline、TextErrorCorrectionPipeline生成/摘要类TextGenerationPipeline、TextGenerationT5Pipeline、SummarizationPipeline、ExtractiveSummarizationPipeline、MGLMTextSummarizationPipeline、CodeGeeXCodeGenerationPipeline、CodeGeeXCodeTranslationPipeline、ConversationalTextToSqlPipeline语义/检索类SentenceEmbeddingPipeline、FeatureExtractionPipeline、TextRankingPipeline、FillMaskPipeline、TableQuestionAnsweringPipeline、FaqQuestionAnsweringPipeline对话类DialogIntentPredictionPipeline、DialogModelingPipeline、DialogStateTrackingPipeline、DocumentSegmentationPipeline评测类TranslationEvaluationPipeline、TranslationQualityEstimationPipeline、UserSatisfactionEstimationPipeline以及TranslationPipeline。multi-modal、audio、sciencemulti-modalmodelscope.pipelines.multi_modal.rstStableDiffusionPipeline、ChineseStableDiffusionPipeline、TextToImageSynthesisPipeline、ImageCaptioningPipeline、VisualQuestionAnsweringPipeline、VisualGroundingPipeline、VisualEntailmentPipeline、VideoQuestionAnsweringPipeline、VideoCaptioningPipeline、AutomaticSpeechRecognitionPipeline、DocumentVLEmbeddingPipeline、MultiModalEmbeddingPipeline、GEMMMultiModalEmbeddingPipeline、VideoMultiModalEmbeddingPipeline、MGeoRankingPipelineaudiomodelscope.pipelines.audio.rstANSPipeline、InverseTextProcessingPipeline、KWSFarfieldPipeline、KeyWordSpottingKwsbpPipeline、LinearAECPipeline、TextToSpeechSambertHifiganPipelinesciencemodelscope.pipelines.science.rst科学计算领域流水线对应 modelscope/pipelines/science 目录如 Unifold 等蛋白结构任务。各领域子包内部按PIPELINES.register_module的方式把类注册到对应Tasks分组下因此所有类都可以通过pipeline(task, model)统一构建无需逐个 import。注册机制与 PipelineTemplatePIPELINES 注册表modelscope/pipelines/builder.py 定义全局注册表PIPELINES Registry(pipelines)。任何 Pipeline 类只要装饰PIPELINES.register_module(group_keyTasks.xxx, module_namexxx)即可被pipeline()/build_pipeline()按任务名调度。这一点在测试中有直接佐证仓库测试 tests/pipelines/test_builder.py 中注册了CustomSingleModelPipeline单模型与CustomMultiModelPipeline多模型两个自定义类然后通过pipeline(task..., pipeline_name...)验证工厂函数能正确实例化自定义流水线这同时演示了用户扩展自定义 Pipeline 的标准姿势。PipelineTemplate自定义流水线的模板modelscope/pipelines/pipeline_template.py 提供了一个已注册到Tasks.task_template的参考实现用于说明一个完整 Pipeline 应该如何定义。其三个接口的约定如下def preprocess(self, input: Any, max_length: int 1024, top_p: float 0.8) - Any: ... def forward(self, input: Any, max_length: int 1024, top_p: float 0.8) - Any: ... def postprocess(self, inputs: Any, postprocess_param1: str None) - Dict[str, Any]: result { OutputKeys.BOXES: np.zeros(4), OutputKeys.OUTPUT_IMG: np.zeros(10, 4), OutputKeys.TEXT_EMBEDDING: np.zeros(1, 1000) } return result模板的约定包括第一个参数是输入其后是请求参数参数必须带类型注解必要时给出默认值postprocess需返回以OutputKeys为键的标准输出字典。照此结构实现并注册即可融入 ModelScope 的统一调度体系。API 文档的生成与阅读方式modelscope.pipelines.rst是 Sphinx API 文档的索引页它通过两条指令工作.. automodule:: modelscope.pipelines自动抓取包的 docstring作为页面引言.. toctree::配合:maxdepth: 2与:caption: Pipeline Api把 base、builder、cv、nlp、multi-modal、audio、science 七个二级页面挂接到索引下。二级页面中的.. autosummary::配合classtemplate.rst位于 docs/source/_templates会为每个 Pipeline 类自动生成带完整 docstring 的 API 条目。这意味着每个 Pipeline 类的用法都直接写在源码 docstring 中。例如在pipeline()的 docstring 里就能找到完整的示例代码具体任务的参数细节则分散在modelscope/pipelines/cv、modelscope/pipelines/nlp等子目录各类的preprocess/forward/postprocess签名与注释中阅读源码即可获得最权威的参数说明。结语一条从任务名到推理服务的完整链路modelscope.pipelines模块把模型 预处理 推理 后处理收敛为一行pipeline(task, model)调用pipeline()负责解析任务与模型配置、处理下载与安全校验、决定具体 Pipeline 类Pipeline基类负责统一的设备管理、参数分流与三段式执行六大领域子包则提供覆盖 cv / nlp / multi-modal / audio / science 的丰富实现。无论是直接使用还是基于PIPELINES注册表 PipelineTemplate扩展自定义流水线该模块都是 ModelScope 推理链路上最值得掌握的入口。【免费下载链接】modelscopeModelScope: bring the notion of Model-as-a-Service to life.项目地址: https://gitcode.com/GitHub_Trending/mo/modelscope创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考