故障排除#

本文档提供Xinference企业版常见问题的解决方案和故障排除指南。

多机部署问题#

Worker无法连接到Supervisor#

问题描述：Worker节点无法成功连接到Supervisor节点

可能原因及解决方案：

  1. 网络连通性问题

    # 测试网络连通性
ping <supervisor-ip>

# 测试端口连通性
telnet <supervisor-ip> <supervisor-port>
nc -zv <supervisor-ip> <supervisor-port>

  2. 防火墙配置问题

    # CentOS/RHEL 防火墙配置
sudo firewall-cmd --permanent --add-port=9997/tcp
sudo firewall-cmd --permanent --add-port=8000/tcp
sudo firewall-cmd --reload

# Ubuntu 防火墙配置
sudo ufw allow 9997/tcp
sudo ufw allow 8000/tcp

  3. IP地址和端口配置错误

    • 确认Supervisor启动时使用的IP地址和端口

    • 检查Worker连接命令中的Supervisor地址

    • 验证IP地址是否为实际的网络接口地址

  4. Supervisor服务未正常启动

    # 检查Supervisor进程
ps aux | grep xinference-supervisor

# 查看Supervisor日志
docker logs <supervisor-container-name>

Web界面无法访问#

问题描述：无法通过浏览器访问Xinference WebUI界面

可能原因及解决方案：

  1. nginx服务未启动

    # 检查nginx进程
ps aux | grep nginx

# 手动启动nginx（在容器内）
./xinf-enterprise.sh --host <supervisor-ip> --port <supervisor-port>

  2. 端口冲突或被占用

    # 检查8000端口占用情况
netstat -tlnp | grep 8000
lsof -i :8000

# 使用自定义nginx端口
./xinf-enterprise.sh --host <supervisor-ip> --port <supervisor-port> --listen-port 8080

  3. IP地址配置问题

    • 确认访问的IP地址是否正确

    • 检查是否使用了内网IP但从外网访问

    • 验证容器的网络模式配置

单机部署问题#

容器启动失败#

问题描述：Docker容器无法正常启动

可能原因及解决方案：

  1. GPU资源问题

    # 检查GPU状态
nvidia-smi

# 检查Docker GPU支持
docker run --rm --gpus all nvidia/cuda:11.0-base nvidia-smi

  2. 内存不足

    # 检查系统内存
free -h

# 调整共享内存大小
--shm-size=64g  # 根据实际情况调整

  3. 存储空间不足

    # 检查磁盘空间
df -h

# 清理Docker缓存
docker system prune -a

模型加载问题#

问题描述：模型下载或加载失败

可能原因及解决方案：

  1. 网络连接问题

    # 配置代理（如需要）
export http_proxy=http://proxy-server:port
export https_proxy=http://proxy-server:port

# 在Docker启动时添加代理
-e http_proxy=$http_proxy \
-e https_proxy=$https_proxy

  2. 存储空间不足

    • 确保模型存储目录有足够空间

    • 大模型通常需要几十GB空间

    • 检查挂载路径的磁盘使用情况

  3. 权限问题

    # 检查目录权限
ls -la /path/to/model/directory

# 修复权限问题
sudo chown -R 1000:1000 /path/to/model/directory

性能问题#

推理速度慢#

问题描述：模型推理响应时间过长

可能原因及解决方案：

  1. GPU资源不足

    # 监控GPU使用情况
nvidia-smi -l 1

# 检查GPU内存使用
nvidia-smi --query-gpu=memory.used,memory.total --format=csv

  2. 模型配置问题

    • 选择合适的模型大小

    • 调整批处理大小

    • 使用量化模型减少内存占用

  3. 网络延迟

    • 确保客户端与服务器网络连通良好

    • 考虑使用本地部署减少网络开销

内存使用过高#

问题描述：系统内存或GPU内存使用过高

解决方案：

  1. 调整模型参数

    • 使用较小的模型

    • 启用模型量化

    • 减少并发请求数量

  2. 优化容器配置

    # 限制容器内存使用
--memory=32g --memory-swap=32g

日志和调试#

查看详细日志#

# 查看容器日志
docker logs -f <container-name>

# 查看Xinference服务日志
# 在容器内启动服务时添加详细日志级别
xinference-local --log-level debug
xinference-supervisor --log-level debug
xinference-worker --log-level debug

常用调试命令#

# 检查服务状态
curl http://<supervisor-ip>:<supervisor-port>/v1/models

# 检查集群节点状态
curl http://<supervisor-ip>:<supervisor-port>/v1/cluster/workers

# 测试模型推理
curl -X POST http://<supervisor-ip>:<supervisor-port>/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model": "model-name", "messages": [{"role": "user", "content": "Hello"}]}'

获取帮助#

如果以上解决方案无法解决您的问题，请：

  1. 收集信息：

    • 系统环境信息（OS、Docker版本、GPU型号等）

    • 错误日志和详细错误信息

    • 使用的镜像版本和配置参数

  2. 联系支持：

    • 查看官方文档获取最新信息

    • 联系技术支持团队

    • 提供详细的问题描述和环境信息

相关文档#