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 个硬核技能本地/分布式集群的三行命令搭建local / supervisor / worker 三剑客launch参数深度剖析——--model-engine、--n-gpu、--n-worker选 A 还是选 B对吞吐和显存的具体影响cal-model-mem显存预演在启动前算清模型到底吃多少显存告别 OOM 试错生产避坑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 UINext.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 xxxtoken 会按 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.rstLinux 上优先vLLM/SGLang吞吐最好资源有限选llama.cpp量化选项多、CPU 可跑模型太冷门兜底transformersMac 首选MLX。3.2 launch 完整命令与参数剖析xinference launch \ --model-name qwen2.5-instruct \ # 必填内置模型名或已注册自定义模型名 --model-type LLM \ # 默认 LLMembedding/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 FOOBAR \ # 注入自定义环境变量KV 对可多次 --max-num-batched-tokens 8192 # 额外 kwargs透传给引擎如 vLLM 批处理参数关键参数的性能语义参数选择建议对性能/资源的实际影响--model-engine高并发选 vllm低资源选 llama_cppvLLM 连续批处理下吞吐可达静态批处理的 5 倍以上llama_cpp 量化多、单机 8GB 可跑 7B--quantization显存紧张选 q4_0 档精度优先 fp16q4_0 相比 fp16 显存约省 60%代价是长文本精度略降--n-gpu单机多卡张量并行填具体数字跨机保持 auto注意--n-worker1时它表示每 worker 的 GPU 数语义会切换--replica需要高可用/多队列时 ≥22 副本可容忍单实例故障吞吐线性翻倍显存×副本数--n-worker模型超过单机显存才用跨 worker 张量并行vLLM 分布式还需在 kwargs 传tensor_parallel_size设为 GPU 总数且pipeline_parallel_size1额外 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 等列——记住 UIDterminate、扩缩容全靠它。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/328-bit 显存减半输出会拆成 model mem / kv_cache / overhead / activation / total 五项。如果 total 超过单卡容量按顺序考虑降--kv-cache-dtype16→8、缩短 context、加大--n-worker跨机、换更低量化档位。坑 2worker 失联/模型拉不起来排查动线网络 → 端口 → 日志。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.rstxinference 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 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 个硬核技能本地/分布式集群的三行命令搭建local / supervisor / worker 三剑客launch参数深度剖析——--model-engine、--n-gpu、--n-worker选 A 还是选 B对吞吐和显存的具体影响cal-model-mem显存预演在启动前算清模型到底吃多少显存告别 OOM 试错生产避坑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 UINext.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 xxxtoken 会按 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.rstLinux 上优先vLLM/SGLang吞吐最好资源有限选llama.cpp量化选项多、CPU 可跑模型太冷门兜底transformersMac 首选MLX。3.2 launch 完整命令与参数剖析xinference launch \ --model-name qwen2.5-instruct \ # 必填内置模型名或已注册自定义模型名 --model-type LLM \ # 默认 LLMembedding/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 FOOBAR \ # 注入自定义环境变量KV 对可多次 --max-num-batched-tokens 8192 # 额外 kwargs透传给引擎如 vLLM 批处理参数关键参数的性能语义参数选择建议对性能/资源的实际影响--model-engine高并发选 vllm低资源选 llama_cppvLLM 连续批处理下吞吐可达静态批处理的 5 倍以上llama_cpp 量化多、单机 8GB 可跑 7B--quantization显存紧张选 q4_0 档精度优先 fp16q4_0 相比 fp16 显存约省 60%代价是长文本精度略降--n-gpu单机多卡张量并行填具体数字跨机保持 auto注意--n-worker1时它表示每 worker 的 GPU 数语义会切换--replica需要高可用/多队列时 ≥22 副本可容忍单实例故障吞吐线性翻倍显存×副本数--n-worker模型超过单机显存才用跨 worker 张量并行vLLM 分布式还需在 kwargs 传tensor_parallel_size设为 GPU 总数且pipeline_parallel_size1额外 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 等列——记住 UIDterminate、扩缩容全靠它。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/328-bit 显存减半输出会拆成 model mem / kv_cache / overhead / activation / total 五项。如果 total 超过单卡容量按顺序考虑降--kv-cache-dtype16→8、缩短 context、加大--n-worker跨机、换更低量化档位。坑 2worker 失联/模型拉不起来排查动线网络 → 端口 → 日志。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.rstxinference 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考