From 06cfbbacc32ad4a6171e159d97b65dc3b9576724 Mon Sep 17 00:00:00 2001 From: WangLX <519407855@qq.com> Date: Thu, 20 Aug 2026 12:22:05 +0800 Subject: [PATCH] feat: establish gateway adapter baseline --- README.md | 2 + ...n-source-baseline-and-development-nodes.md | 141 +++++++++++++++ docs/DEVELOPMENT_PROCESS.md | 8 +- prototype/src/services/gateway.ts | 160 ++++++++++++++++++ 4 files changed, 308 insertions(+), 3 deletions(-) create mode 100644 docs/04-open-source-baseline-and-development-nodes.md create mode 100644 prototype/src/services/gateway.ts diff --git a/README.md b/README.md index 75bda3a..f29f835 100644 --- a/README.md +++ b/README.md @@ -296,6 +296,8 @@ MaaS 模型服务与应用开发 - [产品开发流程](docs/DEVELOPMENT_PROCESS.md) - [阶段 1:产品定义与原型设计](docs/01-product-definition-and-prototype.md) - [阶段 2:可视化交互原型](docs/02-interactive-prototype.md) +- [双端产品形态与开源技术底座](docs/03-dual-portal-and-open-source-foundation.md) +- [开源技术基线与开发节点](docs/04-open-source-baseline-and-development-nodes.md) ## 前端原型 diff --git a/docs/04-open-source-baseline-and-development-nodes.md b/docs/04-open-source-baseline-and-development-nodes.md new file mode 100644 index 0000000..25a3884 --- /dev/null +++ b/docs/04-open-source-baseline-and-development-nodes.md @@ -0,0 +1,141 @@ +# 开源技术基线与开发节点 + +## 文档信息 + +- 产品:模亦灵枢 / MOYI Model Intelligence Hub +- 阶段:阶段 3,系统设计与工程基线 +- 状态:开发基线 v1 +- 更新时间:2026-08-20 +- 当前节点:D1,网关适配契约 + +## 一、开源项目使用决策 + +模亦灵枢不直接修改某个中转站项目并把它整体作为产品,而采用“开源网关能力 + MOYI 自研控制面与双端控制台”的组合方式。这样可以复用成熟的模型代理、虚拟密钥和用量能力,同时保留多类型模型、异步 3D 任务、额度台账和未来 MaaS 能力的产品自主性。 + +| 项目 | 当前定位 | 许可证基线 | 使用方式 | +|---|---|---|---| +| [Otari](https://github.com/mozilla-ai/otari) | 第一阶段模型网关与用量基础 | Apache-2.0 | 计划部署为独立服务,通过 MOYI 适配层调用,不修改其前端作为本产品控制台 | +| [Apache APISIX](https://github.com/apache/apisix) | 后续高性能数据面 | Apache-2.0 | 第一版不进入关键路径,达到容量门槛后再引入 | +| [New API](https://github.com/QuantumNous/new-api) | 产品功能与兼容性参考 | AGPLv3,官方另有品牌与商业许可说明 | 只参考功能边界和交互,不复制代码进入当前代码库 | +| [Sub2API](https://github.com/Wei-Shaw/sub2api) | 共享额度、账号池和运营流程参考 | LGPL-3.0 | 只参考业务流程和测试场景,若未来复用代码需单独完成法务与许可证审计 | + +进入生产前必须锁定实际使用版本的 commit 或镜像 digest,保存 LICENSE、NOTICE、依赖清单和安全扫描结果。本文档是工程决策记录,不替代正式法律意见。 + +## 二、系统职责边界 + +```text +用户端 / 管理端 Vue 控制台 + │ + ▼ + MOYI Control Plane API + 认证 · 用户 · 角色 · 邀请码 + 模型目录 · 额度台账 · 异步任务 + 审计 · 运营 · 网关适配接口 + │ + ┌─────┴─────┐ + ▼ ▼ + Otari Adapter MOYI Task Adapter + 文本/多模态 3D/图像/视频 + Key/预算/用量 排队/进度/文件 + │ │ + └─────┬─────┘ + ▼ + 供应商 API / 自托管模型 +``` + +### 2.1 Otari 负责 + +- OpenAI/Anthropic 兼容请求转发。 +- 供应商凭证、模型别名与基础路由。 +- 虚拟 Key、预算前置校验、用量和成本记录。 +- 网关健康检查和基础可观测数据。 + +### 2.2 MOYI 自研负责 + +- 邀请码注册、登录、用户角色和双端权限。 +- 平台额度账本;Otari 预算是执行限制,不作为财务事实来源。 +- 面向用户的 `sk-moyi-*` 密钥生命周期及其到网关 Key 的映射。 +- 统一模型目录、展示名称和多类型能力 Schema。 +- 3D、图像和视频等异步任务的队列、进度、结果文件和回调。 +- 管理端运营、审计、额度发放和未来支付订单。 +- 对 Otari、APISIX 和自托管模型隐藏实现差异的适配契约。 + +### 2.3 前端不得承担 + +- 不得持有 Otari Master Key、供应商密钥或数据库凭证。 +- 不得直接调用网关管理接口创建 Key、预算和供应商。 +- 不得根据前端余额直接决定是否允许调用。 +- 不得把隐藏管理菜单当作权限控制。 + +## 三、第一版调用契约 + +### 3.1 同步与流式模型 + +```text +应用携带 sk-moyi-* 请求 /v1/* + → 数据面验证 MOYI Key + → 控制面读取用户、模型权限和可用额度 + → Otari 执行供应商路由与预算限制 + → 流式透传响应 + → 用量事件写入 MOYI 台账 +``` + +第一批兼容入口预留: + +- `POST /v1/chat/completions` +- `POST /v1/responses` +- `POST /v1/messages` +- `GET /v1/models` +- `GET /v1/usage` + +最终开放范围以目标 Otari 版本和首批供应商联调结果为准。 + +### 3.2 异步模型 + +```text +POST /v1/tasks + → 校验 Key、模型权限、额度和并发 + → 创建幂等任务与额度预占 + → 排队并调用 3D/图像/视频供应商 + → 轮询或接收回调更新进度 + → 结果文件进入对象存储 + → 成功结算 / 失败释放预占 +``` + +异步任务不强行转换成聊天接口。它与 Otari 共用统一认证、模型目录和用量视图,但使用 MOYI 自研任务适配层。 + +## 四、开发节点 + +每个节点遵循“目标确认—代码与文档—构建/测试—提交—推送—进度同步”的交付方式。页面细节在节点内持续调整,不阻塞核心链路开发。 + +| 节点 | 目标 | 主要产物 | 节点门禁 | +|---|---|---|---| +| D0 原型基线 | 固化品牌、用户端、管理端和认证流程 | Vue 可交互原型 | 已完成,提交 `bebff16` | +| D1 网关适配契约 | 固化开源边界和前端网关接口 | 本文档、类型化 Gateway Client、演示适配器 | 类型检查和前端构建通过 | +| D2 Otari 本地基座 | 运行锁定版本的 Otari 与持久化数据库 | Compose、环境模板、健康检查、许可证清单 | 重启后配置和用量可持久化 | +| D3 身份与权限 | 实现邀请码、登录、会话、角色与管理端守卫 | Control Plane 认证 API、数据库迁移、前端真实登录 | 普通用户无法访问管理 API | +| D4 密钥与模型目录 | 打通 MOYI Key、网关 Key、模型目录和权限 | Key API、模型 Schema、Otari 映射、管理页面 | 创建 Key 后可完成一次真实调用 | +| D5 调用与计量 | 打通同步、流式、用量事件和额度账本 | 代理链路、SSE、幂等计量、用量页面 | 调用量与额度变更可追溯且不重复扣减 | +| D6 异步任务与 3D | 打通任务提交、排队、进度和结果文件 | Task API、队列、对象存储、AI SoulMate 适配器 | 3D 任务完成正常/失败闭环 | +| D7 管理运营 | 接入用户额度、供应商、路由、并发、审计 | 管理端真实 API 与高风险操作审计 | 关键管理操作可追踪和回滚 | +| D8 测试与部署 | 完成功能、性能、安全和上线准备 | 自动化测试、部署、监控、告警、回滚 | UAT 与发布评审通过 | + +## 五、D2 前置资源清单 + +以下内容在进入 D2/D3 时逐项确认,暂未确定项可以先使用本地开发替代方案: + +| 资源 | 开发阶段替代 | 生产前需要确认 | +|---|---|---| +| 服务器与容器环境 | 本地 Docker Desktop | 云服务器、CPU/内存、磁盘、备份和网络 | +| 数据库 | PostgreSQL 本地容器 | 高可用、备份、恢复、加密和保留周期 | +| 缓存与队列 | Redis 本地容器 | 持久化、并发容量和故障恢复 | +| 对象存储 | MinIO 本地容器 | OSS/S3 地区、生命周期、跨域和下载授权 | +| 域名与 TLS | localhost | 控制台、管理端、API 域名和证书 | +| 首批模型供应商 | Mock 或单个测试账号 | 名单、密钥、额度、计价、限流和数据条款 | +| AI SoulMate 3D | Mock Task Adapter | 正式 API、回调、文件格式、超时和计费单位 | +| 邮件/短信 | 控制台验证码 | 服务商、模板、签名、发送限制和风控 | +| 地区与合规 | 不对公网开放 | 服务地区、隐私政策、日志和内容安全要求 | + +## 六、当前结论 + +当前正式进入 D1。D1 不启动真实供应商调用,也不要求提供生产密钥;它先建立稳定的代码边界。D2 开始部署 Otari 时,再由项目负责人确认服务器环境和至少一个可用于联调的供应商测试密钥。 diff --git a/docs/DEVELOPMENT_PROCESS.md b/docs/DEVELOPMENT_PROCESS.md index 9eb0e73..c7f5ef5 100644 --- a/docs/DEVELOPMENT_PROCESS.md +++ b/docs/DEVELOPMENT_PROCESS.md @@ -336,6 +336,8 @@ ## 七、当前进度 - 阶段 0:已完成产品蓝图和品牌定位。 -- 当前阶段:阶段 1,产品定义;现有文档为待评审草案。 -- 下一份产物:补齐需求矩阵并完成阶段 1 评审,随后进入阶段 2 可视化原型设计。 -- 后续阶段:系统架构、数据模型、API 设计和开发计划。 +- 阶段 1:已形成第一版产品定义和 MVP 范围基线,待真实供应商、计费和合规信息持续补充。 +- 阶段 2:已完成品牌化双端可交互原型,版本基线为 `bebff16`。 +- 当前阶段:阶段 3 与阶段 4 交叠推进,先完成开源底座、网关适配和开发环境等工程基线,再逐节点补齐系统设计和实现。 +- 当前开发节点:D1 网关适配契约;下一节点为 D2 Otari 本地基座。 +- 节点规则:每个节点完成代码、文档和验证后独立提交并推送,再向项目负责人同步结果和下一节点所需资源。 diff --git a/prototype/src/services/gateway.ts b/prototype/src/services/gateway.ts new file mode 100644 index 0000000..3737fdd --- /dev/null +++ b/prototype/src/services/gateway.ts @@ -0,0 +1,160 @@ +export type GatewayStatus = 'healthy' | 'degraded' | 'unavailable' + +export interface GatewayHealth { + status: GatewayStatus + checkedAt: string + source: 'demo' | 'otari' +} + +export interface GatewayModel { + id: string + provider?: string + ownedBy?: string +} + +export interface GatewayUsageQuery { + from?: string + to?: string + keyId?: string + model?: string +} + +export interface GatewayUsageRecord { + requestId: string + model: string + inputUnits: number + outputUnits: number + cost?: number + createdAt: string +} + +export interface GatewayPage { + data: T[] + nextCursor?: string +} + +export interface GatewayClient { + health(): Promise + listModels(): Promise + listUsage(query?: GatewayUsageQuery): Promise> +} + +export interface OtariGatewayConfig { + baseUrl: string + accessToken: string + timeoutMs?: number +} + +interface OtariModelResponse { + data?: Array<{ + id: string + provider?: string + owned_by?: string + }> +} + +interface OtariUsageResponse { + data?: Array<{ + request_id?: string + id?: string + model?: string + input_tokens?: number + output_tokens?: number + cost?: number + created_at?: string + }> + next_cursor?: string +} + +export class OtariGatewayClient implements GatewayClient { + private readonly baseUrl: string + private readonly accessToken: string + private readonly timeoutMs: number + + constructor(config: OtariGatewayConfig) { + this.baseUrl = config.baseUrl.replace(/\/$/, '') + this.accessToken = config.accessToken + this.timeoutMs = config.timeoutMs ?? 8000 + } + + async health(): Promise { + const response = await this.request<{ status?: string }>('/health', false) + return { + status: response.status === 'healthy' ? 'healthy' : 'degraded', + checkedAt: new Date().toISOString(), + source: 'otari', + } + } + + async listModels(): Promise { + const response = await this.request('/v1/models') + return (response.data ?? []).map((model) => ({ + id: model.id, + provider: model.provider, + ownedBy: model.owned_by, + })) + } + + async listUsage(query: GatewayUsageQuery = {}): Promise> { + const search = new URLSearchParams() + if (query.from) search.set('from', query.from) + if (query.to) search.set('to', query.to) + if (query.keyId) search.set('key_id', query.keyId) + if (query.model) search.set('model', query.model) + const suffix = search.size ? `?${search.toString()}` : '' + const response = await this.request(`/v1/usage${suffix}`) + return { + data: (response.data ?? []).map((record) => ({ + requestId: record.request_id ?? record.id ?? 'unknown', + model: record.model ?? 'unknown', + inputUnits: record.input_tokens ?? 0, + outputUnits: record.output_tokens ?? 0, + cost: record.cost, + createdAt: record.created_at ?? new Date(0).toISOString(), + })), + nextCursor: response.next_cursor, + } + } + + private async request(path: string, authenticated = true): Promise { + const controller = new AbortController() + const timeout = window.setTimeout(() => controller.abort(), this.timeoutMs) + + try { + const headers = new Headers({ Accept: 'application/json' }) + if (authenticated) headers.set('Authorization', `Bearer ${this.accessToken}`) + const response = await fetch(`${this.baseUrl}${path}`, { + headers, + signal: controller.signal, + }) + if (!response.ok) throw new Error(`Gateway request failed with status ${response.status}`) + return await response.json() as T + } finally { + window.clearTimeout(timeout) + } + } +} + +export class DemoGatewayClient implements GatewayClient { + async health(): Promise { + return { + status: 'healthy', + checkedAt: new Date().toISOString(), + source: 'demo', + } + } + + async listModels(): Promise { + return [ + { id: 'moyi-text-pro', provider: '供应商 A', ownedBy: 'moyi' }, + { id: 'moyi-vision', provider: '供应商 A', ownedBy: 'moyi' }, + { id: 'aisoulmate-3d', provider: '模灵科技', ownedBy: 'moyi' }, + ] + } + + async listUsage(): Promise> { + return { data: [] } + } +} + +export const gatewayClient: GatewayClient = new DemoGatewayClient()