# gemini-fastapi-project

**Repository Path**: aylerh/gemini-fastapi-project

## Basic Information

- **Project Name**: gemini-fastapi-project
- **Description**: 功能；（1）imagen4的fastapi化；（2） tts的的fastapi化-区分男女；（3）实时语音对话-返回文字；（4）上传文件到google drive云盘并返回直链；
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-19
- **Last Updated**: 2026-05-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Gemini Creative Studio (Gemini 智能创意实验室)

这是一个基于 **FastAPI + Docker Compose** 构建的高性能、极简、美观的生成式 AI 服务平台。它集成了 Google 最新的 **Gemini 2.5/3.1** 和 **Imagen 4** 系列模型，向用户提供图像生成 (Text-to-Image) 和高质量语音合成 (Text-to-Speech, TTS) 的双重核心功能。

---
## 缺点
imagen4：free tier的API 端没有免费额度。通过代码调用 API。起始即收费，价格固定为 $0.04 / 张;

## 页面样式

### 主页

![1](./images/1.png)

### Google Drive 本地文件一键分享器
![4](./images/4.png)

## 🚀 项目解决的痛点 (Pain Points Solved)

1. **复杂 API 调用的封装瓶颈**：
   Google 的最新 `google-genai` SDK 在进行多模态交互和音频输出时，返回的是底层的 PCM 原始数据。本项目在后端优雅地将其封装并实时合成为符合浏览器 HTML5 标准播放的 **24kHz 16-bit Mono WAV 容器音频**，免去了前端复杂的编解码处理。
2. **高保真的本地多模态环境搭建**：
   通过 Docker Compose 实现一键打包与快速分发。内置**清华源加速优化**的 Docker 镜像构建，多阶段编译隔离开发与生产依赖，确保在本地及容器云上无缝切换。
3. **沉浸式高档用户体验**：
   不同于普通简陋的后台接口，本项目为开发者和体验者打造了一个**毛玻璃暗黑风 (Glassmorphism Dashboard)** 的高画质动态展示台，包含实时波形模拟器、渐进加载状态、实时 Toast 通知系统，提供极致的视觉与感官交互。
4. **实时语音对话的极低延迟与打断（Barge-in）控制**：
   普通 REST API 语音调用延迟高，且不支持对话打断。本项目集成了最新 **Gemini Multimodal Live API**，通过双向 WebSocket 长连接将延迟缩短至百毫秒级；前端基于 Web Audio 实现了顺滑的 PCM 音频包排队播放器与打断机制，支持在 Gemini 说话时随时用人声打断，表现出与真实人类一模一样的对话体验。
5. **智能应对浏览器麦克风的安全上下文限制 (IP vs localhost)**：
   现代浏览器因安全策略，会默认拦截非安全域名（如 HTTP IP 访问 `127.0.0.1:8046`）的录音权限，导致麦克风调用失败。本项目智能检测这一痛点，在检测到 IP 访问时加载**主动式紫色毛玻璃警告框**，并提供**一键切换到 localhost 访问**按钮、锁 🔒 图标解锁指南和 Chrome Flags 强载指令，极大降低了用户的使用门槛，五秒内扫清设备阻碍。

---

## 🛠️ 技术栈 (Tech Stack)

* **核心框架**：`FastAPI (Python 3.12)` - 异步高并发、极轻量、内建 Pydantic V2 校验。
* **双向低延迟长连接 (WebSockets)**：在 FastAPI 中集成了多模态代理路由 `/ws/live`。通过双向持久化 WebSocket 长连接向 Google Multimodal Live API 端点建立透明隧道，极低延迟双向传输控制帧与 PCM 音频流。
* **AI 核心**：`google-genai` (Google 官方最新统一大模型 SDK) - 连接 **Imagen 4.0** (图像生成)、**Gemini 3.1-Flash-Live** 和 **Gemini 2.5-Flash-Audio**。
* **高精重采样与编解码 (Audio Resampling & Processing)**：
  * **前端实时降频**：自研客户端重采样模块，将 Web Audio API 捕获的原始麦克风输入流（通常为 44.1kHz 或 48kHz）通过线性插值算法**重采样降频为标准 16kHz Mono 16-bit PCM** 字节流并发送，节省带宽，保证极佳的交互连通率。
  * **后端离线封装**：Python 内置 `wave` 模块 - 原始 16-bit PCM little-endian 字节流转标准 WAV 音频容器。
