从单机到 3 节点：xinference 分布式部署的 3 个核心工作流与参数取舍
【免费下载链接】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
你手上有 3 台机器：一台只有 CPU，另外两台各带 4 张 GPU。目标是让同一个模型跑起来、对外暴露 OpenAI 兼容 API，业务增长时能继续加机器。下面按"本地跑通 → 注册自定义模型 → 跨节点集群部署"三条线索，基于仓库当前代码（xinference/deploy/cmdline.py）梳理 xinference CLI 的全部核心命令，并说明每个关键参数在什么场景选什么值、代价是什么。
工具定位
Xinference 是架在 vLLM、SGLang、llama.cpp 等推理引擎之上的模型服务层，pip install xinference后同时获得一组命令行工具和默认监听 9997 端口的 REST 服务。与只服务单一引擎的 vLLM 不同，它用一套 OpenAI 兼容 API 统一管理 LLM、embedding、rerank、图像、音频和视频模型。集群里 supervisor 的作用类似餐厅前台：接住所有请求，派给空闲的 worker 处理。
数据流只有一条：客户端只和 supervisor 的 9997 端口说话，supervisor 按你 launch 时传入的--n-worker、--worker-ip等放置参数把模型调度到 worker，worker 上跑真正的引擎。命令行工具的所有子命令（list、launch、terminate 等）本质都是对 9997 端口的 REST 调用，所以每条管理命令都可以带-e指向远端集群。
🚀 从 0 到第一次响应：最小命令集
下面 6 条命令足以完成安装到跑通模型。每条后面说明它做什么、成功时你应看到什么。
安装 CLI 与 Python 客户端，客户端版本需与服务端一致：
pip install xinference启动本地集群——单机下 supervisor 和 worker 会在同一进程组内拉起，监听 9997：
xinference-local --host 0.0.0.0 --port 9997成功输出形如Xinference supervisor 0.0.0.0:64570 started、Xinference worker ... started、Uvicorn running on http://0.0.0.0:9997。日志与模型缓存默认落在~/.xinference，用环境变量XINFERENCE_HOME可整体挪走。
启动前查一下这个模型支持哪些引擎、格式和量化组合，输出列为 Name / Engine / Format / Size / Quantization：
xinference engine -n qwen2.5-instruct照表格里的一行来 launch。LLM 启动时--model-engine 是必填项，缺了会直接报错而不是用默认引擎；命令会显示实时进度条：
xinference launch --model-engine vllm -n qwen2.5-instruct -s 7 -f pytorch成功输出的最后两行是进度条跑满 100.0%，以及Model uid: qwen2.5-instruct——不指定--model-uid时，uid 默认与模型名相同，后文示例都利用这一点。首次启动会从 HuggingFace 下载权重，国内网络可加环境变量XINFERENCE_MODEL_SRC=modelscope走 ModelScope 镜像。
列出当前运行中的模型，LLM 输出列为 UID / Type / Name / Format / Size / Quantization：
xinference list进入交互式对话验证，输入空行退出：
xinference chat --model-uid qwen2.5-instruct🧮 启动前算账：显存估算与量化选择
launch 失败最常见的结果是 OOM。与其撞墙再退，不如先用cal-model-mem离线估算。它按参数量、量化、上下文长度计算模型权重、KV cache、激活值的显存总和：
xinference cal-model-mem -n qwen2.5-instruct -s 7 -f pytorch -c 32768输出会分行给出model mem、kv_cache、overhead、active和total: xxx MB (x GB)。对照nvidia-smi的空闲显存，留 10% 余量再决定上下文长度；估算支持--kv-cache-dtype 8/16/32，KV cache 用 8-bit 能直接压掉一半以上 cache 占用。
引擎选择遵循官方文档 About Model Engine 的建议：Linux 优先 vLLM 或 SGLang，资源有限选 llama.cpp（量化选项最多），兜底用 transformers；macOS 优先 MLX。引擎参数组合拿不准时，xinference engine -n <name> --model-engine vllm会把该引擎下合法的 format/size/quantization 组合直接列出来。
🧩 接入已有应用与自定义模型
跑起来的模型就是一个标准 OpenAI 端点，业务侧只需改 base_url：
curl -X POST http://127.0.0.1:9997/v1/chat/completions \ -H 'Content-Type: application/json' \ -d '{"model": "qwen2.5-instruct", "messages": [{"role": "user", "content": "你好"}]}'返回结构与 OpenAI Chat Completions 一致；Anthropic 协议走http://127.0.0.1:9997/anthropic。
自定义模型有两条路。模型家族在内置支持范围内时，v0.14.0 起可以直接传本地路径启动，免注册：
xinference launch --model-engine vllm -n qwen1.5-chat --model-path /opt/models/qwen1.5-7b模型结构不在内置家族里时才需要注册。按 自定义模型文档 的模板写好 JSON（含model_family、model_specs、model_uri等字段），再提交到集群：
xinference register -t LLM -f /opt/models/my-model.json --persist--persist 决定注册在服务重启后是否保留，生产环境建议始终带上。注册后用xinference registrations -t LLM核对（Is-built-in 列显示 False 即自定义项），不再需要时xinference unregister -t LLM --model-name my-model移除。分布式场景注册可加--worker-ip 10.1.20.12把模型文件定位到指定节点。
🌐 跨节点协作：supervisor 与 worker 配置
单台机器装不下 DeepSeek 这类大模型时，至少需要 2 个 worker 做跨机并行。supervisor 一台、worker 若干，全部通过 9997 端口通信；当前版本没有旧文档里的coordinator命令，对应入口是xinference-supervisor与xinference-worker（见 pyproject.toml 的[project.scripts]）。
在 10.1.20.11 上启动 supervisor，-H必须写对局域网 IP 或 0.0.0.0：
xinference-supervisor -H 0.0.0.0 --port 9997两台 GPU 机各自加入集群。-e指向 supervisor，-H是本机对 supervisor 可达的 IP：
xinference-worker -e http://10.1.20.11:9997 -H 10.1.20.12 xinference-worker -e http://10.1.20.11:9997 -H 10.1.20.13这条命令的作用就是让 worker 认到主节点并上报自己的地址；supervisor 日志出现 worker 地址即注册成功，xinference list -e http://10.1.20.11:9997应能看到两台的运行模型。
跨机 launch 时注意参数语义：--n-gpu在--n-worker > 1时含义变为"每个 worker 用几张卡"。每台 4 卡、共 2 台，则 8 卡张量并行；用 vLLM v0.11.0+ 时按 分布式推理文档 的要求，必须显式传tensor_parallel_size（等于总 GPU 数）和 pipeline_parallel_size=1，且 Xinference 需 ≥ v1.17.1：
xinference launch -e http://10.1.20.11:9997 \ --model-engine vllm -n deepseek-r1 -s 0_5 -f pytorch \ --n-worker 2 --n-gpu 4 \ --tensor_parallel_size 8 --pipeline_parallel_size 1不想跨机时，用--worker-ip 10.1.20.12和--gpu-idx 0,1可以把小模型钉在指定 worker 的指定卡上，与--n-worker > 1互斥。
📏 参数取舍：引擎、量化与并行
| 参数 | 何时选 | 代价与收益 |
|---|---|---|
--model-engine vllm | Linux 高并发主力 | 吞吐最优，需 vLLM 环境 |
--model-engine llama.cpp | CPU 机 / 低资源 | 量化选项最多，吞吐更低 |
--model-engine sglang | 长上下文、分布式 | v1.3.0 起支持跨 worker |
--quantization q4_0 | 显存紧张 | 权重体积约为 q8_0 一半，精度有损 |
--quantization fp16/none | 精度优先 | 显存接近翻倍，适合小模型 |
--n-gpu | 单机多卡张量并行 | n-worker>1 时变为每机卡数 |
--n-worker | 单机装不下 | 需 ≥2 worker，vLLM 要配 tp/pp |
--replica | 提吞吐与可用性 | 每副本独立占一份显存 |
三个三角关系值得记住：量化位数越低、显存越省、精度越差；上下文越长、KV cache 越大、可并发请求越少；副本越多吞吐越高、总显存占用线性增长。engine 与量化的合法组合不要凭记忆猜，用xinference engine查询，cal-model-mem验算显存，两步都能省下一次失败启动。
✅ 真实环境 Playbook
Playbook A：3 机集群部署 DeepSeek-R1（10.1.20.x 网段）
前提：10.1.20.11（supervisor，CPU 机）、10.1.20.12 / 10.1.20.13（各 4 张 GPU），三台已pip install xinference，防火墙放行 9997 及 supervisor 日志中打印的 worker 内部端口（形如 64570）。
# 10.1.20.11 xinference-supervisor -H 0.0.0.0 --port 9997 # 10.1.20.12 xinference-worker -e http://10.1.20.11:9997 -H 10.1.20.12 # 10.1.20.13 xinference-worker -e http://10.1.20.11:9997 -H 10.1.20.13三台就绪后在 10.1.20.11 上跨机启动：
xinference launch -e http://10.1.20.11:9997 \ --model-engine vllm -n deepseek-r1 -s 0_5 -f pytorch \ --n-worker 2 --n-gpu 4 \ --tensor_parallel_size 8 --pipeline_parallel_size 1验证方法：xinference list -e http://10.1.20.11:9997中 deepseek-r1 一行出现且状态稳定，再curl http://10.1.20.11:9997/v1/models能看到 uid。
Playbook B：单机 7B + vLLM 调优后下线
xinference-local --host 0.0.0.0 --port 9997 --metrics-exporter-port 9998 xinference launch --model-engine vllm -n qwen2.5-instruct -s 7 -f pytorch \ --gpu_memory_utilization 0.9 xinference terminate --model-uid qwen2.5-instruct--gpu_memory_utilization属于引擎透传参数：launch 对未知选项不校验，直接透给 vLLM，占满显存提吞吐。--metrics-exporter-port供 Prometheus 抓取。验证方法：terminate 后再xinference list，表格应为空；显存用nvidia-smi确认已释放。
Playbook C：注册本地模型文件并清理缓存
xinference register -e http://10.1.20.11:9997 -t LLM \ -f /opt/models/my-model.json -w 10.1.20.12 --persist xinference registrations -e http://10.1.20.11:9997 -t LLM xinference cached -e http://10.1.20.11:9997 xinference remove-cache -e http://10.1.20.11:9997 -n my-model --checkcached列出各 worker 的缓存文件及大小；remove-cache会先打印将删除的路径并交互确认，--check跳过交互直接删。验证方法：xinference cached中该模型行消失，磁盘df -h容量回收。
⚠️ 高频踩坑与自救
launch 秒退并报 ValueError。现象：命令刚执行就报--model-engine is required for LLM models。这是 v0.11.0 起的硬性校验（cmdline.py 第 985 行），不是环境故障。第一反应：确认命令里带了--model-engine。根因是引擎不再自动推断；修复就是补上参数，取值用xinference engine -n <name>查出来的合法行。
worker 加入集群后 supervisor 看不到它。现象：worker 进程活着，list里没有它的模型，launch 指定--n-worker 2报 worker 不足。第一反应排查：在 worker 机上执行curl -s http://10.1.20.11:9997应返回 JSON；再nc -vz 10.1.20.11 9997确认端口通。根因通常是两类：supervisor 用默认-H只绑了本机回环，或防火墙拦了 worker 内部端口（supervisor 日志里Xinference supervisor 0.0.0.0:64570 started那行的 64570 才是 worker 实际回连的端口，别只放 9997）。修复：supervisor 显式-H 0.0.0.0，安全组放行 9997 与该内部端口。
launch 进度条卡住或引擎报 CUDA out of memory。现象：下载到 100% 后加载阶段失败，vLLM 日志出现 OOM。第一反应：nvidia-smi看其他进程占了多少卡，确认不是显存被别的东西吃光。根因多是上下文默认值过大导致 KV cache 膨胀。修复：先用cal-model-mem -c <目标上下文>验算 total，把--context-length（透传参数）降到显存装得下的值，或换更激进的量化；--kv-cache-dtype 8是压 cache 的另一条路。
管理命令"连错了集群"。现象：xinference list是空的，但 Web UI 里明明有模型。根因：所有管理命令的默认 endpoint 是127.0.0.1:9997（cmdline.py 的get_endpoint），在跳板机上执行时就打到了本机不存在的实例。修复：对远端集群的所有命令显式加-e http://10.1.20.11:9997；若集群开启了认证，先xinference login -e <endpoint> --username admin --password <pwd>把 token 落盘，之后同 endpoint 的命令自动携带。
一页纸速查
| 命令 | 一句话功能 | 最常用选项 | 适用角色 |
|---|---|---|---|
xinference-local | 单机起 supervisor+worker | --port 9997 | 开发/单机 |
xinference-supervisor | 集群主节点 | -H 0.0.0.0 | 运维 |
xinference-worker | 加入集群的工作节点 | -e、-H | 运维 |
xinference register | 注册自定义模型 | -f、--persist | 开发/算法 |
xinference registrations | 查已注册模型 | -t LLM | 开发 |
xinference unregister | 注销自定义模型 | --model-name | 开发 |
xinference engine | 查引擎/量化合法组合 | -n、--model-engine | 开发 |
xinference launch | 启动模型 | --model-engine、--n-worker | 开发/运维 |
xinference list | 查运行中模型 | -e | 所有人 |
xinference terminate | 停止指定模型 | --model-uid | 开发/运维 |
xinference chat/generate | 命令行对话/补全 | --model-uid | 开发 |
xinference cached | 查各节点模型缓存 | -e、--worker-ip | 运维 |
xinference remove-cache | 删除模型缓存 | -n、--check | 运维 |
xinference cal-model-mem | 估算显存占用 | -s、-c | 开发/运维 |
xinference stop-cluster | 停掉整个集群 | -e（必填） | 运维 |
引擎内部细节、Docker 部署、监控接入的完整选项，去读官方文档 使用 Xinference 与 推理后端 章节，集群拓扑设计参考 分布式推理。
本文基于仓库当前 Xinference v2.x 代码（2026-09），参数以官方文档为准。
【免费下载链接】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），仅供参考
 目录列举选项)
