本文详细介绍了大模型推理服务框架 Xinference 的一键部署方法。内容涵盖环境准备、Docker 本地与分布式集群部署命令详解、Web UI 功能操作指南（包括模型启动、自定义注册、集群监控）以及多种 API 调用方式（Curl、Python SDK、Dify 集成）。文章还补充了常见问题排查与性能优化建议，重点强调了使用 ModelScope 解决国内网络下载问题及 OpenAI 兼容性优势，旨在帮助工程师高效完成大模型推理服务的搭建与集成。
大语言模型推理服务框架对于快速落地 AI 应用至关重要。Ollama 以出色的设计实现了一行命令完成推理框架部署，模型的下载不依赖网络代理，速度较快，且支持多卡 GPU 自动分片。然而，Xinference 提供了更友好的 Web UI 交互体验，支持通过 ModelScope 社区下载模型，解决了国内网络环境下 Hugging Face 连接困难的问题。
在工程实践中，选择合适的推理框架能显著降低部署门槛。Xinference 不仅支持本地单节点部署，还支持分布式集群模式，并兼容 OpenAI API 标准，便于集成到现有业务系统中。
在开始部署前，请确保满足以下基础环境要求：
nvidia-container-toolkit）。使用 Docker 可以最快地启动 Xinference 服务。以下命令将启动一个名为 xinference 的容器，映射端口 9997，并指定使用 ModelScope 作为模型下载源。
docker run -it --name xinference -d \
-p 9997:9997 \
-e XINFERENCE_MODEL_SRC=modelscope \
-e XINFERENCE_HOME=/workspace \
-v /yourworkspace/Xinference:/workspace \
--gpus all \
xprobe/xinference:latest \
xinference-local -H 0.0.0.0
-it：交互式终端，方便查看日志。--name xinference：指定容器名称。-d：后台运行模式。-p 9997:9997：宿主机端口 9997 映射到容器内部 9997。-e XINFERENCE_MODEL_SRC=modelscope：指定模型来源为 ModelScope，避免直接连接 Hugging Face。-e XINFERENCE_HOME=/workspace：设置容器内工作目录。-v /yourworkspace/Xinference:/workspace：挂载宿主机目录，持久化模型数据。--gpus all：允许容器使用宿主机所有 GPU 设备。xinference-local -H 0.0.0.0：启动本地模式，监听所有网络接口。对于大规模推理需求，可采用 Supervisor + Worker 架构。
docker run -it --name xinference-master -d \
-p 9997:9997 \
-e XINFERENCE_MODEL_SRC=modelscope \
-e XINFERENCE_HOME=/workspace \
-v /yourworkspace/Xinference:/workspace \
--gpus all \
xprobe/xinference:latest \
xinference-supervisor -H "${master_host}"
docker run -it --name xinference-worker -d \
-p 16500:16500 \
-e XINFERENCE_MODEL_SRC=modelscope \
-e XINFERENCE_HOME=/workspace \
-v /yourworkspace/Xinference:/workspace \
-e "http://${supervisor_host}:9997" \
-H "${worker_host}"
注意：Worker 节点需要配置环境变量指向 Supervisor 的地址。
部署完成后，浏览器访问 http://<host>:9997 即可进入管理界面。
在 "Launch Model" 页面，支持搜索主流模型（如 Qwen, Llama, ChatGLM 等）。
点击启动按钮后，系统会自动从 ModelScope 下载模型权重并加载至显存。
在此列表可查看已加载模型的状态：
点击 Actions 栏的窗口图标，可弹出内置测试 UI 进行对话验证。
若拥有微调后的模型文件，可通过 "Register Model" 功能添加：
展示 Supervisor 和 Worker 节点的数量，以及 CPU/GPU 的资源使用情况，便于运维监控。
Xinference 提供与 OpenAI 完全兼容的 API 接口，支持多种调用方式。
curl -X 'POST' \
'http://127.0.0.1:9997/v1/chat/completions' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
-d '{
"model": "qwen1.5-chat",
"messages": [
{"role": "system", "content": "You are a helpful assistant."},
{"role": "user", "content": "What is the largest animal?"}
]
}'
利用 openai 库可直接对接 Xinference：
from openai import OpenAI
client = OpenAI(
base_url="http://127.0.0.1:9997/v1",
api_key="not used actually"
)
response = client.chat.completions.create(
model="qwen1.5-chat",
messages=[
{"role": "system", "content": "You are a helpful assistant."},
{"role": "user", "content": "What is the largest animal?"}
]
)
print(response.choices[0].message.content)
在 Dify 中配置模型时：
http://<宿主机 IP>:9997。http://，否则可能报错。默认配置可能受网络影响。务必设置 -e XINFERENCE_MODEL_SRC=modelscope 环境变量，利用国内镜像加速下载。
修改 -p 参数中的宿主机端口，避免与现有服务冲突。
生产环境建议绑定特定 IP (-H <IP>) 而非 0.0.0.0，并配置防火墙规则限制访问来源。
Xinference 通过一行命令即可完成本地部署，两行代码即可构建分布式集群。其开箱即用的 Web UI、灵活的模型注册机制、以及对 ModelScope 的良好支持，使其成为企业私有化部署大模型的理想选择。同时，OpenAI 兼容的 API 设计降低了迁移成本，便于开发者快速接入现有应用生态。
微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog
使用加密算法（如AES、TripleDES、Rabbit或RC4）加密和解密文本明文。 在线工具，加密/解密文本在线工具，online
生成新的随机RSA私钥和公钥pem证书。 在线工具，RSA密钥对生成器在线工具，online
基于 Mermaid.js 实时预览流程图、时序图等图表，支持源码编辑与即时渲染。 在线工具，Mermaid 预览与可视化编辑在线工具，online
解析常见 curl 参数并生成 fetch、axios、PHP curl 或 Python requests 示例代码。 在线工具，curl 转代码在线工具，online
将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具，Base64 字符串编码/解码在线工具，online
将字符串、文件或图像转换为其 Base64 表示形式。 在线工具，Base64 文件转换器在线工具，online