* **前端高级视听系统 (Web Audio & HTML5 Canvas)**：
  * **发光 Orb 粒子环波形**：基于 HTML5 Canvas 和数学正弦/随机波动算法自研绘制了三波段发光粒子 Orb 能量球，随着录音/播放输入电平动态进行呼吸与粒子炸裂膨胀，提供超凡的实时语音律动体验。
  * **排队缓存播放器**：利用 Web Audio API 建立自研低延迟 PCM 缓冲队列，自动管理分包到达的 24kHz 音频流，实现无缝连续播放，并保障随时收到 `interrupted` (VAD 打断指令) 时零延迟重置清空缓冲。
* **容器化与部署**：**多阶段构建 Dockerfile** (`python:3.12-slim` 基础镜像，集成 `APT` 与 `Pip` 清华国内源镜像加速) + **Docker Compose v2** 挂载卷持久化。

---

## 📂 项目结构 (Project Directory Structure)

```text
gemini-fastapi-project/
├── app/
│   ├── templates/
│   │   └── index.html        # 毛玻璃暗黑风创意实验室 Dashboard
│   ├── __init__.py           # 包构造函数
│   ├── config.py             # 基于 pydantic-settings 的配置管理器
│   └── main.py               # 核心 API 路由与 Gemini API 调用核心逻辑
├── docs/
│   ├── 实现.md               # 需求与规范文档
│   └── 优化.md               # 性能、语音和未来的优化指南
├── .env                      # 端口、持久化卷路径、API 密钥等本地配置
├── .gitignore                # 忽略本地临时介质和机密凭证
├── Dockerfile                # 多阶段加速构建 Dockerfile
├── docker-compose.yml        # 一键拉起容器的编排文件
└── requirements.txt          # Python 精简依赖列表
```

---

## 🔧 快速启动指引 (Quick Start)

### 1. 配置环境变量

在项目根目录下创建 `.env` 文件：

```env
INNER_PORT=8046
OUTER_PORT=8046
DATA_PATH_HOST=H:/docker-data/gemini-fastapi-project-data/data
GEMINI_API_KEY=your_gemini_api_key_here

# Google Drive OAuth 凭证配置 (如需启用云端上传与本地文件分享)
GOOGLE_CLIENT_ID=your_google_client_id_here
GOOGLE_CLIENT_SECRET=your_google_client_secret_here
```

> 💡 **提示**：`DATA_PATH_HOST` 为本地主机的目录，用于挂载容器内的持久化存储 `/app/data`，生成的图片与语音文件将实时同步至该目录下。

---

## ☁️ Google Drive 云端同步与一键分享 (Google Drive Integration)

平台深度集成了 **Google Drive API v3**，为用户提供一键备份和公开分享本地或 AI 生成媒体文件的极致体验：

### 1. 核心功能描述
* **AI 媒体一键存盘**：支持在 Imagen 生成图片、TTS 生成音频后，直接点击输出结果视窗中的“保存至 Google Drive”悬浮按钮将其自动备份至云端。
* **本地文件一键分享器**：在页面底部提供极美**玻璃态拖拽区域 (Drop Zone)**，可直接拖入或选择任意本地文件（图片、音频、PDF、压缩包等）秒速同步至云盘中。
* **公开直链自动捕获**：上传完成后，后端自动利用官方 API 将文件权限设为 **“任何人可读 (reader)”**，并实时返回**网页共享链接**、**文件下载直链**和即插即用的 **Markdown 插入码**，一键复制，彻底打通写作、笔记与发布的外链生产链路！

