Google AI Android SDK（Gemin i API 安卓客户端）

从"孤军奋战"到"AI 随身带"：一个 Android 开发者的 Gemini 之旅

张明（化名）是一名移动应用开发者，最近接到了一个棘手的项目需求：用户需要一款在离线环境下也能快速处理图片问答的 Android 应用。传统的云端 AI 调用方案要么延迟高、要么依赖网络稳定性。他在网上找了很久，终于发现了一个来自 Google 的官方工具——Google AI Android SDK，它能让 Gemini 大模型的能力直接运行在 Android 设备上，通过 API 调用完成多模态理解，而不需要复杂的模型压缩或本地部署。

这个 SDK 的本质是一个Android 原生库（aar），封装了与 Google Gemini API 通信的所有逻辑，开发者只需要几行 Kotlin 代码，就能给自己的 App 加上大模型能力。

图1：Google AI Android SDK 示例 APP 界面，运行在 Android 模拟器中

项目背景：从独立 SDK 到统一 Firebase 生态

google/generative-ai-android 是 Google 官方为 Android 开发者提供的 Gemini API 客户端 SDK，由 Google LLC 主导开发和维护，项目采用 Apache-2.0 开源许可证。作为 Google 在移动端布局 Generative AI 能力的重要一环，该 SDK 经历了从独立维护到被统一收编的完整生命周期。

截至本报告撰写时，SDK 的 README 页面已明确标注为 Deprecated（已废弃）。官方给出的解释是：随着 Gemini 2.0 的发布，Google 决定将所有移动端 AI 能力统一整合到 Firebase SDK 中，形成一个统一的 SDK 来覆盖 Gemini、Veo（视频生成）、Imagen（图片生成）等所有生成式 AI 模型。官方表示，这一决策是基于大量开发者反馈作出的，目的是为移动开发者提供一条"极其简单清晰的路径"来使用 Google 的生成式 AI 能力。

尽管已被废弃，但该项目仍具有极高的研究和参考价值：它完整呈现了 Google 在移动端与 LLM API 交互的标准工程实践，包括多模态内容处理、流式响应、错误处理机制等核心技术细节。同时，对于仍在使用旧版 SDK 的项目，理解其架构有助于平滑迁移到 Firebase 统一 SDK。

核心功能：SDK 能做什么？

1. 文本生成与对话

SDK 的核心类 GenerativeModel 封装了对 Gemini Pro 模型的调用能力。开发者只需创建一个 GenerativeModel 实例（传入模型名称和 API Key），然后调用 generateContent() 方法即可发起一次推理请求。整个过程完全基于 Kotlin 协程（Coroutine），天然支持异步操作，不会阻塞主线程。

val model = GenerativeModel(
    modelName = "gemini-pro",
    apiKey = "YOUR_API_KEY"
)
val response = model.generateContent("解释量子计算的基本原理")

2. 多模态理解（图片 + 文本）

通过 generateContent() 方法，SDK 支持同时传入文本和图片（Bitmap）内容，实现图文混合推理。这是 Gemini 模型区别于纯文本模型的核心优势，也是该 SDK 在移动端最具吸引力的功能之一。用户可以选择"照片推理"模式，拍摄或选择一张图片，就图片内容向 Gemini 提问。

图2：照片推理功能示例，演示如何通过 SDK 分析图片内容

3. 流式响应

SDK 还支持流式推理模式（Streaming），通过 generateContentStream() 方法，可以实时获取模型生成的部分结果，而不必等待完整响应生成完毕。这对于实现打字机效果（typing indicator）的对话界面非常重要，能够显著提升用户体验。

4. 聊天对话（Chat）

除了单轮问答，SDK 还提供了 Chat 类来管理多轮对话上下文。开发者无需手动维护对话历史，SDK 内部会自动处理消息的序列化和上下文管理。

5. 安全过滤与内容审核

Gemini 模型内置了安全过滤机制。SDK 通过 SafetySetting 类允许开发者配置不同内容类别的安全阈值，当模型判定内容违规时，会抛出 PromptBlockedException 或 ResponseStoppedException，应用可以捕获并优雅处理。

图3：多轮聊天功能界面，展示 SDK 对话上下文管理能力

技术架构：三层模块化设计

整个仓库采用 Gradle 多项目（Multi-Project）结构，包含三个主要模块：

模块	职责	技术栈
common	API 通信层、请求/响应序列化、通用工具	Kotlin, Ktor HTTP Client, Kotlin Serialization
generativeai	核心 SDK：GenerativeModel、Chat、类型系统	Kotlin, Kotlin Coroutines, Flow
generativeai-android-sample	完整示例 APP	Jetpack Compose, Android Navigation, Material Design 3

common 模块：API 通信层

APIController.kt 是整个通信层的核心，它使用 Ktor（JetBrains 出品的 Kotlin 多平台 HTTP 客户端）作为 HTTP 引擎。默认使用 OkHttp 作为底层实现，在测试环境中则切换为 MockEngine，非常适合单元测试。关键配置包括：

• 超时控制：通过 Ktor 的 HttpTimeout 插件配置请求超时
• JSON 序列化：使用 Kotlin Serialization（@Serializable）进行请求/响应的编解码，Json 配置中 ignoreUnknownKeys = true 保证向前兼容性
• 流式响应处理：通过 Ktor 的 bodyAsChannel 实现流式内容的增量读取

