Skip to content

feat: FreeLLM 代理层 — compression + freellm 包 + README 诚实化 #2

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
anbeime wants to merge 1 commit into
base: main
Choose a base branch
from
Open

feat: FreeLLM 代理层 — compression + freellm 包 + README 诚实化 #2

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
95 changes: 61 additions & 34 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,26 +30,31 @@ TOPGO Platform 是企业级一体化 AI 资源管理平台，整合了 **智能

### 核心架构

TOPGO 采用 **数据平面 / 控制平面分离** 的企业级架构。当前已实现并部署的是
Gateway 数据平面（Go），它已内建调度、健康探测与策略编排能力；Orchestrator
作为独立的控制平面（Python）在 roadmap 中，用于跨实例的资源注册与全局编排。

```
┌─────────────────────────────────────────────────────────┐
│ TOPGO Platform │
├─────────────────────────────────────────────────────────┤
│ ┌─────────────────────┐ ┌─────────────────────────┐ │
│ │ TOPGO Orchestrator │───→│ TOPGO Gateway │ │
│ │ (调度引擎) │ │ (统一网关) │ │
│ │ │ │ │ │
│ │ • 资源自动注册 │ │ • 智能路由 │ │
│ │ • 健康探测与轮转 │ │ • 精准计费 │ │
│ │ • 多维标签管理 │ │ • 用户管理 │ │
│ │ • 策略编排 │ │ • 负载均衡 │ │
│ └─────────────────────┘ └─────────────────────────┘ │
│ ┌─────────────────────────┐ ┌──────────────────────┐ │
│ │ TOPGO Gateway (已实现) │←─│ TOPGO Orchestrator │ │
│ │ 数据平面 · Go + Vue │ │ 控制平面 · Roadmap │ │
│ │ │ │ │ │
│ │ • 智能路由 (GEO) │ │ • 跨实例资源注册 │ │
│ │ • 调度 / 健康探测 │ │ • 全局策略编排 │ │
│ │ • FreeLLM 代理层 │ │ • 资源池同步 │ │
│ │ (压缩 + 免费源池) │ │ │ │
│ │ • 精准计费 / 用户管理 │ │ │ │
│ └─────────────────────────┘ └──────────────────────┘ │
└─────────────────────────────────────────────────────────┘
```

| 组件 | 技术栈 | 功能 |
|------|--------|------|
| **Gateway** | Go + Vue | API 网关、计费、用户管理 |
| **Orchestrator** | Python + Vue | 资源调度、轮转、同步 |
| 组件 | 技术栈 | 状态 | 功能 |
|------|--------|------|------|
| **Gateway** | Go + Vue | ✅ 已实现 | 智能路由、调度、计费、用户管理、FreeLLM 代理层 |
| **Orchestrator** | Python + Vue | 🚧 Roadmap | 跨实例资源注册、全局策略编排、资源池同步 |

## 快速部署

Expand Down Expand Up @@ -82,19 +87,21 @@ docker compose up -d

## 核心功能

### TOPGO Gateway (统一API网关)
### TOPGO Gateway (统一API网关 · 已实现)
- **多模型支持** - Claude、OpenAI (Codex)、Gemini
- **资源凭证管理** - OAuth、API Key
- **精准计费** - 用量级别追踪
- **智能路由** - 基于 GEO 的动态路由
- **用户管理** - API Key、套餐、充值

### TOPGO Orchestrator (智能调度引擎)
- **自动注册** - 自动创建 AI 账号
- **智能轮转** - 按可用量自动调度
- **健康探测** - 实时监控资源状态
- **策略编排** - 多维度路由策略
- **Gateway 同步** - 自动推送资源到网关
### FreeLLM 代理层 (Gateway 内建)
借鉴 OmniRoute 的免费源 + 压缩思路，企业级落地：
- **免费源池** - 内置 10+ 免费 / 免费层 provider 种子清单（Pollinations/Groq/Gemini/Cerebras/SambaNova/DeepSeek/Mistral/Together/OpenRouter/Kiro），复用 `channel_monitor` 自动探活，按 `cost_tier=free` 打标
- **Token 压缩** - Go 原生可插拔引擎（`internal/service/compression`），Lite/Standard/Aggressive 三档，规则引擎对标 OmniRoute 的 Caveman，省 15-70%，代码块自动保护
- **Model 级 failover** (Roadmap) - 在现有 `group_model_routing` 上加同模型 fallback 链 + 8ms 超时切换

