# Sage 智能平台技术白皮书

## 一、平台概述

Sage 是一个面向 AI 时代的智能服务管理平台，集模型网关、计费引擎、产线编排、权限管理于一体，为企业提供从 API 接入到业务结算的全链路基础设施。

**核心理念**：一套平台，统一管理所有 AI 服务的接入、调度、计费和客户关系。

## 二、系统架构

```
┌──────────────────────────────────────────────────────────┐
│                    客户端层                               │
│  Web 管理后台 │ API 调用 (OpenAI 兼容) │ CLI Agent      │
└──────────────┬───────────────────────────────────────────┘
               │
┌──────────────▼───────────────────────────────────────────┐
│                    Sage 平台核心                          │
│                                                          │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────────────┐  │
│  │ 权限管理  │ │ 模型网关  │ │ 计费引擎  │ │ 产线编排   │  │
│  │ RBAC +   │ │ llmage   │ │ Pricing  │ │ Pipeline   │  │
│  │ Session  │ │ UAPI     │ │ Engine   │ │ Orchestrator│ │
│  └──────────┘ └──────────┘ └──────────┘ └────────────┘  │
│                                                          │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────────────┐  │
│  │ 文件管理  │ │ 知识库   │ │ 营销引擎  │ │ 多语言     │  │
│  │ FileMgr  │ │ RAG/KDB  │ │ Discount │ │ i18n       │  │
│  └──────────┘ └──────────┘ └──────────┘ └────────────┘  │
└──────────────┬───────────────────────────────────────────┘
               │
┌──────────────▼───────────────────────────────────────────┐
│                    基础设施层                              │
│  ahserver (异步HTTP) │ sqlor (数据库) │ Redis │ Nginx    │
│  Hermes Agent │ 浏览器测试 (CDP) │ SSH 远程调度          │
└──────────────────────────────────────────────────────────┘
```

## 三、核心模块

### 3.1 模型网关 (llmage)

**功能**：统一的 AI 模型接入层，支持 OpenAI 兼容 API。

| 特性 | 说明 |
|------|------|
| 多供应商 | 同时接入通义、MiniMax、火山方舟、Vidu、自建 GPU 等 |
| 协议统一 | 标准 `/v1/chat/completions`、`/v1/models` 等 OpenAI 兼容接口 |
| 异步任务 | 内置 asyncinference 引擎，支持 submit→poll→result 异步流水线 |
| 数据模板 | Jinja2 模板引擎，灵活适配不同供应商的请求/响应格式 |
| 参数映射 | `_file` 命名规范，自动处理文件 → URL 转换 |

**已接入模型**：146+ 模型，涵盖文本对话、文生图、文生视频、语音识别、人脸识别、音频分离、歌曲评分、声音转换、超分辨率等。

### 3.2 计费引擎 (Pricing)

**功能**：灵活的多维度计费系统，支持按量计费、套餐计费、渠道折扣。

| 特性 | 说明 |
|------|------|
| 按量计费 | 支持 audio_seconds、image_count、video_seconds 等多种计价因子 |
| 独立定价 | 每个模型独立 ppid，不同服务不同单价 |
| 自动记账 | backend_accounting 后台循环处理，实时结算 |
| 余额管控 | checkCustomerBalance 前置检查，欠费自动阻拦 |
| 定价模板 | YAML 格式定价数据，price_factors + unit_prices 灵活配置 |

**定价示例（KTV 产线）**：

| 服务 | 单价 | 计价因子 |
|------|------|---------|
| 语音识别 | 0.01元/秒 | audio_seconds |
| 音频分离 | 0.02元/秒 | audio_seconds |
| 人脸检测 | 0.10元/次 | detect_count |
| 字幕渲染 | 0.01元/条 | subtitle_count |
| 超分辨率 | 0.50元/张 | image_count |
| 声音转换 | 0.15元/秒 | audio_seconds |

### 3.3 权限管理 (RBAC)

**功能**：基于角色的访问控制，支持 Session 管理、跨进程缓存同步。

| 特性 | 说明 |
|------|------|
| 角色体系 | 支持 admin/logined/anonymous/any 四级默认角色 + 自定义角色 |
| 路径权限 | 每个 DSPY/UI 端点可独立配置访问权限 |
| Session 管理 | Redis 存储，跨进程共享，自动过期 |
| 缓存同步 | 权限变更自动广播所有工作进程 |
| 审计日志 | 完整的访问日志和操作记录 |

