这真是个疯狂的消息！终于可以…哎抱歉，X 没有实时翻译功能，快去关注 @thorwebdev 学习如何用 Gemini 3.5 构建你自己的实时翻译应用吧！** 代码地址：https://github.com/google-gemini/gemini-live-translate-livekit… 文档链接：https://ai.google.dev/gemini-api/docs/live-api/live-translate…

google-gemini/gemini-live-translate-livekit

来源：https://github.com/google-gemini/gemini-live-translate-livekit

实时翻译

基于 Gemini Live API 和 LiveKit 的实时广播翻译功能。

组织者对着麦克风讲话——听众选择语言即可收听实时 AI 翻译。每种语言都会启动一个独立的 Gemini Live API 会话，所有请求该语言的听众共享此会话。

工作原理

`` 组织者 → 发布音频 → LiveKit 房间 ↓ TranslationBridge（按语言划分） 以机器人身份加入房间，订阅组织者音频 ↓ Gemini Live API（translationConfig） directionalTranslation → targetLanguageCode ↓ 翻译后的音频重新发布至 LiveKit ↓ 听众 → 订阅 translator-{lang} 音频轨道

## 前提条件

- Node.js 18+
- Gemini API 密钥（https://aistudio.google.com/apikey）
- 运行中的 LiveKit 服务器（本地或云端）

## 设置

### 1. 安装依赖

``bash
npm install

2. 启动本地 LiveKit 服务器

最简单的方式是使用 Docker：

``bash docker run -d
–name livekit
-p 7880:7880
-p 7881:7881
-p 7882:7882/udp
-e LIVEKIT_KEYS=“devkey: secret”
livekit/livekit-server
–dev

或安装 LiveKit CLI 在本地运行：

``bash
# 安装（macOS）
brew update && brew install livekit

# 运行
livekit-server --dev --bind 0.0.0.0

默认开发密钥为 devkey / secret，与 .env.local 文件匹配。

3. 配置环境

编辑 .env.local：

``env LIVEKIT_API_KEY=devkey LIVEKIT_API_SECRET=secret LIVEKIT_URL=ws://localhost:7880 GEMINI_API_KEY=your-gemini-api-key-here BROADCAST_PASSWORD=optional-secure-password

### 4. 运行应用

``bash
npm run dev

打开 http://localhost:3000。

部署到 Cloud Run

我们建议部署到 Google Cloud Run，因为翻译桥是需要持久化容器和长时间请求支持的长期运行进程（涉及与 Gemini 和 LiveKit 的 WebSocket 连接）。

前提条件

• Google Cloud CLI（https://cloud.google.com/sdk/docs/install）（gcloud）
• LiveKit Cloud（https://cloud.livekit.io）账户（免费套餐：每月 50 参与者小时）

部署

首先在 Google Secret Manager 中创建密钥（从 .env.local 读取值）：

