在 Xinference 中部署与调用 Wan2.2-TI2V-5B：多引擎文生视频 / 图生视频实战指南

在 Xinference 中部署与调用 Wan2.2-TI2V-5B：多引擎文生视频 / 图生视频实战指南

【免费下载链接】inferenceSwap GPT for any LLM by changing a single line of code. Xinference lets you run open-source, speech, and multimodal models on cloud, on-prem, or your laptop — all through one unified, production-ready inference API.项目地址: https://gitcode.com/GitHub_Trending/in/inference

Wan2.2-TI2V-5B 是阿里通义万相（Wan）系列中一款面向 text2video 与 image2video 双能力的开源视频生成模型，Xinference 将其作为内置（built-in）视频模型纳入统一推理 API，支持diffusers与MLX两种引擎。本文将基于内置模型规格文档 wan2.2-ti2v-5b.rst，结合 Xinference 视频模块的源码实现（video/core.py、video/engine.py、video/diffusers.py、video/mlx_video.py）与 REST API 路由（api/routers/videos.py），讲解如何一条命令完成模型启动、如何在 GPU（diffusers 引擎）与 Apple Silicon（MLX 引擎）之间选择，以及如何通过统一视频 API 完成文生视频与图生视频的调用。

模型规格速览

其中Wan2.2-ti2v-5B这一模型名在 Xinference 的视频模型注册表中同时登记了两条规格（见 video/model_spec.json）：

• diffusers 规格：engine: "diffusers"、model_format: "diffusers"，Hugging Face 源为Wan-AI/Wan2.2-TI2V-5B-Diffusers，ModelScope 源为Wan-AI/Wan2.2-TI2V-5B-Diffusers（revision 为master），默认torch_dtype为bfloat16，并且该条规格标记为featured: true；
• MLX 规格：engine: "MLX"、model_format: "mlx"、cache_name: "Wan2.2-ti2v-5B-mlx"，Hugging Face 源为SceneWorks/wan2.2-ti2v-5b-mlx，ModelScope 源为Xorbits/wan2.2-ti2v-5b-mlx，并带有独立的缓存文件过滤规则（config.json、model.safetensors、t5_encoder.safetensors、tokenizer.json、vae.safetensors）。

这也说明：在 Xinference 中，同一个模型名可以同时绑定多个引擎与多个下载源，引擎的选择由--model-engine参数驱动，下载源的选择由--download-hub参数驱动。

一键启动：CLI 命令与关键参数

原文档给出的标准启动命令如下：

xinference launch --model-name Wan2.2-ti2v-5B --model-type video --model-engine diffusers

命令拆解：

• --model-name Wan2.2-ti2v-5B：指定内置模型名，Xinference 会从内置注册表（video/model_spec.json）解析出模型规格；
• --model-type video：声明模型类型为视频模型；
• --model-engine diffusers：显式选择 diffusers 引擎。

引擎选择与默认行为

从 video/core.py 的resolve_video_model_name_and_engine可以看出引擎解析逻辑：

• 当未显式传入model_engine时，Xinference 会按注册顺序取该模型第一个可用引擎作为默认值；
• 在 video/engine.py 的register_builtin_video_engines中，diffusers被注册为第一个引擎，注释明确指出“The first registered engine remains the default for models with several runtimes, preserving the existing diffusers behavior for Wan models”——即对 Wan 系列模型，默认引擎保持为diffusers；
• 若显式传入model_engine，则通过大小写不敏感匹配确认该引擎是否可用，不匹配时会报错Video model {model_name} cannot be run on engine {model_engine}.。

因此在实际部署时：

# 显式选择 diffusers 引擎（GPU / CUDA 环境） xinference launch --model-name Wan2.2-ti2v-5B --model-type video --model-engine diffusers # 显式选择 MLX 引擎（Apple Silicon 环境，需 Python >= 3.11） xinference launch --model-name Wan2.2-ti2v-5B --model-type video --model-engine MLX

