大模型推理服务框架 Xinference 一键部署指南

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 的地址。

五、Web UI 操作指南

部署完成后，浏览器访问 http://<host>:9997 即可进入管理界面。

1. 启动模型 (Launch Model)

在 "Launch Model" 页面，支持搜索主流模型（如 Qwen, Llama, ChatGLM 等）。

• Model Format：支持 PyTorch, GPTQ, AWQ, GGUFv2 等多种格式。
• Model Size：覆盖 0.5B 至 110B 全尺寸模型。
• Quantization：支持 4-bit, 8-bit 及不量化选项，平衡性能与显存。
• N-GPU：自动或手动选择使用的 GPU 数量，支持多卡切分。
• Replica：设置服务副本数以实现负载均衡。

点击启动按钮后，系统会自动从 ModelScope 下载模型权重并加载至显存。

2. 运行中的模型 (Running Models)

在此列表可查看已加载模型的状态：

• ID/Name：调用 API 时所需的标识符。
• Address：容器内部地址，外部调用通常使用宿主机 IP。
• GPU Indexes：显示模型占用的 GPU 索引，支持动态分配。
• Size/Quantization：展示模型参数量级及量化精度。

点击 Actions 栏的窗口图标，可弹出内置测试 UI 进行对话验证。

3. 注册自定义模型 (Register Model)

若拥有微调后的模型文件，可通过 "Register Model" 功能添加：

• 填写模型名称、格式、上下文长度、尺寸及本地路径。
• 注册成功后，在 "Custom Models" 分类下即可启动。

4. 集群信息 (Cluster Information)

展示 Supervisor 和 Worker 节点的数量，以及 CPU/GPU 的资源使用情况，便于运维监控。

六、API 调用示例

Xinference 提供与 OpenAI 完全兼容的 API 接口，支持多种调用方式。

1. Curl 请求

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?"}
    ]
  }'

2. Python SDK 调用

利用 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)

3. Dify 平台集成

在 Dify 中配置模型时：

• 模型名称：填入 Running Models 中的 Name。
• 服务器 URL：填写 http://<宿主机 IP>:9997。
• 模型 UID：填入对应的 ID。
• 注意协议头必须包含 http://，否则可能报错。

七、常见问题与优化建议

1. 模型下载慢

默认配置可能受网络影响。务必设置 -e XINFERENCE_MODEL_SRC=modelscope 环境变量，利用国内镜像加速下载。

2. 显存不足

• 尝试使用量化版本（如 4-bit GPTQ）。
• 减少并发副本数 (Replica)。
• 检查是否有其他进程占用 GPU。

3. 端口冲突

修改 -p 参数中的宿主机端口，避免与现有服务冲突。

4. 数据安全

生产环境建议绑定特定 IP (-H <IP>) 而非 0.0.0.0，并配置防火墙规则限制访问来源。

八、总结

Xinference 通过一行命令即可完成本地部署，两行代码即可构建分布式集群。其开箱即用的 Web UI、灵活的模型注册机制、以及对 ModelScope 的良好支持，使其成为企业私有化部署大模型的理想选择。同时，OpenAI 兼容的 API 设计降低了迁移成本，便于开发者快速接入现有应用生态。