sysHAX API使用指南：如何通过RESTful接口调用异构推理服务

sysHAX API使用指南：如何通过RESTful接口调用异构推理服务

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

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

sysHAX是一个开源的异构协作加速运行时系统，能够智能地在CPU和GPU之间分配AI推理任务，实现资源的高效利用和推理性能的优化。本文将详细介绍如何通过RESTful API接口调用sysHAX的异构推理服务，让您轻松掌握这一强大的AI推理加速工具。

🚀 sysHAX系统架构概览

sysHAX采用微服务架构设计，通过智能调度算法在CPU和GPU之间动态分配推理任务。系统架构如下图所示：

sysHAX异构加速架构

从图中可以看到，sysHAX包含以下核心组件：

• 核心引擎(Engine)：负责整体系统的生命周期管理
• 调度器(Scheduler)：智能调度决策，分配任务到合适设备
• 任务执行器(Runner)：向CPU或GPU服务发送请求并处理响应
• 系统监控器(SystemMonitor)：实时监控系统资源使用情况
• 指标服务(MetricsService)：收集和报告任务执行性能数据

📡 API接口快速入门

基础配置准备

在使用sysHAX API之前，您需要确保系统正确部署。配置文件位于config/config.example.yaml，您需要根据实际环境进行配置：

services: gpu: host: "0.0.0.0" port: 7001 cpu: host: "0.0.0.0" port: 7002 conductor: host: "0.0.0.0" port: 7010

sysHAX主服务默认运行在7010端口，您可以通过该端口访问所有API接口。

核心API接口

sysHAX提供了简洁的RESTful API接口，主要包含两个核心端点：

1. 聊天补全接口/v1/chat/completions

这是sysHAX最主要的API接口，支持流式和非流式两种响应模式：

请求示例（非流式）：

curl -X POST http://localhost:7010/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{ "messages": [ {"role": "user", "content": "你好，请介绍一下openEuler操作系统"} ], "model": "qwen2.5-7b", "max_tokens": 1000 }'

请求示例（流式响应）：

curl -X POST http://localhost:7010/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{ "messages": [ {"role": "user", "content": "你好，请介绍一下openEuler操作系统"} ], "model": "qwen2.5-7b", "max_tokens": 1000, "stream": true }'

2. 通用转发接口/{full_path:path}

sysHAX还提供了通用转发接口，可以将未识别的请求自动转发到GPU服务：

sysHAX部署架构

该接口支持所有HTTP方法（GET、POST、PUT、DELETE、PATCH、OPTIONS），确保与现有AI服务API的兼容性。

🔧 API参数详解

请求参数说明

响应格式

非流式响应示例：

{ "id": "chatcmpl-123", "object": "chat.completion", "created": 1677652288, "model": "qwen2.5-7b", "choices": [{ "index": 0, "message": { "role": "assistant", "content": "openEuler是一个开源的Linux发行版..." }, "finish_reason": "stop" }], "usage": { "prompt_tokens": 9, "completion_tokens": 12, "total_tokens": 21 } }

流式响应示例：

data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1677652288,"model":"qwen2.5-7b","choices":[{"index":0,"delta":{"content":"open"},"finish_reason":null}]} data: {"id":"chatcmpl-123","object":"chat.completion.chunk","created":1677652288,"model":"qwen2.5-7b","choices":[{"index":0,"delta":{"content":"Euler"},"finish_reason":null}]} data: [DONE]

⚡ 智能调度特性

sysHAX的核心优势在于其智能调度能力。系统会根据以下因素自动选择最佳推理设备：

1. 资源监控与负载均衡

系统实时监控CPU和GPU的资源使用情况，包括：

• CPU/GPU利用率
• 内存使用情况
• 当前并发任务数
• 响应延迟指标

CPU架构示意图

2. 自动PD解耦功能

sysHAX支持自动Prefill-Decode解耦功能，可根据任务特性智能优化：

