企业官网建设流程全解析

sysHAX故障排查手册：常见问题诊断与解决方案的完整清单

【免费下载链接】sysHAXsysHAX Heterogeneous collaborative acceleration runtime项目地址: https://gitcode.com/openeuler/sysHAX

前往项目官网免费下载：https://ar.openeuler.org/ar/

sysHAX异构协作加速运行时是openEuler社区推出的高性能AI推理任务调度系统，能够智能地在CPU和GPU之间分配任务，实现资源的高效利用和推理性能的优化。然而，在实际部署和使用过程中，用户可能会遇到各种问题。本手册为您提供sysHAX故障排查的完整指南，帮助您快速定位和解决常见问题。🚀

📊 系统架构与关键组件理解

在开始故障排查之前，了解sysHAX的基本架构非常重要。sysHAX采用微服务架构设计，主要包含以下核心组件：

sysHAX架构图

1. 核心引擎(Engine)- 负责整体系统的生命周期管理和调度循环
2. 调度器(Scheduler)- 根据系统监控指标做出智能调度决策
3. 任务执行器(Runner)- 负责向CPU或GPU服务发送请求并处理响应
4. 系统监控器(SystemMonitor)- 实时监控系统资源使用情况
5. 指标服务(MetricsService)- 收集和报告任务执行性能数据

🔍 常见问题诊断与解决方案

1. 服务启动失败问题排查

问题1：sysHAX服务无法启动

症状：执行syshax run或python3 main.py后服务立即退出或报错。

排查步骤：

1. 检查配置文件路径：确保config/config.yaml文件存在且格式正确
2. 验证端口占用：检查8010端口是否被其他进程占用

   sudo netstat -tlnp | grep :8010

3. 查看日志文件：检查logs/sysHAX.log中的错误信息
4. 验证环境变量：确保必要的环境变量已正确设置

解决方案：

• 如果端口被占用，修改config.yaml中的端口配置或停止占用进程
• 检查配置文件语法，特别是YAML缩进是否正确
• 确保Python依赖已正确安装：pip install -r requirements.txt

问题2：GPU/CPU后端服务连接失败

症状：sysHAX启动时显示"服务连通性测试失败"。

排查步骤：

1. 检查后端服务状态：

   # 检查GPU服务 curl http://localhost:8001/health # 检查CPU服务 curl http://localhost:8002/health

2. 验证配置文件中的服务地址和端口
3. 检查防火墙设置
4. 查看vLLM容器日志

解决方案：

• 确保vLLM服务已正确启动并监听指定端口
• 更新config/config.yaml中的服务配置
• 检查Docker容器网络配置

2. 性能问题诊断

问题3：推理响应速度慢

症状：AI推理任务执行时间过长，吞吐量低于预期。

排查步骤：

1. 检查系统资源使用情况：

   # CPU使用率 top -bn1 | grep "Cpu(s)" # GPU使用率 nvidia-smi # 内存使用情况 free -h

2. 查看sysHAX监控指标：

   • GPU KV缓存使用率
   • CPU KV缓存使用率
   • 运行中请求数
   • 等待中请求数

3. 检查NUMA配置是否正确

解决方案：

• 调整OMP_NUM_THREADS和CUSTOM_CPU_AFFINITY环境变量
• 优化vLLM配置参数，如--gpu_memory_utilization
• 启用PD解耦功能：设置auto_pd_offload: true

问题4：内存不足错误

症状：出现"Out of memory"或"CUDA out of memory"错误。

排查步骤：

1. 检查当前内存使用情况
2. 查看交换请求数量指标
3. 分析模型大小与可用内存的匹配度

解决方案：

• 减少--gpu_memory_utilization参数值
• 增加系统交换空间
• 使用量化模型减少内存占用
• 调整--block_size和--swap_space参数

3. 配置相关问题

问题5：配置文件加载错误

症状：系统启动时提示配置解析错误。

排查步骤：

1. 验证YAML文件语法
2. 检查必需配置项是否完整
3. 查看环境变量覆盖是否正确

解决方案：

• 使用syshax config validate验证配置
• 参考config/config.example.yaml创建正确的配置文件
• 确保所有服务地址和端口配置正确

问题6：环境变量不生效

症状：设置了环境变量但系统行为未改变。

排查步骤：

1. 检查环境变量名称是否正确
2. 验证环境变量作用域
3. 查看日志中环境变量加载情况

解决方案：

• 使用export命令设置环境变量
• 在启动脚本中显式设置环境变量
• 检查.bashrc或.profile文件中的环境变量设置

4. 容器化部署问题

问题7：Docker容器启动失败

症状：执行docker run命令时容器无法启动或立即退出。

sysHAX部署架构

排查步骤：

1. 检查Docker镜像是否存在
2. 验证NVIDIA Container Toolkit安装
3. 检查端口映射配置
4. 查看容器日志：docker logs <container_name>

解决方案：

