Xinference CLI 完整实战指南：一条命令快速部署、扩容与治理开源模型集群

Xinference CLI 完整实战指南：一条命令快速部署、扩容与治理开源模型集群

【免费下载链接】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

开源大模型部署的三大痛点你大概都踩过：环境搭建繁琐、参数组合混乱（引擎、格式、量化、卡数怎么搭配？）、资源浪费（显存溢出、缓存堆积、模型卸载后残留）。Xinference 命令行工具（xinference CLI）就是为解决这些问题而生的——一行xinference-local拉起完整服务，一条xinference launch命令把 LLM/Embedding/图像/音视频模型送上统一推理 API，再用cached、terminate等命令完成资源治理。读完本文，你将掌握 4 个硬核技能：

1. 本地/分布式集群的三行命令搭建（local / supervisor / worker 三剑客）；
2. launch参数深度剖析——--model-engine、--n-gpu、--n-worker选 A 还是选 B，对吞吐和显存的具体影响；
3. cal-model-mem显存预演，在启动前算清模型到底吃多少显存，告别 OOM 试错；
4. 生产避坑：worker 失联排查、PD 分离副本配置、缓存清理标准流程。

一、全景能力矩阵：先建立全局心智

Xinference 的 CLI 不是一锅大杂烩，而是三套独立可执行文件 + 一组管理子命令的结构（入口定义见 pyproject.toml 的[project.scripts]）：

二进制	职责域	典型场景
xinference-local	单机服务：内嵌 supervisor + worker	开发测试、小规模生产
xinference-supervisor	分布式控制面：注册 worker、调度模型	多机集群主节点
xinference-worker	分布式执行面：承载模型推理	各 GPU 节点
xinference（子命令组）	业务操作：launch/terminate/list/register/cached 等	对着任意 endpoint 运维模型

子命令组的完整实现位于 xinference/deploy/cmdline.py，按"用户动线"可分为三块：节点启动（local/supervisor/worker）、模型生命周期（register→launch→list→terminate→remove-cache）、查询与治理（engine/cached/cal-model-mem/stop-cluster/login）。

💡 注意：裸命令xinference --port 9997直接启动本地集群的方式已被标记弃用，请使用独立的xinference-local。

二、工作流一：环境与节点初始化

2.1 本地集群：一行命令起步

# 启动本地集群：supervisor 与 worker 同进程拉起，默认监听 127.0.0.1:9997 xinference-local \ --host 0.0.0.0 \ # 允许跨机器访问（开发机联调必加） --port 9997 \ # 默认端口，客户端与 API 都走它 --metrics-exporter-port 9998 \ # 独立端口暴露 Prometheus 指标，接监控必加 --log-level INFO # 生产用 INFO；排查问题临时切 DEBUG

启动后访问http://<host>:9997即有内置 Web UI（Next.js 静态导出，无需 Node 运行时）。模型与日志默认落在~/.xinference，磁盘紧张时可用环境变量XINFERENCE_HOME=/data/xinference迁移——这是很多人忽略的第一个坑。

2.2 分布式集群：supervisor + worker 两节点起步

当 DeepSeek-V3 这类 671B 模型单机装不下时，进入分布式模式。官方说明见 doc/source/user_guide/distributed_inference.rst：

# 主节点（控制面） xinference-supervisor \ --host 0.0.0.0 \ # 控制面默认就是 0.0.0.0，务必放行防火墙 --port 9997 \ # 客户端/Worker 注册入口 --supervisor-port 64570 # 内部通信端口，worker 之间张量并行走它 # 各 GPU 节点（执行面） xinference-worker \ --endpoint http://10.0.0.10:9997 \ # 必须指向 supervisor 的 endpoint --host 0.0.0.0 \ # worker 对外暴露地址 --worker-port 64571 # 不指定则自动取空闲端口

为什么分 supervisor/worker 而不是传统"coordinator"？控制面与执行面解耦后，supervisor 崩溃不丢 GPU 进程，worker 扩缩容只是多跑/少跑一条命令——这是资源弹性扩展的工程基础。

集群开启认证时，CLI 侧先xinference login --username admin --password xxx，token 会按 endpoint 哈希缓存到本地，后续所有子命令自动带鉴权，不用每条命令都传--api-key。