### 2. OAuth 2.0 配置步骤
1. 访问 [Google Cloud Console API Credentials](https://console.cloud.google.com/apis/credentials)。
2. 创建一个类型为 **“Web application”** 的 OAuth Client ID。
3. 在 **“已授权的重定向 URI” (Authorized redirect URIs)** 中，填入容器的回调接收端点：
   `http://localhost:8046/api/gdrive-callback`
4. 复制生成的 Client ID 和 Client Secret，并填入项目根目录的 `.env` 配置文件中。
5. 运行以下启动指令重建容器，点击底部卡片的“使用 Google 账号快捷登录授权”大按钮完成扫码即可！

### 3. 智能上传报错与一键修复引导机制 (Interactive Troubleshooting)
如果在上传或连通测试时遇到任何 Google 云端限制，前端会自动触发**极具设计感的玻璃态交互引导弹窗**，帮助您一键修复环境阻碍：
* **API 未开启 (HttpError 403 - accessNotConfigured)**：
  * **报错表现**：接口提示 `Google Drive API has not been used in project... before or it is disabled`。
  * **一键修复提示**：前端弹窗会自动捕获并提取出**您专属的 API 开启链接**，提供高亮蓝色大按钮 **「① 前往开启 Google Drive API」**。您只需在新页面中点击“启用 (ENABLE)”，并回到网页点击 **「② 我已启用，重新尝试上传」** 即可瞬间打通，**完全不需要重新扫码或更改配置**！
* **授权失效 (invalid_grant / token.json 异常)**：
  * **报错表现**：登录凭证到期、过期或权限被手动撤销。
  * **一键修复提示**：弹窗会智能解析并浮现紫色警告框，提供 **「① 断开并重置授权连接」** 按钮，一键抹除容器内失效的 token，刷新页面引导您极速重新扫码授权登录。
* **通用开发者调试面板**：
  * 针对其他非预期错误，弹窗会以极其炫酷的暗色代码框形式渲染**最底层的完整 API Error Traceback 信息**，并提供重新尝试上传快捷入口，极大地方便了开发者的本地调试与部署验证。

---

## 🔍 云端检索舱 (Cloud Image Search Hub)

项目创新集成了 **云端检索舱 (Cloud Image Search Hub)** 功能，支持用户通过输入任意自然语言，让 AI 引擎实时联网深度检索符合要求的互联网高清大图。

### 1. 核心亮点与特色 (Key Highlights)
* **大模型联网搜索工具 (Google Search Grounding)**：默认使用 **Gemini 2.5** 系列联网搜索工具。通过 Google 的实时搜索引擎获取互联网最新的图文与多媒体资源，解决传统 AI 无法提供最新或特定网图链接的痛点。
* **渐进式玻璃态骨架屏加载 (Skeleton Loading UI)**：在检索期间，页面会展示精美的发光玻璃态骨架卡片（Skeleton Grid），带给用户顺滑、高端、极具仪式感的等待交互体验。
* **高阶容错与多模型降级链 (Self-Healing Fallback Chain)**：为了应对大模型 API 偶发的 503 超载或 429 频控限制，后端独创了自愈降级机制。当首选模型不可用或返回空时，会自动按 `gemini-2.5-flash` ➡️ `gemini-2.0-flash` ➡️ `gemini-2.0-flash-lite` 链条进行指数避让（Backoff）和自动重试，并在前端显示友好重试提示。
* **一键打包下载全部 ZIP (Batch ZIP Download)**：提供并行化多线程下载器，秒级拉取所有检索到的高清大图，并在内存中进行 ZIP 打包归档，实现真正的一键批量下载。
* **二次流转集成**：检索到的图片卡片提供「一键保存到本地服务器 DATA 目录」和「一键直传 Google Drive 并生成公开外链」的双重操作入口，完美融入内容创作者的工作流。

---

### 2. 通过 PowerShell 一键构建启动


在 Windows 11/10 PowerShell 下执行以下指令：

```powershell
# 拉起并构建镜像
docker compose down;docker compose up -d --build
```

运行成功后，访问以下地址体验：
* **创意实验室 UI 界面**：`http://localhost:8046/`
* **API 接口健康检查**：`http://localhost:8046/api/health`

---

## 🧩 核心接口设计 (Core Endpoints)

### 1. 图像生成 [POST] `/api/generate-image`
* **模型支持**：`imagen-4.0-generate-001` (标准), `imagen-4.0-fast-generate-001` (快速), `imagen-4.0-ultra-generate-001` (超高清)
* **参数样例**：
  ```json
  {
    "prompt": "A futuristic city with flying cars at sunset, photorealistic 8k",
    "aspect_ratio": "16:9",
    "model": "imagen-4.0-generate-001"
  }
  ```

### 2. 语音合成 [POST] `/api/generate-tts`
* **模型支持**：`gemini-3.1-flash-tts-preview`, `gemini-2.5-flash-preview-tts`
* **声线库**：
  * **男声**：`Charon` (沉稳/默认), `Puck` (轻快), `Fenrir` (温暖)
  * **女声**：`Kore` (中性/专业/默认), `Aoede` (温柔)
* **参数样例**：
  ```json
  {
    "text": "Hello world! This is a test of the Gemini Creative Studio.",
    "gender": "male",
    "voice_name": "Charon",
    "model": "gemini-3.1-flash-tts-preview"
  }
  ```

## 🎨 核心技术解析 (Architecture Breakdown)

### 1. 为什么选择 `response_modalities=["AUDIO"]`？
传统的语音合成 (TTS) 需要依赖第三方封闭云 API（如微软 Azure TTS 或阿里语音），存在情感死板、合成限制多等问题。
Gemini 2.5/3.1 Flash 原生支持**端到端多模态音频生成**。通过指定返回媒介为 `["AUDIO"]`，模型能够根据输入的上下文，**直接理解文本中的情感语气**（如括号内的情绪提示词 `[excited]` 或 `[sigh]`），生成极其自然、带有人类真实呼吸声和语调起伏的音频。

### 2. PCM 原始流转换为标准 WAV 音频
Gemini API 返回的音频片段是**原始 PCM (Pulse Code Modulation) 字节流**：
* **采样率**：`24000 Hz`
* **通道数**：`1 (Mono, 单声道)`
* **位深**：`16-bit` (Signed little-endian)

由于原始 PCM 字节流没有音频头信息，浏览器 `audio` 标签以及大多数播放器无法直接播放。
本项目在后端利用 Python 标准库 `wave`，实时在内存/磁盘中构造 **WAV 容器头文件 (WAV Header)**，封装成标准的 `RIFF/WAVE` 结构。

```python
with wave.open(filepath, "wb") as wf:
    wf.setnchannels(1)        # 1 - Mono
    wf.setsampwidth(2)        # 2 bytes - 16-bit
    wf.setframerate(24000)    # 采样率 24kHz
    wf.writeframes(audio_bytes)
```
此方法**无需引入 ffmpeg 等庞大的外部二进制依赖**，纯 Python 极速处理，单次合成开销小于 5ms，极其轻量！

---

## 📈 性能与系统优化路径 (Future Optimizations)

### 1. 引入异步任务队列 (Celery + Redis)
目前，图像和音频生成均是在 FastAPI 路由函数中通过协程同步阻塞调用 Google GenAI。虽然使用了异步编程，但面对极高并发时，容易造成等待积压。
* **改进建议**：
  将 `/api/generate-image` 和 `/api/generate-tts` 重构为**异步后台任务模式**：
  1. 用户发起生成请求，后端快速生成一个任务 ID (Task ID) 并返回 `202 Accepted`。
  2. Celery 异步工作节点 (Worker) 从 Redis 队列中读取任务，与 Google API 通信并保存媒体文件。
  3. 前端通过 **WebSocket** 或 **轮询 (SSE/Polling)** 获取任务执行状态与资源 URL，极大提高大并发下系统的稳定性和韧性。

### 2. 边缘缓存优化 (FastAPI-Cache)
对于重复的图像 prompt 或完全相同的 TTS 文本，可以采用 Redis 进行数据哈希缓存。
* **改进建议**：
  引入 `fastapi-cache`，对生成请求的 payload（prompt、voice_name、model）进行 MD5 签名：
  * 如果缓存中存在，直接返回已保存的 `image_url` 或 `audio_url`。
  * 这样既减少了对 Google Gemini API 额度的无谓消耗，又将响应延迟直接降低至 1ms 级别。

### 3. 前端音频流式播放与波形绘制优化
当前前端使用定时器和 CSS 关键帧动画模拟音频播放时的波形跳动。
* **改进建议**：
  引入 HTML5 的 **Web Audio API** 结合 `AudioContext` 和 `AnalyserNode`，实时读取生成音频的频率数据，在 HTML5 `canvas` 上通过频率数组精确、优雅地渲染出随声音音调起伏而真实波动的可视化音轨。