• 确保已正确安装NVIDIA驱动和CUDA
• 重启Docker服务：sudo systemctl restart docker
• 检查容器资源限制设置
• 验证共享内存配置：--shm-size=64g

问题8：容器间通信失败

症状：GPU容器和CPU容器无法正常通信。

排查步骤：

1. 检查IPC命名空间共享配置
2. 验证网络连通性
3. 检查防火墙规则
4. 查看容器网络模式

解决方案：

• 确保使用正确的--ipc参数
• 检查容器启动顺序（必须先启动GPU容器）
• 验证端口映射是否正确
• 使用docker network inspect检查网络配置

5. 硬件兼容性问题

问题9：GPU设备无法识别

症状：nvidia-smi命令无输出或显示"No devices were found"。

排查步骤：

1. 检查NVIDIA驱动安装
2. 验证CUDA版本兼容性
3. 检查PCIe设备识别
4. 查看内核日志：dmesg | grep -i nvidia

解决方案：

• 重新安装NVIDIA驱动
• 更新内核版本
• 检查硬件连接
• 验证GPU设备在BIOS中已启用

问题10：NUMA配置问题

症状：CPU性能未达到预期，NUMA亲和性失效。

CPU架构示意图

排查步骤：

1. 检查NUMA节点分布：lscpu | grep -i numa
2. 验证CPU绑核配置
3. 检查内存分配策略
4. 测试跨NUMA访问性能

解决方案：

• 确保每个NUMA节点使用的CPU数量相同
• 正确设置CUSTOM_CPU_AFFINITY环境变量
• 调整OMP_NUM_THREADS与绑核数量匹配
• 使用numactl命令验证NUMA配置

6. 日志分析与监控

问题11：日志信息不足

症状：遇到问题时日志中没有足够的信息进行诊断。

解决方案：

1. 启用调试日志级别：

   export DEBUG=true export LOG_LEVEL=DEBUG

2. 检查日志文件位置：logs/sysHAX.log
3. 配置日志轮转策略
4. 使用结构化日志分析工具

问题12：监控指标异常

症状：Prometheus指标显示异常值或无法获取指标。

排查步骤：

1. 检查vLLM指标端点
2. 验证网络连通性
3. 查看指标采集频率
4. 检查指标解析逻辑

解决方案：

• 确保vLLM服务启用了指标导出
• 检查防火墙规则允许指标访问
• 验证指标URL配置正确
• 使用curl手动测试指标端点

🛠️ 故障排查工具箱

常用诊断命令清单

配置文件验证清单

在部署sysHAX前，请确保以下配置项正确：

1. 服务端口配置：

   • GPU服务端口：8001
   • CPU服务端口：8002
   • sysHAX服务端口：8010

2. 环境变量设置：

   • OMP_NUM_THREADS：CPU推理线程数
   • CUSTOM_CPU_AFFINITY：CPU绑核方案
   • INFERENCE_OP_MODE=fused：CPU推理加速
   • SYSHAX_QUANTIZE：量化方案（q4_0或q8_0）

3. Docker配置：

   • 共享内存大小：--shm-size=64g
   • IPC命名空间共享：--ipc container:vllm_gpu
   • GPU访问权限：--gpus=all

📈 性能优化建议

1. 资源调优策略

根据您的硬件配置，以下优化建议可能有所帮助：

• GPU内存优化：调整--gpu_memory_utilization参数，平衡性能与稳定性
• CPU线程配置：根据NUMA节点数量合理分配线程
• 批处理大小：根据负载调整cpu_max_batch_size参数
• PD解耦时机：监控KV缓存使用率，优化PD分离阈值

2. 监控与告警设置

建议设置以下监控指标告警：

• GPU KV缓存使用率 > 90%
• CPU KV缓存使用率 > 80%
• 等待请求数持续增长
• 服务响应时间超过阈值

🔧 高级故障排查

对于复杂问题，可以采取以下高级诊断方法：

1. 性能剖析：使用perf或nvprof进行性能分析
2. 网络跟踪：使用tcpdump分析容器间通信
3. 内存分析：使用valgrind检测内存泄漏
4. 系统调用跟踪：使用strace跟踪系统调用

🎯 总结

sysHAX异构协作加速运行时是一个强大的AI推理调度系统，但正确的配置和故障排查能力是确保其稳定运行的关键。通过本手册提供的诊断方法和解决方案，您可以快速定位和解决大多数常见问题。

记住，良好的监控和日志记录是预防问题的第一道防线。定期检查系统状态、分析性能指标，并保持软件和驱动程序的更新，将帮助您最大限度地发挥sysHAX的性能优势。

如果您在排查过程中遇到本手册未涵盖的问题，建议查阅官方文档或检查源代码中的具体实现细节。祝您使用sysHAX愉快！✨

【免费下载链接】sysHAXsysHAX Heterogeneous collaborative acceleration runtime项目地址: https://gitcode.com/openeuler/sysHAX