All-in-one Model Console WebUI，以 Gemini 原生能力为主，同时支持 OpenAI 兼容标准聊天 API
AMC WebUI 是一款基于 React 18 的 All-in-one Model Console WebUI，主打 Google Gemini 原生能力，并提供额外的 OpenAI 兼容标准聊天模式。项目坚持 Local-First 原则：聊天数据默认存储于浏览器 IndexedDB，在保障隐私的同时提供流畅体验；同时支持独立后端部署模式，用于服务端托管 Gemini 密钥与代理请求。
当前仓库围绕 Vite + React SPA 作为唯一主线构建形态：
- 标准模式：本地通过 Vite 开发 / 构建，适合日常开发与静态部署
- Docker 部署模式：
web + api双服务部署，普通 Gemini 请求走/api/gemini/*，Live API 由浏览器使用本地 key 直连 - 静态前端 + 独立 API 模式：前端部署到 Pages/CDN，后端单独托管 Node API 服务
- 项目的主能力路径，适用于 Thinking、Live API、Gemini Files API、Deep Search、Google Search、代码执行、图片生成等 Gemini 专属能力
- 可结合 AMC 自带的 Gemini 代理与服务端托管密钥能力使用
- 面向 标准聊天 的兼容路径，使用独立的 API Key、Base URL 和模型列表
- 请求会发送到
POST {Base URL}/chat/completions，适用于 OpenAI 官方接口、Gemini 的 OpenAI 兼容端点，或其他兼容chat/completions的服务 - 支持普通响应与流式响应，并保留系统提示词、
temperature、top_p等通用聊天参数
- OpenAI 兼容模式 不会覆盖 Gemini 原生配置；两套 Key 分开保存，模型列表也独立维护
- OpenAI 兼容模式当前 不走 Gemini 原生工具链；README 中提到的 Gemini 专属能力，仍以 Gemini 原生模式为准
- OpenAI 兼容 Base URL 应填写到接口根路径，例如
https://api.openai.com/v1；应用会自动补上/chat/completions
- 支持 Gemini 3.0 / 3.1 / 2.5 系列模型的思维链可视化
- 可设置 Token 预算 或 推理等级 (Minimal / Low / Medium / High)
- 实时查看 AI 的逻辑演算过程
- 双向实时流式交互，支持语音通话
- 屏幕共享与视觉识别
- 音频可视化 (AudioWorklet API)
- 代码块自动识别并渲染为交互式 HTML 预览（自动全屏）
- 支持 ECharts 图表渲染
- 支持 Mermaid 流程图与 Graphviz 图渲染
- 自动 Canvas 生成模式（可配置触发模型）
- 浏览器端音频预处理与压缩流程，尽量降低音频上传的 Token 与带宽消耗
- 支持 ZIP / 文件夹拖入，自动解析代码库结构
- 支持图片、PDF、视频、音频、文本等多种文件类型
- 可配置各文件类型使用 Gemini Files API 还是直接 Base64 上传
- 文件分辨率可调（Low / Medium / High / Ultra）
- 深度搜索：聚合 Google Search，自动规划搜索任务并提供精准引用
- URL 上下文：自动抓取 URL 内容作为对话上下文
- 本地 Python 沙箱：基于 Pyodide (WASM) 的浏览器端 Python 运行环境
- 预装 numpy、pandas、matplotlib、scipy、scikit-learn 等科学计算库
- 自动检测代码依赖并安装
- 支持文件挂载与生成文件下载
- matplotlib 图表自动捕获输出
- TTS 语音合成：30+ 种语音可选
- 语音转录：支持多种 Gemini 模型进行语音转文字
- Imagen 4.0 图片生成：支持 Fast / Standard / Ultra 三档，可配置宽高比与尺寸
- 双 API 模式：支持在 Gemini 原生 与 OpenAI 兼容 两条请求路径之间切换
- 多 Key 轮询：Gemini 原生 Key 与 OpenAI 兼容 Key 均支持多 Key 轮询
- 配置隔离：OpenAI 兼容模式使用独立 Key、独立 Base URL、独立模型列表，不会污染 Gemini 设置
- Gemini API 代理：Gemini 原生模式支持通过 SDK 原生
baseUrl配置接入自定义 Gemini API 代理
- 支持中文 / 英文 / 跟随系统三种语言设置
- 覆盖所有 UI 组件（聊天、设置、侧边栏、快捷键等）
- 提供完整 Web App Manifest、Service Worker 与安装/更新提示
- 可安装为桌面/移动端应用，并支持离线打开应用 Shell
- 运行时接口请求保持网络优先，模型响应与同步能力仍需联网
- 支持画中画 (Picture-in-Picture) 模式
- 日志与用量页采用“严格精确”模式：只有在已存储字段足以精确还原官方费用时才显示价格
- 新生成的聊天、TTS、转写与部分图片生成请求会记录更完整的计费元数据
- 纯文本聊天请求会在本地补齐
TEXT -> TEXT模态证据，因此纯文本gemini-3.1-pro-preview、gemini-3-flash-preview与gemini-3.1-flash-lite-preview对话可显示价格 - 历史记录或缺少精确定价字段的请求会继续显示
—
- 基于 Web Locks API 的跨标签页数据同步
- 确保多标签页同时操作时数据一致性
- 内置快捷键系统，支持新建聊天、打开日志、切换模型、画中画等操作
- 所有快捷键均可自定义覆盖
- 5 个安全过滤类别：骚扰、仇恨言论、色情内容、危险内容、公民诚信
- 每个类别可独立配置过滤级别（OFF / None / High / Medium / Low）
- 内置 Onyx（暗色）、Pearl（亮色）主题
- 支持跟随系统主题自动切换
- 完整的聊天记录导入 / 导出
- 会话分组管理
- 会话搜索（标题 + 内容全文搜索）
- 开发者日志面板（API 调用监控、Token 用量统计）
# 克隆仓库
git clone https://github.com/yeahhe365/AMC-WebUI.git
cd AMC-WebUI
# 安装依赖
npm install
# 启动开发服务器
npm run dev访问 http://localhost:5173，在 设置 -> API 配置 中填入你的 Gemini API Key。
除了在界面中手动配置，也可在根目录创建 .env.local（仅前端开发模式使用）：
GEMINI_API_KEY=your_api_key_here
VITE_OPENAI_API_KEY=your_openai_compatible_key_here如需切换到 OpenAI 兼容模式：
- 进入 设置 -> API 配置，将 API 模式切换为 OpenAI 兼容
- 填写 OpenAI 兼容 API Key，或在
.env.local中预置VITE_OPENAI_API_KEY - 填写 OpenAI 兼容 Base URL，例如
https://api.openai.com/v1 - 进入 设置 -> 模型，选择或编辑该模式下独立维护的模型列表
示例 Base URL：
- OpenAI 官方：
https://api.openai.com/v1 - Gemini OpenAI 兼容端点：
https://generativelanguage.googleapis.com/v1beta/openai - 其他兼容服务：填写其
chat/completions所属的/v1或等价根路径
项目包含双容器部署：
web：Nginx 托管前端静态资源，并反向代理/api/*到api服务api：Node 服务，提供/api/gemini/*代理
运行方式：
# 在仓库根目录
npm run build
docker compose up -d --build默认访问 http://localhost:8080。如需关闭后台运行可执行 docker compose down。
说明：
- Docker 默认是 BYOK 自用模式：启动后在 设置 -> API 配置 填入 Gemini API Key 即可使用普通聊天与 Live API，不需要在
.env或docker-compose.yml里配置GEMINI_API_KEY。 web镜像默认直接打包宿主机已生成的dist/，不再在容器内执行前端生产构建。- 修改前端代码后，请先重新执行
npm run build，再执行docker compose up -d --build。
⚠️ 安全边界说明 当前web + api代理方案定位为 受信任/自托管环境（trusted self-hosted deployment）。 默认 BYOK 模式会使用浏览器设置里的 API Key 发起请求；它本身并不足以作为公开互联网下“无鉴权多用户 API 网关”。 若要对公网开放，请额外引入鉴权、配额/限流、滥用防护、审计与租户隔离等能力。
部署时请区分两类配置：
| 变量名 | 用途 | 公开性 | 默认值 |
|---|---|---|---|
GEMINI_API_KEY |
可选的服务端托管 Gemini API Key（配置后优先于浏览器设置 key） | 仅服务端 | 空 |
PORT |
api 服务监听端口 |
仅服务端 | 3001 |
GEMINI_API_BASE |
Gemini 上游地址（代理目标） | 仅服务端 | https://generativelanguage.googleapis.com |
ALLOWED_ORIGINS |
逗号分隔 CORS 白名单（跨域部署时使用） | 仅服务端 | 空 |
RUNTIME_SERVER_MANAGED_API |
前端默认启用服务端托管 API | 公开运行时配置 | false |
RUNTIME_USE_CUSTOM_API_CONFIG |
前端默认启用“自定义 API 配置” | 公开运行时配置 | true |
RUNTIME_USE_API_PROXY |
前端默认启用 API 代理 | 公开运行时配置 | true |
RUNTIME_API_PROXY_URL |
前端默认 Gemini 代理地址 | 公开运行时配置 | /api/gemini |
说明：
- 上述
RUNTIME_*会在容器启动时写入runtime-config.js，可被浏览器读取，因此只能放“可公开”信息。 - 默认 BYOK 模式只需要在设置界面填写 API Key：普通 Gemini 代理会使用浏览器请求携带的 key；Live API 会使用浏览器本地 key 直接建立官方 Live WebSocket 连接，不再经过 AMC 后端换取临时 token。
- 如需服务端统一托管普通 Gemini 请求的 key，可配置
GEMINI_API_KEY并将RUNTIME_SERVER_MANAGED_API=true；Live API 仍需要浏览器中可用的 API Key。 - OpenAI 兼容模式当前不读取
RUNTIME_API_PROXY_URL、RUNTIME_USE_API_PROXY或RUNTIME_SERVER_MANAGED_API；它会直接使用设置里的 OpenAI 兼容 Base URL 和独立 Key 发起chat/completions请求。如需走你自己的网关，请直接把该网关地址填为 OpenAI 兼容 Base URL。 - 浏览器本地 key 适合自用/可信部署。它不会因为“保存在本地”而变成服务器密钥，同一浏览器上下文中的脚本、扩展、XSS 或设备风险仍可能读取它。
- 前端在部署时默认只依赖后端端点：
/api/gemini/*；Live API 从浏览器直连官方 Live 服务。
可将前端部署在 Cloudflare Pages，同时将 server/ 独立部署到任意 Node 运行环境（VM、容器平台、Serverless 容器等）：
- 前端（Pages）执行标准构建并发布
dist：
npm run build- 后端（独立服务）构建并启动：
npm run build:api
npm run start:api- 在前端运行时配置中将以下值指向后端公开地址（示例）：
RUNTIME_API_PROXY_URL=https://your-api.example.com/api/gemini
- 如需服务端统一托管普通 Gemini 请求的密钥，在后端环境设置
GEMINI_API_KEY；如果使用 BYOK，可不设置该变量。跨域部署时按需配置ALLOWED_ORIGINS=https://your-pages-domain.pages.dev。Live API 不使用独立 API 服务的 token 端点，而是从浏览器直连。
补充：
server/当前承载的是 Gemini 原生代理链路；OpenAI 兼容模式默认不会经过这个 Node API 服务- 如果你希望 OpenAI 兼容模式也走自建网关，请把该网关的兼容 Base URL 直接填到前端设置中
如果你希望通过 Google AI Studio 网页端账号提供 API 来源，也可以尝试将 AIStudioToAPI 部署为第三方 Gemini 兼容后端。它提供 Gemini Native API 格式的 /v1beta/* 接口，可作为 AMC WebUI 的自定义 API 代理地址。
示例：
RUNTIME_API_PROXY_URL=https://your-aistudio-to-api.example.com/v1beta
在界面中也可以进入 设置 -> API 配置，启用“自定义 API 配置 / API 代理”，并填入 AIStudioToAPI 的 Gemini 兼容 Base URL（例如 http://localhost:7860/v1beta）。AMC WebUI 中填写的 API Key 应与 AIStudioToAPI 部署时配置的 API_KEYS 对应。
注意：AIStudioToAPI 属于第三方项目，请自行评估账号登录、鉴权、限流与公网暴露风险；它可替代普通 Gemini API 代理来源。AMC WebUI 的 Live API 当前采用浏览器直连官方 Live 服务，不再依赖 AMC 后端 token 端点。
npm run build # 构建生产版本
npm run preview # 本地预览构建结果npm run typecheck
npm run lint
npm run test
npm run knip
npm run build
# 或者一次性执行
npm run verify如果只想验证 Gemini Code Execution 相关链路，可以执行：
npm run test:code-execution这个命令覆盖：
- 文本 / CSV / 代码文件的 MIME 与上传策略
- Code Execution 请求构造与多轮历史回放
- 流式
thoughtSignature保留 - Live API 中
codeExecutionResult.output展示
如果你想用真实 GEMINI_API_KEY 做一次手动联调检查，也可以执行：
GEMINI_API_KEY=your_key_here npm run verify:code-execution:api可选环境变量：
CODE_EXECUTION_MODEL：覆盖默认模型（默认gemini-2.5-flash）
这个脚本会：
- 上传一个临时 CSV 文件，并显式使用
text/csv - 发起一次启用
codeExecution的请求 - 检查响应里是否同时出现
executableCode和codeExecutionResult - 复用第一轮完整模型内容发起第二轮追问，验证多轮历史可继续使用
| 层级 | 技术栈 |
|---|---|
| 核心框架 | React 18 + TypeScript 5.5 + Vite 5 |
| 样式方案 | Tailwind CSS 4 + CSS 变量主题系统 |
| 持久化层 | 原生 IndexedDB（db.ts 封装），支持 Web Locks 跨标签写锁 |
| Gemini SDK | @google/genai 1.2+，含流式 / 非流式消息、文件上传、图片生成、TTS、转录 |
| 音频引擎 | AudioWorklet API（实时流处理）+ 浏览器端 Worker 音频预处理 / 压缩流程 |
| 渲染引擎 | React-Markdown + KaTeX (公式) + Highlight.js (代码高亮) + Mermaid.js + Graphviz (viz.js) |
| Python 沙箱 | Pyodide (WASM)，Web Worker 内执行，预装科学计算库 |
| API 代理 | 基于 @google/genai SDK httpOptions.baseUrl 的 Gemini API 代理配置 |
| PWA | Web App Manifest + beforeinstallprompt / appinstalled 安装事件处理 |
| 部署形态 | Vite 标准构建 / Docker Compose（web+api）/ Cloudflare Pages + 独立 API |
| 生产部署若采用服务端托管普通 Gemini API，前端默认请求后端端点： |
/api/gemini/*
Live API 默认由浏览器使用本地 API Key 直连官方 Live 服务。
AMC-WebUI/
├── src/ # 前端应用源码（Vite SPA）
│ ├── components/ # UI 组件（chat / message / layout / settings / modals 等）
│ ├── hooks/ # 业务 hooks（app / chat / chat-input / data-management / live-api / ui）
│ ├── services/ # Gemini / Pyodide / API / 日志等基础设施
│ ├── stores/ # Zustand 状态（chat / settings / ui）
│ ├── utils/ # 导出、会话、IndexedDB、Markdown、文件处理等工具
│ ├── runtime/ # 运行时配置读取与公开配置映射
│ ├── contexts/ # I18n / WindowContext 等上下文
│ ├── constants/ # 模型、提示词、快捷键、主题等常量
│ ├── types/ # TypeScript 类型定义
│ ├── styles/ # 全局样式、动画、Markdown 样式
│ ├── App.tsx # 应用入口组件
│ └── index.tsx # React 挂载入口
├── server/ # 独立 Node API（/api/gemini/*）
│ ├── src/
│ └── tsconfig.json
├── public/ # 静态资源与 runtime-config.js 模板
├── e2e/ # Playwright 端到端测试
├── docs/ # 计划、规范与文档
├── docker/ # 部署辅助脚本
├── vite.config.ts # Vite 配置（React、静态复制、手工分包）
├── playwright.config.ts # E2E 配置
├── vitest.config.ts # 单元/集成测试配置
├── eslint.config.js # ESLint 配置
├── knip.json # 未使用文件/导出分析配置
├── package.json # 前端依赖与脚本
└── docker-compose.yml # web + api 双服务部署入口
| 类型 | 模型 |
|---|---|
| Gemini 3.x | gemini-3-flash-preview, gemini-3.1-flash-live-preview, gemini-3.1-flash-lite-preview, gemini-3.1-pro-preview |
| Robotics | gemini-robotics-er-1.6-preview |
| Gemma 4 | gemma-4-31b-it, gemma-4-26b-a4b-it |
| Imagen 4.0 | imagen-4.0-fast-generate-001, imagen-4.0-generate-001, imagen-4.0-ultra-generate-001 |
| 图片生成 | gemini-2.5-flash-image, gemini-3-pro-image-preview, gemini-3.1-flash-image-preview |
| TTS | gemini-3.1-flash-tts-preview (30+ 种语音) |
我们欢迎任何形式的贡献！
- 报告问题：提交 GitHub Issue
- 代码贡献：Fork 仓库 -> 创建特性分支 -> 提交 Pull Request
- 支持作者：点个 Star 或前往 爱发电 支持持续开发
- Linux.do：也称 L 站，是一个活跃的中文技术社区，围绕 AI、软件开发、资源分享与前沿资讯展开讨论；社区愿景是“新的理想型社区”，社区文化是“真诚、友善、团结、专业，共建你我引以为荣之社区”。
Developed with ❤️ by yeahhe365