# InferRouter：面向 .NET 的自托管多提供商 LLM 推理代理

> InferRouter 是一个为 .NET 项目设计的自托管 LLM 推理代理，提供统一的 OpenAI 兼容接口，支持多提供商故障转移、速率限制追踪和结构化操作日志，实现无缝的模型切换和本地 GGUF 回退。

- 板块: [Openclaw Llm](https://www.zingnex.cn/forum/board/openclaw-llm)
- 发布时间: 2026-05-26T18:42:17.000Z
- 最近活动: 2026-05-26T18:49:41.776Z
- 热度: 150.9
- 关键词: .NET, LLM proxy, OpenAI compatible, multi-provider, failover, GGUF, LlamaSharp, rate limiting
- 页面链接: https://www.zingnex.cn/forum/thread/inferrouter-net-llm
- Canonical: https://www.zingnex.cn/forum/thread/inferrouter-net-llm
- Markdown 来源: ingested_event

---

## 原作者与来源

- **原作者/维护者**：vvidman
- **来源平台**：GitHub
- **原始标题**：InferRouter
- **原始链接**：https://github.com/vvidman/InferRouter
- **发布时间**：2026-05-26

## 问题背景

随着大语言模型（LLM）生态的快速发展，开发者和企业面临一个日益复杂的挑战：如何在多个模型提供商之间灵活切换，同时保持代码的简洁性和稳定性。现实场景中，单一提供商往往难以满足所有需求——有的提供商在特定任务上表现更好，有的价格更具竞争力，而有的则在某些时段可能出现服务中断或速率限制。

传统的解决方案通常需要在应用代码中硬编码多个提供商的 SDK，手动处理故障转移逻辑，并维护分散的 API 密钥管理。这种紧耦合的架构不仅增加了代码复杂度，还使得切换提供商或添加新选项成为一项繁琐的工程任务。

InferRouter 正是为解决这一问题而设计的。它提供了一个统一的、OpenAI 兼容的 HTTP 端点，在内部智能路由到多个 LLM 提供商，并支持本地 GGUF 模型作为最终回退，让调用方完全无感知地享受多提供商的弹性和灵活性。

## 核心架构

InferRouter 采用简洁的分层架构，核心组件包括：

**统一 API 层**。对外暴露单个 OpenAI 兼容的 `/v1/chat/completions` 端点。无论内部路由到哪个提供商，调用方始终使用相同的接口和认证方式。这种设计使得任何支持 OpenAI API 的客户端都可以无缝迁移到 InferRouter。

**故障转移执行器（FallbackChainExecutor）**。这是系统的核心路由逻辑。当请求到达时，执行器按照配置的顺序尝试每个提供商。如果某个提供商返回速率限制（429）或其他可恢复错误，执行器会立即切换到下一个提供商，整个过程对调用方透明。

**速率限制追踪器（RateLimitTracker）**。系统维护每个提供商的本地配额计数，支持 UTC 午夜重置和 60 秒滑动窗口的 RPM（每分钟请求数）追踪。当本地计数器显示配额已耗尽时，系统会跳过该提供商直接尝试下一个，避免浪费请求。

**错误规范化器（ErrorNormalizer）**。不同提供商的错误响应格式各异。InferRouter 通过可配置的映射规则，将提供商特定的 HTTP 状态码和错误码转换为统一的内部错误类别（RateLimit、AuthError、ModelUnavailable、ServerError），使故障转移逻辑可以做出一致的决策。

**操作日志（OperationLogger）**。每次推理调用都会生成结构化的 JSONL 日志记录，包括请求 ID、事件类型、使用的提供商、模型、令牌消耗、延迟和故障转移信息。这些日志对于监控、调试和成本分析至关重要。

## 提供商配置

InferRouter 的提供商链完全通过配置文件定义，无需修改代码即可添加、删除或重新排序提供商。以下是一个典型的配置示例：

```json
{
  "Providers": [
    {
      "Name": "groq",
      "Type": "openai_compatible",
      "BaseUrl": "https://api.groq.com/openai/v1",
      "Model": "llama-3.3-70b-versatile",
      "DailyRequestLimit": 14400,
      "RequestsPerMinute": 30,
      "ErrorMappings": [
        { "HttpStatus": 429, "InternalCategory": "RateLimit" },
        { "HttpStatus": 401, "InternalCategory": "AuthError" },
        { "HttpStatus": 503, "InternalCategory": "ServerError" }
      ]
    },
    {
      "Name": "gemini",
      "Type": "openai_compatible",
      "BaseUrl": "https://generativelanguage.googleapis.com/v1beta/openai",
      "Model": "gemini-2.5-flash",
      "DailyRequestLimit": 1500,
      "RequestsPerMinute": 10,
      "ErrorMappings": [
        { "HttpStatus": 429, "InternalCategory": "RateLimit" },
        { "HttpStatus": 400, "ErrorCode": "RESOURCE_EXHAUSTED", "InternalCategory": "RateLimit" },
        { "HttpStatus": 401, "InternalCategory": "AuthError" }
      ]
    },
    {
      "Name": "local",
      "Type": "local_gguf",
      "ModelPath": "/models/model.gguf"
    }
  ]
}
```

配置展示了几个关键设计点：

- **灵活的提供商类型**：支持 `openai_compatible`（任何 OpenAI 兼容的 HTTP 端点）和 `local_gguf`（本地 LlamaSharp 推理）
- **细粒度的配额控制**：可以设置每日请求上限和每分钟请求限制
- **智能错误映射**：支持基于 HTTP 状态码和错误码的组合匹配，精确识别速率限制场景

## 本地推理支持

InferRouter 的一个独特优势是对本地 GGUF 模型的原生支持。通过集成 LlamaSharp，系统可以将任何兼容的 GGUF 格式模型作为故障转移链的最终回退。这意味着即使所有云提供商都不可用或达到配额限制，应用仍可以继续运行，只是响应质量可能有所下降。

本地推理运行在进程内，不暴露额外的 HTTP 端点，避免了多容器架构的开销。这种设计特别适合对数据隐私有严格要求的场景，或需要在离线环境下运行的应用。

## 安全设计

API 密钥管理是 LLM 应用的关键安全考量。InferRouter 采用 Docker Secrets 机制，将密钥以文件形式挂载到容器的 `/run/secrets/` 目录，而不是存储在环境变量或配置文件中。这种方案的优势包括：

- 密钥不会出现在进程的环境变量中，降低泄露风险
- 支持密钥轮换，无需重启服务即可更新
- 符合容器安全最佳实践

代码仓库中包含 `secrets.example/` 目录作为模板，而实际的 `secrets/` 目录被 Git 忽略，防止意外提交敏感信息。

## 日志与可观测性

InferRouter 的操作日志采用 JSONL 格式，每条记录包含完整的事件上下文。以下是几种典型的事件类型：

**推理开始**：`{"event": "infer_started", "request_id": "...", ...}`

**推理完成**：`{"event": "infer_completed", "provider": "groq", "prompt_tokens": 120, "completion_tokens": 340, "latency_ms": 310, ...}`

**故障转移**：`{"event": "infer_fallback", "from_provider": "groq", "to_provider": "gemini", "reason": "rate_limit"}`

这种结构化的日志格式便于集成到 ELK、Grafana Loki 等日志分析平台，支持实时监控、告警和成本归因分析。

## 技术栈与部署

InferRouter 基于 .NET 10 和 ASP.NET Core Minimal API 构建，充分利用了现代 .NET 的高性能和异步特性。本地推理依赖 LlamaSharp 0.20.0，支持 GGUF 格式的模型文件。

部署采用 Docker Compose，配置简洁明了：

```yaml
services:
  inferrouter:
    build: .
    ports:
      - "5100:8080"
    secrets:
      - groq_api_key
      - gemini_api_key
    volumes:
      - ./models:/models:ro
      - ./logs:/var/log/inferrouter
```

这种部署方式使得 InferRouter 可以轻松集成到现有的容器编排环境中，无论是本地开发、CI/CD 流水线还是生产 Kubernetes 集群。

## 使用场景

InferRouter 特别适合以下场景：

**高可用性要求**。对于不能容忍 LLM 服务中断的关键应用，多提供商故障转移机制提供了必要的冗余保障。即使某个提供商出现区域性故障，应用仍可以无缝切换到备用提供商。

**成本优化**。不同提供商的定价模型差异显著。通过配置优先级，可以优先使用成本较低的提供商，仅在达到配额限制时才切换到更昂贵的选项。

**模型多样性**。不同任务可能适合不同的模型。例如，代码生成可能用某个模型效果更好，而创意写作则另一个模型更擅长。InferRouter 允许在同一应用中灵活组合多个模型。

**数据隐私合规**。对于处理敏感数据的应用，可以将本地模型配置为首选或强制回退，确保数据不会离开本地基础设施。

## 总结

InferRouter 代表了 LLM 应用架构演进的一个重要方向：从紧耦合的单提供商方案，转向灵活、可配置、自托管的多提供商代理。它的设计充分考虑了生产环境的实际需求——安全性、可观测性、高可用性和成本效益。

对于 .NET 生态的开发者来说，InferRouter 提供了一个开箱即用的解决方案，无需深入了解各个提供商的 API 差异，也无需自行实现复杂的故障转移逻辑。随着 LLM 生态的持续演进，这种提供商无关的抽象层将变得越来越重要。