generativeai 模块：类型系统

SDK 定义了一套完整的 Kotlin 类型系统来对应 Gemini API 的请求和响应结构：

• Content：消息内容，支持文本（TextContent）和图片（ImageContent）两种模式
• GenerateContentResponse / GenerateContentRequest：生成内容的请求和响应
• SafetySetting：安全设置
• Tool / ToolConfig：工具调用配置（为 Function Calling 预留）
• GenerationConfig：生成配置（温度、最大 token 数、停止序列等）
• FinishReason：生成停止原因枚举

类型转换通过 conversions.kt 中的扩展函数（如 toInternal() / toPublic()）在内外部类型之间进行转换。

示例 APP：工程实践参考

generativeai-android-sample 模块是一个功能完整的参考应用，展示了 SDK 的所有主要能力：

• Compose Navigation：使用 Jetpack Navigation 实现多页面路由（菜单 → 文本摘要 → 照片推理 → 聊天）
• MVVM 架构：每个功能页面都有对应的 ViewModel + UiState 分离
• Material Design 3：完整的 Jetpack Compose UI 实现

部署与集成：如何把这个 SDK 用起来？

环境要求

• Android Studio：建议 Hedgehog（2023.1.1）或更高版本
• Android SDK：compileSdk 34（Android 14），minSdk 21+
• Gradle：项目使用 Gradle 8.x，wrapper 包含在仓库中
• Kotlin：1.8+
• Java：JDK 17

集成方式

开发者需要从源码构建 aar 库，然后上传到私有 Maven 仓库（或直接使用 MavenLocal）：

# 克隆仓库
git clone https://github.com/google/generative-ai-android.git
cd generative-ai-android

# 构建并发布到本地 Maven 仓库
./gradlew publishToMavenLocal

# 在自己的 Android 项目中引入依赖
implementation("com.google.ai.client.generativeai:generativeai:0.2.0")

获取 API Key

需要在 Google AI Studio 免费申请 API Key，然后将 Key 以安全方式（如 Gradle Properties 或环境变量）注入应用。需要注意的是，API Key 直接暴露在客户端存在安全风险，生产环境应通过后端代理或 Firebase App Check 等机制保护。

Web UI 支持

该 SDK 本身不提供 Web 界面，但 generativeai-android-sample 模块完整展示了一个现代化的 Material Design 3 UI 参考实现，包含三个主要功能页面：文本摘要、照片推理、多轮聊天，可直接作为开发者的 UI 设计参考。

争议与局限

1. 已被官方废弃

这是该项目最核心的局限。Google 已明确表示不再向该 SDK 添加任何新功能，也不会进行进一步维护。虽然现有代码仍然可用，但新项目应直接使用 Firebase SDK 中的 Vertex AI for Firebase 模块。

2. API Key 安全问题

作为纯客户端 SDK，所有 API Key 都必须嵌入或嵌入在客户端代码中。恶意用户可以通过反编译 APK 提取 Key 并滥用，引发意料之外的账单。更安全的做法是搭建后端服务作为代理，由后端持有 Key，前端通过后端转发请求。

3. 网络依赖

该 SDK 完全依赖 Google Gemini API 的可用性，无法在离线环境下工作。对于需要本地推理的场景（如设备端隐私保护、无网络环境），需要考虑其他方案，如 Google 的 on-device ML 能力或 TensorFlow Lite。

4. 功能已被 Firebase 替代

Firebase 统一 SDK 在功能上完全覆盖了本项目，并增加了与 Firebase Auth、App Check 等其他 Firebase 服务的集成能力。如果项目已经使用了 Firebase，迁移到 Firebase SDK 几乎是无缝的。

行业意义与历史价值

尽管已被废弃，google/generative-ai-android 在 AI 移动端应用发展史上具有标志性意义：

1. 开创了"LLM as a Service"的 Android 端标准化封装模式

在 2023 年之前，移动端调用云端大模型更多是"野生"状态，开发者各自封装 HTTP 请求。Google 官方 SDK 的出现，将 API 契约、类型安全、错误处理、安全过滤等最佳实践固化为标准库，推动了整个行业向规范化方向演进。

2. 揭示了 Google Gemini 生态的演进策略

该项目从独立维护到被 Firebase 收编，折射出 Google 在 AI 战略上从"分散探索"到"统一整合"的转变。Firebase 作为 Google 移动端的核心平台，统一入口策略有助于降低开发者的学习和维护成本，但也意味着开发者对 Google 生态的依赖进一步加深。

3. 流式响应与多模态处理的工程参考

SDK 中对流式响应的处理（Ktor Channel + Flow）、多模态内容序列化、以及与 Kotlin 协程的无缝集成，都是高质量的 Kotlin 工程实践，对 Android 开发者具有重要的学习价值。

总结与建议

维度	评价
功能完整性	★★★★★（覆盖 Gemini 主流能力）
代码质量	★★★★★（Google 官方出品，工程标准高）
文档质量	★★★★☆（清晰但已被归档）
活跃状态	★★☆☆☆（已废弃，不再维护）
部署便捷性	★★★☆☆（需从源码构建，非标准 Maven 依赖）

核心结论：该项目适合作为技术参考和历史研究对象。如果你要启动新项目，强烈建议直接使用 Firebase SDK。如果你需要理解如何用 Kotlin 高质量地封装 LLM API 调用，这个仓库的代码值得深入研读。