聚合AI：统一调度和管理大模型API的轻量级中转系统

综合介绍

聚合 AI (juhe-ai) 是一款专为个人、小团队及工作室打造的轻量级大模型中转与账号调度管理系统。其核心聚焦于 OpenAI 兼容协议接入，能够将多个零散的上游大模型账号（如 OpenAI OAuth 或传统 API Key）集中收敛，对外提供统一的标准 /v1 调用入口。通过该平台，用户可以轻松实现多账号的集中化维护、按业务分组的授权隔离、智能失败重试与无感调度切换。系统内置了完善的数据看板与日志审计功能，不仅能实时记录模型调用日志、Token消耗数额与估算成本，还能监控追踪 AI 接口的首字响应性能趋势。得益于 Node.js 与 SQLite 的轻量化技术选型，聚合 AI 无需配置 Redis 等复杂高可用集群依赖，支持本地化一键快速部署，极大降低了开发者调度多平台大模型资源与权限管控的复杂度，让 AI 服务始终保持高效稳定运行。

功能列表

• 统一标准化接口透传：对外暴露符合行业标准的 /v1 入口，完美兼容 Codex、OpenAI SDK、Cherry Studio、NextChat 等各类主流客户端工具，实现客户端代码零修改无缝接入。
• 智能多账号调度调度：支持配置高可用负载池，在处理高并发请求时自动筛选可用账号；当触发限流、API 异常或处于冷却期时，自动无缝切换至同组备用账号，保证前端业务不中断。
• 全链路数据统计与审计：底层自动记录所有请求详情，精确包括每次调用的模型、收发 Token 用量、耗时明细与金额成本估算，并生成清晰的可视化统计趋势图与错误排查摘要。
• 分组权限隔离管控：支持将不同的上游高优账号进行多维度分组，根据不同团队或业务线生成专属本地 API Key 并绑定特定分组，实现资源调用的物理隔离与细粒度安全管控。
• 全方位 AI 性能实时监控：提供深度的性能仪表盘，不仅统计基础成本，更支持双向查看“首字输出耗时 (First Token)”和“总耗时”的均值与最大极值趋势，辅助用户精准排查网络瓶颈。
• 极简全平台本地化部署：后端采用 Node.js 服务端应用开发，数据落盘默认依赖轻量级 SQLite，告别繁重外部组件。支持源码运行与提供预编译包，原生支持一键部署至 Windows、macOS 及 Linux 环境。

使用帮助

一、聚合 AI 系统安装与轻量部署流程

聚合 AI 为使用者提供了极其轻巧的部署体验，无论是毫无编程背景的个人用户还是全栈开发者，都能通过几步操作将其运行起来。

1. 使用预编译发布包（推荐日常使用者及快速体验用户）
官方已经将环境依赖打包处理，支持各主流操作系统的快捷启动。

• Windows 环境开箱即用：
  1. 在项目发布页获取最新的 juhe-ai-release.zip 压缩包。
  2. 打开 PowerShell 终端，解压压缩包：Expand-Archive .\juhe-ai-release.zip -DestinationPath . -Force。
  3. 进入解压后的文件目录：Set-Location .\juhe-ai-release。
  4. 运行系统启动脚本启动服务：pwsh .\start.ps1。
• macOS / Linux 环境一键部署：
  1. 准备好下载的 juhe-ai-release.tar.gz 文件。
  2. 在终端窗口中执行解压缩命令：tar -xzf juhe-ai-release.tar.gz。
  3. 切换至对应目录：cd juhe-ai-release。
  4. 赋予权限并执行启动脚本：bash ./start.sh。
     服务启动后，直接在浏览器中访问 http://服务器IP:3000/ 即可进入美观的 Ant Design Vue 管理后台界面。系统初始默认管理员账号与密码均为 admin，出于安全考虑，首次登录后请务必在设置面板中修改复杂密码。

2. 源代码环境开发部署（推荐专业开发者及需定制化用户）
如果需要进行二次开发或自定义，请确保您的环境已安装 Node.js (>= 22.13.0) 以及 pnpm 包管理器 (>= 9.0.0)。

1. 通过 Git 克隆项目源码至本地机器：git clone https://github.com/huanmin123/juhe-ai.git。
2. 进入项目根目录并执行包依赖安装：pnpm install。
3. 复制后端及前端的环境变量配置文件模板，以初始化本地参数：
   Copy-Item backend/.env.example backend/.env
Copy-Item frontend/.env.example frontend/.env (注：如在 Linux 下请直接使用 cp 命令)。
4. 运行全栈开发服务器：pnpm dev。
   启动完成后，前端图形管理界面将托管在 http://127.0.0.1:5173，而为所有外部应用提供 OpenAI 兼容代理网关的入口则位于 http://127.0.0.1:3000/v1。

二、聚合 AI 核心业务模块操作指南

完成框架搭建并登录后，按照以下三步闭环流标准化操作，即可将零碎的 API 资产转化为一个强健的调度中枢。

第一步：录入真实大模型账户底座（AI 账户管理）

1. 在左侧功能导航树点击 “AI 账户管理” 或 “我的 AI 账户”，进入资产控制中心。
2. 点击右上角的“添加账号”按钮，系统全面兼容市面主流凭据——您可以输入抓取的 OpenAI OAuth Token，或是传统的官方 API Key (sk-... 格式)。
3. 在表单中您可以精细化控制该账号：自定义权重优先级决定负载均衡比重、配置并发上限避免封号。如果您处于特殊网络环境，系统甚至支持针对不同账号设定独立的数据抓取代理（Proxy）地址。
4. 信息保存提交后，聚合 AI 底层 Worker 会瞬间发起异步心跳检测，复测连通性无误后账号随即转入可用队列。