下载源（download-hub）

Xinference 支持auto、huggingface、modelscope、openmind_hub、csghub等下载源。在 video/core.py 的match_diffusion中，auto模式会结合环境配置自动选择 ModelScope 或 Hugging Face；若指定了不存在的源组合会抛出明确错误。国内网络环境可优先使用 ModelScope：

xinference launch --model-name Wan2.2-ti2v-5B --model-type video --model-engine diffusers --download-hub modelscope

虚拟环境隔离

从 video/core.py 可以看到，Xinference 默认启用虚拟环境机制（受XINFERENCE_ENABLE_VIRTUAL_ENV环境变量控制），会依据模型规格中的virtualenv字段自动创建独立环境并安装依赖：

• diffusers 规格依赖diffusers==0.35.1、ftfy、imageio-ffmpeg、imageio等（依赖由#engine#标记按引擎分流）；
• MLX 规格依赖mlx-video @ git+https://github.com/Blaizzy/mlx-video.git@87db56a...（固定 commit）与系统 NumPy。

这套机制使不同视频模型可以各自持有互不冲突的依赖版本，避免“依赖地狱”。

双引擎架构解析

diffusers 引擎：面向 NVIDIA GPU

在 video/engine.py 中，DiffusersVideoEngineModel声明了required_libs = ("diffusers",)，其match逻辑为：模型规格未指定引擎或引擎为diffusers即视为匹配。

实际加载逻辑位于 video/diffusers.py：对于model_family == "Wan"的模型，若具备text2video能力则加载WanPipeline；若具备image2video能力，则额外加载CLIPVisionModel（image_encoder子目录，torch.float32）与AutoencoderKLWan（vae子目录），组装WanImageToVideoPipeline。因此 Wan2.2-TI2V-5B 同时声明 text2video 与 image2video 两项能力，在 diffusers 引擎下会走WanPipeline分支（推理时仍可同时处理文本与图像条件）。

默认生成配置default_generate_config为空，推理默认num_inference_steps = 50、默认fps = 10（见 video/diffusers.py）。

MLX 引擎：面向 Apple Silicon

在 video/engine.py 中，MLXVideoEngineModel有两个硬性前置检查：

1. 必须是 Apple Silicon 平台（platform.system() == "Darwin"且platform.machine() == "arm64"）；
2. Python 版本必须 >= 3.11（Blaizzy/mlx-video的要求）。

match还要求模型名必须出现在MLX_VIDEO_MODEL_NAMES白名单中——Wan2.2-ti2v-5B已在该名单内（video/engine.py）。

MLX 引擎的执行细节可参考 video/mlx_video.py：

• 所有 MLX 推理被固定到单线程ThreadPoolExecutor(max_workers=1)上执行，原因在类注释中说明：MLX 的 GPU stream 是线程局部的（thread-local）；
• 加载阶段对 Wan 系列模型做了官方 checkpoint → mlx-video 原生布局的自动转换（_prepare_wan_model/_convert_wan_model），转换结果缓存在${模型路径}.mlx-video目录下，并通过 manifest（.xinference-mlx-video-conversion.json）记录来源指纹与转换器版本，二次加载时若未变化则直接复用；
• MLX 规格的默认生成配置为width: 1280、height: 704、num_frames: 81、scheduler: "unipc"（见 video/model_spec.json）。

通过 REST API 调用视频生成

路由注册

Xinference 在 api/routers/videos.py 注册了三个视频生成端点：

服务端实现位于 api/restful_api.py，其中create_videos以 JSON body 接收TextToVideoRequest，create_videos_from_images以 multipart form 上传图片文件。

curl 示例

文生视频（text2video）：

curl -X POST http://localhost:9997/v1/video/generations \ -H "Content-Type: application/json" \ -d '{ "model": "wan2.2-ti2v-5B", "prompt": "A cat walking on the beach at sunset, cinematic lighting", "n": 1 }'

