Google Gen AI Kotlin SDK 1.0：用协程与 Flow 原生接入 Gemini

预计阅读时间：10 分钟

Google Gen AI SDK for Kotlin 1.0 正式发布后，Kotlin 开发者不再需要手写 Gemini HTTP 请求，也不必在项目中绕道调用 Java SDK。这个 SDK 从一开始就按 Kotlin Multiplatform（KMP）设计，通过协程、Flow、不可变数据类以及命名参数，为 JVM、Android 和共享代码模块提供一致的 Gemini 接口。

它同时覆盖 Gemini Developer API 与 Google Cloud 上的 Gemini Enterprise Agent Platform。应用通常只需调整环境变量和认证方式，而不用替换整套业务调用代码。

一套依赖覆盖 KMP、JVM 与 Android

SDK 已发布到 Maven Central，坐标为 com.google.genai:google-genai-kotlin:1.0.0。

在 Kotlin Multiplatform 项目中，将依赖放进 commonMain：

// build.gradle.kts
kotlin {
    sourceSets {
        commonMain.dependencies {
            implementation("com.google.genai:google-genai-kotlin:1.0.0")
        }
    }
}

普通 JVM 或 Android 项目可以直接添加：

// build.gradle.kts
dependencies {
    implementation("com.google.genai:google-genai-kotlin:1.0.0")
}

Gradle 会通过 Module Metadata 选择合适的平台变体。这里的价值不只是少写几行配置：团队可以把提示词构造、响应解析和部分 AI 工作流放到共享模块中，同时让后端和 Android 客户端保留各自的平台集成层。

认证方式取决于使用的服务。Gemini Developer API 可以读取 GEMINI_API_KEY 或 GOOGLE_API_KEY：

export GEMINI_API_KEY="replace-with-your-api-key"
./gradlew run

如果接入企业平台，则设置 GOOGLE_GENAI_USE_ENTERPRISE=true，并使用标准 Google Cloud Application Default Credentials。API 密钥不要写入源码、移动端安装包或版本库；Android 应用更适合通过受控后端代理高权限调用。

从单次生成升级到流式对话

SDK 的主要入口是 Client。下面是一个可直接改造为 JVM 命令行程序的最小示例。运行前添加上述依赖并配置 API 密钥：

import com.google.genai.kotlin.Client
import kotlinx.coroutines.runBlocking

fun main() = runBlocking {
    Client().use { client ->
        val response = client.models.generateContent(
            model = "gemini-flash-latest",
            text = "用两句话解释事件驱动架构。"
        )

        println(response.text)
    }
}

use 会在请求结束后关闭底层网络引擎和 HTTP 连接。对于短生命周期的 CLI 或函数任务，这一点尤其重要；在长期运行的 Ktor、Spring Boot、Quarkus 或 Micronaut 服务中，则可以这样实践：把 Client 注册为单例，并在应用停止时统一关闭，而不是每个请求创建一次客户端。

交互式界面更关心首个 token 的延迟。generateContentStream 返回冷 Flow<GenerateContentResponse>，只有开始收集时才执行请求：

import com.google.genai.kotlin.Client
import kotlinx.coroutines.runBlocking

fun main() = runBlocking {
    Client().use { client ->
        client.models.generateContentStream(
            model = "gemini-flash-latest",
            text = "给出一个 Kotlin 微服务的可观测性检查清单。"
        ).collect { chunk ->
            chunk.text?.let(::print)
        }
        println()
    }
}

在服务端把这个 Flow 转发为 Server-Sent Events 或 WebSocket 消息时，还需要处理客户端断开、协程取消、超时和背压。不要把每个 chunk 当作完整句子解析；流式分片可能落在任意文本边界上。

多轮场景可以使用 client.chats.create(...)。聊天服务会维护历史消息、追加轮次并格式化上下文，也支持 sendMessageStream(...)。这减少了手工拼接历史的代码，但并不意味着上下文没有成本：生产系统仍应限制轮数、裁剪旧消息，并避免把敏感信息长期保留在会话中。

多模态、图像与实时交互共用同一模型接口

