内容
节<p align="center src="assets/banner alt="Frugal —、本地和的方式运行 AI width="100%>
**🇬 · [🇷繁体中文.ru.md)**
[
[](LICENSE)
[](pyproject.toml)
-25c.svg)
[](https://githubKRZ23/frugal/stargazers)
[](https://github.com/SRKRZ23/commits/main)
低成本、本地和可验证的方式运行 AI 代理。**
🌐 **[在线https://frugal.netlify.app)** · 🎞 **[交互式演示](https://frugal-costlify.app/de)**
Frugal 是和代理的即插维层。它工作负载都变得 💸 **** — 每个计量，级联廉价→前沿，强制执行严格预算
🏠 **本地**私有/简单的任务路由到设备模型（O / vLLM /m）
- ✅验证** — 离义断言、检测和 RAG CI
- 🔎 **自我感知** — 服务器，允许代理读取 `$/token` 支出
一个软件包，模块，** 密钥** — 所有内容都可以在确定提供程序上离线运行，因此您可以立即尝试、演示。
```bash install -e .
frugal demo # 端到端演示，完全离线
```
## 为什么
代理 AI 会使账单飙升 — 每个 token 都有价格，大多数代理在琐碎工作上会烧掉前沿 token，泄露私有提示到云端，并且在层**静失败。 是一个薄层，解决了这四个问题，围绕的成本**计量构建。
## 九个模块，一个共享的成本账本。您 — 路由、验证、服务在同一个地方计量（和您）可以始终看到 `$/token真相。
```mflowchart TB
savers["sp R["route — cascade cheap→frontier C["cache — = $0"]
L["local — on 0 private leaks"]
end
subgraph it's good enough E["eval — drift · LLM judge"]
G["rag — / citation checks"]
subgraphsee and cap the spend"]
MC["mcp — agent reads its own $/token"]
GW["gateway — OpenAI-compatible budget proxy"]
EC["economics — won't-save warning"]
end
M[("meter — one shared cost ledger + hard budget cap")]
R --> M
C --> M
--> M
E --> M G --> M
MC --> M
GW --> M
EC --> M### 路由工作原理
廉价或本地模型首先回答。**置信度检查**决定该答案是否值得；只有不确定的答案才会升级到前沿模型。如果价格差距太小，无法覆盖检查，Frugal **会警告您，而不是悄悄多收费用**。
```mermaid
flowchart LR
P["prompt"] --> CH["cheap / local model"]
CH --> K{"confidence<br/>check"}
K -->|high| DONE["answer — cost saved"]
K -->|low| ESC["escalate to frontier"]
ESC
K -.->|"price gap too small?"| WARN["economics warns you"]
```
## 查看账单
<p align="center"><img src="assets/charts/cost-curve.png" alt="累计成本：仅前沿 $10.20 vs Frugal $0.83 超过,400 次请求 — 节省 91.9%" width="100%"></p>
```text
FRUGAL — 实时成本 (gpt-4o-mini 廉价 → gpt-4o 升级，真实价格)
处理的请求 : 2400
仅前沿 : $ 10.2000 ██████████████████████████████████
frugal : $ 0.8262 ██
节省 91.9% .3738 保存在您的钱包中)
```
`python examples/live_cost_demo.py`（动画）或 `--cast` 生成 [asciinema](https://asciinema.org) 记录（`examples/demo.cast`）。真实价格；实际节省取决于您的工作负载和置信度信号 — 请参阅 [在线站点上的节省明细](https://frugal-cost-router.netlify.app/#savings)。
<p align="center"><img src="assets/charts/savings.png" alt="按场景划分的节省 — 88–97% 本地，90.6% 免费对数 −7% 级联损失钱" width="100%"></p>
Frugal 不假装它总能赢：在小价格差距（Haiku→Sonnet，约 3 倍）下，重新采样检查的成本可能**高于节省的成本**。该工具会计算并警告您 — 发布它**不**适用的地方，您可以信任它适用的地方。
## 自己验证（10 秒）
不要相信数字 — 重现它们。无需 API 密钥：
```bash
pip install -e . && frugal demo # 端到端，离线，~2s
python benchmarks/run_all.py # 离线基准测试表
python benchmarks/stress_test.py # 8 个维度：线程安全、ReDoS、模糊测试、内存
python benchmarks/stress_deep.py # 6 个对抗维度：敌对输入、竞争（钻石）
python benchmarks/cost_model.py # 真实价格节省数学（重现数字）
```
集群上有模型吗？在 **您的** 模型上重新运行确切的模型比较并提出异议：`FRUGAL_MODELS=... python benchmarks/bench_models.py`。这里的每个声明都可以通过一个命令进行检查。（参见 [WEAKNESSES.md](WEAKNESSES.md) 了解数字的含义和证明内容。）
## 模块
| 模块 | 功能 | 导入 |
|---|---|---|
| `frugal.meter` | 每次调用的成本/代币/延迟核算 + 预算保护 | `from frugal import Meter` |
| `frugal.route` | 级联路由：廉价模型优先，仅在需要时升级 | `from frugal import cascade` |
| `frugal.local` | 按成本/隐私/复杂度路由本地↔云；AMD 快速入门 | `from frugal.local import LocalRouter` |
| `frugal.eval` | `assert_semantic` / `assert_no_hallucination` / `assert_tone` + 漂移 | `from frugal.eval import assert_semantic` |
| `frugal.rag` | `ragcheck`：检索命中率、忠实度、引用覆盖率 | `from frugal.rag import ragcheck` |
| `frugal.mcp` | MCP 服务器，暴露实时成本遥测 + PII/注入防护 | `from frugal.mcp import FrugalMCP` |
| `frugal.gateway` | OpenAI 兼容代理：计量 + 预算 + 路由（`[gateway]`） | `from frugal.gateway import create_app` |
| `frugal.cache` | 响应缓存 — 第二个成本杠杆；命中成本为 $0 | `from frugal import ResponseCache` |
| `frugal.economics` | 当廉价/前沿对无法覆盖路由开销时发出警告 | `from frugal.economics import routing_savings` |
## 快速入门
```python
from frugal import Meter, MockProvider, cascade
from frugal.eval import assert_semantic
from frugal.mcp import FrugalMCP
provider = MockProvider() # 换成 get_openai(...) / get_ollama(...)
meter = Meter(budget_usd=0.50)
r = cascade("say hi", provider, meter) # -> 停留在廉价模型
r = cascade("prove this design, step by step", provider, meter) # -> 升级
```
## 命令行界面
```bash
frugal demo # 离线端到端演示
frugal diagnose your_log.jsonl # 项目在您的提示日志上的节省 — 离线，无模型调用，无内容离开盒子
frugal diagnose your_log.jsonl --live --backend ollama --host http://localhost:11434 \
--cheap qwen2.5:7b --frontier phi4:14b # 测量它：实际路由每个提示，观察成本 + 延迟 + 升级
frugal route "explain this bug" # 级联路由一个提示，打印成本
frugal rag check examples/rag_example.json
frugal mcp # 列出 MCP 成本遥测工具
frugal gateway --budget 5.00 # OpenAI 兼容预算网关（需要 frugal[gateway]）
```
## 真实提供商
```python
from frugal.providers import get_openai, get_ollama
cloud = get_openai(base_url="https://api.openai.com/v1") # 或任何 OpenAI 兼容端点
local = get_ollama(model="llama3") # http://localhost:11434
```
在 **AMD ROCm** 上提供本地模型（MI300X / Radeon），只需一条命令：
```bash
MODEL=meta-llama/Llama-3.1-8B-Instruct src/frugald_quickstart.sh
# -> OpenAI 兼容端点在 http://localhost:8000/v1
```
## 测试
```bash
pip install -e '.[dev]'
pytest -q
```
## 基准测试（已测量）
每个数字都是通过在标记的综合工作负载上运行代码生成的 — 使用 `python benchmarks/run_all.py` 重现（写入 [`benchmarks/RESULTS.md`](benchmarks/RESULTS.md)）。
| 内容 | 结果 | 备注 |
|---|---|---|
| **路由节省的成本** — *基准命名，无稻草人* | **~70–79%** vs **前沿默认** 基线（gpt-4o-mini→gpt-4o），最高 **~97%** 使用本地 $层，**负 (−3 至 −12%)** 在小价格差距（Haiku→Sonnet）| 与 **廉价** 基线相比，Frugal 成本 **更多** — 其价值在于质量恢复在升级的 ~17% + 治理 + 测量的 $/token，**不是** 降低账单。2026 年实际价格；运行 `benchmarks/cost_model。完整方法 + 未证明的内容： **[METHODOLOGY.md](METHODOLOGY.md)** |
| **私有提示泄漏** 到云端 | **0 / 6** | 隐私不变性：`private` 标记的提示始终保持本地 |
| 混合工作负载的本地份额 | **96.2%** 保留在付费层之外 | 复杂度启发式偏爱廉价层（） |
| 幻觉标记精度/召回率 | **1.0 / 1.0** 在标记集上 | 启发式门控；小集合 |
| PII + 注入防护 | **F1 1.0** | 10 个样本标记集 |
| RAG 门控精度 vs 标签 | **1.0** （5 例）| 聚合命中/忠实度 0.6 反映了 2 个植入的坏案例 |
| 计量开销 | **~0.005 ms/调用** （~185k 调用/秒；随负载变化）| 与任何网络调用相比可忽略 |
| **路由机制** 工作原理 | 路由 *机制* 有效；*置信度信号* 决定质量。默认对数概率置信度对于演示来说不错，但在真实模型上不充分 — 使用 `frugal.route.make_self_consistency(...)` （或对数概率/验证器）。更大的廉价模型提高了廉价≈强匹配率（0.5b → 67% 3B 编码器），因此更多流量可以安全地保持廉价。基准测试表面而不是隐藏内容 — [WEAKNESSES.md](WEAKNESSES.md) 了解数字证明和未证明的内容。 |
### 真实模型结果（在租用 CPU 节点上测量）
在 **租用 CPU 节点** 上运行 `benchmarks/bench_cluster，使用该节点的 Ollama 模型 — **`qwen2.5-c3b`（廉价）和 `qwen2.5:7b强力）**，CPU 推理，自一致性置信度，6 个提示。单次运行，真实数字（模型采样不可预测）：
| 指标 | 值 |
|---|---|
| 廉价层延迟 p50 / p95 | **1.56s / 13.1s** |
| 强力层延迟 p50 / p95 | **3.70s / 69.1s** （7B CPU — 长尾是您不将简单工作发送到这里的原因） |
| 廉价≈强力一致性 | **4 / 6（67%）** — 使用强大的廉价模型，大多数答案已经匹配 |
| 升级（自一致性） | **2 / 6** — 只有不确定的提示才会升级 |
| 本地代币成本 | **$0** （本地）；模拟云 ≈ $55 / 1M 请求，$0.90/1M |
| 较早的小模型替代运行（`qwen2.5:0.5b` + `qwen2.5:3b`）显示 **置信度信号发现** 极为鲜明：**对 12 个提示中的 0 个进行对冲** （真实模型不会自我对冲 — 无效信号），而 **自一致性** 对 12 个提示中的 9 个进行升级。 |
**发现（诚实）：** 路由 *机制* 有效；*置信度信号* 决定质量。默认对数概率置信度对于演示来说不错，但在真实模型上不充分 — 使用 `frugal.route.make_self_consistency(...)` （或对数概率/验证器）。更大的廉价模型提高了廉价≈强匹配率（17% 变成 67% 使用b 编码器），因此更多流量可以安全地保持廉价。该基准测试表面而不是隐藏 — [WEAKNESSES.md](WEAKNESSES.md) 了解数字证明和未证明的内容。
### 跨模型比较（租用节点，LLM 评判）
`benchmarks/bench_models.py` 在 **租用 CPU 节点** 上 — 5 个真实 Ollama 模型，CPU 推理，由 **LLM 评判器** （`qwen2.5:7b`）评估优于参考 `phi4:14b`（5 个提示，`num_predict=220`）：
| 模型 | p50 秒 | p95 秒 | tok/s | 质量评判 0-1 | 是否等同于 14B 参考 |
|---|---|---|---|---|---|
| **qwen2.5-coder:3b** | **12.7** | 27.6 | 6.5 | 0.80 | **5/5** |
| qwen2.5:7b | 20.2 | 59.4 | 3.2 | 0.82 | 5/5 |
| deepseek-r1:7b | 59.3 | 70.9 | 3.6 | 0.64 | 5/5 |
| phi4:14b（参考） | 60.1 | 116.8 | 1.5 | 0.86 | — |
| deepseek-r1:14b | 113.8 | 115.2 | 1.8 | 0.80 | 5/5 |
**证明内容（真实数字）：**
1. **廉价层在此处足够用**。`qwen2.5-coder:3b` **比 `phi4:14b` 快 4.7 倍**，且法官评级与 14B 在 **5/5** 个提示中相同 — 因此路由到此处并很少升级可降低延迟/成本 ~80%，而几乎没有质量损失。运行 `benchmarks/cost_model.py` 获取 2026 年实际价格；完整方法 + 未证明的内容： **[METHODOLOGY.md](METHODOLOGY.md)** |
2. **推理模型对于简单工作来说是一个糟糕的默认选择**。`deepseek-r1:7b` 得分 *最低* 质量（0.64），同时发出 *最多* 的 token（冗长的 `<think>`），而 `deepseek-r1:14b` 最慢（113 秒），且没有质量提升 — 正是 Frugal 存在的“token 海啸”，以便路由。|
3. **诚实的警告：** N=5，相对容易的提示 → 保留率在 100%；7B 法官过于宽容；仅限 CPU，在租用的节点上。重现：`FRUGAL_MODELS=... FRUGAL_BENCH_N=... python benchmarks/bench_models.py`。
#### 更难的提示会破坏 100% 的饱和度
在 **困难** 集上重新运行（编码带有边缘情况，多步骤推理，长上下文检索 — `benchmarks/data_hard.py`，`FRUGAL_PROMPTSET=hard`，N=6）：
| 模型 | p50 秒 | 质量评判 0-1 | 是否等同于 14B 参考 |
|---|---|---|---|
| qwen2.5-coder:3b | 34.1 | 0.733 | **5/6（83** |
| qwen2:7b | 89. 0.75 | 6（83%） |
4:14b（参考 149.8 | 0 | — |
在困难任务中，廉价层的保留率从% 下降到 83：它真正失败了 ~1中的 6 个，这正是 **升级应该捕获的流量**。它仍然快了 4.4 83% 的情况下质量足够 因此路由论文仍然成立，并且现在有测量的升级率而不是 100% 的饱和度。
### GPU 与 CPU 用于廉价层（租）
在 **租用的 GPU** 上运行 `qwen2.5-coder:3b`（`benchmarks/bench_gpu/`），CUDA 确认（部分卸载 — 3B 模型无法完全适应小
| 廉价层 `coder:3b` | p50 | tok/s |
|---|---|---|
| 租用的 CPU 节点 | 12.7 秒 | 6.5 |
| **租用的 GPU** | **1.13 秒** | 11.5 |
**在中等性能 上快 11 倍**。这是路由论文的结论：在任何 GPU 上，廉价层几乎是，因此您可以将几乎所有内容路由到它，并将 ~17% 的困难提示升级实际置信度的（更大的卡将完全适合模型并更快 — 这正是该项目瓶颈的硬件，参见 [Backing](#backing--whats)
### 与纯代理的实时对抗
`benchmarks/compare_litellm_live.py` 在租用的节点上 — 相同的模型（`qwen2.5-coder:3b` / `qwen2.5:7b`），12 个相同的提示。代理（LiteLLM 风格）发送每个提示到强模型；Frugal 按复杂性路由：
| 指标 | 代理（全部→强） | Frugal（路由） | Frugal 节省 |
|---|---|---|---|
| 强模型调用 | 12 | **6** | 一半 |
| 总延迟 | 373.9 秒 | 252. | **-32.5 |
| 模拟成本（云价格） | $0.01568 | $0.00723 | **-53.9%** |
诚实的警告：基线是一个代理直通（`litellm` 包无法在 CPU 资源不足的节点上完成安装 — 行为相同）；云密钥运行需要您的密钥。另请参阅 `benchmarks/bench.py` 增加一个 **裁判 （多个模型投票）通过 — 在小模型差距（3B↔7B）上保留率达到 100%；仍然由 LLM 裁判，而不是人工。
## 在集群上运行（模型在外部）
Frugal 是控制层；GPU 位于您的集群上。将环境变量指向那里 — 无需代码更改 — 相同的脚本现在在模拟上运行离线，在真实 Ollama / vLLM 端点上驱动：
```bash
export FRUGAL_LOCAL_BASE_URL=http://cpu-node:11434 FRUGAL_LOCAL_MODEL=llama3
export FRUGAL_CLOUD_BASE_URL=http-node:8000/vUGAL_CLOUD_MODEL=Llama-3.1-70B-Instruct
python benchmarks/bench_cluster.py # 真实延迟，token，$，质量保留
```
### 多节点分布式路由（两台物理机器）
`benchmarks/bench_multinode.py` — 廉价层在 **节点 A**（，`qwen2.5:3b`），强在 **节点 B**（节点，`qwen2.5:7b`，通过 SSH 隧道到达）。LocalRouter 按提示决定；8 个提示的平衡混合：
| 指标 | 值 |
|---|---|
| 路由到节点 A（本地）/ 节点 B（租用） | **7 / 1** |
| 节点 A 延迟 p50 | **0.53 秒** |
| 节点 B 延迟（一个困难的） | **50.5 秒** （7B 在繁忙的 CPU 节点上） |
| 私有提示 | 2 |
| **跨网络跳跃的私有提示泄漏** | **0** |
**证明：** 路由机制真正跨机器运行，通过保持 p50 低来发送只有困难的提示到重型层，并且 **隐私不变性在真实网络跳跃中保持** — 每个 `private` 提示都保留在节点 A 上。可调 `FRUGAL_COMPLEXITY_THRESHOLD`。
## 场景
[`examples/scenarios/`](examples/scenarios/) 下的可运行故事，每个故事都有一个价值主张：`scenario_coding_agent.py`（预算上限代理），`scenario_private_data.py`（0 泄漏），`scenario_ci_eval.py`（在 CI 中捕获静默回归）。
## 面向企业
推理现在占据了 **约85% 的企业AI预算**。Uber在4月份就烧掉了他们整个2026年的AI编码预算；一家公司在一个月内花费了 **5亿美元购买Claude**；Palantir的CEO称token定价是“破碎的”。我们提供了一种经济高效的解决方案。 在 **每月1000万美元** 的推理支出下，预计每年可节省 **60–90百万美元**。
→ 完整列表（Meta · Amazon · Google · xAI · Uber · Palantir · Klarna …），节省费用表格，以及适用的场景： **[实时网站的企业部分](https://frugal-cost-router.netlify.app/#enterprise)**
· **[交互式演示](https://frugal-cost-router.netlify.app/deck.html)**。
## 本仓库的其他内容
- [`rules/AGENTS.md`](rules/AGENTS.md) — 10条复制粘贴规则，使任何编码代理都具有成本意识。
- [`awesome-onprem-ai.md`](awesome-onprem-ai.md) — 精选的本地优先/本地部署AI工具列表。
## 诚实说明
`frugal/meter/pricing.py`中的价格数据是 **近似的公开列表价格**，并且用户可编辑 - 在依赖美元价值之前，请与您的提供商核实。评估断言是 **廉价的启发式门控**，用于持续集成，而不是精确的评判标准；传递`provider=`参数可将它们升级为LLM评判标准。
## Frugal的不同之处（它不仅仅是一个LiteLLM包装器）
像LiteLLM / Portkey / Helicone这样的代理程序会跨提供商路由和记录日志。Frugal在某些方面与它们重叠，但其重点在于 **决策 + 验证循环**，而不仅仅是代理：
| | LiteLLM / 网关 | **Frugal** |
|---|---|---|
| 多提供商代理 | ✅ | ✅（网关） |
| **成本感知级联**（廉价→在实际置信度检查时升级） | 大部分手动 | ✅ 可测量，具有自一致性 |
| **离线评估断言 + RAG检查，用于CI** | ✕ | ✅ |
| **MCP服务器**，暴露代理自己的$/token | ✕ | ✅ |
| **本地优先**路由，基于隐私/复杂性 | 部分 | ✅（0个私人泄漏，已测试） |
| **模型间基准测试**，可复制 | ✕ | ✅（`bench_models.py`） |
| 零依赖，可完全离线运行（模拟） | ✕ | ✅ |
如果您只需要一个提供商代理，请使用LiteLLM。Frugal用于 *决定运行什么并证明它足够好* - 廉价，本地，在CI中。
## 路线图和维护
开发者们最关心的是新仓库的寿命，因此明确说明：本仓库正在积极维护，遵循Apache-2.0许可，问题和PR会得到及时处理。近期路线图：
- 更广泛的，人类评判的，多工作负载评估（消除“小N”的限制）
- 对数概率/验证器置信度（比自一致性更廉价）
- 预留预算模式（零超额硬上限）
- 与LiteLLM/Portkey的直接对比
- 更多提供商适配器 + 持久性指标存储
不是承诺一个基础 - 而是承诺诚实，积极的维护和公开的路线图。
## 安全
`frugal.mcp.guard`的PII/注入检查是一个 **第一道启发式检查**，而不是一个安全产品 - 它们能捕获明显的漏洞，但可能会漏掉巧妙的攻击；请不要仅依赖它们作为唯一的控制措施。通过私人问题报告漏洞。参见 [WEAKNESSES.md](WEAKNESSES.md) 以获取完整的诚实审计。
## 支持与未来
Frugal是在租用的普通CPU/GPU节点上**单独构建和基准测试**的 - 这也是其性能的上限。上面的数字是CPU绑定的，或者是在小型部分卸载GPU上运行的；最大的突破口是 **硬件**。一个完整的GPU（或AMD MI300X类加速器）可以使廉价层几乎瞬间完成，并让基准测试从“小N，一个租用节点”升级为广泛的，人类评判的，多工作负载证明 - 在公开环境中。
**我欢迎能够实现这一目标的支持：
- 🅰️ **天使投资** - 用于资助计算、评估和对本地AI成本效率栈（Frugal + [REPOMIND v3](https://github.com/SRKRZ23/repomind-v3)）进行全职工作的资金。
- 🎁 **不可退款的资助** - 研究 / 开源软件 / 硬件资助；无需股权，无需偿还。
- 🖥️ **硬件赞助** - GPU / 加速器访问（优先支持AMD ROCm）以公开运行更大的基准测试。
- 🤝 **收购 / 人员收购** - 强大的小团队通过这种方式将人员和知识产权加入更大的公司（Wang / Suleyman / Shazeer模式）。Frugal和REPOMIND是一个本地，成本高效推理的命题 - 我将带来两者。
📬 **Sardor Razikov** — razikovsardor1@gmail.com · [GitHub](https://github.com/SRKRZ23) · [LinkedIn](https://linkedin.com/in/sardor-razikov-569a5327b) · [X](https://x.com/SardorRazi99093)
## 许可证
Apache-2.0。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器