### 3.4 产线编排 (Pipeline)

**功能**：将多个 AI 原子服务编排为完整的业务流程。

**KTV 产线示例**（14 个 GPU 服务 → llmage API 统一调度）：

```
音频准备 → Demucs 分离(人声/伴奏/MIDI) → ASR 语音识别(逐字时间戳)
      ↓                                          ↓
  人声提取                               精准字幕生成
      ↓                                          ↓
  RVC 变声                                卡拉OK渲染
      ↓                                          ↓
  ┌──────────────── 视频合并 ────────────────────┘
  ↓
输出：KTV 视频(双音轨) + MTV 视频 + ASS 字幕
```

**核心特性**：
- 全链路通过 llmage API 调度，不直连 GPU
- 异步任务自动轮询
- 自动记账（每个子任务独立计费）
- 费用预估 + 模型选择（客户参与决策）

### 3.5 模型选择与费用预估

产线内置智能模型选择流程：

```
故事板生成 → 模型选择(费用预估) → 视频生成
                ↓
          客户看到：
          - 快乐马：0.03元/秒，快速经济
          - 通义万象 WAN 2.7：0.05元/秒，高质量 ⭐推荐
          - 豆包 Seedance 2.0：0.08元/秒，旗舰级
          ↓
          客户选择 → 按选择生成
```

**费用预估包含**：
- 总视频时长 × 单价 = 基础费用
- 20% 容错系数（重试/失败）
- 其他服务费用明细（demucs + ASR + 字幕等）

## 四、技术特性

### 4.1 异步流水线

Sage 的 asyncinference 引擎提供完整的异步任务管理：

```
POST /v1/pipeline/submit → {"taskid":"...","status":"PENDING"}
  → 后台轮询 (每 5s)
  → GET /status?task_id=xxx → {"status":"SUCCEEDED","usage":"..."}
  → 自动更新 llmusage → 触发记账
```

### 4.2 供应商抽象 (UAPI)

通过统一的 UAPI 层实现供应商无关的接口抽象：

```yaml
供应商配置:
  ktv-gateway: https://ktv.opencomputing.net:10443
  tongyi-wan: https://dashscope.aliyuncs.com
  vidu: https://api.vidu.com

端点模板:
  demucs-separate: POST /demucs/api/demucs-separate
  asr-transcribe: POST /asr/api/asr-transcribe
  realesrgan-upscale: POST /realesrgan/api/realesrgan-upscale
```

每个端点通过 Jinja2 模板处理请求/响应转换，实现供应商 API 差异的透明化。

### 4.3 数据库设计规范

- 统一使用 xls2ddl 建表工具
- 字符集标准：`utf8mb4 COLLATE utf8mb4_unicode_ci`
- 支持 emoji、多语言字符
- 自增 ID + UUID 双标识体系

### 4.4 前端框架

- 基于 bricks-mp（自研 JSON 驱动 UI 框架）
- 支持 Jinja2 服务端渲染
- 暗色主题、响应式布局
- 浏览器端到端测试（CDP 协议）

## 五、部署架构

```
┌─────────────────┐     ┌──────────────────┐
│  tokentest      │     │  production      │
│  测试环境        │     │  生产环境         │
├─────────────────┤     ├──────────────────┤
│ Sage :9180      │     │ Sage :9180       │
│ MariaDB         │     │ MariaDB          │
│ Redis           │     │ Redis            │
│ Nginx :443      │     │ Nginx :443       │
└────────┬────────┘     └────────┬─────────┘
         │                       │
         └───────────┬───────────┘
                     │
          ┌──────────▼──────────┐
          │   GPU 计算集群       │
          │   opencomputing.net  │
          ├─────────────────────┤
          │ Demucs :9083        │
          │ ASR :9925           │
          │ RealESRGAN :9082    │
          │ Face :9081          │
          │ ...                 │
          └─────────────────────┘
```

## 六、总结

Sage 平台通过统一的模型网关、灵活的计费引擎、完善的权限管理和可编排的产线系统，为企业提供了一站式的 AI 服务商业化平台。无论是简单的 API 代理还是复杂的多步骤 AI 工作流，Sage 都能以一致的方式管理和计费。