schedion/llmrouter

llmrouter

llmrouter是一个可编程的OpenAI兼容大语言模型路由器，允许您组合多个提供商、优雅降级并缓存响应，而无需更改上游客户端代码。

核心功能

• 多提供商支持：开箱即用支持Groq、OpenRouter、NVIDIA NIM、Hugging Face Inference API等主流LLM服务提供商
• 智能路由：自动在不同提供商间切换，实现服务故障时的优雅降级
• 缓存机制：支持精确匹配缓存（通过TTL控制）和语义缓存（可全局或按请求开关）
• 可观测性：提供Prometheus指标（/metrics）和轻量级HTML仪表盘（/metrics/dashboard）监控流量与提供商状态

使用场景

• 需要整合多个LLM服务提供商的应用场景
• 希望避免单一提供商依赖，提升服务可用性
• 需要缓存LLM响应以降低成本和提高响应速度
• 需使用OpenAI兼容接口但不想受限于单一平台

配置说明

1. 模型目录配置：规范模型映射存储在config/model_catalog_seed.yaml，可通过脚本生成模型索引：

   bash
   ./scripts/build_free_model_catalog.py \
     --providers groq,openrouter,nvidia_nim,huggingface \
     --output generated/model_index.json --pretty
   

2. 凭证设置：通过环境变量配置提供商凭证（如PROVIDER_KEY_GROQ、PROVIDER_KEY_OPENROUTER等）
3. 缓存配置：
   • 精确匹配缓存：通过LLMROUTER_CACHE_TTL设置有效期（秒，0表示禁用）
   • 语义缓存：通过LLMROUTER_SEMANTIC_CACHE_ENABLED全局开关，或请求头X-LLMRouter-Semantic-Cache/X-LLMRouter-Semantic-Threshold按请求控制

Docker部署示例

快速启动

bash
# 拉取镜像（选择适合的版本）
docker pull schedion/llmrouter:latest  # 含语义缓存依赖（仅amd64）
# 或
docker pull schedion/llmrouter:slim    # 无语义缓存依赖（多架构支持）

# 运行容器（替换环境变量为实际凭证）
docker run -d \
  -p 8000:8000 \
  -e PROVIDER_KEY_GROQ=your_groq_key \
  -e PROVIDER_KEY_OPENROUTER=your_openrouter_key \
  -e LLMROUTER_MODEL_INDEX_URL="https://raw.githubusercontent.com/schedion/llmrouter/refs/heads/main/generated/model_index.json" \
  schedion/llmrouter:latest

Docker Compose示例

使用提供的docker-compose.sample.yml（需更新镜像名称和凭证）：

bash
docker compose -f docker-compose.sample.yml up -d

镜像版本说明

• schedion/llmrouter:slim：最小体积版本，不含语义缓存依赖（支持linux/amd64、linux/arm64、linux/arm/v7）
• schedion/llmrouter:latest：完整版本，包含语义缓存依赖（仅支持linux/amd64）

接口使用示例

bash
# 列出可用模型
curl http://localhost:8000/v1/models

# 发起聊天完成请求
curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
        "model": "gpt-oss-20b",
        "messages": [
          {"role": "system", "content": "您是一个简洁的助手。"},
          {"role": "user", "content": "你好"}
        ]
      }'

开源信息

• GitHub仓库：https://github.com/schedion/llmrouter
• Docker Hub镜像：https://hub.docker.com/r/schedion/llmrouter
• 许可证：The Unlicense