三、工作流二：核心业务执行——launch 深度剖析

launch是整个 CLI 的心脏，它把 Web UI 上"选模型→选引擎→选量化→点确认"的流程压缩成一条命令（对比 UI 版本可看 assets/screenshot.png 的 Launch Model 页面）：

3.1 启动前先问一句：engine 能跑什么？

参数组合的最大坑在于引擎×格式×量化不是自由组合。别猜，用engine子命令直接查：

# 查询 qwen2.5-instruct 支持哪些引擎及参数组合 xinference engine --model-name qwen2.5-instruct # 指定 vllm 引擎后，只列出该引擎下合法的 format/size/quantization 组合 xinference engine --model-name qwen2.5-instruct --model-engine vllm

官方引擎选型建议（见 doc/source/getting_started/using_xinference.rst）：Linux 上优先vLLM/SGLang（吞吐最好）；资源有限选llama.cpp（量化选项多、CPU 可跑）；模型太冷门兜底transformers；Mac 首选MLX。

3.2 launch 完整命令与参数剖析

xinference launch \ --model-name qwen2.5-instruct \ # 必填：内置模型名或已注册自定义模型名 --model-type LLM \ # 默认 LLM；embedding/image/audio 按需改 --model-engine vllm \ # LLM 必填！选错引擎是最常见的启动失败原因 --size-in-billions 7 \ # 参数量，多 size 模型必填 --model-format pytorch \ # pytorch 或 ggufv2，须与引擎匹配 --quantization fp8 \ # 量化档位，决定显存占用的核心开关 --replica 2 \ # 副本数：同一模型多实例横向扩容 --n-gpu auto \ # auto=每 worker 全部卡；显存吃紧时手动设 1 --model-path ./local/qwen \ # 指向本地权重，跳过下载环节 --env FOO=BAR \ # 注入自定义环境变量（KV 对，可多次） --max-num-batched-tokens 8192 # 额外 kwargs：透传给引擎（如 vLLM 批处理参数）

关键参数的性能语义：

参数	选择建议	对性能/资源的实际影响
--model-engine	高并发选 vllm；低资源选 llama_cpp	vLLM 连续批处理下吞吐可达静态批处理的 5 倍以上；llama_cpp 量化多、单机 8GB 可跑 7B
--quantization	显存紧张选 q4_0 档，精度优先 fp16	q4_0 相比 fp16 显存约省 60%；代价是长文本精度略降
--n-gpu	单机多卡张量并行填具体数字，跨机保持 auto	注意：--n-worker>1时它表示每 worker 的 GPU 数，语义会切换
--replica	需要高可用/多队列时 ≥2	2 副本可容忍单实例故障，吞吐线性翻倍，显存×副本数
--n-worker	模型超过单机显存才用	跨 worker 张量并行；vLLM 分布式还需在 kwargs 传tensor_parallel_size（设为 GPU 总数）且pipeline_parallel_size=1
额外 kwargs	一切未声明的--xxx参数	launch开启ignore_unknown_options，--max-num-batched-tokens、--gpu-memory-utilization等引擎原生参数可直接透传，这是调优的正规入口

3.3 自定义模型：register 与持久化

内置库没有的模型（或自训 LoRA 基座），先注册再启动：

# 注册：--persist 让配置写入文件系统，服务重启后仍可见 xinference register --model-type LLM --file ./custom_llama.json --persist # 查看已注册模型（含 is_builtin 标识，区分内置与自定义） xinference registrations --model-type LLM # 下线时注销 xinference unregister --model-type LLM --model-name custom-llama-7b

四、工作流三：状态监控与资源清理

4.1 巡检与交互验证

xinference list # 按 LLM/embedding/rerank/image/audio/video 分组表格输出 xinference chat --model-uid <uid> # 终端内流式对话，最快验证模型健康 xinference generate --model-uid <uid> # 补全模式交互

list输出 UID、format、quantization 等列——记住 UID，terminate、扩缩容全靠它。

4.2 生命周期收尾：terminate → cached → remove-cache

