内容
# ILTER — AI 网关
将 AI 模型部署到生产环境中带来了许多关键的运营挑战，例如不可预测的成本、数据隐私风险和 API 中断。**ILTER** 是一个独立的网关，位于您的应用程序和 AI 提供商之间；它可以将您的整个 AI 流量转换为安全、优化和完全可控的基础设施，而无需在代码中进行任何架构更改。
* 🧩 **MCP 网关和市场：** 将 AI 连接到您的 API、CRM 或 MCP 服务器 — 无需任何更改。
* ⚡ **智能路由：** 每个请求都实时评估其复杂度，并路由到合适的模型层级。
* 🌐 **智能备份：** 提供商宕机或限速？ILTER 自动切换到另一个密钥或提供商，无需任何更改。
* 💰 **预算控制：** 每个密钥设定每日/每月的硬性消费限额 — 流量在限额达到时立即被切断。
* 🪪 **个人身份信息保护：** 邮件、社保号码和其他敏感数据在离开您的网络之前被屏蔽。
* 🧠 **语义缓存：** 查询直接从缓存中提供服务 — 使用 SHA-256 精确匹配作为后备。
* 🛡️ **提示防护：** 在模型接收到请求之前，阻止注入、毒性内容和非主题请求。
* 🌀 **代理循环检测：** 通过速率、指纹、成本或深度检测循环，防止烧毁预算。
* ⏱️ **定时引擎：** 使用标准定时表达式调度重复的 AI 工作流 — 无需外部队列。
* 📡 **可观察性：** Prometheus 指标和 OpenTelemetry 跟踪，适用于 Grafana、Datadog 或 Honeycomb。
* 📊 **仪表盘：** 内置的 Web 界面，用于 KPI、审计日志、API 密钥和内置聊天游乐场 — 无需服务器。
> 所有这些基础设施都无需外部服务器、Node.js/Python 环境或复杂的依赖项。**它作为一个零设置、单一静态可执行文件（二进制文件）存在，可以在几秒钟内运行。**
```bash
./ilter serve
# 代理：http://localhost:8181/v1/chat/completions
# 仪表盘：http://localhost:9191
# 指标：http://localhost:9192/metrics
```
---
## 仪表盘
<table>
<tr>
<td width="33%">
<img src="docs/assets/overview.jpg" alt="Overview dashboard" />
<br /><strong>概览</strong><br />
实时 KPI、每日成本趋势、提供商/模型分析，以及每个功能的“一键切换”中心。
</td>
<td width="33%">
<img src="docs/assets/chat.jpg" alt="Chat playground" />
<br /><strong>聊天</strong><br />
内置的游乐场，用于在仪表盘中测试任意注册模型的提示，无需离开仪表盘。
</td>
<td width="33%">
<img src="docs/assets/mcp-marketplace.jpg" alt="MCP Marketplace" />
<br /><strong>MCP 市场</strong><br />
浏览并一键安装社区 MCP 服务器 — 文件系统、GitHub、Postgres 等。
</td>
</tr>
<tr>
<td width="33%">
<img src="docs/assets/smart-router.jpg" alt="Smart Router strategies" />
<br /><strong>智能路由</strong><br />
管理路由策略 — 成本优先、质量优先或自定义规则 — 并实时切换活动策略。
</td>
<td width="33%">
<img src="docs/assets/requests-logs.jpg" alt="Request logs" />
<br /><strong>日志</strong><br />
完整的请求历史记录，包括成本、延迟和状态，可按时间范围和提供商筛选。
</td>
<td width="33%">
<img src="docs/assets/jobs.jpg" alt="Scheduled jobs" />
<br /><strong>作业</strong><br />
使用内嵌调度器直接从仪表盘调度 AI 工作流，并显示下一次/上一次运行状态。
</td>
</tr>
</table>
---
## 功能
每家整合 AI 的企业都面临着不可控的成本、隐私问题和不可预测的代理行为。ILTER 直接在网关层面解决了这些问题。
### 🧩 MCP 网关和市场
将 AI 连接到内部 API 或 CRM 通常需要进行大量的客户端修改。
- **零客户端更改：** 自动将注册的 MCP 服务器中的工具注入到每个聊天完成请求中。
- **拦截：** ILTER 捕获 `tool_calls`，在本地执行 MCP 服务器工具（`stdio`/SSE），并将结果返回给模型。
- **OpenAPI 桥接：** 将任何 REST API 即时转换为 MCP 工具列表。
- **OAuth PKCE 支持：** 端口 `8181` 上的标准 OAuth PKCE 授权端点（`/.well-known/*`、`/authorize`、`/token`、`/register`）适用于远程 MCP 客户端。
### ⚡ 智能路由
对每个简单问题都使用昂贵的模型会浪费工程时间和金钱。ILTER 根据上下文动态路由请求。
- **实时评分：** 基于字数、需要推理的短语、代码块和工具调用的 `<0.03ms` 启发式复杂度评分（0-100）。
- **自动分层选择：** 在经济、标准和高级模型之间动态路由。
- **自定义覆盖：** 例如，`complexity > 50 → gpt-4o` 或 `prompt contains "analyze" → claude-sonnet`。
- **负载均衡：** 在健康的提供商电路中采用加权轮询、成本优化、延迟优化和基于优先级的策略。
### 🌐 智能备份
不要被锁定在单一供应商或因提供商宕机而中断。
- **单一端点：** 在一个统一的 OpenAI 兼容 API 后隐藏 9 个提供商。
- **断路器：** `RetryTransport → CircuitBreakerTransport`。5 次连续失败会打开电路并触发自动备份。
- **无缝备份：** 在宕机期间从 OpenAI 切换到 Anthropic，无需更改代码。
### 🧠 语义缓存
- **向量搜索：** Redis Stack 支持的相似性搜索，用于捕获和提供重复查询。
- **精确匹配备份：** SHA-256 缓存即使在没有嵌入模型的情况下也有效。
- **异步操作：** 缓存写入不会阻塞主请求路径。
### 🛡️ 提示防护
- **安全：** 提示注入检测和毒性过滤。
- **主题控制：** 基于关键词和自定义正则表达式规则，阻止特定主题。
- **操作：** 将每个规则的严重性设置为 `block`、`warn` 或 `mask`。
### 💰 预算控制
每令牌定价会带来月底的意外惊喜。ILTER 实时跟踪每个 API 密钥的成本并强制执行硬性限制。
- **硬性开关：** 可配置的每日和每月消费限额（美元）。当限额被突破时，立即返回 `429 budget_exceeded`。
- **警告阈值：** 默认 80% 使用率警报。
- **实时跟踪：** 通过仪表盘查看按模型、提供商和个别密钥划分的成本。
### 🪪 个人身份信息保护
将客户数据发送到云提供商违反了 GDPR 和 HIPAA。ILTER 在数据离开您的网络之前对其进行屏蔽。
- **三层引擎：** 布隆过滤器 + 阿霍-科拉西克字典树 + 正则表达式共同工作。
- **检测类型：** 名称（EN/TR）、电子邮件、电话号码、社保号码/国家身份证（TCKN）、信用卡（Luhn 验证）、IP地址。
- **三种模式：** 屏蔽（`[PII_EMAIL]`）、可逆（`PII:EMAIL:a8b9f1` — 在响应/SSE 流中恢复）、或阻止（`422 pii_blocked`）。
- **超快：** `<0.04ms` 延迟开销，内存占用 `<5MB`。
### 🌀 代理循环检测
代理工作流可能进入无限循环，隔夜产生巨大的账单。ILTER 在您睡觉时捕获它们。
- **速率限制：** 如果 >30 请求/秒，则阻止。
- **指纹匹配：** 如果在 20 个请求的窗口中发送相同的提示 >5 次，则阻止。
- **成本累积：** 如果在 5 分钟内单个会话花费 >$5，则阻止。
- **会话深度：** 如果单个会话超过 100 个请求，则限制。
### ⏱️ 定时引擎
运行周期性 AI 任务（摘要、报告）通常需要外部队列和工作线程。ILTER 直接在二进制文件中嵌入了此功能。
- **无需外部队列：** 使用标准定时表达式（例如，`0 9 * * 1`）。
- **工作流状态：** 使用 `{{.Input}}` 和 `{{.prev}}` 在步骤之间传递数据。
- **鲁棒执行：** 网络钩子触发、指数退避和死信队列包含在内。
### 📡 可观察性
- **指标：** `/metrics` 上的原生 Prometheus 指标（端口 `9192`）。
- **跟踪：** OpenTelemetry（OTLP 推送）适用于 Grafana Cloud、Datadog 或 Honeycomb。
- **审计日志：** 完整的请求日志、成本趋势和 PII 事件指标。
### 📊 其他
无需 npm、无需构建步骤、无需单独的服务器。现代 Web 界面直接通过 `embed` 嵌入到 Go 二进制文件中。
- **概览：** KPI、每月支出、路由决策和功能切换中心。
- **聊天游乐场：** 直接从仪表盘使用任何注册模型。
- **管理：** 创建 API 密钥、配置阈值、注册 MCP 服务器和管理 Cron 作业。（可在端口 `9191` 访问）。
---
## 快速入门
```bash
# 不需要任何依赖 — 它可以直接运行
./ilter serve
```
对于交互式设置向导：
```bash
./ilter init
```
要查看充满模拟成本、请求和 PII 事件的仪表盘：
```bash
./ilter init --demo && ./ilter serve
```
您的第一个真实请求（将现有的 OpenAI SDK 指向 ILTER）：
```bash
curl -X POST http://localhost:8181/v1/chat/completions \
-H "Authorization: Bearer <ilter-api-key>" \
-H "Content-Type: application/json" \
-d '{"model": "gpt-4o-mini", "messages": [{"role": "user", "content": "Hello!"}]}'
```
---
## 支持的提供商
| 提供商 | 备注 |
|----------|--------|
| **OpenAI** | 原生格式 |
| **Anthropic** | 系统消息提取、内容块转换 |
| **Google Gemini** | OpenAI 兼容模式 |
| **DeepSeek** | OpenAI 兼容 |
| **OpenRouter** | 自动注入 `HTTP-Referer` + `X-Title` 头部 |
| **Ollama** | 本地推理，OpenAI 兼容模式 |
| **Qwen (Alibaba)** | OpenAI 兼容，模型名称映射 |
| **OpenCode** | `opencode_go` 和 `opencode_zen` SDK 端点映射 |
| **Mock** | 用于本地测试的内置模拟提供商 |
---
## 架构
```text
您的应用程序
│ OpenAI API 格式
▼
ILTER :8181
│
├─ 认证 — ilter-xxxx 密钥（Argon2id/SHA-256 + LRU 缓存）
├─ 速率限制器 — Redis / 内存令牌桶，RPM/TPM 每密钥
├─ 预算强制执行者 — 每月消费限额，硬拒绝
├─ 提示注入 — 从 DB 注入系统提示
├─ 个人身份信息屏蔽 — 布隆 + 阿霍-科拉西克 + 正则表达式，<0.04ms
├─ 防护栏 — 注入检测，主题阻止
├─ MCP 注入 — 工具注入 + tool_calls 拦截 + OAuth PKCE
├─ 智能路由 — 实时复杂度评分和层级选择
├─ 循环检测器 — 速率 / 指纹 / 成本 / 会话
├─ 语义缓存 — Redis Stack 向量搜索 + SHA256 备份
└─ 提供商路由器 — 加权轮询、断路器、备份
│
├─ OpenAI / Anthropic / Gemini / DeepSeek
├─ OpenRouter / Ollama / Qwen / OpenCode
└─ ...
ILTER :9191 → 仪表盘（Astro + React，Go 嵌入）
ILTER :9192 → /metrics （Prometheus，OpenTelemetry 桥接）
```
- **语言：** Go 1.26.3，单一二进制文件，无 CGo（`CGO_ENABLED=0`），goroutine 并发。
- **路由器：** `chi` v5。
- **数据库：** SQLite — `modernc.org/sqlite`，纯 Go，WAL 模式。
- **缓存：** Redis Stack 7+ — 可选，优雅降级。
- **配置：** 编译默认 + `ILTER_*` 环境变量 — 无需配置文件。
→ 架构详情：[`docs/architecture.md`](docs/architecture.md)
→ 设计决策和 FAQ：[`docs/faq.md`](docs/faq.md)
→ 网关比较：[`docs/comparison.md`](docs/comparison.md)
---
## Docker 和容器部署
```bash
# 单个容器（基于 scratch 的镜像，<20MB）
# 管理密钥和提供商密钥足以直接启动到 `serve` — 无需
# `ilter init` 步骤。SQLite 数据库在首次启动时创建，并且
# 设置了 ILTER_PROVIDER_<NAME>_API_KEY 的提供商将自动启用。
docker run -d \
-p 8181:8181 -p 9191:9191 -p 9192:9192 \
-v $(pwd)/data:/app/data \
-e ILTER_ADMIN_API_KEY=<your-own-random-secret> \
-e ILTER_PROVIDER_OPENAI_API_KEY=sk-... \
ghcr.io/ilter-ai/ilter:latest
# 完整本地栈：ILTER + Redis Stack + Ollama
docker compose up -d
```
如果没有设置 `ILTER_ADMIN_API_KEY` 和提供者密钥，`serve` 将拒绝启动 — 这样就无法进行身份验证或路由请求 — 并退出，并显示一条消息，指示您运行 `ilter init` 或同时设置两者。
镜像大小：**<20MB**（3 阶段构建：Bun web → Go UPX → 空 `scratch` 基础镜像）。这仅适用于 Docker 镜像 — [Releases](https://github.com/ilter-ai/ilter/releases) 中的纯二进制文件（无 UPX）约为 35-40MB。
---
## 配置
默认情况下无需配置。三个级别的覆盖：
| 级别 | 方法 | 示例 |
|--------|--------|-------|
| **启动** | `ILTER_*` 环境变量 | `ILTER_SERVER_PORT=9090`，`ILTER_METRICS_LISTEN_ADDR=:9192` |
| **运行时** | 仪表盘或 `ilter init` 向导 | 切换 PII，添加提供者，更新路由策略 |
| **每密钥** | 仪表盘或管理 API | 基于团队的预算，速率限制，允许的模型 |
→ 所有选项：[`docs/configuration.md`](docs/configuration.md)
---
## CLI
| 命令 | 描述 |
|-------|---------|
| `ilter serve` | 启动代理 + 仪表盘 |
| `ilter init` | 交互式设置向导 |
| `ilter init --demo` | 带有模拟数据的仪表盘演示 |
| `ilter models` | 支持的模型 — 提供商，层级，成本 |
| `ilter models --update` | 从所有提供商发现模型 |
---
## 开发
```bash
make build # Go 二进制文件 + web 资产
make check # 构建 + 校验（Go + web）
make test # go test -race -count=1 ./...
make fix # gofumpt + biome 格式化
```
贡献指南：[`CONTRIBUTING.md`](CONTRIBUTING.md)
---
## 性能
Apple M4，Go 1.26.3：
| 操作 | 延迟 |
|-------|---------|
| 核心代理开销 | <0.8ms |
| 个人身份信息防护扫描 | 0.031ms |
| 智能路由评分 | 0.022ms |
| 循环指纹识别 | 0.008ms |
---
## 许可证
Apache 2.0 with Commons Clause — 见 [LICENSE](LICENSE)。
连接信息
猜你喜欢
暂无推荐服务器