• Prefill阶段：通常分配至GPU进行并行计算
• Decode阶段：根据负载情况智能分配到CPU或GPU

GPU与CPU协同架构

3. 动态调度策略

调度器位于src/core/scheduler.py，采用多种调度策略：

• 基于资源利用率的负载均衡
• 基于任务优先级的队列管理
• 基于历史性能的自适应调度

🛠️ 高级配置选项

配置自动PD解耦

在config/config.example.yaml中，您可以配置自动PD解耦功能：

decider: # 是否开启自动PD offload auto_pd_offload: true # CPU最大并发量 cpu_max_batch_size: 20

超时设置

系统支持自定义请求超时时间：

system: # 请求超时时间(秒) request_timeout: 600

📊 性能监控与指标

sysHAX提供了丰富的性能监控指标，帮助您优化推理服务：

关键性能指标

• 请求延迟：端到端响应时间
• 吞吐量：单位时间处理的请求数
• 资源利用率：CPU/GPU使用率
• 错误率：请求失败比例

系统CPU信息

监控接口

系统监控器位于src/core/monitor.py，实时收集以下指标：

• 系统级资源使用情况
• 服务级性能数据
• 任务级执行统计

🔍 故障排除指南

常见问题及解决方案

1. API请求超时

   • 检查配置文件中的超时设置
   • 确认后端服务正常运行
   • 检查网络连接状态

2. 调度决策异常

   • 验证系统监控数据准确性
   • 检查资源使用情况
   • 查看调度器日志

3. 性能下降

   • 优化batch size配置
   • 调整自动PD解耦参数
   • 监控资源瓶颈

日志查看

sysHAX的日志系统位于src/utils/logger.py，支持多级别日志记录：

• INFO：常规操作日志
• WARNING：警告信息
• ERROR：错误信息
• DEBUG：调试信息（需手动开启）

🎯 最佳实践建议

1. 合理的batch size配置

根据您的硬件配置调整cpu_max_batch_size参数，平衡并发性能和资源使用。

2. 启用自动PD解耦

对于长文本生成任务，建议启用自动PD解耦功能，可以显著提升推理效率。

3. 监控系统指标

定期查看系统监控数据，根据实际负载调整调度策略。

4. 渐进式部署

在生产环境中，建议先在小规模流量上测试sysHAX的调度效果，逐步扩大部署规模。

📈 性能优化技巧

1. 模型选择优化

• 轻量级模型适合CPU推理
• 复杂模型优先使用GPU
• 根据任务特性选择合适模型

2. 请求批处理

• 合理设置请求批处理大小
• 利用sysHAX的智能调度能力
• 平衡延迟和吞吐量

NPU与CPU协同架构

3. 资源预留策略

• 为关键任务预留资源
• 设置合理的资源使用阈值
• 实现弹性伸缩机制

🚀 快速开始示例

步骤1：安装sysHAX

# 克隆仓库 git clone https://gitcode.com/openeuler/sysHAX # 进入项目目录 cd sysHAX # 安装依赖 pip install -r requirements.txt

步骤2：配置服务

复制配置文件并修改：

cp config/config.example.yaml config/config.yaml # 编辑config.yaml，配置您的GPU和CPU服务地址

步骤3：启动sysHAX

python main.py

步骤4：测试API接口

使用curl或Postman测试API接口：

# 测试聊天接口 curl -X POST http://localhost:7010/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{"messages":[{"role":"user","content":"Hello"}],"model":"test-model"}'

💡 总结

sysHAX通过其智能的异构协作加速能力，为AI推理服务提供了强大的性能优化方案。通过本文介绍的RESTful API接口，您可以轻松地将sysHAX集成到现有的AI服务架构中，享受自动化的资源调度和性能优化。

无论您是AI服务开发者、系统管理员还是运维工程师，掌握sysHAX API的使用都将帮助您构建更高效、更可靠的AI推理服务平台。现在就开始使用sysHAX，体验智能异构加速带来的性能提升吧！🚀

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