AI推理赫尔墨斯路由

特性介绍

Hermes-router是一个Kubernetes（K8s）原生的AI推理智能路由方案，用于接收用户推理请求并转发至合适的推理服务后端，通过感知全局KV Cache与支持PD分离架构优化推理效率，提升资源利用率与服务稳定性，适用于云原生场景下的AI推理优化。

应用场景

• 传统聚合推理架构中部署，支持推理请求的智能转发。
• 静态xPyD推理架构中部署，支持PD分离场景下推理请求的智能转发。

能力范围

• 实现面向k8s环境的智能路由架构，端到端处理用户请求。
• 支持用户配置路由的后端架构与路由策略。
• 支持以helm形式在k8s环境部署。

亮点特征

• 模块解耦：配置加载、服务发现、指标收集与路由策略等模块解耦，功能可组合、易维护。
• 可扩展性：通过工厂模式与策略模式，支持路由策略迭代更新，符合开闭原则。
• 智能路由：基于KV Cache匹配度与后端负载情况选择最优后端，提升推理效率。

实现原理

特性运行时序图如下所示：

时序图的起点为用户发起推理请求，在此之前智能路由已完成初始化，因此首先对初始化阶段进行介绍：

1. 智能路由读取配置。
2. 启动服务发现模块（周期性更新后端列表）。
3. 启动指标收集模块（周期性更新后端负载指标）。

每次收到推理请求的处理流程如下：

1. 接收用户推理请求。
2. 调用服务发现模块获取可用后端列表。
3. 调用指标收集模块获取后端负载指标。
4. 调用KV Cache管理模块获取各后端对请求的匹配程度。
5. 根据路由策略选择最佳后端并转发请求。
6. 接收后端推理结果并返回给用户。

与相关特性的关系

• 依赖推理引擎（如vLLM）提供推理服务及指标接口。
• 依赖KV Cache管理工具（如Mooncake）提供全局KV Cache信息。

安装

前提条件

硬件要求

hermes-router本身对硬件环境无特殊要求。

软件要求

• Kubernetes v1.33.0及以上版本。

开始安装

openFuyao平台

1. 登录openFuyao管理面。
2. 左侧导航栏选择“应用市场 > 应用列表”跳转到“应用列表”界面。
3. 勾选左侧“场景”中的“人工智能/机器学习”，查找“hermes-router”卡片。或通过搜索框输入“hermes-router”。
4. 单击“aiaio-installer”卡片，进入“详情”界面。
5. 单击“部署”进入“部署”界面。
6. 输入应用名称、选择安装版本和命名空间。命名空间可以选用已有命名空间或新建命名空间，创建命名空间请参见命名空间。
7. 在参数配置的“Values.yaml”中对路由进行配置。
8. 单击“部署”完成安装。

独立部署

除了openFuyao平台安装部署，本特性还提供独立部署功能，有以下两种途径：

• 从openFuyao官方镜像仓库获取项目安装包。

1. 拉取项目安装包。

   helm pull oci://helm.openfuyao.cn/charts/hermes-router --version xxx

   其中xxx需替换为具体项目安装包版本，如0.0.0-latest。拉取得到的安装包为压缩包形式。

2. 解压安装包。

   tar -zxvf hermes-router

3. 安装部署。

   在hermes-router同级目录下执行如下命令：

   helm install --generate-name ./hermes-router

• 从openFuyao GitCode仓库获取：

1. 从仓库拉取项目。

   git clone https://gitcode.com/openFuyao/hermes-router.git

2. 安装部署。 在hermes-router同级目录下执行如下命令：

   helm install --generate hermes-router/charts/hermes-router

配置AI推理路由

前提条件

• 已获取hermes-router项目文件。
• hermes-router尚未安装部署。

背景信息

无。

使用限制

• 暂不支持请求认证等网关能力，需避免服务入口暴露给无关用户。
• 当前仅支持vLLM推理引擎。
• 当前仅支持AI推理场景，不支持AI训练场景。

