世界模型（实验性）

世界模型根据提示词生成环境视频，并在模型支持时接受初始图像。Xinference 的首个版本提供一个同步 API：

POST /v1/worlds/generations

通用请求字段包括 model、prompt、可选的 image 或 video，以及 generation_config。动作、位姿等模型特定的控制项通过 extra_body 传递。首个版本不包含连续会话，也不提供专用的动作或流式 API。

支持的模型

• Matrix-Game-3.0-5B

• HY-WorldPlay-5B

• Astra

世界模型使用 Xinference 标准的引擎选择流程。通过 GET /v1/engines/world/<MODEL_NAME> 查询可用引擎，并在启动模型时使用 model_engine 选择引擎。首个内置引擎为 PyTorch，且需要 NVIDIA CUDA GPU。

快速开始

启动模型:

xinference launch \
  --model-name Matrix-Game-3.0-5B \
  --model-type world \
  --model-engine PyTorch

使用 cURL 生成：

curl -X POST \
  http://<XINFERENCE_HOST>:<XINFERENCE_PORT>/v1/worlds/generations \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "<MODEL_UID>",
    "prompt": "move forward through the scene",
    "image": "data:image/png;base64,<BASE64_DATA>",
    "generation_config": {"response_format": "b64_json"},
    "extra_body": {
      "num_frames": 97,
      "request_id": "world-request-1"
    }
  }'

使用 Xinference Python 客户端生成：

from xinference.client import Client

client = Client("http://<XINFERENCE_HOST>:<XINFERENCE_PORT>")
model = client.get_model("<MODEL_UID>")
result = model.generate(
    prompt="move forward through the scene",
    image="start.png",
    generation_config={"response_format": "b64_json"},
    num_frames=97,
    request_id="world-request-1",
)

响应沿用现有的视频结果结构。生成项位于 result["data"][0]，其中包含 url 或 b64_json。b64_json 是不带 data:video/... 前缀的原始 Base64 数据。公共 REST 端点接受以 Base64 data URL 形式上传的媒体；Python 客户端会将本地文件路径或字节转换为该格式。公共端点有意不接受远程 HTTP URL 或服务器本地路径。Matrix-Game-3.0-5B 和 Astra 需要输入图像；HY-WorldPlay-5B 支持纯文本生成或图像条件生成。首批适配器均不接受预留的 video 输入。

进度与取消

长时间运行的请求可以在 extra_body 中包含调用方生成的 request_id``（Python 客户端中为 ``model_kwargs）。请求运行期间，可通过以下方式轮询进度:

client.get_progress("world-request-1")

或者使用 REST 端点:

GET /v1/requests/world-request-1/progress

进度响应为 {"progress": <float>}，取值范围为 0 到 1。已完成的进度记录默认保留五分钟（可通过 XINFERENCE_REMOVE_PROGRESS_INTERVAL 配置）。

使用以下方式中止同一请求:

client.abort_request("<MODEL_UID>", "world-request-1")

或者:

POST /v1/models/<MODEL_UID>/requests/world-request-1/abort
{"block_duration": 30}

对于远程客户端，b64_json 可直接使用，但会在响应中物化完整结果。url 当前返回运行该模型的 worker 上的路径，适用于共享该文件系统的客户端。Xinference 目前不会复制或清理这些文件。产物存储、公开下载 URL 和连续流式传输属于独立的未来能力，不在首个同步版本的范围内。

首次启动时会从固定的 GitHub 修订版本下载适配器源码，以及所选模型需要的辅助基础权重。选择 ModelScope 只会改变模型权重来源，不会镜像适配器源码。启动时因此需要同时访问这两个已配置的来源。首个版本不提供覆盖整套依赖的全托管隔离网络预部署流程。

Astra 的相机控制仍是模型特定参数，通过 extra_body 或 model_kwargs 传递。例如，cam_type 接受 1 到 7，分别对应上游预设的相机轨迹。Astra 的官方推理方式在单张 24 GB NVIDIA GPU 上运行。