### TOPGO Orchestrator (控制平面 · Roadmap)
Gateway 已内建调度 / 健康探测 / 策略编排；Orchestrator 将这些能力抽取为独立控制平面，支持跨实例资源注册与全局编排。

## 资源供给流程

Expand All @@ -114,20 +121,24 @@ docker compose up -d

```
api-token/
├── backend/ # TOPGO Gateway (Go)
│ ├── cmd/server/ # 主入口
│ ├── internal/ # 核心逻辑
│ ├── frontend/ # Vue 前端
│ └── deploy/ # 部署配置
├── backend/ # TOPGO Gateway (Go)
│ ├── cmd/server/ # 主入口
│ ├── internal/
│ │ ├── service/
│ │ │ ├── compression/ # FreeLLM 代理层 · Token 压缩 (新)
│ │ │ ├── freellm/ # FreeLLM 代理层 · 免费源池 seed (新)
│ │ │ ├── channel.go # 渠道管理 + channel_monitor 探活
│ │ │ ├── scheduler_*.go # 调度 / 轮转 / fallback
│ │ │ └── openai_gateway_*.go # 统一 ingress
│ │ ├── ent/ # ORM (entgo)
│ │ └── server/ # 路由 / 中间件
│ ├── frontend/ # Vue 前端
│ └── deploy/ # 部署配置
│
├── orchestrator/ # TOPGO Orchestrator (Python)
│ ├── src/ # 核心逻辑
│ ├── web/ # Vue 前端
│ └── docs/ # 文档
│
├── docs/ # 公共文档
├── deploy/ # 公共部署配置
└── docker-compose.yml # 一体化部署
├── orchestrator/ # TOPGO Orchestrator (Python) · 🚧 Roadmap
├── docs/ # 公共文档
├── deploy/ # 公共部署配置
└── docker-compose.yml # 一体化部署
```

## 环境配置
Expand Down Expand Up @@ -160,8 +171,24 @@ api-token/
## 文档

- [GEO 智能路由架构](TOPGO_GEO_ARCHITECTURE.md)
- [FreeLLM 代理层设计](TOPGO_FREELLM_PROXY.md)
- [Gateway 部署指南](backend/deploy/README.md)
- [Orchestrator 配置说明](orchestrator/docs/configuration.md)

## 与 OmniRoute 的对位与借鉴

同赛道（LLM 路由/网关），受众错开，不重复收录：

| 维度 | TOPGO Platform | OmniRoute |
|------|----------------|-----------|
| 定位 | 企业级 AI 资源管理（数据/控制平面分离） | 个人/开发者免费路由 |
| 技术栈 | Go Gateway + Vue（Orchestrator Python roadmap） | 100% TypeScript |
| 免费源 | FreeLLM 代理层 · 10+ provider 种子池，复用 channel_monitor 探活 | 90+ 免费层 / 11 家永久免费 |
| failover | GEO 智能路由（地域级）+ Model 级 fallback (roadmap) | 4-tier auto-fallback (Subscription→API Key→Cheap→Free) |
| token 优化 | Go 原生压缩（Lite/Standard/Aggressive，规则引擎对标 Caveman） | RTK + Caveman + LLMLingua-2，省 15-95% |
| 企业功能 | 多租户、计费、OAuth、资源池轮转、套餐充值 | 无 |

