模型加载指南#
本文档旨在提供模型加载的功能说明。
加载对话框会将模型声明的默认加载配置填入对应控件,没有专用控件的设置会出现在高级引擎参数中。用户修改和已保存的加载配置优先。切换引擎时,只替换自动填入的默认值,并保留用户修改。结构化默认参数在请求和保存的配置中保留 JSON 类型。
在 运行模型 页面,选择 清除失败记录,可移除运行资源已清理的启动失败记录。也可以调用 DELETE /v1/models/{model_uid}。此操作只清除状态记录,保留已缓存的模型文件。启用身份认证时,需要 models:write 权限。
首次启动在全部副本完成前始终可以取消,即使部分副本已经就绪。在 运行模型 页面点击 取消启动,会调用 POST /v1/models/{model_uid}/cancel,停止尚未完成的工作,并移除本次启动创建的副本。GET /v1/models/instances 通过 can_cancel_launch 标识是否支持此操作。已运行模型的扩容不会启用首次启动取消操作。
备注
LMDeploy 后端已移除,因为其 Xinference 集成已无人维护。使用 InternVL 模型时,请选择 vLLM 或 Transformers。
更新模型目录#
在 模型启动 页面中,选择 更新 旁的模型类型。 更新 会刷新整个类别。选择 更新单个模型,输入 Hub 中准确的模型名称(或 world 模型族名称),即可仅更新该模型,也支持尚未出现在列表中的模型。其他目录条目会保留。此操作仅更新共享元数据,不会下载权重或重启运行中的模型。启用认证时,两种操作都要求管理员或 models:register 权限。
模型收藏#
启动模型 页面的星标会保存到当前账号,切换浏览器或重启服务器后仍然保留。不同模型类别按模型名称识别收藏。读取或修改收藏需要 models:list 权限。未启用认证时,所有访问者共用一份收藏。 启用认证时,修改收藏需要用户会话;API key 只能读取。
收藏保存在所选认证数据库的 model_favorites 表中。默认 SQLite 后端使用 <XINFERENCE_HOME>/auth/auth.db (通过 XINFERENCE_AUTH_DB_PATH 配置)。未启用认证时,同一路径保存共享收藏,且只初始化收藏表。
旧浏览器收藏没有账号身份,因此不会自动导入。选择 导入浏览器收藏,可将其添加到当前账号。如果任意写入失败,或导入期间切换了账号,浏览器中的副本会保留;重试不会产生重复记录。
GET /v1/model_favorites 返回当前认证账号收藏的模型名称列表。在同一路径使用 PUT 或 DELETE,请求体为 {"model_name": "org/model"},可添加或移除单个名称。两种操作均为幂等操作。服务端根据认证确定所有者,客户端不能指定其他所有者。
LLM 启动推荐#
Added in version v3.5.0.
在 LLM 的部署窗口中,点击推荐配置按钮,检查填好的配置后再部署。LLM、Embedding、Rerank 和音频模型都支持推荐,目前限单副本。自定义模型路径和自定义引擎参数仍需手动配置。
推荐配置是怎么选出来的#
点击启动窗口右上角的 推荐配置,就能一起填好引擎、格式、模型大小和量化方式。填好后仍然可以修改,确认后再点击 部署。推荐结果也会指定工作节点,让配置对应到刚才检查过的那台机器。
Xinference 会先看您已经选了什么。比如,已经选了 8B 模型,就只会推荐 8B 的配置,不会自行换成更小的模型。您指定的工作节点、GPU 和虚拟环境设置也会保留。系统会分别检查各台机器,排除不兼容的配置。如果找不到合适的配置,就保持表单不变,方便您调整后再试。
有内存数据时,Xinference 优先选择估算能放下的最大规格;否则退回到尚未验证内存的最小规格。同一规格下优先使用已安装的引擎,也会考虑可通过虚拟环境安装的引擎。
前面的条件相同时,再按平台选择引擎:Apple Silicon 上优先 MLX,使用 CUDA 的 Linux 上优先 vLLM、其次 SGLang,CPU 上优先 llama.cpp。同一个引擎支持多种量化时,会优先考虑 Q4_K_M、Int4 等常见的 4 位量化。到这里仍有多个同等选择,才优先使用该工作节点上已缓存的权重。也就是说,不会仅仅因为某个模型已经下载过,就改变您选定的规格或跳过前面的选择顺序。
估算使用离线架构信息和可获得的检查点大小。MoE 权重包含全部驻留专家。完整注意力的 KV cache、Gated DeltaNet 循环状态和工作区分别计算。MLX、Transformers、vLLM、SGLang 和 llama.cpp 共用这套计算方式,但工作区上界各不相同。包括 MLA 在内的未知布局仍标记为未验证。
默认按一个序列、模型注册的最大 context、FP16 KV cache、无图像 tokens 和无保留前缀缓存估算。预算为当前空闲内存的 80%:GPU 使用候选卡中最少的空闲显存,CPU 和 Apple Silicon 使用可用系统内存。已知总显存时,另外检查 vLLM 的默认 GPU 预留;SGLang 按初始化时的可用内存计算预算。多卡请求仍只检查兼容性。已知超出预算的配置会被排除。工作区上界是估算值,不是实测峰值。除单独检查 vLLM 默认预留外,不对引擎预分配建模;自定义引擎设置需要手动配置。推荐不会预留资源。
使用 API#
POST /v1/models/recommend 是只读接口。提供 model_name 和 model_type="LLM";可选的 constraints 对象接受 model_size_in_billions、worker_ip、enable_virtual_env、n_gpu 和 gpu_idx。提供的约束均为硬性要求,不会被静默放宽。 LLM 约束还接受 context_length。
LLM 约束还接受正整数 context_length``(文本输入加输出 tokens)和 ``concurrency,以及非负整数 vision_tokens``(每个序列编码后的图像 tokens)和 ``prefix_cache_bytes``(整个实例额外保留的缓存)。省略 ``context_length 时,使用各个候选模型注册的最大 context,编码后的图像 tokens 也计入这个上限。最大值未知的模型仍保持未验证。推荐的 vLLM max_model_len 和 SGLang context_length 等于每个序列的文本加图像 tokens。llama.cpp 使用 n_parallel=concurrency 和 n_ctx=(context_length + vision_tokens) * concurrency,因为 context 会在各个槽位间分配。Web UI 会应用这些高级启动参数。其他工作负载字段影响估算,不设置请求限制。不支持工作负载选项的旧 worker 会去掉这些选项后重试,其候选保持未验证,并附带版本警告。图像工作负载需要视觉元数据。 多个图像可通过 vision_tokens_per_image 指定单个图像编码后的最大 token 数;零表示将全部图像 tokens 视为一个图像。缓存状态随并发增加,模型权重只计算一份。vLLM (CUDA) 和 SGLang 共用 16,384-token 的预填充工作区估算,使用融合注意力和采样行 logits。
推荐配置通过 context_length 返回每个请求的总 token 上限,包括编码后的图像 tokens。llama.cpp 还返回 n_parallel,与估算的并发数一致;启动层会把统一上限映射到各个引擎。
curl -X POST http://127.0.0.1:9997/v1/models/recommend \
-H 'Content-Type: application/json' \
-d '{
"model_name": "qwen2.5-instruct",
"model_type": "LLM",
"constraints": {"model_size_in_billions": "7", "n_gpu": 1}
}'
响应中的 status 为 recommended 或 no_recommendation。推荐成功时,config 包含与启动接口兼容的字段,例如 model_engine、model_format、model_size_in_billions、quantization 和 worker_ip。reasons 和 warnings 中的条目包含 code 和 message 字段。如果没有配置满足约束,请查看说明并调整约束,或手动配置启动参数。
推荐不保证内存充足或启动成功。它不会预留资源、下载模型文件或安装依赖。现有启动行为不变;部署仍需单独执行。
config 还包含实际生效的 enable_virtual_env,以及提供的 n_gpu 和 gpu_idx 约束。n_gpu=null 请求使用 CPU,而 n_gpu="auto" 使用现有启动分配策略,不会计算所需的 GPU 数量。
recommended 和 no_recommendation 均返回 HTTP 200。未知模型返回 HTTP 404;无效请求返回 HTTP 422。原因和警告代码使用小写蛇形命名(snake_case)。响应始终包含 memory_not_verified 警告。
统一 LLM 上下文长度#
Added in version v4.1.0: 在启动 API、CLI 和 Web UI 中统一配置上下文长度。
在启动 API 中设置 context_length,或在 CLI 中使用 --context-length,可选择每个请求的输入与输出 token 总上限。Web UI 支持拖动上下文滑块或输入精确整数;模型默认值 会清除覆盖设置。滑块默认选中模型原生上下文长度。模型和引擎已登记 YaRN 配置时,上限包含已核实的扩展范围。将鼠标悬停在 上下文长度 旁的问号上,可查看原生长度、扩展上限和所选引擎是否支持自动 YaRN。上下文选择会保存在配置历史中,并传给配置推荐 API。
启动层将此设置映射到 vLLM 的 max_model_len,SGLang、Transformers 和 MLX 的 context_length,以及 llama.cpp 的总槽位容量 n_ctx=context_length*n_parallel。已有引擎参数仍可使用;统一参数与原生参数冲突时会被拒绝。省略该设置会保留引擎默认值。
Added in version v4.2.0: 为已登记配置的模型提供自动 YaRN 上下文扩展。
对于已登记相应模型格式的 Qwen3.5、Qwen3.6 和 Qwen3.8,vLLM、SGLang、MLX 和 llama.cpp 均可使用自动 YaRN。Qwen3.8-Flash-Next 支持 vLLM 和 SGLang;SGLang 需要 0.5.22 或更新版本。
所选长度在原生窗口内时不修改 RoPE。超过原生长度时,会在模型启动时启用 YaRN,扩展倍数为所选长度除以原生长度后向上取整(例如,原生长度为 262,144 tokens 时,524,288 tokens 使用 2 倍,1,000,000 tokens 使用 4 倍)。所需环境变量只作用于模型进程。Qwen3.5、Qwen3.6 和 Qwen3.8-Max 的自动扩展上限为 1,010,000 tokens;Qwen3.8-27B 和 Qwen3.8-Flash-Next 为 1,000,000 tokens。手工 RoPE 覆盖和已扩展的 checkpoint 配置优先。未登记配置的模型保留已有引擎行为。修改所选长度需要重启模型;引擎不会按请求切换扩展配置。
MLX 支持文本和多模态语言模型。llama.cpp 按每个并行槽的上下文窗口选择扩展倍数;增加 n_parallel 不会增加该倍数。GGUF 元数据中已有的扩展设置优先于自动设置。
对于已登记 YaRN 配置的模型,使用权重缓存重载时不能增加当前上下文长度。如需增加,请重新部署模型,以便再次检查 checkpoint 和 RoPE 设置。
显式设置上下文上限后,MLX 会拒绝没有剩余输出空间的提示词,并把 max_tokens 限制在剩余 token 预算内。缓存命中的提示词 tokens 和处理后的图像 tokens 都计入输入上限。非流式请求超出输入上限时返回 HTTP 400;流式请求通过 SSE 报告错误,不会开始生成。
xinference launch --model-name qwen3.5 --model-engine vLLM \
--size-in-billions 9 --model-format awq --quantization Int4 \
--context-length 32768
以下命令使用自动 YaRN 将 Qwen3.8-27B 的上下文扩展到一百万 tokens:
xinference launch --model-name qwen3.8 --model-engine vLLM \
--size-in-billions 27 --model-format pytorch --quantization none \
--context-length 1000000
其他模型类型的推荐#
Added in version v3.5.0.
Embedding、Rerank 和音频模型也可以点击 推荐配置,或调用 POST /v1/models/recommend,将 model_type 分别设为 embedding、rerank 或 audio。推荐只填写该类型支持的字段,不选择模型大小。Embedding 和 Rerank 优先使用可用的 sentence-transformers 引擎;音频模型在 Apple Silicon 上优先使用可用的 MLX,否则优先考虑常规的 Transformers 或 PyTorch 后端。已经安装的引擎优先于需要虚拟环境安装依赖的引擎,同一引擎内优先选择未量化版本。与 LLM 不同,这些类型暂不按权重是否缓存来打破平局。您指定的工作节点、GPU 和虚拟环境条件仍然有效,但这些类型不接受 model_size_in_billions。推荐只是起步配置,不保证内存够用。图片和视频模型暂不支持推荐。
仅下载模型,不启动#
Added in version v3.4.0.
打开模型的部署窗口,点击 部署 旁边的 仅下载,就能提前下载部署所需的模型文件。这个操作不会占用 GPU、创建模型子进程、安装虚拟环境,也不会把模型加载到内存中。
对应的 REST 接口是 POST /v1/cache/models。如果需要在请求尚未结束时查询进度或取消下载,请传入 cache_uid,用它来标识这次下载任务。
curl -X POST http://127.0.0.1:9997/v1/cache/models \
-H 'Content-Type: application/json' \
-d '{
"cache_uid": "download-qwen",
"model_name": "qwen2.5-instruct",
"model_type": "LLM",
"model_engine": "transformers",
"model_format": "pytorch",
"model_size_in_billions": "0_5",
"quantization": "none"
}'
查询进度和取消下载时,使用同一个 cache_uid:
curl http://127.0.0.1:9997/v1/cache/models/download-qwen/progress
curl -X POST http://127.0.0.1:9997/v1/cache/models/download-qwen/cancel
仅下载任务也可以暂停和恢复:
curl -X POST http://127.0.0.1:9997/v1/downloads/download-qwen/pause
curl -X POST http://127.0.0.1:9997/v1/downloads/download-qwen/resume
Xinference 会保存尚未完成的仅下载任务。如果 Supervisor 或工作节点意外停止,重启后,正在进行的任务会显示为 interrupted (已中断),可以通过上述恢复接口继续下载。恢复时会复用模型仓库缓存中已有的文件。下载了一部分的文件能否断点续传,取决于所选模型仓库的客户端;如果不支持,这个未完成的文件会重新下载。
GET /v1/downloads 会列出正在下载、已暂停、已中断和失败的任务。暂停和恢复只适用于仅下载任务。如果是在启动模型的过程中下载文件,仍需使用启动取消接口,因为暂停整个启动过程还涉及保留已分配的运行资源。
在分布式部署中,可以通过 worker_ip 指定把文件下载到哪个工作节点的本地缓存。不指定时,Supervisor 会选择一个工作节点。
GET /v1/cache/models 为每个缓存模型返回 model_type 和 model_engine。引擎列表报告文件所属 Worker 发现的候选引擎,并遵循该 Worker 的虚拟环境设置。rerank 和 world 的缓存版本只标识模型名称,因此这些类型的候选引擎不按缓存格式校验。null 表示元数据未知或引擎发现失败;空列表表示当前未发现匹配的引擎。查询缓存不会下载权重、准备环境或启动模型。
副本#
提交部署后,弹窗立即显示等待提示和已用时间,涵盖副本准备及加载阶段。某个副本就绪或进度达到 100% 不代表请求已经完成。部署响应返回后停止等待计时,弹窗关闭前可能还需完成配置保存。取消失败时继续等待,保留原开始时间。仅下载操作仍使用独立的进度展示。
部署期间,进度接口 GET /v1/models/{model_uid}/progress 会报告每个副本所处的阶段。模型文件下载完成后,如果另一个启动任务正在准备共享虚拟环境,副本会报告 waiting_for_dependencies;安装依赖包时报告 installing_dependencies;环境就绪后报告 loading。
Web 界面会在各副本的卡片中显示该副本的文件下载详情。
安装依赖包期间,每个副本的进度会显示主安装任务计划安装的包数量,以及其虚拟环境中已有的包数量。等待共享环境的副本没有自己的安装计数。如果安装器无法解析出可靠的计划,则不显示计数。
副本加载模型时,Web 界面仍会显示依赖包的安装结果。如果本次无需安装依赖包,副本卡片也会明确提示。
从 运行中的模型 添加副本时,Web UI 会等待整个请求完成,不使用普通请求的 60 秒超时,并显示等待耗时和逐副本进度。副本就绪前,进度保持在 100% 以下。只有成功响应才能确认整批完成并关闭弹窗;之后刷新失败不会改变新增成功的结论。连接或网关异常时,请先核实当前副本,再结束跟踪或重试;界面不会自动重新提交。跟踪状态仅保存在当前页面,重新加载页面后会丢失。
副本用来指定模型加载的实例份数。比如,你有两张 GPU,每张卡可以放下模型的一个副本,你可以设置副本数为 2。这样,两个完全相同的模型实例将分布在这两张 GPU 上。Xinference 会自动进行负载均衡,确保请求均匀分配到多张卡上。用户看到的仍是一个模型,这大大提升了整体资源利用率。
旧版本多实例部署:
当您拥有多张GPU显卡时,每张显卡可承载一个模型实例,此时可将实例数量设置为等于GPU数量。例如:
2张GPU,2个实例:每张GPU运行一个模型实例
4张GPU,4个实例:每张GPU运行一个模型实例
Added in version v1.15.0.
引入一个新的环境变量:
XINFERENCE_ALLOW_MULTI_REPLICA_PER_GPU
控制是否启用单GPU多副本功能,默认值:1
新功能:智能副本部署
单GPU多副本
新增支持:即使仅有一块GPU,也能运行多个模型副本。
场景:您拥有1个GPU且显存充足
配置:副本数量=3,GPU数量=1
结果:3个模型实例,在同一GPU上运行,共享GPU资源
混合GPU分配
智能分配: 副本数可以不等于GPU数量,系统会智能分配
场景: 你有2张GPU,需要3个副本
配置: 副本数=3,GPU数量=2
结果: GPU0运行2个实例,GPU1运行1个实例
为每个副本指定运行位置#
在分布式部署中,可以用 replica_config 为每个副本指定工作节点,也可以进一步指定 GPU 编号。工作节点地址必须使用注册时的完整 IP:port。配置条目数必须与 replica 一致,目前每个条目只能指定一个工作节点。
from xinference.client import Client
client = Client("http://localhost:9997")
model_uid = client.launch_model(
model_name="qwen2.5-instruct",
model_engine="vllm",
replica=2,
replica_config=[
{
"replica_uid": "primary",
"devices": [
{
"worker_ip": "192.168.1.10:9978",
"n_gpu": 1,
"gpu_idx": [0],
}
],
},
{
"replica_uid": "secondary",
"devices": [
{
"worker_ip": "192.168.1.11:9978",
"n_gpu": 1,
"gpu_idx": [0],
}
],
},
],
)
在命令行中,也可以将相同的位置配置作为 JSON 数组传给 xinference launch:
xinference launch \
--model-name qwen2.5-instruct \
--model-engine vLLM \
--replica 2 \
--replica-config '[{"replica_uid":"primary","devices":[{"worker_ip":"192.168.1.10:9978","n_gpu":1,"gpu_idx":[0]}]},{"replica_uid":"secondary","devices":[{"worker_ip":"192.168.1.11:9978","n_gpu":1,"gpu_idx":[0]}]}]'
为兼容旧用法,--replica_config 仍然可用,但建议使用 --replica-config。如果省略 --replica,命令行会按数组条目数确定副本数量;如果显式指定,则必须与条目数一致。
replica_config 不能与模型级的 worker_ip、n_gpu、gpu_idx 参数同时使用,也不支持 n_worker > 1。因此,命令行不允许将 --replica-config 与 --worker-ip、--gpu-idx、非 auto 的 --n-gpu 或大于 1 的 --n-worker 一起使用。目前,每个副本只能指定一个工作节点。如果省略 replica_uid,Xinference 会使用稳定的默认名称 {model_uid}-{replica_index},例如 my-model-0。省略 gpu_idx 并设置 n_gpu="auto",则由选定的工作节点自动分配 GPU。
在 运行中的模型 中,新增副本 弹窗提供自动调度和逐副本指定两种模式。逐副本指定需要为每个新副本选择一个 Worker,并可逐行填写 GPU 索引和副本别名。GPU 索引对应所选 Worker 的本地编号;留空时自动分配,选择 CPU 时不传 GPU 索引。只提交当前选中的模式。GPU 可用性和别名冲突由服务端检查,现有扩容限制仍然适用。
对于正在运行的模型,可以一次增加一个或多个副本。新副本默认复用已有的启动配置,您也可以单独调整新副本的引擎和设备分配,不影响已有副本。运行位置可以不指定,此时由 Supervisor 自动选择工作节点。
result = client.add_model_replica(model_uid)
scale_result = client.add_model_replica(
model_uid,
replica=2,
model_engine="vllm",
n_gpu=1,
)
result = client.add_model_replica(
model_uid,
replica_config={
"replica_uid": "burst-capacity",
"devices": [
{
"worker_ip": "192.168.1.12:9978",
"n_gpu": 1,
"gpu_idx": [1],
}
],
},
)
remaining = client.terminate_model_replica(
model_uid, replica_id=result["replica_id"]
)
一次增加多个副本时,replica_config 也可以是一个列表,为每个新副本提供一条位置配置。如果其中任何一个副本启动失败,Xinference 会回滚本次操作创建的副本。
使用 Xavier 分布式运行的模型,以及通过 n_worker > 1 启动的模型,暂不支持增加副本。删除最后一个副本时,运行中的模型也会终止。
混合分配策略#
当前策略为 空闲优先 :调度器始终尝试将副本分配至最空闲的GPU。使用 XINFERENCE_LAUNCH_STRATEGY 参数选择启动策略。
设置环境变量#
Added in version v1.8.1.
有时我们希望在运行时为特定模型指定环境变量。从 v1.8.1 开始,Xinference 提供了单独配置环境变量的功能,无需在启动 Xinference 前设置。
针对 Web UI。

