内容
<h1 align="center">LLMRix 模型路由</h1>
<p align="center">
<strong>面向生产的 Java 多模型路由和编排框架。</strong>
</p>
<p align="center">
<em>OpenAI 兼容提供商 · Spring AI · LangChain4j · 语义路由 · 上下文强盗 · Fugu 编排</em>
</p>
<p align="center">
<a href="https://github.com/llmrix/llmrix-router/stargazers"><img src="https://img.shields.io/github/stars/llmrix/llmrix-router?style=for-the-badge&logo=github&color=ffca28" alt="GitHub Stars"></a>
<a href="https://github.com/llmrix/llmrix-router/network/members"><img src="https://img.shields.io/github/forks/llmrix/llmrix-router?style=for-the-badge&logo=github&color=8bc34a" alt="GitHub Forks"></a>
<a href="./LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue?style=for-the-badge" alt="License"></a>
<a href="#requirements"><img src="https://img.shields.io/badge/Java-17%2B-orange?style=for-the-badge&logo=openjdk&logoColor=white" alt="Java Version"></a>
<a href="#spring-boot"><img src="https://img.shields.io/badge/Spring%20Boot-3.x-6db33f?style=for-the-badge&logo=springboot&logoColor=white" alt="Spring Boot"></a>
<img src="https://img.shields.io/badge/version-1.0.0-blue?style=for-the-badge" alt="Version">
</p>
<p align="center">
<a href="#why-llmrix">为什么选择 LLMRix</a> •
<a href="#architecture">架构</a> •
<a href="#modules">模块</a> •
<a href="#quick-start">快速入门</a> •
<a href="#spring-boot">Spring Boot</a> •
<a href="#openai-compatible-server">服务器</a> •
<a href="#orion-client">客户端</a>
</p>
<p align="center">
<a href="./README.zh-CN.md">简体中文</a> | <a href="./README.md">English</a>
</p>
LLMRix 通过一个稳定的 `ChatModel` 接口暴露多个模型提供商。它使用能力、质量、成本、延迟、配额和健康信号选择合格的模型，然后应用有界重试、冷却和回退，而不会将路由复杂性泄漏到应用程序代码中。
将其用作嵌入式 Java SDK、Spring Boot 启动器或 OpenAI 兼容的路由服务。
> 项目状态：通用可用性 (`1.0.0`)。Java API 和配置模型已准备好投入生产，语义版本控制严格执行。
## 为什么选择 LLMRix
- **一个模型合约**，适用于 OpenAI 兼容的提供商、Spring AI、LangChain4j 和自定义实现。
- **策略与执行分离**：策略对候选者进行排名；执行者负责超时、重试、配额、冷却和回退的正确性。
- **流安全故障转移**：在第一个发出块之前允许故障转移，在输出开始后禁止。
- **本地或分布式状态**：零基础设施本地模式和 Redis 支持的健康、租赁、RPM 和 TPM，用于多实例部署。
- **OpenAI 兼容边缘**：`/v1/chat/completions`、`/v1/responses` 和 `/v1/models`，包括 SSE 流式传输。
- **框架中立的客户端**：Orion 提供了一个小型 Java 客户端和可选的 Spring Boot 自动配置。
- **可观察性设计**：生命周期事件、Micrometer 指标、Spring 观察、请求 ID 和健康指标。
- **可组合的高级路由**：语义路由、上下文强盗、在线影子流量、评估和 Fugu 风格的迭代编排。
## 架构
[打开交互式 HTML 架构](docs/architecture/index.html)，或下载 [SVG](docs/architecture/llmrix-architecture.svg)。
框架拥有路由语义和请求正确性。基础设施仍然负责 TLS、WAF、负载均衡、Redis HA、密钥管理、遥测存储和容器编排。
## 模块
| 工件 | 责任 |
|---|---|
| `llmrix-model-router-core` | 提供者中立的 API、候选模型、策略、执行、状态 SPI、配额、健康和事件。 |
| `llmrix-model-router-integrations` | OpenAI 兼容、Spring AI、LangChain4j、Redis、Bucket4j、ONNX、评估、影子流量和 Fugu 适配器。 |
| `llmrix-model-router-spring-starter` | 路由器属性、自动配置、Micrometer/观察、执行器和配置元数据。 |
| `llmrix-model-router-server` | OpenAI 兼容的 HTTP/SSE 端点、身份验证 SPI、请求 ID 和协议错误处理。 |
| `llmrix-model-orion` | 用于路由服务器的轻量级框架中立 Java 客户端。 |
| `llmrix-model-orion-spring-starter` | Orion 自动配置和 Micrometer 集成。 |
| `llmrix-model-examples` | 可执行的示例和集中的测试套件。不是生产依赖项。 |
## 要求
- Java 17 或更高版本；推荐 Java 21。
- 使用任一启动器时使用 Spring Boot 3.x。
- Redis 是可选的，仅在共享的多实例运行时状态下需要。
## 快速入门
### Maven
```xml
<dependency>
<groupId>com.llmrix.model</groupId>
<artifactId>llmrix-model-router-core</artifactId>
<version>1.0.0</version>
</dependency>
<dependency>
<groupId>com.llmrix.model</groupId>
<artifactId>llmrix-model-router-integrations</artifactId>
<version>1.0.0</version>
</dependency>
```
### 主要和备用
```java
ChatModel model = RoutedChatModel.of(primary).fallbackTo(backup);
ChatResponse response = model.chat("Review this Java code for concurrency issues");
```
### 基于策略的路由
```java
RoutedChatModel model = RoutedChatModel.builder()
.candidate("reasoning", reasoningModel, c -> c
.capabilities(Capability.REASONING, Capability.TOOLS)
.inputCostPerMillion(1.25)
.outputCostPerMillion(10.00))
.candidate("fast", fastModel, c -> c
.capabilities(Capability.CHAT, Capability.CODE)
.inputCostPerMillion(0.27)
.outputCostPerMillion(1.10))
.strategy(Strategies.balanced())
.timeout(Duration.ofSeconds(30))
.maxRetries(1)
.build();
ChatResponse response = model.chat(ChatRequest.builder()
.userMessage("Find the race condition")
.routingHints(RoutingHints.builder()
.require(Capability.CODE)
.maxCostUsd(0.05)
.build())
.build());
```
应用程序可以同步、异步或作为 `Flow.Publisher<ChatChunk>` 调用。文本、图像、输入音频、工具、结构化响应格式、用法、完成原因和通用生成选项由提供者中立的核心类型表示。
## 路由模型
每个请求都遵循一个确定的执行管道：
1. 验证请求并规范化路由提示。
2. 删除违反能力、模型、上下文、成本、配额、并发性或健康约束的候选者。
3. 使用配置的策略对合格的候选者进行排名。
4. 获取运行时配额和并发租赁。
5. 在有界的每次尝试和总超时内执行。
6. 仅在配置的预算内重试可重试的故障。
7. 标记故障、应用冷却并移至下一个备用。
8. 结算令牌使用量、释放租赁并发布生命周期观察。
内置策略包括优先级、轮询、加权随机、平衡评分、语义评分和上下文强盗选择。自定义策略实现 `RoutingStrategy`；自定义运行时持久性实现 `RouterStateStore` 或 `BanditStateStore`。
## Spring Boot
```xml
<dependency>
<groupId>com.llmrix.model</groupId>
<artifactId>llmrix-model-router-spring-starter</artifactId>
<version>1.0.0</version>
</dependency>
```
```yaml
llmrix:
model:
router:
default-route: general
routes:
general:
strategy: balanced
candidates: [primary, backup]
fallbacks: [backup]
execution:
timeout: 30s
max-retries: 1
state:
mode: local # use redis for shared multi-instance limits and health
candidates:
primary:
provider: openai-compatible
base-url: https://api.openai.com/v1
api-key: ${OPENAI_API_KEY}
model-name: gpt-4.1-mini
capabilities: [chat, tools, code]
backup:
provider: openai-compatible
base-url: https://api.deepseek.com/v1
api-key: ${DEEPSEEK_API_KEY}
model-name: deepseek-chat
capabilities: [chat, code]
```
启动器创建路由模型 bean，在应用程序提供自己的 bean 时进行备份，在启动时验证无效的候选配置，并为相应的主机库提供健康和遥测集成。
### 共享状态
```yaml
llmrix:
model:
router:
state:
mode: redis
redis:
uri: redis://localhost:6379/0
key-prefix: llmrix:model:router
lease-ttl: 2m
quota-window: 1m
```
Redis 模式是故障关闭的：无效配置或不可用的存储不会静默地将全局限制降级为 JVM 本地限制。实现使用 Lettuce 和原子 Lua 操作；不需要 Redisson。
## OpenAI 兼容服务器
可选服务器公开：
| 端点 | 支持 |
|---|---|
| `POST /v1/chat/completions` | 同步和 SSE 流式聊天完成。 |
| `POST /v1/responses` | 核心响应 API 子集，显式拒绝不支持的语义字段。 |
| `GET /v1/models` | 可用的路由模型和路由标识符。 |
它支持不透明的 Bearer 密钥，通过 `ApiKeyVerifier`，传播或生成 `X-Request-Id`，并发出 OpenAI 形状的错误。它故意不颁发密钥，不管理租户，也不存储秘密；这些责任属于 IAM 或秘密管理系统。
## Orion 客户端
```java
OrionModelClient client = OrionModelClient.builder()
.baseUrl("https://router.example.com/v1")
.apiKey(System.getenv("LLMRIX_API_KEY"))
.build();
ChatModel model = client.chatModel("support-route");
ChatResponse response = model.chat("Summarize this incident");
```
请求级选项支持请求 ID 和安全的自定义标头。身份验证不能动态覆盖，并且标头名称和值针对 CRLF 注入进行了验证。
## 可靠性和流式传输
- 重试和故障转移仅适用于被分类为可重试的故障。
- 流式请求可以在其第一个块之前切换候选，在数据对调用者可见后永远不会切换。
- 取消传播到活动候选并释放运行时状态。
- 带有工具的请求不得盲目重放，因为工具可能有副作用。
- 上游 HTTP 状态在提供者域异常上保留；非 HTTP 故障使用 `-1`。
## 可观察性
路由器和 Fugu 生命周期监听器是稳定的核心可观察边界。可选的 Spring 集成提供 Micrometer 计数器/定时器、第一个令牌延迟、观察上下文、执行器健康和请求 ID 相关性。Orion 公开其自己的依赖无关的监听器 SPI，并在通过 Spring 使用时将其适配到 Micrometer。
该框架发出遥测数据，但不部署 Prometheus、Grafana、OpenTelemetry Collector 或日志存储。
## Fugu 编排
`FuguOrchestrator` 实现用于求解器-审阅器和精炼工作流的迭代候选/角色选择。它支持基于规则或 ONNX 的策略、有界回合、重试/故障转移、可选的共享冷却状态和生命周期 `Flow.Publisher`。生命周期流表示编排事件，而不是模型令牌块。
训练、奖励建模和策略推出保持离线。运行时策略清单在推理前进行版本化和验证。
## 扩展点
| SPI | 用它来 |
|---|---|
| `ChatModel` / 流模型合约 | 集成提供者或现有的模型客户端。 |
| `RoutingStrategy` | 实现业务特定的候选排序。 |
| `RouterStateStore` | 持久化健康、配额和并发状态。 |
| `BanditStateStore` | 共享上下文强盗选择和奖励。 |
| 路由器/Fugu 监听器 | 导出跟踪、指标、审计事件或反馈。 |
| `ApiKeyVerifier` | 将服务器连接到外部身份基础设施。 |
| 候选工厂注册表 | 将提供者类型添加到 Spring Boot 配置中。 |
## 构建和测试
```bash
mvn clean test
mvn package -DskipTests
```
测试集中在 `llmrix-model-examples` 中。Redis 集成测试需要一个真实的 Redis 实例；HTTP/SSE 测试需要允许绑定本地端口。CI 预计在 Java 17 和 Java 21 上运行。
## 范围
LLMRix 是一个路由框架，而不是 API 网关、模型主机、训练平台、秘密管理器或基础设施控制平面。当需要网关功能时，请将其部署在 Higress、APISIX、Nginx 或云负载均衡器后面。提供者密钥应通过部署环境或托管的秘密存储提供。
## 兼容性
该项目遵循语义版本控制。在 `1.0` 之后，公共 Java API、Maven 坐标、协议行为和 `llmrix.model.*` 配置在主版本内保持向后兼容。实验性 API 明确记录并排除在此保证之外。
## 贡献
欢迎提交错误报告、功能请求和拉取请求 - 请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 和 [GIT_CONVENTIONS.md](GIT_CONVENTIONS.md)。请在参与之前阅读 [行为准则](CODE_OF_CONDUCT.md)。
## 安全
要报告漏洞，请遵循 [安全策略](SECURITY.md)。不要公开创建问题。
## 更新日志
发布历史记录在 [CHANGELOG.md](CHANGELOG.md) 中维护。
## 许可证
MIT 许可证 - 请参阅 [LICENSE](LICENSE)。
连接信息
猜你喜欢
暂无推荐服务器