Live API - Web 控制台

此仓库包含一个基于 React 的入门应用，用于通过 WebSocket 使用 Live API。它提供了用于流式音频播放、录制用户媒体（例如来自麦克风、网络摄像头或屏幕捕获）的模块，以及统一的日志视图，以帮助您开发应用程序。

在此观看 Live API 的演示：这里。

使用方法

要开始使用，请先创建一个免费的 Gemini API 密钥，并将其添加到 .env 文件中。然后执行以下命令：

$ npm install && npm start

我们在该仓库的其他分支中提供了一些示例应用：

使用 GenAI SDK 的新演示：

• demos/proactive-audio - 展示了 Live API 的主动音频功能

原始演示：

• demos/GenExplainer
• demos/GenWeather
• demos/GenList

示例

以下是整个应用的示例，该应用将使用 Google 搜索进行知识增强，然后使用 vega-embed 渲染图表：

import { type FunctionDeclaration, SchemaType } from "@google/generative-ai";
import { useEffect, useRef, useState, memo } from "react";
import vegaEmbed from "vega-embed";
import { useLiveAPIContext } from "../../contexts/LiveAPIContext";

export const declaration: FunctionDeclaration = {
  name: "render_altair",
  description: "以 JSON 格式显示 Altair 图表。",
  parameters: {
    type: SchemaType.OBJECT,
    properties: {
      json_graph: {
        type: SchemaType.STRING,
        description:
          "要渲染的图表的 JSON 字符串表示。必须是字符串，而不是 JSON 对象。",
      },
    },
    required: ["json_graph"],
  },
};

export function Altair() {
  const [jsonString, setJSONString] = useState<string>("");
  const { client, setConfig } = useLiveAPIContext();

  useEffect(() => {
    setConfig({
      model: "models/gemini-2.0-flash-exp",
      systemInstruction: {
        parts: [
          {
            text: '你是我有用的助手。每当我请求你绘制图表时，请调用我提供的 "render_altair" 函数。无需询问更多信息，只需根据你的判断做出最佳选择。',
          },
        ],
      },
      tools: [{ googleSearch: {} }, { functionDeclarations: [declaration] }],
    });
  }, [setConfig]);

  useEffect(() => {
    const onToolCall = (toolCall: ToolCall) => {
      console.log(`收到工具调用`, toolCall);
      const fc = toolCall.functionCalls.find(
        (fc) => fc.name === declaration.name
      );
      if (fc) {
        const str = (fc.args as any).json_graph;
        setJSONString(str);
      }
    };
    client.on("toolcall", onToolCall);
    return () => {
      client.off("toolcall", onToolCall);
    };
  }, [client]);

  const embedRef = useRef<HTMLDivElement>(null);

  useEffect(() => {
    if (embedRef.current && jsonString) {
      vegaEmbed(embedRef.current, JSON.parse(jsonString));
    }
  }, [embedRef, jsonString]);
  return <div className="vega-embed" ref={embedRef} />;
}

开发

该项目使用 Create React App 引导启动。 项目包括：

• 一个事件驱动的 WebSocket 客户端，以简化 WebSocket 和前端之间的通信
• 用于处理音频输入和输出的通信层
• 一个用于开始构建您的应用和查看日志的样板视图

可用脚本

在项目目录中，您可以运行以下命令：

npm start

以开发模式运行应用。
打开 http://localhost:3000 即可在浏览器中查看。

如果您进行编辑，页面将会重新加载。
您还会在控制台中看到任何 lint 错误。

npm run build

将应用构建为生产版本，并输出到 build 文件夹。
它会在生产模式下正确打包 React，并优化构建以获得最佳性能。

构建文件会被压缩，文件名会包含哈希值。
您的应用已准备好部署！

有关更多信息，请参阅关于部署的部分。 这是一个展示 Live API 的实验性项目，并非 Google 的官方产品。我们将尽最大努力支持和维护这个实验，但实际效果可能因人而异。我们鼓励开源项目，以便相互学习。请在分享这些作品及创作衍生作品时，尊重我们及其他创作者的权利，包括版权和商标权。如需了解更多 Google 的相关政策，可访问此处。

Live API Web Console 快速上手指南