> OmniRoute 的免费源清单 / 多级 failover / 压缩三点已反哺 TOPGO 的 FreeLLM 代理层，
> 详见 [TOPGO_FREELLM_PROXY.md](TOPGO_FREELLM_PROXY.md)。

## 许可证

Expand Down
148 changes: 148 additions & 0 deletions TOPGO_FREELLM_PROXY.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,148 @@
# TOPGO FreeLLM 代理层设计

把 OmniRoute 的三个独有卖点（免费源池 / 多级 failover / token 压缩）反哺进 TOPGO
Gateway 的 FreeLLM 代理层。本文档是落地参照，不是空气架构——每个卖点都映射到
`backend/internal/` 里真实存在的代码。

## 设计立场

OmniRoute 是 100% TypeScript、面向个人开发者的免费路由。TOPGO 是 Go、面向企业的
资源管理平台。两者受众错开，直接照搬 TS 引擎进 Go 网关是企业级反模式（外部进程
多一跳延迟、第三方耦合）。因此本代理层走 **Go 原生、可插拔、分阶段**：

| 卖点 | OmniRoute | TOPGO 落地 | 状态 |
|------|-----------|-----------|------|
| 免费源池 | 90+ 免费层 / 11 家永久免费 | `freellm` seed 清单 + 复用 `channel_monitor` 探活 | ✅ 已实现（seed） |
| token 压缩 | RTK + Caveman + LLMLingua-2 | `compression` 包，Lite/Standard/Aggressive，规则引擎对标 Caveman | ✅ 已实现（规则引擎）；LLMLingua-2 ONNX 🚧 Phase 2 |
| 多级 failover | 4-tier auto-fallback | GEO 地域路由（已有）+ Model 级 fallback | 🚧 Model 级 Roadmap |

---

## 1. Token 压缩 — `internal/service/compression`

### 1.1 架构

可插拔 `Engine` 接口，调用点只传 `body []byte` 进、拿 `body []byte` 出，零耦合
ent/wire/gateway 内部：

```go
type Engine interface {
Name() string
Compress(text string, mode Mode) string
}

// 调用点（gateway ingress 顶部，json.Unmarshal 之前）
body, stats, _ := compression.RewriteRequestBody(body, engine, compression.Options{Mode: compression.ModeStandard})
```

- **格式感知**：识别 OpenAI Chat Completions（`messages[].content`）、OpenAI
Responses（`input[].content[].{text,input_text}` + 顶层 `instructions`）、Anthropic
Messages（`messages[].content[].text` + 顶层 `system`）。其它 JSON 原样透传。
- **代码块保护**：`CompressCode=false`（默认）时，``` ``` 包裹的代码段原样保留，只压
缩散文。避免破坏 prompt 里的代码示例。
- **幂等、无副作用、并发安全**。
- **点编辑**：用 gjson/sjson 做字段级改写（与本仓库 `openai_gateway_chat_completions.go`
同款模式），保留原始 key 顺序与非文本字段。

### 1.2 引擎

| 引擎 | 模式 | 说明 | 目标节省 |
|------|------|------|----------|
| `LiteEngine` | lite | 空白/分隔符归一化，CJK 安全 | ~10-15% |
| `RuleEngine` | standard | 规则表：冗长短语→精简（"in order to"→"to"、"utilize"→"use"），删填充词（"basically"/"very"） | ~30-50% |
| `RuleEngine` | aggressive | standard + 连续重复行去重 + 空行清理 | ~50-70% |

规则表对标 OmniRoute 的 Caveman（规则式散文压缩），~80 条安全改写，单词边界锚定、
大小写不敏感，CJK 不命中（自然降级为空白归一化）。

### 1.3 集成点

[backend/internal/service/openai_gateway_chat_completions.go](backend/internal/service/openai_gateway_chat_completions.go)
的 `ForwardAsChatCompletions` 入口，`body []byte` 进来后、`json.Unmarshal` 之前插入
一行压缩调用。Anthropic / Gemini ingress 同理。压缩 `Stats` 写入 `usage_log`，复用
现有计费/可观测通路。

