从单机到 3 节点：xinference 分布式部署的 3 个核心工作流与参数取舍

从单机到 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等放置参数把模型调度到 workerworker 上跑真正的引擎。命令行工具的所有子命令list、launch、terminate 等本质都是对 9997 端口的 REST 调用所以每条管理命令都可以带-e指向远端集群。 从 0 到第一次响应最小命令集下面 6 条命令足以完成安装到跑通模型。每条后面说明它做什么、成功时你应看到什么。安装 CLI 与 Python 客户端客户端版本需与服务端一致pip install xinference启动本地集群——单机下 supervisor 和 worker 会在同一进程组内拉起监听 9997xinference-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 / Quantizationxinference 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_SRCmodelscope走 ModelScope 镜像。列出当前运行中的模型LLM 输出列为 UID / Type / Name / Format / Size / Quantizationxinference 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/32KV cache 用 8-bit 能直接压掉一半以上 cache 占用。引擎选择遵循官方文档 About Model Engine 的建议Linux 优先 vLLM 或 SGLang资源有限选 llama.cpp量化选项最多兜底用 transformersmacOS 优先 MLX。引擎参数组合拿不准时xinference engine -n name --model-engine vllm会把该引擎下合法的 format/size/quantization 组合直接列出来。 接入已有应用与自定义模型跑起来的模型就是一个标准 OpenAI 端点业务侧只需改 base_urlcurl -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.0xinference-supervisor -H 0.0.0.0 --port 9997两台 GPU 机各自加入集群。-e指向 supervisor-H是本机对 supervisor 可达的 IPxinference-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_size1且 Xinference 需 ≥ v1.17.1xinference 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 vllmLinux 高并发主力吞吐最优需 vLLM 环境--model-engine llama.cppCPU 机 / 低资源量化选项最多吞吐更低--model-engine sglang长上下文、分布式v1.3.0 起支持跨 worker--quantization q4_0显存紧张权重体积约为 q8_0 一半精度有损--quantization fp16/none精度优先显存接近翻倍适合小模型--n-gpu单机多卡张量并行n-worker1 时变为每机卡数--n-worker单机装不下需 ≥2 workervLLM 要配 tp/pp--replica提吞吐与可用性每副本独立占一份显存三个三角关系值得记住量化位数越低、显存越省、精度越差上下文越长、KV cache 越大、可并发请求越少副本越多吞吐越高、总显存占用线性增长。engine 与量化的合法组合不要凭记忆猜用xinference engine查询cal-model-mem验算显存两步都能省下一次失败启动。✅ 真实环境 PlaybookPlaybook A3 机集群部署 DeepSeek-R110.1.20.x 网段前提10.1.20.11supervisorCPU 机、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:9997cmdline.py 的get_endpoint在跳板机上执行时就打到了本机不存在的实例。修复对远端集群的所有命令显式加-e http://10.1.20.11:9997若集群开启了认证先xinference login -e endpoint --username admin --password pwd把 token 落盘之后同 endpoint 的命令自动携带。一页纸速查命令一句话功能最常用选项适用角色xinference-local单机起 supervisorworker--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），仅供参考