第二步：架构业务分组与访问权限分配（分组管控）
多账号调度的灵魂在于高灵活的分组隔离。

1. 前往相关配置项中创建一个具有辨识度的分组（例如命名为：“开发部高频测试组”、“商务对接智能体专用”）。
2. 将刚才录入的多个高连通率的上游账号统一勾选、绑定至此分组中。一旦中转服务器接收到带有此分组标记的请求，将在此分组包含的所有有效账户内启动轮询；如果任一账号发生 429 报错（请求过多），系统将悄无声息地向下一个健康账户发起自动重试，确保输出端流式文本毫不卡顿。

第三步：生产及分发终端调用秘钥（API Key 签发）

1. 切换至核心功能的 “API Key 管理” 界面。
2. 点击“生成新密钥”，指定该秘钥用途并挂载入刚刚完成配置的业务分组。
3. 此时聚合 AI 会在本地数据库中派生出一串全新的虚拟 sk-xxx 本地密钥。请将其发放给最终业务人员或填入聊天工具，真实的上游密钥则被永远雪藏在数据库保险箱内，达成绝对安全。

第四步：连接客户端体验丝滑交互
配置大功告成，现在请打开您的任何一款 AI 应用平台（如 Cursor 编辑器、Chatbox、NextChat 等）：

1. 寻找配置页面，将网络 接口地址 (Base URL) 篡改为您的专属聚合 AI 代理网址，例如：http://127.0.0.1:3000/v1。
2. 将刚刚签发的那串虚拟 API Key 填入身份验证栏。
3. 您可以毫无顾忌地开启连续对话，所有的繁琐调度与失败接管工作都已被聚合AI默默承担。

三、查阅并利用系统审计监测大屏
系统的“性能看板”对于长期维护价值巨大。在总览仪表盘，系统整理了近 31 天全景图谱，直观显示您的全域请求成功率、单日 Token 吞吐峰值和消耗成本预估走向。
如果您接到用户反馈“最近 AI 回答很慢”，可立刻进入系统特设的**“性能监控”**面板。该面板借助强大的 Echarts 统计底层逻辑，精准剖析各请求队列中“首 Token 获取耗时”和“总对话生成耗时”的极值与均线走向。您可以通过此数据准确研判是上游模型厂商拥堵，还是配置的网络代理节点存在高延迟，从而针对性实施维护调优。

应用场景

1. 企业研发团队内部大模型资源统筹分发
   在中小研发团队中，通常只采买了极少量的企业级大额度 API Key。如果将原文 Key 四处分发，极易因成员意外泄露造成严重损失，且无法追责滥用来源。通过聚合 AI 构建防火墙，管理员可为主账户建立统一资源池，并按小组或具体员工派发细粒度权限的子密钥，既屏蔽了原始凭据的泄露风险，也能借由强大的数据仪表盘统计不同业务线的开销额度。
2. 重度个人开发者保证工具的高可用心流
   面对极其依赖代码联想补全插件和第三方聊天客户端的独立开发者，网络超时或官方单账号触发严苛的流控限制会严重打乱开发心流。利用该系统的多账户并发与失败自动切换特性，将数个含有低额度或免费额度的副账号同时挂载入同一个调用组。当主账号额度告罄或短时限流时，调度引擎会在毫秒级切换备用池继续回答，保障前端永远在线。
3. 小型外包工作室的项目精准账目核算
   工作室在为多位不同甲方开发或运维 AI 对话机器人、智能客服体时，常常苦恼于一笔糊涂账。通过在聚合 AI 平台为每一个外包项目分配隔离的分组与独立虚拟 Key，工作室技术负责人能够从后台原始审计日志中一键调出指定项目在指定周期的 Token 调用流水和等效美元花费，实现清晰规范的甲乙方成本核销。

QA

1. 聚合 AI 未来支持接入非 OpenAI 的国产大模型吗？
   本系统当前的战略焦点是将基于 OpenAI 协议的交互中转与轻量调度做到极致，因此主要支持 OpenAI 兼容 API (/v1)。但从系统整体代码架构角度，作者已预留了良好的供应商扩展接口空间（Provider 机制），不排除在未来的维护更新中逐步拓展对国内其他闭源生态模型的平滑适配支持。
2. 我的核心 API 密钥托管在这套系统里，安全性有保障吗？
   您可以绝对放心。聚合 AI 在架构设计初衷上就摒弃了所有的云端依赖与外部通信。系统的数据储存使用的是完全本地化读写的 SQLite 文件数据库（物理存放在代码同级 backend/data/ 目录下）。只要您的服务器权限严密、不将敏感目录挂载至外网，您配置的所有高价值密钥、聊天调用记录和数据图表只会安静地躺在您的私有硬盘中。
3. 聚合 AI 如何化解偶尔出现的“网络代理超时”或“模型高并发崩溃”现象？
   系统具备极为智能的异常熔断与动态降级处理机制。当发生因上游节点封锁引起的错误或模型生成异常时，聚合AI的后端网关不会立刻向用户的聊天窗口返回报错红字，而是会在底层将该故障账号标记为“冷却期”，并将其无感剥离出调度轮询池。随后系统瞬间在剩余的健康账户组内继续重新请求该次对话，彻底把服务波动阻挡在系统内部，实现外部的无感稳定。
4. 我需要准备一台很高配置的服务器来运行它吗？
   不需要。系统的设计理念是极简的轻量化中台，专门砍掉了常规商业网关厚重的 Redis 缓存组件与 Kafka 消息队列，仅凭借高效的 Node.js 异步 I/O 及精简的 SQLite 底层并发读写。对于绝大部分单体开发者及几十人规模的小微团队而言，一台基础家用主机、树莓派或者是配置极低的轻量级云服务器（如 1核2G）便足以支撑高并发的流式请求转储与日志审计工作。