SDK 不只提供文本生成。通过 Content、Part 和 Blob，应用可以在同一请求中提交图片与文本。例如读取一张图并要求模型检查其中的技术标注：

import com.google.genai.kotlin.Client
import com.google.genai.kotlin.types.Blob
import com.google.genai.kotlin.types.Content
import com.google.genai.kotlin.types.Part
import java.io.File
import kotlinx.coroutines.runBlocking

fun main() = runBlocking {
    val image = File("diagram.png").readBytes()

    Client().use { client ->
        val response = client.models.generateContent(
            model = "gemini-flash-latest",
            content = Content(
                parts = listOf(
                    Part(inlineData = Blob("image/png", image)),
                    Part(text = "检查这张架构图，并指出可能的单点故障。")
                )
            )
        )
        println(response.text)
    }
}

在技术、医学或科学图表分析中，还可以通过 Tool(googleSearch = GoogleSearch()) 启用 Google Search Grounding，并检查响应中的搜索查询、引用来源和 grounding metadata。Grounding 能帮助核对外部事实，但不能替代专业审核；特别是医疗判断和安全关键系统，不应直接执行模型结论。

对于图像生成，响应中的图片以 Blob 字节形式出现，可以写入文件。SDK 也支持把原图和编辑指令一起发送，实现会话式图像编辑。处理这类输出时，应验证 MIME 类型、限制文件大小，并为生成内容建立审核和版权合规流程。

低延迟语音与实时多模态应用则可以通过 client.live.connect(...) 建立持久 WebSocket 会话。接收端通常在独立协程中收集音频或转写消息，发送端持续提交文本或原始 PCM 音频。实现时必须补齐断线重连、会话关闭、音频缓冲和权限提示，不能把演示代码中的短生命周期处理原样搬进生产环境。

工具调用让模型接入真实业务

通过 FunctionDeclaration 和 JSON Schema，开发者可以把后端能力描述给模型。模型负责判断是否发起调用，应用负责校验参数、执行真实函数并处理结果。

val telemetryTool = FunctionDeclaration(
    name = "getDatacenterMetrics",
    description = "Fetch current CPU and thermal metrics for a cloud region",
    parameters = Schema(
        type = Type.OBJECT,
        properties = mapOf(
            "region" to Schema(type = Type.STRING)
        ),
        required = listOf("region")
    )
)

val response = client.models.generateContent(
    model = "gemini-flash-latest",
    text = "Check telemetry for europe-west1",
    config = GenerateContentConfig(
        tools = listOf(
            Tool(functionDeclarations = listOf(telemetryTool))
        )
    )
)

response.functionCalls?.firstOrNull()?.let { call ->
    println("Tool: ${call.name}, arguments: ${call.args}")
}

聊天服务还提供 Automatic Function Calling，可以把 Kotlin callable 注册到会话中，由 SDK 协调调用。不过“自动”只应简化编排，不应绕过权限边界。写操作、付费操作和基础设施变更必须进行参数校验、身份鉴权、超时限制、幂等控制和审计记录，必要时加入人工确认。

落地时优先检查这些边界

Google Gen AI SDK for Kotlin 1.0 为 Kotlin 团队提供了统一且符合语言习惯的 Gemini 接入层，尤其适合已经采用协程、KMP 或 Kotlin 服务端框架的项目。建议从一个低风险、可观测的文本生成场景开始，再逐步引入流式响应、图片、Live API 和工具调用。

上线前应确认以下事项：

根据运行环境选择 Developer API 或企业平台，并把认证配置留在部署层。
长期服务复用 Client，同时在应用退出时可靠关闭资源。
为模型请求设置超时、并发限制、重试策略和成本监控。
对流式输出、工具参数和生成文件进行边界校验。
保存必要的模型版本、提示词版本、调用耗时和工具审计信息。
对医疗、安全、财务和基础设施操作保留确定性规则与人工审批。

1.0 意味着 Kotlin 项目现在有了稳定的起点，但模型输出仍然是非确定性的外部输入。把 SDK 当作类型安全的集成层，而不是业务安全机制，才能在保持开发效率的同时控制生产风险。