路由智能服务

📌 Skill基础信息

Skill名称：RoutIR

简称：routir

来源：社区第三方（hltcoe）

运行宿主：Claude-Code CLI

核心定位：提供统一的检索引擎服务框架，支持密集/稀疏检索、重排序、融合和查询扩展等多阶段检索流水线，适合构建企业级检索系统和RAG应用场景。

🧩 内部核心组成

核心能力模块

• HTTP/gRPC服务框架：统一托管检索引擎服务
• 流水线DSL：小型领域特定语言，用于组合多阶段检索流程
• 客户端SDK：同步/异步客户端接口
• 服务代理机制：支持本地与远程服务混合部署
• 扩展框架：通过配置文件实现新功能扩展

核心命令/工具

配置文件结构

• services：服务引擎配置
• collections：文档集合配置
• server_imports：主服务器导入配置
• file_imports：自定义扩展文件导入

🛠 安装与启用方式

安装命令：

skills install --user hltcoe/routir

关键依赖：

• uvx 工具链（禁止使用原生pip/python）
• 可选依赖：transformers、torch等运行时依赖

启动服务：

uvx --with "routir[dense] @ ." routir my-config.json --port 5000

验证服务：

curl http://localhost:5000/avail
curl http://localhost:5000/ping

📋 标准工作流

1. 配置阶段：编写JSON配置文件，定义服务引擎和文档集合
2. 启动服务：通过uvx启动RoutIR服务器，指定端口和传输协议
3. 服务发现：自动发现并代理远程主服务器服务
4. 客户端调用：使用Client/AsyncClient连接服务端点
5. 流水线执行：通过DSL描述多阶段检索流程，调用pipeline接口
6. 结果处理：获取排序后的文档ID和评分结果

典型调用链路：配置加载 → 服务注册 → 客户端连接 → DSL解析 → 并行执行 → 结果融合 → 返回排序列表

⚠️ 关键限制、缺陷、注意事项

平台限制：

• 强制要求uvx工具链，不支持原生Python环境
• gRPC功能需要额外依赖配置

资源消耗：

• 密集检索模型需要显著GPU内存
• 缓存配置不当可能导致内存压力

生产环境适用性：

• ✅ 适合企业内部检索系统
• ✅ 支持高并发批量处理
• ❌ 实时性要求极高的场景需要谨慎评估

已知坑点：

• 本地服务优先级高于远程服务（命名冲突时）
• 远程集合重排序需要配置内容缓存
• 流水线必须明确指定结果集大小(%N)

✅ 适用场景 & ❌ 不适合场景

适用场景：

• 企业级文档检索系统
• 多模态检索应用（支持多视图文档）
• 混合检索流水线（本地+远程服务组合）
• 检索模型评估和实验平台

不适合场景：

• 超低延迟实时检索（建议<50ms）
• 极小规模部署（框架开销相对较大）
• 无Python扩展能力的封闭环境
• 单一模型简单检索需求（过度工程化）