本指南帮助中国开发者快速搭建基于 React 的 Google Live API 网页控制台，实现音频流、摄像头/屏幕捕获及实时日志查看功能。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统：Windows, macOS 或 Linux
• Node.js：建议安装 LTS 版本 (v18 或更高)
• 包管理器：npm (随 Node.js 安装) 或 yarn
• API 密钥：需要拥有 Google Gemini API Key
  • 获取地址：https://aistudio.google.com/apikey
  • 注意：由于网络环境限制，访问 Google AI Studio 可能需要特定的网络配置。

安装步骤

1. 克隆项目代码

   git clone https://github.com/google-gemini/multimodal-live-api-web-console.git
   cd multimodal-live-api-web-console
   

2. 配置 API 密钥 在项目根目录下创建 .env 文件，并填入您的 API Key：

   echo "REACT_APP_GEMINI_API_KEY=你的_API_KEY_在此" > .env
   

   (注：如果 .env 文件中变量名不同，请参考项目实际示例文件，通常为 REACT_APP_ 开头)

3. 安装依赖并启动 为了获得更快的下载速度，建议临时使用国内镜像源（如淘宝镜像）安装依赖：

   # 使用 npm 默认安装
   npm install
   
   # 或者使用国内镜像加速安装
   npm install --registry=https://registry.npmmirror.com
   
   # 启动开发服务器
   npm start
   

4. 访问应用 浏览器自动打开或手动访问：http://localhost:3000

基本使用

启动成功后，您将看到一个包含音频控制、媒体输入选择和统一日志视图的基础界面。

核心功能模块

• 音频流：内置模块支持实时音频播放与录制。
• 媒体捕获：支持调用麦克风、摄像头或进行屏幕共享。
• 日志监控：统一的日志面板用于调试 WebSocket 通信和 API 响应。

简单代码示例

以下是一个集成 Google 搜索 grounding 并使用 vega-embed 渲染图表的最小化应用逻辑示例（参考自官方 Demo）：

import { type FunctionDeclaration, SchemaType } from "@google/generative-ai";
import { useEffect, useRef, useState, memo } from "react";
import vegaEmbed from "vega-embed";
import { useLiveAPIContext } from "../../contexts/LiveAPIContext";

export const declaration: FunctionDeclaration = {
  name: "render_altair",
  description: "Displays an altair graph in json format.",
  parameters: {
    type: SchemaType.OBJECT,
    properties: {
      json_graph: {
        type: SchemaType.STRING,
        description:
          "JSON STRING representation of the graph to render. Must be a string, not a json object",
      },
    },
    required: ["json_graph"],
  },
};

export function Altair() {
  const [jsonString, setJSONString] = useState<string>("");
  const { client, setConfig } = useLiveAPIContext();

  useEffect(() => {
    setConfig({
      model: "models/gemini-2.0-flash-exp",
      systemInstruction: {
        parts: [
          {
            text: 'You are my helpful assistant. Any time I ask you for a graph call the "render_altair" function I have provided you. Dont ask for additional information just make your best judgement.',
          },
        ],
      },
      tools: [{ googleSearch: {} }, { functionDeclarations: [declaration] }],
    });
  }, [setConfig]);

  useEffect(() => {
    const onToolCall = (toolCall: ToolCall) => {
      console.log(`got toolcall`, toolCall);
      const fc = toolCall.functionCalls.find(
        (fc) => fc.name === declaration.name
      );
      if (fc) {
        const str = (fc.args as any).json_graph;
        setJSONString(str);
      }
    };
    client.on("toolcall", onToolCall);
    return () => {
      client.off("toolcall", onToolCall);
    };
  }, [client]);

  const embedRef = useRef<HTMLDivElement>(null);

  useEffect(() => {
    if (embedRef.current && jsonString) {
      vegaEmbed(embedRef.current, JSON.parse(jsonString));
    }
  }, [embedRef, jsonString]);
  return <div className="vega-embed" ref={embedRef} />;
}

进阶演示

项目其他分支提供了更多高级用例，您可以切换分支查看：

• 主动音频 (Proactive Audio): demos/proactive-audio
• 生成式解释器: demos/GenExplainer
• 天气查询: demos/GenWeather
• 列表生成: demos/GenList