命令行使用时,使用 --env 指定环境变量。
示例用法:
xinference launch xxx --env A 0 --env B 1
以 vLLM 为例,它有 V1 和 V0 两个版本,默认会自动判定使用哪个版本。如果想在加载模型时强制通过设置 VLLM_USE_V1=0 来使用 V0,可以指定该环境变量。
配置模型虚拟空间#
Added in version v1.8.1.
对于这部分,请参考 开关虚拟空间和定制依赖。
批处理 / 连续批处理#
Xinference支持批处理以提升吞吐量。对于基于 transformers 引擎的大型语言模型,可启用连续批处理功能,该功能可在启动时通过环境变量进行配置。
关键设置:
XINFERENCE_BATCH_SIZE和XINFERENCE_BATCH_INTERVAL用于控制常规的批处理行为。
示例(大型语言模型,Transformers):
XINFERENCE_BATCH_SIZE=32 XINFERENCE_BATCH_INTERVAL=0.003 xinference-local --log-level debug
xinference launch -e <endpoint> --model-engine transformers -n qwen1.5-chat -s 4 -f pytorch -q none
图像和视频模型的批处理能力取决于所选原生引擎和模型。Diffusers 不使用 Xinference 自研的逐步调度器。请参阅 图像 和 视频。
有关详细行为、支持的模型以及中止请求的信息,请参阅 连续批处理 。
思考模式#
某些混合推理模型(例如Qwen3)支持可选的 思考模式 。您可在启动时通过 --enable-thinking 参数启用该功能。
示例用法:
xinference launch -n qwen3-xxx --model-engine vllm --enable-thinking
启动配置历史#
模型从 Web UI 成功启动后,Xinference 会将启动配置保存到 Supervisor 的启动历史数据库中,并按用户在浏览器中保留一份缓存,方便快速访问,也能应对短暂的网络故障。再次打开部署窗口时,会恢复服务端保存的最新配置;如果您已经开始编辑表单,则不会覆盖正在修改的内容。
在配置历史窗口中,您可以删除自己的记录,但用于自动启动的记录不能删除。启用身份验证时,浏览器缓存会按访问令牌中的用户名隔离,不会混入其他用户的配置。
历史窗口也会列出您在其他模型上保存的配置,但不会自动套用。确认 用作模板 后,Xinference 会保留当前模型名称,去掉原来的模型 UID、历史记录和自动启动相关信息,再将其余启动选项填入表单。这个操作只填写配置,不会启动模型。
重新配置和升级运行中的模型#
Added in version v4.0.0.
在 v4.2.0 版本发生变更: enable_weight_cache 的默认值从 False 改为自动选择(None)。 保留权重的模型现在支持多副本、扩容和逐个副本重载。
GPU 权重保留默认自动选择:模型环境和配置支持时自动开启,不支持时正常启动。省略 enable_weight_cache 或传入 None 表示自动选择,设为 True 表示必须开启,设为 False 则关闭。部署对话框中的 保留 GPU 权重以支持重载 提供 自动、开启 和 关闭 三种选择。此功能需要 vLLM 0.31.0+ 或 SGLang 0.5.21+、Linux CUDA 或 ROCm、每个副本仅使用一个 Worker,且副本内的张量并行度固定。支持多副本和扩容,每个副本独立保留自己的权重。
声明 quantization_method="compressed-tensors" 的检查点,在 vLLM 的 compressed-tensors 加载器不支持预处理 IPC 权重时使用原生权重加载。自动权重保留会跳过该配置;显式启用权重保留则拒绝启动。
部署模型前配置 GPU 权重保留。#
在「运行中的模型」页面打开重新配置。#
在模型详情页选择「重新配置 / 升级模型」。#
启用权重保留后,Xinference 会在原引擎继续服务的同时准备新的模型进程。新进程共享兼容的缓存权重,并创建自己的 KV 缓存和 CUDA Graph。只有加载和健康检查成功后,新请求才切换过去;已有请求(包括流式请求)仍由原引擎完成。准备失败时,原引擎继续服务。模型 UID 和 GPU 预留保持不变。终止模型会释放相关进程和缓存权重。
多副本重载会先在所有副本上校验参数,再逐个更新引擎。状态包含 replicas、completed_replicas 和 replica_count。某个副本失败后停止后续更新:后续副本标记为 skipped,已成功的副本保留新配置,失败副本通过 restored 报告是否恢复原引擎。partial=true 表示仅部分副本完成,可重试重载以完成更新。页面会显示各副本进度和部分失败的结果。重载期间添加或删除副本返回 HTTP 409;终止整个模型可以取消操作。
开始替换前,仅当先前的引擎共享同一 Worker 上的 GPU 分配或同一个引擎进程时,重载才会等待这些引擎退出。位于独立 Worker 或已知互不重叠的 GPU 上的副本可以在先前请求完成期间更新。如果无法确定部署位置,此等待最多持续 300 秒;超时后返回可重试的部分错误,现有请求和清理仍会继续。任何副本发生更改之前,都会检查所需的引擎退出等待功能;请重启不支持此功能的模型。
Worker 恢复时使用各副本已提交的配置。模型级自动启动配置仅在所有副本成功后更新。部分失败后,各副本可能暂时使用不同配置;重载元数据通过 mixed_parameters 列出值不同的参数。
Supervisor 意外重启并丢失重载状态时,仅凭 Actor 报告无法确认原始目标副本集合,以及模型级自动启动配置是否已提交。即使已报告的副本都已就绪,重载结果仍会返回 status=error 和 outcome_unknown=true。仍存活的引擎继续服务;请检查各副本当前配置后再决定是否重试。
结果无法确认时,可在 Web UI 中点击 重新应用当前显示的配置,即使没有修改也会提交当前显示的值。空白字段和各副本值不同的字段,只有在指定值后才会提交。
POST /v1/models/{model_uid}/reload 接受部分 model_config,以及可选的 python_executable 和 drain_timeout 字段,返回 HTTP 202 和 operation_id。轮询 GET /v1/models/{model_uid}/reload,直到 status 为 ready 或 error。发生错误时,restored=true 表示原引擎仍在服务。通过 GET /v1/models/{model_uid}/reload/config 查询支持的参数、当前值、引擎版本和 Python 可执行文件。无效参数返回 HTTP 400;已有重新加载操作时返回 HTTP 409。drain_timeout 控制仅修改解析器时的请求等待时间(默认 300 秒,最大 3600 秒);替换引擎不会强制停止已有请求。
切换期间,两个引擎都需要运行显存:共享权重不会共享 KV 缓存或 CUDA Graph。请为两个引擎预留足够的 GPU 显存。两个 Xinference 环境以及最初启动模型的版本,都必须支持模型无中断替换。 启动替代引擎前,Xinference 会检查空闲显存,并为原引擎保留配置的显存预算;显存不足或无法获取驱动进程显存信息时会拒绝操作。
显存不足时不会自动退回原地重建。即使模型以默认的 0.9 显存比例启动,也需要为替换预留足够空间;否则重新加载失败,当前引擎继续处理推理。
连续升级时,drain_timeout 也会限制等待前一个引擎退出的时间。超时不会停止当前请求;后续升级会重试失败的清理操作。
启用认证时,选择 python_executable 需要管理员权限。只有管理员获取的重新加载元数据包含当前解释器路径。
要更换模型环境,将 python_executable 设置为 Worker 机器上已安装的 Python 绝对路径。目标环境必须预先安装 Xinference 和模型引擎;重新加载不会安装软件包。兼容的引擎和 PyTorch 版本会复用保留的权重。不同版本使用独立的权重缓存,需要额外的 GPU 显存;上游兼容性检查仍然启用。在 Web 界面中,进入运行中模型的详情页,使用 重新配置 / 升级模型。
from xinference.client import Client
client = Client("http://127.0.0.1:9997")
operation = client.reload_model(
"my-model", {}, python_executable="/opt/xinference-new/bin/python"
)
xinference reload --model-uid my-model \
--python-executable /opt/xinference-new/bin/python
vLLM 支持修改 max_num_seqs、max_num_batched_tokens、max_model_len、gpu_memory_utilization 和 enforce_eager。
对于支持推理的模型,两个引擎也接受通过相同重新加载 API 修改 reasoning_content。此操作只修改 Xinference 的推理解析器,保持引擎和 GPU 权重不变,无需启用 enable_weight_cache,也不受权重保留所需最低引擎版本的限制。已有请求(包括流式请求)先完成,再应用新设置;新请求等待解析器修改完成。重新加载元数据中的 hot_parameters 列出这些设置,enabled 仍表示启动时是否保留权重。热更新同样要求每个副本仅使用一个 Worker,并逐个副本应用。只有重建引擎并复用保留权重时,weights_reused 才为 true。
对于启动时启用了权重保留的 vLLM 视觉模型,limit_mm_per_prompt 支持将正数图片上限改为另一个正数,例如 {"image": 8}。未指定的模态限制会保留在引擎、恢复及自动启动配置中。引擎会重建以重新进行多模态显存分析并设置缓存预算,同时复用保留的权重。不支持将图片数量设为零,也不支持为初始已禁用的编码器启用图片;此操作不能修改其他模态的限制。
SGLang 支持修改 max_running_requests、max_prefill_tokens、context_length、chunked_prefill_size、mem_fraction_static、disable_cuda_graph、cuda_graph_max_bs_decode、cuda_graph_max_bs_prefill 和 schedule_conservativeness。
对于启用权重保留的 SGLang 视觉模型,limit_mm_data_per_request 接受部分图片数量配置,例如 {"image": 8}。引擎使用保留的权重重建,由新的 tokenizer 进程应用数量限制。其他模态限制会保留在引擎、故障恢复和自动启动配置中。初始不限数量或图片数量为零时,都可以改为正数,因为此设置仅校验请求中的数量,不会禁用视觉编码器。新的图片数量上限必须为正整数。 如需恢复为不限数量或零张图片,必须重新启动模型。 初始图片数量为零时,Xinference 会跳过 SGLang 默认的图片预热。
并行度、GPU 放置、模型路径、精度、量化和权重布局选项不能通过重新加载修改。此集成尚不支持流水线/数据并行、单个副本跨 Worker 切分、LoRA、推测解码、权重卸载和 PD 部署。量化模型必须通过上游 IPC 兼容性检查。vLLM 的多 GPU 缓存使用其原生多进程执行器。在运行中模型的详情页,选择 重新配置 / 升级模型 来修改支持的值并查看进度。
from xinference.client import Client
client = Client("http://127.0.0.1:9997")
uid = client.launch_model(
model_name="qwen2.5-instruct", model_engine="vLLM",
model_size_in_billions="0_5", model_format="pytorch",
quantization="none", n_gpu=1, enable_weight_cache=True,
gpu_memory_utilization=0.4,
)
job = client.reload_model(uid, {"max_num_seqs": 32})
print(job["operation_id"])
print(client.get_model_reload_status(uid))
xinference reload --model-uid MODEL_UID --model-config '{"max_num_seqs": 32}'
curl http://127.0.0.1:9997/v1/models/MODEL_UID/reload
无需重启引擎即可修改思考内容解析:
job = client.reload_model(uid, {"reasoning_content": True})
对于启动时启用了权重保留且图片上限为正数的视觉模型:
job = client.reload_model(uid, {"limit_mm_per_prompt": {"image": 8}})
修改启用权重保留的 SGLang 视觉模型的图片数量上限:
job = client.reload_model(uid, {"limit_mm_data_per_request": {"image": 8}})