iamapsrajput/modelmuxer

# ModelMuxer - 智能 LLM 路由器 ModelMuxer 是一个智能 LLM 路由服务，通过为每个请求自动选择最佳的提供商和模型来优化成本与质量。它使用直接的提供商连接以获得最佳性能和可靠性，并提供成本跟踪、预算管理和智能启发式路由等高级功能。 ## 功能 - **多提供商支持**：直接连接 OpenAI、Anthropic、Mistral、Google、Groq、Cohere、Together AI - **智能路由**：结合意图分类、成本估算和延迟先验的启发式提供商/模型选择 - **成本跟踪**：实时成本监控和预算管理（Redis 为可选，带有内存回退机制） - **策略执行**：PII 脱敏、越狱检测，以及基于租户的模型/区域允许和拒绝列表 - **可观测性**：全面的指标、追踪和监控 ## 快速开始 ### 安装 ``` # 克隆仓库 git clone https://github.com/your-org/modelmuxer.git cd modelmuxer # 安装依赖 poetry install # 使用直接 provider API keys 设置环境 cp .env.example .env # 使用您的直接 provider API keys 编辑 .env： # OPENAI_API_KEY=sk-... # ANTHROPIC_API_KEY=sk-ant-... # MISTRAL_API_KEY=... # GOOGLE_API_KEY=... # 运行服务器 poetry run python -m app.main ``` ### 基本用法 ``` # 启动服务器 poetry run python -m app.main --mode basic # 发起请求 curl -X POST http://localhost:8000/v1/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer your-api-key" \ -d '{ "messages": [{"role": "user", "content": "Hello, how are you?"}], "model": "gpt-3.5-turbo" }' ``` ## 配置 ### 环境变量 `.env` 中的关键配置选项： ``` # 直接 Provider API Keys (主要) OPENAI_API_KEY=sk-... ANTHROPIC_API_KEY=sk-ant-... MISTRAL_API_KEY=... GOOGLE_API_KEY=... GROQ_API_KEY=gsk_... COHERE_API_KEY=... TOGETHER_API_KEY=... # Provider 配置 (仅限直接连接) PROVIDER_ADAPTERS_ENABLED=true # Intent Classifier (阶段 1) ROUTER_INTENT_CLASSIFIER_ENABLED=true INTENT_LOW_CONFIDENCE=0.4 INTENT_MIN_CONF_FOR_DIRECT=0.7 # 测试模式 TEST_MODE=false # 定价和成本估算 PRICE_TABLE_PATH=./scripts/data/prices.json LATENCY_PRIORS_WINDOW_S=1800 ESTIMATOR_DEFAULT_TOKENS_IN=400 ESTIMATOR_DEFAULT_TOKENS_OUT=300 # 预算阈值 MAX_ESTIMATED_USD_PER_REQUEST=0.08 ``` ### 部署模式 通过 `MODELMUXER_MODE` 环境变量或 `--mode` CLI 标志进行设置： - **基本模式**（默认）：带有成本跟踪和宽松启动验证的直接提供商路由 - **生产模式**：具有严格启动验证的相同功能（当未配置任何提供商或路由器配置无效时硬失败） ## 架构：仅限直接提供商 ModelMuxer 专门使用直接提供商连接，提供： - **更低延迟**：直接进行 API 调用，无代理开销 - **更好的错误处理**：特定于提供商的错误处理和重试逻辑 - **增强的控制力**：对每个提供商进行细粒度的配置 - **提升的可观测性**：详细的遥测和断路器模式 ### 提供商要求 **必须至少配置一个提供商才能使 ModelMuxer 正常运行：** - **OpenAI**：设置 `OPENAI_API_KEY=sk-...` 以使用 GPT 模型 - **Anthropic**：设置 `ANTHROPIC_API_KEY=sk-ant-...` 以使用 Claude 模型 - **Mistral**：设置 `MISTRAL_API_KEY=...` 以使用 Mistral 模型 - **Google**：设置 `GOOGLE_API_KEY=...` 以使用 Gemini 模型 - **Groq**：设置 `GROQ_API_KEY=gsk_...` 以使用 Groq 模型 - **Together AI**：设置 `TOGETHER_API_KEY=...` 以使用 Together AI 模型 - **Cohere**：设置 `COHERE_API_KEY=...` 以使用 Cohere 模型 如果未配置任何提供商： - 服务将在启动时记录警告 - 请求将失败并返回 503 错误 - 检查您的 API key 配置并确保密钥有效 ## API 参考 ### Chat Completions ``` POST /v1/chat/completions ``` 兼容 OpenAI 的 chat completions API。ModelMuxer 将自动路由至最佳的提供商。 ### 健康检查 ``` GET /health ``` 返回服务健康状态。 ### 指标 ``` GET /metrics/prometheus ``` Prometheus 指标 endpoint。 ## 开发 ### 运行测试 ``` # 运行所有测试 poetry run pytest # 运行特定测试类别 poetry run pytest tests/unit/core/test_intent_classifier.py poetry run pytest tests/routing/ ``` ### 代码质量 ``` # 格式化代码 poetry run black . # Lint 代码 poetry run ruff check . # 类型检查 poetry run mypy . ``` ## 成本估算与预算管理 ModelMuxer 包含一个全面的成本估算和预算管理系统，有助于控制支出并根据成本约束优化模型选择。 ### 价格表 系统使用一个集中式的价格表（`scripts/data/prices.json`），其中包含所有受支持的提供商和模型的当前市场价格。价格表格式为： ``` { "provider:model": { "input_per_1k_usd": 2.5, "output_per_1k_usd": 10.0 } } ``` **格式说明：** - 价格以美元（USD）为单位，按每 1k token（1,000 个 token）计算 - `input_per_1k_usd` 等同于 `input_per_mtok_usd`（mtoks = tokens/1000） - 系统在启动时会自动加载并验证此价格表 - 无效的条目将被记录并跳过，从而允许使用部分价格表 - 元数据键（以 `_` 开头）将被自动过滤掉 **价格表管理：** - 通过编辑 `scripts/data/prices.json` 更新价格 - 价格在启动时加载一次（更改需要重启） - 缺失价格会导致模型在路由期间被跳过 - 允许零价格（适用于免费模型） ### 延迟先验 系统使用由近期测量结果组成的环形缓冲区来维护每个模型的延迟先验。它为 ETA 计算提供 p95 和 p99 百分位估算，有助于同时进行成本和性能优化。 **延迟先验的工作原理：** 1. **测量收集**：在每次成功的请求之后，记录所使用模型的实际响应延迟 2. **时间窗口存储**：测量结果存储在具有可配置时间窗口（默认为 30 分钟）的环形缓冲区中 3. **自动清理**：自动移除超出窗口的旧测量结果，以保持估算的时效性 4. **百分位计算**：系统根据近期测量结果计算 p95 和 p99 百分位，并对小样本量使用偏差校正 5. **默认估算**：对于尚无测量结果的模型，系统根据模型类别使用合理的默认值（高端模型：p95 为 1500ms，标准模型：p95 为 800ms） 6. **ETA 选择**：路由器使用 p95 延迟进行保守的 ETA 估算 **注意**：当前的实现仅支持内存，并在应用重启时重置。对于需要持久化延迟跟踪的生产部署，请考虑实现基于 Redis 的版本。 ### 预算网关 预算网关在路由决策前执行成本约束： - **请求前估算**：在选择模型之前，使用 token 启发式算法和当前价格估算成本 - **预算执行**：阻止超过 `MAX_ESTIMATED_USD_PER_REQUEST` 的请求 - **降级路由**：在预算允许的情况下自动选择更便宜的模型，实现不牺牲质量的成本优化路由 - **结构化错误**：当超出预算时返回 HTTP 402 以及详细的成本信息 **预算如何影响计划选择：** 1. **直接路由**：当首选模型在预算范围内时，将直接选中它 2. **降级路由**：如果首选模型超出预算，路由器会自动考虑偏好列表中更便宜的替代方案 3. **预算超出**：如果偏好列表中没有模型在预算范围内，请求将被拒绝并返回结构化错误 4. **成本排序**：可负担的模型按成本排序（最便宜的优先），以在保持质量的同时优化支出 **预算决策流程：** ``` Request → Token Estimation → Cost Estimation for Each Model → Budget Check ↓ Within Budget? → Yes → Select Model → Execute ↓ No → Try Cheaper Models → Any Affordable? → Yes → Select Cheapest → Execute ↓ No → Return Budget Exceeded Error (HTTP 402) ``` ### 配置 配置预算约束和估算参数： ``` # 预算阈值 (典型值: 0.05 conservative, 0.08 balanced, 0.15 permissive) MAX_ESTIMATED_USD_PER_REQUEST=0.08 # 延迟测量窗口 (默认 30 分钟) LATENCY_PRIORS_WINDOW_S=1800 # 未提供时的默认 token 估算 ESTIMATOR_DEFAULT_TOKENS_IN=400 ESTIMATOR_DEFAULT_TOKENS_OUT=300 ``` ### 错误响应格式 ModelMuxer 对所有 API 错误使用标准化的错误响应格式。所有错误响应都包含一个结构一致的 `error` 对象： ``` { "error": { "message": "Human-readable error description", "type": "error_category", "code": "specific_error_code", "details": { // Additional error-specific information } } } ``` #### 预算超出错误 (HTTP 402) ``` { "error": { "message": "Budget exceeded: No models within budget limit of $0.08", "type": "budget_exceeded", "code": "insufficient_budget", "details": { "limit": 0.08, "estimate": 0.12 } } } ``` #### 验证错误 (HTTP 400) ``` ``` #### 身份验证错误 (HTTP 401) ``` { "error": { "message": "Invalid API key provided.", "type": "authentication_error", "code": "invalid_api_key", "details": {} } } ``` #### 速率限制错误 (HTTP 429) ``` { "error": { "message": "Rate limit exceeded: 100/100 requests per minute", "type": "rate_limit_exceeded", "code": "security_rate_limit", "details": { "current": 100, "limit": 100, "window": "minute" } } } ``` #### 提供商错误 (HTTP 502) ``` { "error": { "message": "Provider error: OpenAI API returned 429", "type": "provider_error", "code": "provider_error", "details": {} } } ``` #### 服务不可用错误 (HTTP 503) ``` { "error": { "message": "Provider openai is not available", "type": "service_unavailable", "code": "provider_unavailable", "details": {} } } ``` ### 与现有系统集成 新的成本估算系统与现有的成本跟踪系统协同工作： - **请求前估算**：新系统在路由前估算成本 - **请求后跟踪**：现有系统在完成后跟踪实际成本 - **遥测集成**：两个系统都为监控和指标做出贡献 - **向后兼容性**：现有的成本跟踪继续原样工作 ### 响应头 当启用调试模式（`SERVER_DEBUG=true`）时，API 包含用于可观测性的附加头信息： - **`X-Route-Decision`**：显示选定的提供商和模型（例如，`openai:gpt-4o-mini`） - **`X-Route-Estimate-USD`**：显示以 USD 为单位的估算成本（例如，`0.000150`） **注意**：这些头信息是非契约性的，可能会在不另行通知的情况下更改。它们仅用于调试和监控目的。 ## 阶段 1：意图分类器 Routing Mind 意图分类器是智能路由的第一个构建块。它会在做出路由决策之前分析每个请求，并为其标记任务标签和置信度得分。 ### 功能 - **轻量级分类**：默认使用启发式算法，带有可选的低成本 LLM 集成 - **确定性结果**：测试模式确保行为可重现 - **特征提取**：从 prompt 中提取词法和结构信号 - **遥测集成**：OpenTelemetry spans 和 Prometheus 指标 ### 意图标签 分类器支持 7 种意图标签： - `chat_lite`：简单对话和基础问题 - `deep_reason`：复杂分析、解释和推理 - `code_gen`：代码生成和编程任务 - `json_extract`：JSON 解析和结构化数据提取 - `translation`：语言翻译任务 - `vision`：图像分析和 OCR 任务 - `safety_risk`：潜在有害内容检测 ### 配置 ``` # 启用/禁用 classifier ROUTER_INTENT_CLASSIFIER_ENABLED=true # 置信度阈值 INTENT_LOW_CONFIDENCE=0.4 INTENT_MIN_CONF_FOR_DIRECT=0.7 ``` ### 用法 分类器会在每个请求上自动运行，并将意图元数据附加到响应中： ``` { "router_metadata": { "selected_provider": "openai", "selected_model": "gpt-3.5-turbo", "routing_reason": "Simple query detected", "intent_label": "chat_lite", "intent_confidence": 0.85, "intent_signals": { "token_length_est": 45.2, "has_code_fence": false, "has_programming_keywords": false, "signals": { "code": false, "translation": false, "vision": false, "safety": false } } } } ``` ### 测试 分类器包含使用 60 个带标签示例的数据集进行的全面测试： ``` # 运行 intent classifier 测试 poetry run pytest tests/unit/core/test_intent_classifier.py -v ``` 测试套件验证： - 在带标签的数据集上准确率 ≥ 80% - 测试模式下的结果具有确定性 - 对已禁用 feature flag 的正确处理 - 置信度得分验证 - 特征信号提取 ### 架构 意图分类器由以下部分组成： 1. **特征提取**（`app/core/features.py`）：提取词法和结构信号 2. **意图分类**（`app/core/intent.py`）：带有 LLM 回退的启发式分类 3. **集成**（`app/router.py`）：接入带有遥测的 `HeuristicRouter.select_model` 4. **遥测**（`app/telemetry/metrics.py`）：Prometheus 计数器和 OpenTelemetry spans ### 未来增强 - 集成低成本的 LLM 以提高准确率 - 基于模型性能的动态置信度阈值 - 感知意图的路由决策 - 用于意图策略的 A/B 测试框架 ## 监控与指标 ModelMuxer 提供全面的 Prometheus 指标，用于监控路由决策、成本估算和系统性能。 ### 关键指标 - **`modelmuxer_router_cost_estimate_usd_sum`**：按路由、模型和预算状态划分的估算总成本 - 标签：`route`、`model`、`within_budget`（true/false） - `within_budget` 标签有助于分析预算网关的有效性 - **`modelmuxer_router_budget_exceeded_total`**：按路由和原因划分的预算超出事件 - **`modelmuxer_router_decision_latency_ms`**：路由器决策延迟分布 - **`modelmuxer_provider_latency_seconds`**：按提供商和模型划分的提供商响应延迟 ### 预算监控 成本估算指标中的 `within_budget` 标签提供了以下方面的可见性： - 模型超出预算阈值的频率 - 哪些模型最常因成本原因被降级路由 - 不同请求类型的预算网关有效性 ### Grafana 仪表板 `grafana/dashboard_modelmuxer.json` 中提供了一个预配置的 Grafana 仪表板，用于可视化这些指标。 ## 已知限制 ### 延迟先验（仅限内存） 当前的延迟跟踪系统（`LatencyPriors`）被实现为内存中的环形缓冲区，该缓冲区在应用重启时会重置。这意味着： - **限制**：服务重启时会丢失所有延迟测量结果 - **影响**：在收集到新的测量结果之前，ETA 估算将回退到默认值 - **临时方案**：对于生产部署，请考虑实现一个跨重启持久化测量结果的基于 Redis 的版本 - **未来增强**：该接口设计为易于替换为持久化后端 ## 贡献 请阅读 [CONTRIBUTING.md](CONTRIBUTING.md) 以了解有关我们的行为准则和提交 pull request 流程的详细信息。 ## 许可证 该项目基于 Business Source License 1.1 授权 - 详见 [LICENSE](LICENSE) 文件。 ## 商业授权 如需商业授权和企业支持，请联系： - 电子邮件：licensing@modelmuxer.com ## 支持 获取帮助和提问： - 在 GitHub 上创建一个 issue - 查看 [文档](docs/) - 查阅[故障排除指南](docs/troubleshooting.md)

标签：AI网关, API管理, DLL 劫持, LLM路由, 大语言模型, 成本管理, 搜索引擎查询, 用户代理, 自定义请求头, 逆向工具