ModelScope Server 部署指南：基于 FastAPI 的通用模型服务与 vLLM 大模型推理实践

ModelScope Server 部署指南基于 FastAPI 的通用模型服务与 vLLM 大模型推理实践【免费下载链接】modelscopeModelScope: bring the notion of Model-as-a-Service to life.项目地址: https://gitcode.com/GitHub_Trending/mo/modelscope输出文章开头导读 本文围绕 ModelScope 开源库内置的modelscope server命令展开讲解如何通过一条命令将绝大多数模型CV、NLP、音频、多模态等快速拉起到本地 HTTP 推理服务并介绍使用 vLLM 引擎对外提供大模型LLM推理与 OpenAI 兼容接口的两种实践路径。读完本文你将掌握服务启动参数、接口调用方式/call、/describe、/health、二进制数据图像/音频/视频的 base64 传输约定以及结合 ModelScope 官方镜像和模型缓存目录进行服务化部署的完整方案。 /输出文章开头导读一、概述一条命令拉起模型服务modelscope server是 ModelScope 库提供的本地模型服务命令底层基于 FastAPI 框架开发requirements/server.txt 中声明了fastapi、uvicorn、sse-starlette三个服务端依赖。它通过解析模型仓库中的configuration.json自动识别任务类型并在服务启动时构建对应的 pipeline因此绝大多数模型无需额外编写服务代码即可对外提供 HTTP 推理接口。从命令行入口看server是modelscope命令族的子命令之一其注册与执行逻辑位于 modelscope/cli/server.pyclass ServerCMD(CLICommand): name server staticmethod def register(subparsers: ArgumentParser) - None: parser subparsers.add_parser( ServerCMD.name, helpLaunch the local inference HTTP server.) add_server_args(parser) parser.set_defaults(_commandServerCMD) def execute(self): run_server(self.args)也就是说modelscope server ...最终会调用 modelscope/server/api_server.py 中的run_server(args)使用 uvicorn 拉起一个 FastAPI 应用。1.1 快速启动示例使用--model_id指定模型 ID、--revision指定模型版本即可启动服务modelscope server --model_idmodelscope/Llama-2-7b-chat-ms --revisionv1.0.5服务默认监听8000端口可以通过--port参数修改端口。启动成功后可通过http://ip:port/docs查看 FastAPI 自动生成的接口文档Swagger UI。1.2 通过官方镜像一条命令启动如果环境中没有安装 ModelScope 库也可以直接使用官方镜像启动文档中的镜像构建计划仍在完善中使用时请以实际发布的镜像标签为准docker run --rm --name maas_dev --shm-size50gb --gpusdevice0 \ -e MODELSCOPE_CACHE/modelscope_cache \ -v /host_path_to_modelscope_cache:/modelscope_cache \ -p 8000:8000 \ reg.docker.alibaba-inc.com/modelscope/modelscope:ubuntu22.04-cuda11.8.0-py310-torch2.1.0-tf2.14.0-1.9.5-server \ modelscope server --model_idmodelscope/Llama-2-7b-chat-ms --revisionv1.0.5这条命令的关键点在于--shm-size50gb为大模型推理预留足够的共享内存--gpusdevice0将 GPU 设备 0 透传给容器MODELSCOPE_CACHE/modelscope_cache-v挂载将宿主机上的模型缓存目录挂载进容器避免重复下载模型-p 8000:8000将容器的 8000 端口映射到宿主机。二、服务端参数详解modelscope server的全部参数在 modelscope/server/api_server.py 的add_server_args中定义def add_server_args(parser: argparse.ArgumentParser): parser.add_argument( --model_id, requiredTrue, typestr, helpThe target model id) parser.add_argument( --revision, requiredTrue, typestr, helpModel revision) parser.add_argument(--host, default0.0.0.0, helpHost to listen) parser.add_argument(--port, typeint, default8000, helpServer port) parser.add_argument(--debug, defaultdebug, helpSet debug level.) parser.add_argument( --external_engine_for_llm, typebool, defaultTrue, helpUse LLMPipeline first for llm models.)参数是否必填默认值说明--model_id是无目标模型 ID例如modelscope/Llama-2-7b-chat-ms--revision是无模型版本号revision例如v1.0.5--host否0.0.0.0服务监听地址默认监听所有网卡--port否8000服务监听端口--debug否debug调试级别设置--external_engine_for_llm否True对 LLM 模型是否优先使用外部推理引擎LLMPipeline其中--external_engine_for_llm与 modelscope/pipelines/builder.py 中的 pipeline 构建逻辑直接相关。从源码可以看到当模型配置中未显式指定 pipeline 类型、且任务属于text_generation或chat时若该参数未显式指定则默认置为True此时会优先走外部引擎如 swift对应的 LLM pipeline如果用户不希望使用外部引擎可显式传入--external_engine_for_llmFalse。2.1 启动流程从模型下载到 pipeline 构建服务启动时通过 FastAPI 的 startup 事件完成模型的加载见 modelscope/server/core/event_handlers.pydef _startup_model(app: FastAPI) - None: logger.info(download model and create pipeline) app.state.pipeline create_pipeline( app.state.args.model_id, app.state.args.revision, app.state.args.external_engine_for_llm) info {} info[task_name] app.state.pipeline.group_key info[schema] get_task_schemas(app.state.pipeline.group_key) app.state.pipeline_info info app.state.pipeline_sample get_task_input_examples( app.state.pipeline.group_key) logger.info(pipeline created.)create_pipeline的实现位于 modelscope/utils/input_output.py它先从模型仓库下载configuration.json通过model_file_download解析出cfg.task再以task、model_id、model_revision调用pipeline(...)完成 pipeline 构建。也就是说服务启动时自动按需下载模型文件根据模型配置中的task字段自动匹配对应任务的 pipeline构建完成后将 pipeline 实例、任务 schema 和输入示例保存在app.state中供后续请求使用。三、HTTP 接口说明3.1 路由总览路由统一在 modelscope/server/api/routers/router.py 中注册api_router APIRouter() api_router.include_router(model_router.router, tags[prediction], prefix) api_router.include_router(health.router, tags[health], prefix/health)FastAPI 应用在 modelscope/server/api_server.py 的get_app中创建启用 Swagger UIswagger_ui_parameters{tryItOutEnabled: True}因此访问http://ip:port/docs即可在线调试接口。服务默认提供以下接口接口方法路径说明推理接口POST/call调用 pipeline 进行推理描述接口GET/describe获取服务输入输出信息及输入 sample 数据健康检查GET/health服务健康检查3.2/describe获取输入输出 schema 与示例/describe接口定义在 modelscope/server/api/routers/model_router.pyrouter.get(/describe) async def describe(request: Request): info {} info[schema] request.app.state.pipeline_info info[sample] request.app.state.pipeline_sample return info它返回两部分内容schema当前模型对应任务的输入input、参数parameters与输出output的 JSON Schema。schema 由 modelscope/utils/input_output.py 中的get_task_schemas从pipeline_schema.json读取或由PipelineInfomation基于任务输入输出定义TASK_INPUTS/TASK_OUTPUTS动态生成sample该任务的示例输入数据来自pipeline_inputs.json见get_task_input_examples。实际调用推理时可以直接把/describe返回的 example 数据拷贝到/call的请求体中非常方便。3.3/call推理调用router.post(/call) async def inference(request: Request, body: BaseModel Body(examples[{ usage: copy body from describe }])): pipeline_service request.app.state.pipeline pipeline_info request.app.state.pipeline_info request_json await request.json() result call_pipeline_with_json(pipeline_info, pipeline_service, request_json) output pipeline_output_to_service_base64_output( pipeline_info[task_name], result) return output请求体为 JSON 格式核心字段是input必填与parameters可选。call_pipeline_with_json会依据任务的输入类型定义TASK_INPUTS对请求体做解码处理文本、数字等类型原样透传图像、音频、视频等二进制输入支持三种形式HTTP/OSS URL、本地文件路径或 base64 编码后的字符串见decode_base64_to_image/decode_base64_to_audio/decode_base64_to_video的实现它们会先判断内容是否以http、oss开头或是否为存在的文件路径否则按 base64 解码。响应同样为 JSON对于图像、视频、PCM/WAV 音频等二进制输出字段服务端会统一编码为 base64 字符串见pipeline_output_to_service_base64_output与base64_encoder_mapnumpy 数组会转换为 Python 列表确保响应可被 JSON 序列化。3.4/health健康检查健康检查接口定义在 modelscope/server/api/routers/health.py返回标准ApiResponse定义见 modelscope/server/models/output.py{Code: 200, Data: {}, Message: success, RequestId: , Success: true}可用于负载均衡探活、容器编排健康检查等场景。四、vLLM 大模型推理支持对于 LLM 模型ModelScope 提供了 vLLM 推理支持目前仅部分模型支持 vLLM 推理。4.1 方式一vLLM 直接加载 ModelScope 模型vLLM 原生并不认识 ModelScope 的模型 ID但可以通过设置环境变量VLLM_USE_MODELSCOPETrue让 vLLM 从 ModelScope 模型仓库下载模型。启动普通 server原生 vLLM APIVLLM_USE_MODELSCOPETrue python -m vllm.entrypoints.api_server \ --modeldamo/nlp_gpt2_text-generation_english-base \ --revisionv1.0.0启动 OpenAI 兼容接口VLLM_USE_MODELSCOPETrue python -m vllm.entrypoints.openai.api_server \ --modeldamo/nlp_gpt2_text-generation_english-base \ --revisionv1.0.0两种启动方式的区别vllm.entrypoints.api_servervLLM 自带的普通 HTTP 推理服务vllm.entrypoints.openai.api_server提供 OpenAI 兼容的/v1/chat/completions、/v1/completions等接口便于对接现有的 OpenAI SDK 生态。4.2 模型下载与缓存策略设置了VLLM_USE_MODELSCOPETrue后vLLM 的模型解析会走 ModelScope 的下载逻辑如果模型已经存在于 ModelScope 的 cache 目录中则直接使用缓存不会重复下载否则会从模型仓库下载模型。这一点与 ModelScope 库自身的缓存机制一致。结合官方镜像使用时可以通过环境变量MODELSCOPE_CACHE指定缓存目录并用-v将宿主机目录挂载为缓存目录实现多容器共享、避免重复下载docker run --rm --name maas_dev --shm-size50gb --gpusdevice0 \ -e MODELSCOPE_CACHE/modelscope_cache \ -v /host_path_to_modelscope_cache:/modelscope_cache \ -p 9090:9090 \ reg.docker.alibaba-inc.com/modelscope/modelscope:ubuntu22.04-cuda11.8.0-py310-torch2.1.0-tf2.14.0-1.9.5-server \ python -m vllm.entrypoints.api_server --model modelscope/Llama-2-7b-chat-ms --revision v1.0.5 --port 90904.3 部署要点小结显式指定端口vLLM 服务端口通过--port指定上例为9090并在docker run中用-p 9090:9090做端口映射大模型推理对显存与共享内存要求较高容器建议设置较大的--shm-size--revision需与模型仓库中实际存在的版本标签一致否则无法解析模型vLLM 支持范围以模型实际兼容性为准并非所有模型都能直接跑通 vLLM 推理。五、常见问题与排查思路缺少服务端依赖如果直接运行modelscope server报ModuleNotFoundError需要先安装领域依赖和服务端依赖。run_server中的异常提示给出了标准安装方式pip install modelscope[DOMAIN]DOMAIN包括cv、nlp、audio、multi-modal、science再安装pip install modelscope[server]。模型下载缓慢或失败确认MODELSCOPE_CACHE缓存目录有足够磁盘空间首次启动会下载模型属于正常现象后续启动会复用缓存。/call返回异常先通过/describe获取该任务的输入 schema 与示例数据检查请求体中的input字段结构是否匹配对于图像/音频/视频等二进制输入确认传入的是 URL、本地路径或正确的 base64 编码。端口冲突modelscope server默认监听 8000可通过--port修改vLLM 服务同理。六、总结modelscope server将「模型下载 → pipeline 构建 → HTTP 服务暴露」整合为一条命令配合自动生成的 Swagger 文档、/describe描述接口与 base64 二进制传输约定可以显著降低模型服务化的门槛而VLLM_USE_MODELSCOPETrue则打通了 vLLM 与 ModelScope 模型仓库之间的链路为 LLM 场景提供了高性能推理与 OpenAI 兼容接口两种服务形态。相关实现细节可继续在仓库中深入阅读服务入口、API 定义、路由实现、pipeline 构建 以及 输入输出编解码。【免费下载链接】modelscopeModelScope: bring the notion of Model-as-a-Service to life.项目地址: https://gitcode.com/GitHub_Trending/mo/modelscope创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考