图生视频（image2video，上传本地图片文件）：

curl -X POST http://localhost:9997/v1/video/generations/image \ -F "model=wan2.2-ti2v-5B" \ -F "prompt=a drone shot flying over a mountain lake" \ -F "image=@./input.png"

其中model字段对应启动时生成的模型 UID（默认与--model-name同名，可通过--model-uid自定义）。

使用 Xinference Python Client

同步客户端RESTfulVideoModelHandle（client/restful/restful_client.py）提供了text_to_video与image_to_video方法：

from xinference.client import Client client = Client("http://localhost:9997") model = client.get_model("wan2.2-ti2v-5B") # 文生视频 result = model.text_to_video( prompt="A cat walking on the beach at sunset, cinematic lighting", n=1, ) # result 为 VideoList，data 中每项含 url 或 b64_json # 图生视频（image 可为本地路径或 bytes） result = model.image_to_video( image="./input.png", prompt="a drone shot flying over a mountain lake", )

参数说明（与源码 docstring 一致）：

• prompt：str或List[str]，引导视频生成的提示词；
• image：str（本地路径）或bytes（图片二进制），用于图生视频；
• n：每个 prompt 生成的视频数量，范围 1～10；
• negative_prompt：负面提示词（可选）；
• response_format："url"或"b64_json"，默认b64_json（见 video/diffusers.py 与 video/mlx_video.py）。

其他可用参数

在 diffusers 引擎下，以下参数可透传给底层 pipeline（video/diffusers.py 的load/ 生成方法支持）：

• 加载参数：scheduler（如CogVideoXDDIMScheduler）、torch_dtype、cpu_offload、sequential_cpu_offload、group_offload、compile_graph（torch.compile）、layerwise_cast（FP8 逐层 cast）、device_map（多卡时自动balanced）等；
• 生成参数：num_inference_steps（默认 50）、fps（默认 10）、guidance_scale、seed、negative_prompt等。

注意：MLX 引擎的参数名与 diffusers 存在差异（如steps、guide_scale），Xinference 在 video/mlx_video.py 中做了guidance_scale→guide_scale的自动映射，调用方无需关心。

能力校验与错误处理

Xinference 会根据模型声明的model_ability对请求做前置校验（video/mlx_video.py）：

• 传入图片但模型不具备image2video能力 → 报错；
• 无图片且模型不具备text2video能力 → 报错；
• n < 1或response_format非法 → 报错。

对应地，内置注册表校验逻辑位于 video/tests/test_video_engine.py（如("Wan2.2-ti2v-5B", "Xorbits/wan2.2-ti2v-5b-mlx")的 MLX 源映射断言），可用于核对注册数据是否完整。

小结与适用场景

在 Xinference 中部署 Wan2.2-TI2V-5B 的完整路径为：

1. 选择硬件：NVIDIA GPU 环境使用--model-engine diffusers；Apple Silicon（macOS arm64、Python >= 3.11）使用--model-engine MLX；
2. 选择下载源：国内网络可加--download-hub modelscope；
3. 启动模型：xinference launch --model-name Wan2.2-ti2v-5B --model-type video --model-engine <引擎>，其余依赖自动装入独立虚拟环境；
4. 统一调用：通过POST /v1/video/generations（文生视频）与POST /v1/video/generations/image（图生视频），或使用 Python Client 的text_to_video/image_to_video。

该模型适合在统一的 Xinference 视频推理 API 下快速接入文生视频与图生视频工作流，双引擎设计则让用户在同一套接口上自由切换 GPU 与 Apple Silicon 平台。

【免费下载链接】inferenceSwap GPT for any LLM by changing a single line of code. Xinference lets you run open-source, speech, and multimodal models on cloud, on-prem, or your laptop — all through one unified, production-ready inference API.项目地址: https://gitcode.com/GitHub_Trending/in/inference