# 1) 终止实例：释放 GPU 显存，但权重缓存仍在磁盘 xinference terminate --model-uid 5f9d8b7c-1a2b-3c4d-5e6f-7a8b9c0d1e2f # 2) 查看磁盘缓存（分布式可用 --worker-ip 定位到具体节点） xinference cached --model_name qwen2.5-instruct # 3) 清理缓存：不带 --check 会先列出将被删除的路径并要求交互确认 xinference remove-cache --model_version qwen2.5-instruct-q4_0 xinference remove-cache --model_version xxx --check # 脚本化时跳过二次确认

首次 launch 会自动从模型源下载权重并本地缓存（进度条实时显示，如上图）；缓存 ≠ 实例，terminate释放的是显存，remove-cache释放的是磁盘——运维巡检时两者都要看。

4.3 停整个集群

# 先打印 supervisor 与全部 worker 信息供确认，再执行 xinference stop-cluster --endpoint http://10.0.0.10:9997

五、高阶调优与生产避坑

坑 1：显存溢出——先算账再启动

别用"启动→OOM→改参数→再来"的循环。cal-model-mem离线估算权重 + KV Cache + 激活值总占用：

xinference cal-model-mem \ --model-name deepseek-chat \ # 可选：指定后按真实模型结构估算 --size-in-billions 671 \ --model-format pytorch \ --quantization fp8 \ --context-length 32768 \ --kv-cache-dtype 8 # KV Cache 位宽 8/16/32，8-bit 显存减半

输出会拆成 model mem / kv_cache / overhead / activation / total 五项。如果 total 超过单卡容量，按顺序考虑：降--kv-cache-dtype16→8、缩短 context、加大--n-worker跨机、换更低量化档位。

坑 2：worker 失联/模型拉不起来

排查动线：网络 → 端口 → 日志。supervisor 的--supervisor-port与 worker 的--worker-port必须互达（这是张量并行的内部通道，9997 通了但模型启动卡住，90% 是这个端口被防火墙挡了）；日志按local_/supervisor_/worker_前缀分文件落在~/.xinference，--log-level DEBUG可临时开细节。多 worker 部署时确认--n-worker数量与实际 worker 数一致，且--n-gpu语义是"每 worker 卡数"。

坑 3：副本级精细编排——PD 分离

Prefill 与 Decode 阶段计算特征不同，生产集群可用--replica-config做 PD 分离（Prefill-Decode Separation，文档见 doc/source/user_guide/pd_separation.rst）：

xinference launch \ --model-name deepseek-r1 --model-engine vllm \ --replica-config '[{"role":"prefill","n_gpu":4},{"role":"decode","n_gpu":8}]'

副本数自动取 JSON 数组长度，且不能再与--worker-ip/--gpu-idx/--n-gpu混用（CLI 会直接报错拦截）。Web UI 里对应的"Worker Count"配置见下图：

坑 4：引擎级微调入口

需要动引擎原生参数（如 llama.cpp 的n_ctx、采样器）时，直接在 launch 尾部追加--key value即可透传，等价于 UI 里的"Additional parameters passed to the inference engine"表单：

六、场景分类命令速查矩阵

场景	命令	核心选项
单机起服	xinference-local	--host--port--metrics-exporter-port
分布式主节点	xinference-supervisor	--port--supervisor-port
分布式工作节点	xinference-worker	--endpoint--worker-port
集群鉴权	xinference login	--username--password
注册/注销模型	xinference register / unregister	--model-type--file--persist
查引擎组合	xinference engine	--model-name--model-engine
启动模型	xinference launch	--model-engine--quantization--n-worker--replica-config
巡检实例	xinference list / chat / generate	--model-uid
终止实例	xinference terminate	--model-uid
缓存治理	xinference cached / remove-cache	--model_version--worker-ip--check
显存预演	xinference cal-model-mem	--size-in-billions--context-length--kv-cache-dtype
停集群	xinference stop-cluster	--endpoint

进阶指引：CLI 只是控制面的一半，另一半是 REST API（每个子命令底层都调用 xinference/client/restful/restful_client.py），用 Python 客户端可把本文动线脚本化；接入监控时优先看 doc/source/user_guide/metrics.rst 与--metrics-exporter-port；完整安装与部署路径见 doc/source/getting_started/ 目录下的安装与 Docker Compose 指南。掌握"engine 查询 → cal-model-mem 算账 → launch 启动 → cached 治理"这条主链路，你已经覆盖了 Xinference 生产运维 90% 的日常操作。

【免费下载链接】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