``bash source <(grep -v ‘^#’ .env.local | sed ‘s/^/export /’)

echo -n “GEMINI_API_KEY" | gcloud secrets create gemini-api-key --data-file=- echo -n "LIVEKIT_API_KEY” | gcloud secrets create livekit-api-key –data-file=- echo -n “$LIVEKIT_API_SECRET” | gcloud secrets create livekit-api-secret –data-file=-

然后部署：

``bash
gcloud run deploy live-translate \
  --source . \
  --region us-central1 \
  --allow-unauthenticated \
  --min-instances 0 \
  --max-instances 1 \
  --timeout 3600 \
  --no-cpu-throttling \
  --set-secrets "\
GEMINI_API_KEY=gemini-api-key:latest,\
LIVEKIT_API_KEY=livekit-api-key:latest,\
LIVEKIT_API_SECRET=livekit-api-secret:latest" \
  --set-env-vars "\
LIVEKIT_URL=wss://your-project.livekit.cloud"

后续部署（仅代码更改，保留现有密钥和环境变量）：

``bash gcloud run deploy live-translate –source . –region us-central1

关键设置：
- `--set-secrets` — 运行时从 Secret Manager 注入密钥（不会存储在镜像或 Cloud Run 配置中）
- `--min-instances 0` — 允许服务在非活跃时完全缩放至零以节省成本
- `--max-instances 1` — `TranslationSessionManager` 单例要求单实例运行
- `--timeout 3600` — 允许最长 1 小时的会话
- `--no-cpu-throttling` — 在请求间保持 CPU 分配（用于音频处理，仅在实例活跃时计费）

### 扩展与资源限制（来自现场活动的经验教训）

在运行高听众数量（例如 1000+ 并发用户）和多种活跃翻译语言（例如 20+ 种语言）的现场活动时，请特别注意以下资源和配额限制：

#### 1. Cloud Run CPU 和内存（OOM 保护）
* **问题：** `@livekit/rtc-node` SDK 运行原生 C++ WebRTC 客户端程序。每个活跃的翻译桥都会打开新的 PeerConnection 并管理实时音频编解码。这每种语言消耗约 20-30 MiB 内存和约 10% 的 vCPU 核心。
* **症状：** 如果内存超过默认的 512 MiB 限制，容器将立即因内存不足（OOM）错误崩溃，所有活跃听众将断开连接。
* **解决方案：** 对于 15-20 种活跃语言，分配至少 **4 个 vCPU 和 4 GiB 内存**（对于更大规模，最高可至 8 个 vCPU / 32 GiB）：
  ``bash
  gcloud run services update live-translate --cpu 4 --memory 4Gi --region us-central1
  ``

#### 2. 并发限制（防止“速率超限”）
* **问题：** Cloud Run 的默认并发限制为 80 个请求。如果 1000 个用户尝试在完全相同的瞬间加入/刷新页面（例如在分享链接时），多余的请求将溢出队列，Google 前端（GFE）将以纯文本 `Rate exceeded.` 错误拒绝它们。
* **解决方案：** 将容器上的请求并发数提高到最大值 **1000**：
  ``bash
  gcloud run services update live-translate --concurrency 1000 --region us-central1
  ``
  *（注意：一个 4 vCPU 的容器完全能够并发生成数千个 JWT 密钥，因为这是一个快速的 CPU 密码学操作）。*

#### 3. 提供商配额设置（Gemini 与 LiveKit）
* **Gemini API 密钥：** 您必须使用 **付费层级（层级 1-3）** 的 Google AI Studio API 密钥。免费层级对并发活跃 WebSocket 连接施加严格限制（通常为 3-5 个），这将导致在同时翻译多种语言时桥接断开或无法启动。
* **LiveKit Cloud：** LiveKit Cloud 的免费层级限制为 **100 个并发连接**。对于大规模受众，请确保您的 LiveKit Cloud 账户已升级到按使用量计费的付费计划（例如 **Ship** 或 **Scale** 层级），该计划解锁无限制的并发参与者。

#### 4. 自动缩放限制
由于此演示架构通过内存中的单例管理器（`TranslationSessionManager`）维持活跃翻译会话，**水平自动缩放必须锁定为 1 个实例**（`--max-instances 1`）。在没有数据库协调（例如 Redis）的情况下扩展到多个容器将导致多个重复的翻译机器人实例加入同一房间。

#### 5. 动态“缩放至零”和保活
* **问题：** 由于听众直接连接到 LiveKit，机器人通过出站连接传输音频，一个设置了 `--min-instances 0` 的容器在广播期间会收到恰好 0 个入站 HTTP 请求。默认情况下，Cloud Run 会认为容器处于空闲状态并在活动期间将其关闭。
* **解决方案：** 广播者客户端页面自然会每 3 秒查询活跃翻译状态端点（`/api/translate/status`）以监控听众。这种持续的入站轮询流量自然地使 Cloud Run 容器在整个广播期间保持温暖。
* **结果：** 您可以安全地以 `--min-instances 0` 部署，在应用空闲时完全不付费。容器在第一个请求时自动启动，在活动广播期间保持活跃，并在广播者离开 15 分钟后自动关闭。

## 安全与认证（可选）

### 1. 简单密码保护（仅广播者）
为保护广播/会话创建而不限制公开观看页面，您可以设置 `BROADCAST_PASSWORD` 环境变量。

- **本地开发**：在 `.env.local` 中添加 `BROADCAST_PASSWORD=your-secret-password`。
- **Cloud Run**：在 Google Secret Manager 中创建一个密钥，并使用 `--update-secrets` 将其绑定到您的服务：
  ``bash
  # 1. 在 Secret Manager 中创建密钥
  echo -n "your-secret-password" | gcloud secrets create broadcast-password --data-file=-

  # 2. 更新您的 Cloud Run 服务以将密钥挂载为环境变量
  gcloud run services update live-translate \
    --region=us-central1 \
    --update-secrets="BROADCAST_PASSWORD=broadcast-password:latest"
  ``

配置后，应用程序将在创建会话或访问广播页面前自动提示组织者输入密码。密码会缓存到主机的 `sessionStorage` 中，以允许页面刷新。

### 2. 完整访问控制（Identity-Aware Proxy）
要将访问权限限制为特定的 Google 账户，请启用 Identity-Aware Proxy（IAP）。这将添加一个 Google 登录页面——只有授权用户才能访问应用。

``bash
gcloud run services update live-translate --region us-central1 --iap

注意： IAP 锁定整个应用程序，包括听众观看页面。请参阅 docs/authentication.md 获取完整的设置说明。

使用方法

1. 点击 创建会话 — 您将被带到广播页面
2. 允许麦克风访问并开始讲话
3. 与听众分享二维码（或 URL）
4. 听众打开链接，从下拉菜单中选择语言
5. 服务器为该语言启动一个 Gemini Live API 翻译桥
6. 后续请求相同语言的听众共享现有桥接

项目结构

`` src/ ├── app/ │ ├── api/ │ │ ├── sessions/ # 创建/列出/删除会话 │ │ ├── token/ # LiveKit 令牌生成 │ │ └── translate/ # 请求翻译，检查状态 │ ├── session/[id]/ │ │ ├── broadcast/ # 组织者视图 │ │ └── watch/ # 听众视图 + 语言选择器 │ ├── globals.css │ ├── layout.tsx │ └── page.tsx # 着陆页 ├── components/ │ └── SessionQRCode.tsx └── lib/ ├── languages.ts # 支持的语言 ├── translation-bridge.ts # LiveKit ↔ Gemini 桥接 └── translation-session-manager.ts # 单例：每语言最多 1 个会话

## 关键设计决策

- **仅音频** — 无视频，保持简单且低带宽消耗
- **`translationConfig`** — 使用 Gemini 原生定向翻译，而非基于提示
- **`@livekit/rtc-node`** — 服务器端机器人以编程方式加入房间（非浏览器）
- **每语言单例** — `TranslationSessionManager` 确保每个房间每种语言最多一个 Gemini 会话
- **听众音频切换** — 客户端使用 `setSubscribed()` 仅订阅所选翻译机器人的音频轨道
- **可靠的转录交付** — 转录通过 `publishData`（可靠数据通道）发送，不依赖于音频轨道订阅状态
- **标签页关闭清理** — `navigator.sendBeacon()` 在 `beforeunload` 时触发，以减少订阅者数量并关闭空闲的 Gemini 会话
- **串行音频帧队列** — `captureFrame` 调用通过 Promise 链式执行，以避免音频源 FFI 层中的帧堆积

## 架构与扩展

### 当前设计（演示版）

所有参与者——组织者、翻译机器人和听众——共享**单个 LiveKit 房间**。听众使用 `setSubscribed()` 仅听到他们选择的语言。

``
                    ┌─────────────────────┐
                    │    LiveKit 房间     │
                    │                     │
  组织者 ──────▶    │  translator-fr ─┐   │ ◀── 听众 (法语)
                    │  translator-de ─┤   │ ◀── 听众 (德语)
                    │  translator-zh ─┘   │ ◀── 听众 (中文)
                    └─────────────────────┘

此设计适用于：

• 最多约 15-20 种同时进行的语言
• 开发服务器上最多约 50 个听众，或 LiveKit Cloud 上约 200-300 个听众

局限性：

• 信令扇出为 O(n)：每个参与者加入/离开都会通知所有其他人。1000 个听众时，每次加入会发送约 1000 条信令消息。
• 轨道发布开销：每个听众接收所有已发布轨道的元数据（即使他们未订阅）。
• 单个 Node.js 进程：所有 Gemini WebSocket 连接和音频管道在一个进程中运行。

推荐的生产架构

对于大规模部署（100+ 听众，20+ 种语言），请使用三层设计，按语言设置单独的交付房间：

`` 层级 1 — 接入 层级 2 — 翻译 层级 3 — 交付 ┌──────────────┐ ┌──────────────────┐ ┌─────────────────┐ │ 主房间 │ │ Worker (法语) │ │ 房间: sess-fr │ │ │ 订阅 │ Gemini Live API │ 发布 │ │ │ 组织者 ─────┼────────────▶│ 法语翻译 ├────────▶│ 67 个听众 │ │ （发布音频） │ └──────────────────┘ └─────────────────┘ │ │ ┌──────────────────┐ ┌─────────────────┐ │ │ 订阅 │ Worker (德语) │ 发布 │ 房间: sess-de │ │ ├────────────▶│ Gemini Live API ├────────▶│ 67 个听众 │ │ │ └──────────────────┘ └─────────────────┘ │ │ ┌──────────────────┐ ┌─────────────────┐ │ │ 订阅 │ Worker (中文) │ 发布 │ 房间: sess-zh │ │ ├────────────▶│ Gemini Live API ├────────▶│ 67 个听众 │ └──────────────┘ └──────────────────┘ └─────────────────┘

**优点：**
- **隔离的故障域** — Worker 崩溃只影响一种语言
- **水平扩展** — Worker 是无状态的，可通过 Kubernetes/Cloud Run 部署
- **无信令风暴** — 每个交付房间有 1 个发布者 + N 个听众（无 N² 问题）
- **无限语言** — 每种语言是一个独立的、可独立扩展的房间
- **CDN 就绪** — 对于 10K+ 观众，使用 LiveKit Egress → HLS → CDN 交付房间

**权衡：** 切换语言需要重新连接房间（约 200ms 音频间隙），而单房间设计中可即时切换订阅。

## 许可证与免责声明

版权所有 © 2026 Google LLC

所有软件均根据 Apache License, Version 2.0 (Apache 2.0) 许可；除非符合 Apache 2.0 许可，否则您不得使用此文件。您可以在 https://www.apache.org/licenses/LICENSE-2.0 获取 Apache 2.0 许可证副本。

所有其他材料均根据 Creative Commons Attribution 4.0 International License (CC-BY) 许可。您可以在 https://creativecommons.org/licenses/by/4.0/legalcode 获取 CC-BY 许可证副本。

除非适用法律要求或书面同意，否则根据 Apache 2.0 或 CC-BY 许可分发的所有软件和材料均按“原样”分发，不附带任何明示或暗示的保证或条件。请参阅具体许可证以了解有关许可证权限和限制的详细信息。

这不是一款官方的 Google 产品。