### 1.4 Phase 2：LLMLingua-2 ONNX

LLMLingua-2 是 ML 语义裁剪（MobileBERT ONNX），压缩率更高但需要模型文件。规划为
`compression` 包的第三个 `Engine` 实现，通过 ONNX Runtime Go 绑定加载，**opt-in**，
不替换规则引擎。规则引擎保底（无依赖、低延迟），LLMLingua-2 按需开启。

---

## 2. 免费源池 — `internal/service/freellm`

### 2.1 定位

`freellm.SeedCatalog()` 是 **种子清单**，不是 live client。10 个真实免费 / 免费层
provider（Pollinations keyless 在首位，Groq/Gemini/Cerebras/SambaNova/DeepSeek/
Mistral/Together/OpenRouter/Kiro 跟随），按 `AuthScheme`/`Protocol`/`FreeTier`/
`Models`/`RateLimitRPM` 标注。

### 2.2 集成路径

种子清单灌入 Gateway 现有 `channel` 表，复用已有基础设施，**不新建表**：

- 探活 → [channel_monitor](backend/ent/channelmonitor) + `channel_monitor_history` +
`channel_monitor_request_template`（已实现，定期探测上游可用性）。
- 路由/过滤 → `group` + `group_account_filter`（migration 081）。
- 标签 → 按 `cost_tier=free` 归类，与付费源隔离调度（避免免费源限流拖垮付费 SLA）。

### 2.3 鉴权模型

只有 Pollinations 无需凭证。其余都是免费层/注册额度，运营者启用时自备 credential。
这符合企业姿态：免费源拉伸预算，不替代凭证治理。

---

## 3. Model 级 failover — Roadmap

### 现状

- GEO 路由（地域级）已在 [TOPGO_GEO_ARCHITECTURE.md](TOPGO_GEO_ARCHITECTURE.md) 设计，
Gateway 评分算法落地。
- `group_model_routing`（migration 040）+ `group_invalid_request_fallback`（migration
043b）已有 group→account 级 fallback。
- `scheduler_cache` / `scheduler_outbox` / `openai_account_scheduler` 是真实轮转引擎。

### 缺口（对应 OmniRoute 的 Provider→Connection→Model 三层）

缺 Model 级：DeepSeek 免费源挂了，8ms 内切 Qwen 免费源。

### 落地计划

1. `group_model_routing` 上加同 model 的 fallback 链（一个 model 映射到多个 channel）。
2. scheduler 加超时切换阈值（8ms 连接级 / N ms 首字节级）。
3. `error_passthrough_rule` 配合：5xx / 超时触发同 model 下一 channel，不透传给客户端。

**未本次实现**——scheduler 热路径手术风险高，需独立 PR + 完整 e2e 测试覆盖。

---

## 4. 串成闭环（与前序"四色卡片 MCP"联动）

TOPGO Gateway 若暴露为 MCP Server，FreeLLM 代理层的"智能路由 + 免费源 + 压缩"即成为
卡片 MCP 的 model 调用底座，省掉 Pro 订阅。链路：

```
四色卡片 MCP ──clawhub install topgo──→ TOPGO Gateway (MCP Server)
├─ compression (省 token)
├─ freellm pool (免费源)
└─ GEO + Model failover (高可用)
```

api-token（本仓库）+ 四色卡片 + OmniRoute 参照，三者闭环。

---

## 5. 验证

```bash
cd backend
go test ./internal/service/compression/ # 15 用例，覆盖 OpenAI/Anthropic/Responses + 代码块保护 + Stats
go test ./internal/service/freellm/ # 种子清单唯一性 + Find
go build ./... # 全量编译
```

压缩包自包含：仅依赖 gjson/sjson/testify（均已在 go.mod），不依赖 ent/wire，可独立
编译与测试。
Loading
Loading