操作步骤

1. 准备values.yaml配置文件。

   确保已获取hermes-router项目的helm chart文件夹，并找到values.yaml配置文件，该文件中的app配置段定义AI推理路由的核心参数。

2. 配置基础路由参数。

   • app.namespace：指定路由服务关联的k8s命名空间，用于限定服务发现等操作的范围，示例：namespace: "ai-inference"。
   • app.strategy：配置路由策略，支持KV Cache Aware策略和轮询策略，示例：strategy: "kv-aware"。
   • app.timeout：设置非流式响应的超时时间（单位：秒），超过该时间未完成的请求将被终止，示例：timeout: 120。

3. 配置服务发现规则。

   通过app.discovery配置后端推理服务的自动发现机制：

   • app.discovery.type：服务发现类型，当前仅支持k8s-service（基于k8s原生部署的服务发现）。
   • app.discovery.interval：服务发现刷新间隔（单位：秒），定期更新后端服务列表，示例：interval: 5。
   • app.discovery.labelSelector：通过k8s标签筛选后端服务，仅匹配指定标签的服务，示例：labelSelector: { app: vllm }。
   • app.discovery.inferencePort：后端推理服务端口，示例：inferencePort: 8000。
   • app.discovery.timeout：服务发现操作的超时时间（单位：秒），示例：timeout: 10。

4. 配置指标收集参数。

   在app.collector中设置后端服务指标的收集规则，以支持KV Cache Aware策略：

   • app.collector.type：指标收集类型，当前仅支持vllm。
   • app.collector.interval：指标刷新间隔（单位：秒），定期采集后端服务指标，示例：interval: 5。
   • app.collector.timeout：指标收集超时时间（单位：秒），示例：timeout: 10。
   • app.collector.metrics：需要收集的指标列表，例如XPU缓存使用率vllm:gpu_cache_usage_perc。

5. 配置KV Cache全局管理器信息。

   若使用kv-aware策略，需通过app.kvmanager配置KV Cache全局管理器的连接参数：

   • app.kvmanager.url：KV Cache全局管理器的访问地址，示例：url: "http://10.96.xxx.xxx"。
   • app.kvmanager.port：KV Cache全局管理器端口，示例：port: 8080。
   • app.kvmanager.matchPath：KV Cache全局管理器的路由匹配接口路径，示例：matchPath: "/match_sort"。
   • app.kvmanager.timeout：访问KV Cache全局管理器的超时时间（单位：秒），示例：timeout: 10。

6. 部署路由以应用配置。

   用户参考安装章节部署路由以应用配置。

相关操作

安装部署后，用户可以通过修改ConfigMap获values.yaml更新AI推理路由配置。

使用AI推理服务

前提条件

• 已成功部署hermes-router AI推理服务。
• 已成功部署聚合/PD分离的推理后端，hermes-router能够正确发现后端服务与推理指标。
• 已获取hermes-router的入口URL，如：http://localhost:8000/rest/hermes-router/v1beta1/v1/chat/completons。

背景信息

• 推理请求接口采用OpenAI API风格。
• 支持流式/非流式响应。

使用限制

• 当前仅支持OpenAI API接口风格的纯文本推理，不支持多模态推理。

操作步骤

1. 构造推理请求，示例如下：

{
  "model": "deepseek-ai/DeepSeek-R1-Distill-Qwen-1.5B",
  "messages": [{"role": "user", "content": "请介绍openFuyao开源社区"}],
  "stream": true
}

2. 向hermes-router发送推理请求，以curl发送请求为例：

curl http://localhost:8000/rest/hermes-router/v1beta1/v1/chat/completons \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-ai/DeepSeek-R1-Distill-Qwen-1.5B",
    "messages": [{"role": "user", "content": "请介绍openFuyao开源社区"}],
    "stream": true
  }'

3. 接收推理结果：

• 流式响应逐块返回以data:开头的json对象。
• 非流式响应一次性返回完整结果。

相关操作

无。