简介面向 Android 开发者的 Kimi API 流式输出实现资源解决在 Android 端对接 Kimi 大模型 API 并处理流式文本输出的问题涵盖从发起请求到逐字展示返回内容的完整链路。适用于聊天机器人、智能助手等打字机效果的实时交互场景适合具备 Android 与 Kotlin 基础、希望快速掌握大模型 API 接入的开发者。压缩包共 813 个文件约 14.99MB以 Kotlin 源码、XML 布局与 JSON 数据配置为主同时包含 Gradle 构建脚本、JAR 依赖库及编译生成的 dex/class 字节码文件properties 文件记录参数配置txt 文件提供说明参考结构对应一个完整可运行的 Android 项目。已有 1231 人学习/下载。通过这份资源可获得网络请求封装、流式数据处理逻辑、界面刷新机制等核心实现便于理解 Kimi API 流式返回在多线程、协程与 UI 更新中的衔接方式配合 Gradle 配置可直接导入 IDE 阅读或二次开发已编译的 APK 与 class 文件可用于效果验证便于排查流式传输中的常见问题。1. KIMI API 流式输出让Android应用拥有“打字机”级响应体验做过大模型客户端的人应该都有感受如果用户问完问题屏幕要干等几秒甚至十几秒才一次性弹出全部文字那体验基本算是毁了。流式输出的价值不在于“炫技”而在于把首字延迟压到 1 秒以内让用户觉得对面的模型是在思考、在打字而不是卡死了。这套“KIMI API 流式输出”项目就是一套完整的 Android 端流式接入实现核心是围绕 SSEServer-Sent Events协议建立一条长连接通道逐行读取模型返回的增量 token并在 UI 上实时渲染。它适合两类人一类是想快速把 Kimi 模型接到自己 App 里的业务开发者另一类是正在做 ChatUI 但被流式解析、消息拼接、网络切换这类问题折磨的客户端工程师。看完这篇你可以直接拿这套代码做底子改改模型参数就能跑。2. 项目定位与技术选型为什么流式模式是移动端的必然选择2.1 流式输出和普通 JSON 返回的本质区别KIMI API 同时支持同步返回和流式返回两种模式两者的差异不只是“快一点”那么简单。同步模式下服务端要等完整内容生成完毕才一次性返回一个长回答可能耗时 15 秒到 30 秒期间客户端完全空转流式模式则通过 SSE 服务端推送服务端每生成一小段文本就立刻通过已建立的 HTTP 连接推给客户端。也就是说你看到的第一个字可能只花了 800ms后面每个 token 间隔只有几十毫秒整体感知速度完全不是一回事。从协议层面来看SSE 是单向的文本事件流它复用普通的 HTTP 连接不需要像 WebSocket 那样升级协议、处理帧掩码也没有重连时的复杂握手。在移动端弱网环境下SSE 的恢复成本比 WebSocket 低很多这也让我在实际项目中更倾向于在“模型对话”这个场景下使用它。Kimi 的流式接口本身就是标准 SSE 格式每条事件以event:开头标记事件类型随后是data:携带 JSON 数据。这个格式在 Android 端可以直接用 OkHttp 的 EventSource 接口处理不需要自己解析原始字节流。2.2 依赖选型与基础配置实现这套项目用到的依赖非常克制核心只有两个OkHttp 和 okhttp-sse 扩展库。前者负责 HTTP 连接、超时控制与连接池管理后者提供 EventSource 抽象帮你屏蔽掉 SSE 格式解析的底层细节。项目用的是 OkHttp 4.x 版本配合 Kotlin 协程使用网络层全部走挂起函数避免回调地狱。// build.gradle.kts (Module) dependencies { implementation(com.squareup.okhttp3:okhttp:4.12.0) implementation(com.squareup.okhttp3:okhttp-sse:4.12.0) implementation(org.jetbrains.kotlinx:kotlinx-coroutines-android:1.7.3) implementation(androidx.lifecycle:lifecycle-viewmodel-ktx:2.6.2) }有几个细节值得说明一下。okhttp-sse这个库是独立于 OkHttp 发布的版本号必须与主库保持一致否则会出现类找不到的运行时异常。另外协程库我选择androidx.lifecycle里的viewModelScope而不是自己裸建CoroutineScope这样 ViewModel 销毁时协程会自动取消不会有后台线程泄漏的问题。2.3 项目目录结构从入口到底层链路的模块划分拿到这份源码之后第一件事不是跑起来而是先看它目录是怎么切的。这套项目的划分方式很干净app/src/main/java/com/example/kimiapi/ ├── MainActivity.kt # 入口只做页面初始化和权限申请 ├── network/ # 网络层 │ ├── ApiClient.kt # OkHttp Client 单例配置超时和日志 │ ├── KimiApiService.kt # 请求封装定义 URL、Header 和 Body │ └── StreamParser.kt # SSE 事件流解析把 data 转成业务实体 ├── repository/ # 数据仓库层 │ └── ChatRepository.kt # 对话仓库上游拿数据下游抛状态 ├── viewmodel/ │ └── ChatViewModel.kt # UI 状态持有者管理 Loading/Success/Error └── ui/ ├── ChatAdapter.kt # RecyclerView 适配器负责气泡展示 └── ChatActivity.kt # 对话界面处理输入和事件绑定这里我想强调一下分层的动机。很多人做这种接入会直接把网络请求写在 Activity 里项目跑通是没问题但你一旦要加“多轮对话记忆”“换模型参数”“拦截消息做埋点”这些功能Activity 就会变成一片乱麻。这套代码把网络层拆到network把数据与 UI 的桥接放到repository和viewmodel你要做二次开发时只需要改其中一层其他层不用动。这个结构对新手友好对想加功能的熟手也留了足够的操作空间。3. 核心模块拆解一条流式消息从进入到上屏的旅程3.1 发起请求前的准备工作构建可复用的 OkHttp EventSource这一步是整套流式链路的地基。需要创建一个带 Tail 的OkHttpClient配置合理的超时时间同时把 API Key 作为拦截器统一附加到请求头。注意这里有个关键点超时时间千万不能套用普通 JSON 接口的 8 秒或 10 秒配置因为流式接口的连接时长本身就可能超过 30 秒特别是模型在思考阶段时中间可能长时间没有数据返回但连接仍然是健康的。如果超时设得太短会出现“长时间没有 token 就自动断开”的假故障。object ApiClient { private const val API_KEY Bearer sk-xxxxxxxxxxxx private const val BASE_URL https://api.example.com/v1/chat/completions val client: OkHttpClient by lazy { OkHttpClient.Builder() .connectTimeout(30, TimeUnit.SECONDS) .readTimeout(0, TimeUnit.MILLISECONDS) // 流式场景不设读超时 .writeTimeout(30, TimeUnit.SECONDS) .addInterceptor { chain - val request chain.request().newBuilder() .header(Authorization, API_KEY) .header(Content-Type, application/json) .build() chain.proceed(request) } .build() } }这段代码里最有价值的配置是readTimeout(0, TimeUnit.MILLISECONDS)。流式场景中每次数据返回的间隔完全由服务端生成速度决定不做读超时可以避免误杀慢速输出。缺点是如果网络假死连接不会自动断开这时需要依赖后面的“心跳检测机制”来兜底。另外注意 API Key 的拼接需要带Bearer前缀协议对 Header 的格式要求非常严格少了这个前缀会直接 401。3.2 发起流式请求并监听事件有了客户端配置下一步就是真正发出流式请求并接收事件。这里用的是okhttp-sse库的EventSources.createFactory方法它会帮我们解析 HTTP 响应里的 SSE 帧格式然后把解析好的事件回调到EventSourceListener中。class StreamParser { fun startStream( messages: ListMapString, String, onEvent: (String) - Unit, onError: (Throwable) - Unit, onFinished: () - Unit ) { val request Request.Builder() .url(ApiClient.BASE_URL) .post(generateBody(messages)) .build() val factory EventSources.createFactory(ApiClient.client) val eventSource factory.newEventSource(request, object : EventSourceListener() { override fun onEvent(eventSource: EventSource, id: String?, type: String?, data: String) { if (type completionEvent) { val content parseDeltaContent(data) onEvent(content) } else if (type errorEvent) { onError(RuntimeException(Stream error: $data)) } } override fun onFailure(eventSource: EventSource, t: Throwable?, response: Response?) { onError(t ?: IOException(Unknown stream failure)) } override fun onClosed(eventSource: EventSource) { onFinished() } }) } }completionEvent是 Kimi API 流式返回中最重要的一个事件类型。当服务端生成了一部分内容时就会推送这个事件data字段中携带的是一个完整的 JSON 字符串里面包含增量文本、消息ID、结束标记和 token 用量等信息。这里有个容易被忽略的细节onEvent回调里的type是事件类型名而data是 JSON 字符串不是纯文本。你需要在内部再解析一次提取出choices[0].delta.content字段才是真正的增量文本。// 服务端单帧推送的数据结构 { id: chatcmpl-7Zx1a2b3c, object: chat.completion.chunk, created: 1699999999, model: kimi-32k, choices: [ { index: 0, delta: { content: 这是一个增量token }, finish_reason: null } ] }3.3 事件体解析与消息状态更新拿到原始 JSON 后不能直接把它拼到 UI 上还需要做一层转化。这里我习惯的做法是定义一个StreamChunk数据类把 JSON 里的有效字段抽取出来然后交给 ViewModel 更新状态。这样做的好处是把底层协议与 UI 解耦后面如果换成其他大模型 API你只需要替换StreamParser的解析逻辑。data class StreamChunk( val contentDelta: String, // 增量文本 val isFinish: Boolean, // 是否生成完毕 val messageId: String, // 当前消息的唯一标识 val totalTokens: Int? // token 用量统计最后一帧才返回 ) fun parseDeltaContent(data: String): String { val json JSONObject(data) val choices json.optJSONArray(choices) if (choices null || choices.length() 0) return val delta choices.getJSONObject(0).optJSONObject(delta) ?: return return delta.optString(content, ) }这段解析逻辑有几个边界情况特别注意。第一当模型回答结束时服务端会推送最后一帧此时choices里delta可能是一个空对象但finish_reason字段是stop所以不能因为“解析不到 content 就丢掉最后一帧”否则你会漏掉finish_reason和 token 用量。第二在多轮对话中每条消息的id不同你需要用它来区分当前渲染的是哪条气泡而不是简单地把所有增量追加到同一个字符串里。第三totalTokens只在最后一帧返回如果你想做计费展示务必在收到isFinish为 true 的那一帧里去读。3.4 ViewModel 层如何把回调流安全地送到 UI 线程StreamParser的回调是跑在 OkHttp 的线程池里的直接拿它去更新 RecyclerView 会触发线程异常。正确的做法是让 ViewModel 持有一个MutableStateFlow在onEvent回调里通过viewModelScope.launch把数据切换到主线程并更新状态。这里我踩过一个坑如果每收到一个 token 就emit一次完整文本RecyclerView 会频繁触发局部刷新在低端机上会出现掉帧甚至卡死。优化手段是“节流合并”——把一小段时间内的多个增量拼成一条再刷新。class ChatViewModel : ViewModel() { private val _uiState MutableStateFlowChatUiState(ChatUiState.Initial) val uiState: StateFlowChatUiState _uiState // 用于拼接当前回答的临时缓冲 private val answerBuffer StringBuilder() fun startChat(userMessage: String) { answerBuffer.clear() val messages buildMessages(userMessage) _uiState.value ChatUiState.Loading viewModelScope.launch { val parser StreamParser() parser.startStream( messages messages, onEvent { content - answerBuffer.append(content) _uiState.value ChatUiState.Streaming(answerBuffer.toString()) }, onError { error - _uiState.value ChatUiState.Error(error.message ?: 网络异常) }, onFinished { _uiState.value ChatUiState.Success(answerBuffer.toString()) } ) } } private fun buildMessages(userMessage: String): ListMapString, String { return listOf( mapOf(role to user, content to userMessage) ) } }这段代码展示了一个最小的流式状态机Initial表示初始态Loading表示正在等待第一帧Streaming表示正在接收增量Success表示流式结束Error表示异常中断。UI 层只需要观察uiState这个 Flow根据状态切换加载动画、文本内容和错误提示。构建messages时目前这个实现只传了当前用户消息如果要做多轮对话你需要在这里把历史消息一并塞进去后面我会在二次开发章节专门讲。3.5 UI 展示层RecyclerView 的稳定增量刷新策略最后一步是把这个状态渲染到界面上本质上是 RecyclerView 的局部更新问题。我的实现是让 Adapter 暴露一个updatePartialText(position, newText)方法每次Streaming状态触发时只更新最后一个 item 的文本而不是调用notifyDataSetChanged全量刷新。另外还有一个小细节关于流光效果——如果你想让输出更像 ChatGPT 那样有一个光标在闪烁可以在 Adapter 里给最后一条消息单独加一个 View 的透明度动画动画只在Streaming状态运行一旦流式结束就停止并隐藏。这个视觉效果不算复杂但对产品体验的提升非常直接。4. 运行步骤把这份代码在本地跑起来的完整流程4.1 前置条件与开发环境要求开始之前确认你的开发环境满足下面几个条件。第一Android Studio 版本建议用最新稳定版Kotlin 插件版本 1.9 以上因为代码里用到了StateFlow和data object等较新的语法特性。第二AGPAndroid Gradle Plugin版本需要 7.4 以上build.gradle.kts里的配置才能原样运行。第三准备一个可以访问公网的环境因为 API 请求是直接走 HTTPS 的。如果你拿到的项目包自带gradle/wrapper目录建议直接使用项目指定版本的 Gradle避免因为版本不一致导致编译报错。代码需要用到网络权限记得在AndroidManifest.xml里声明uses-permission android:nameandroid.permission.INTERNET /还有一个调试期非常好用的配置。为了让每次请求的响应速度符合真实场景你在拿到 SDK 后应该顺手检查一下默认的 API 地址端口。如果 API 网关做了私有化部署地址会和项目默认值不同你只需要改ApiClient.BASE_URL这一处常量即可不用动其他业务代码。4.2 最小化改造不需要改业务代码就能完成换 Key 接入从仓库拉下来的代码默认带的是一个过期或不可用的测试 Key你需要在ApiClient里把它替换成自己的 Key。这个操作只需要改API_KEY常量。这里我给一个“先验证后集成的建议”先单独运行项目确认能收到流式文本再定制 UI 样式。// 在 MainActivity 中将其注释替换为自己的Key private val YOUR_API_KEY Bearer sk-your-key-here替换完 Key 后直接 RunApp 会进到一个最简单的聊天页面。试着问一句“用一句话介绍你自己”正常情况下页面会在 1 秒内出现打字机效果并逐字输出完成。如果出现 401先检查 Key 是否复制完整——很多人是复制 Key 时把末尾的空格或多出来的引号带进去了。如果 429说明账号配额不足要等一段时间再试。4.3 验证流式行为的关键标志怎么判断这套代码真正跑通了呢不看编译成功而是看下面这三个现象。第一页面上的文本是“逐字蹦出来”的而不是等待数秒后一次性出现完整回答。第二在系统网络监控工具里能看到同一个 URL 存在持续的长连接期间分数次推送数据。第三当你在生成中途锁屏或切到后台再回来文本还在持续累积没有被系统杀掉——这个体现的是协程对后台任务的处理能力。如果第一眼没看到逐字输出大概率是解析环节出了问题。最常见的错误是把StreamParser当成了“批量下载器”手动把data里的所有内容拼接起来再一次性传递给 UI。正确做法是每收到一个onEvent回调就立刻把content增量送出去。这里给出一个排查思路在onEvent回调的方法入口加一条Log.d(StreamParser, eventType$type content$content)如果日志里一条条信息开启说明链路是通的问题出在 ViewModel 拼接或 UI 刷新层。5. 常见问题排查流式接入期最容易踩的五个坑5.1 现象一直等不到第一帧数据这个是最常见的情况请求发出去Logcat 安静得像什么都没发生两三秒后才一次性返回所有内容。原因在于服务端在生成第一个 token 之前需要漫长的 Prefill预填充时间特别是你传入的 histories 很长、或者问题涉及大量背景知识时这个时间可能超过 5 秒。另一个可能是代理或网关层面把 SSE 响应缓冲了它不是边收边转而是等全部响应结束才一次性转给客户端。解决路径分两步。第一步确认不是代码问题在 OkHttp 的日志拦截器里看响应是否被 Buffer 了。如果日志输出是“一次性输出完整响应”那就是网络链路问题需要调整代理配置关闭缓冲。第二步做应用层兜底在 UI 上把“等待第一帧”的时间作为 Loading 状态展示超过 10 秒再提示超时而不是让用户干等。5.2 现象流式内容出现重复或拼接断裂这是比“拿不到数据”更诡异的问题。具体表现是文本输出过程中前一段 token 被重复追加了一次或者两条增量中间丢了一个字符导致最终答案语义不通。原因通常是事件帧解析时没有处理好\r\n与\n的混用。SSE 协议标准规定帧之间以空行分隔但不同服务端实现可能使用不同的换行符OkHttp 的 SSE 解析器对这种差异做了兼容但如果你自己在data里做了二次 split就很容易踩到拼接断裂的坑。解决的觉悟是永远不要在自定义代码里对data做“按行拆分再重组”的操作。你可以通过onEvent回调拿到的data是完整的一帧 JSON直接把它丢给解析函数。如果确实需要对超长文本分段截断截断位置必须选在 Unicode 字符的边界上不能用Byte长度切否则中文会被劈成乱码。5.3 现象点击停止后回调仍在触发用户点击“停止生成”按钮后理论上流式连接应该终止。但实际很多项目里按钮虽然置灰了onEvent却还在不停输出后台线程也没有释放。原因是只用EventSource.cancel()取消了连接但 OkHttp 底层的连接池和回调队列依然在工作协程的 Job 没有同时取消。我在这个项目里的解决方案是把EventSource对象和协程 Job 绑定在一起管理。点击停止按钮时先赋 Job.cancel() 再赋 eventSource.cancel()。顺序不能反过来因为如果先断连接OkHttp 会触发一次onFailure回调如果 Job 还没取消这次回调会进来一次意外状态更新。class ChatRepository { private var currentJob: Job? null private var currentEventSource: EventSource? null fun stopStream() { currentJob?.cancel() currentEventSource?.cancel() currentJob null currentEventSource null } }这个设计同时解决了另一个隐藏问题用户在快速连续发消息时上一次的请求可能会污染下一次的回答。每次startStream之前调用一次stopStream可以保证任意时刻只有一条流式连接在活跃状态。5.4 现象长对话出现明显卡顿和内存上涨当对话轮数超过 20 轮、文本长度累计到几万字符时UI 刷新会开始掉帧内存占用量也在持续上涨。原因不是 API 返回变慢了而是 Adapter 每次通知局部刷新时都要重建整条 item 的视图且历史消息文本全部被SpannableString缓存了下来。应对方案是给消息列表做“虚拟化”处理。RecyclerView 本身已经复用了 item 视图但对于超大文本你需要限制每个 item 的最大显示长度超出部分折叠起来点击展开查看完整内容。另外增量刷新时不要用notifyItemChanged(position)会触发 ViewHolder 的onBindViewHolder全量重绘而是通过自定义 View 暴露一个appendText(text)方法内部只拼接 Spannable 的新增部分。5.5 现象API 返回 401 或 429 导致整个流程崩掉这两个错误码是流式接入里出现频率最高的鉴权类报错处理方式必须做到“体面不可感知”。401 是 Key 无效或过期需要在收到这个状态时跳到设置页提示用户重新输入 Key。429 是请求被限流表示账号的每分钟请求数RPM或每分钟 Token 数TPM超了配额这种情况盲目重试只会加重限流。推荐的做法是用 OkHttp 的RetryAndFollowUpInterceptor配合自定义重试策略。对于 429读取响应头里的Retry-After字段按其指定的秒数延迟重试对于 401直接放弃重试抛出让用户处理的上层错误。不要试图在代码里硬循环“重试 5 次”那只会让你的 App 被网关封禁更长时间。6. 二次开发经验把 Demo 改造成可上线的对话产品如果只是把流式文本打印出来那这个项目只能算 demo。想真正用于生产我最建议你从下面三个方向做二次开发。第一个是引入“多轮上下文管理”把历史消息按对话轮次组装进请求上下文让模型能记忆前文第二个是给输出文本做 Markdown 渲染因为模型默认输出包含大量代码块和列表纯文本展示效果非常劝退第三个是加入“停止生成”和“重新生成”按钮对 Token 用量做统计展示这个对控制成本意义重大。多轮上下文的实现并不复杂核心是维护一个MutableListMapString, String作为消息历史。在buildMessages里把历史列表和当前用户问题合并fun buildMessagesWithHistory(history: ListChatRecord, newQuestion: String): ListMapString, String { return history.map { record - mapOf(role to record.role, content to record.content) } listOf(mapOf(role to user, content to newQuestion)) }注意这里有个“上下文窗口”问题把全部历史都塞进去最终会超过模型的 token 上限。你需要自己实现一个滑动窗口比如只保留最近 10 轮对话或者按字符数截断旧记录。这个截断策略直接影响模型的记忆效果——窗口太长会导致接口报错太短则让模型“失忆”。实际调优过程中不同业务的敏感度差异非常大代码里加一个可配置的参数比较好private val MAX_HISTORY_ROUNDS 10 private val MAX_HISTORY_CHARS 4000第二个方向是 Markdown 渲染。Android 生态中常用的方案是集成com.github.jeziellago:compose-markdown或io.noties.markwon但直接引入第三方库会带来包体积上升。这里我提供一个轻量思路增量渲染的风险比较大更稳妥的做法是在onFinished后才对完整文本做一次性 Markdown 转换流式期间只做纯文本展示。虽然代价是结束时有一瞬间的格式跳变但可以完美避免“半个代码块被解析成错误格式”的问题。在一次性输出中用 Markwon 绑定 TextView 即可val markwon Markwon.builder(context) .usePlugin(FencedCodePlugin.create()) .build() markwon.setMarkdown(binding.tvMessage, fullText)第三个方向是 Token 用量展示。finish_reason为stop的那一帧里带有usage.total_tokens字段把它存到StreamChunk里即可。这个数据的价值不只是展示给用户看你还可以用来做成本统计比如按天汇总用户消耗的 Token 数。这里的坑是SSE 流式响应中usage字段只出现在最后一帧如果中途出错或者用户手动停止你就要到错误事件的响应体里去找已经消耗的部分。说到线上环境的稳定性我最想分享的教训是永远要在客户端和服务端之间加一层“超时看门狗”。SSE 是一个长时间保持的连接虽然 OkHttp 禁用了读超时但如果网络全国范围内不可用连接不会自动断开。我习惯在ChatViewModel里起一个Debounce计时器比如每 15 秒检查一次——如果最近 15 秒没有任何新 token 到达就主动触发一次重连或通知用户“网络已断开”。这个检查和心跳不同它不是定期发 Ping而是观测“我方是否收到新数据”。实现起来只需要在onEvent回调里重置计时器即可。从那以后我每次接入任何大模型 SDK都会强制走一遍“首帧时延、断线重连、多余上下文截断”这三个维度的压测这套习惯让线上问题率直接降了一个等级。希望这篇拆解能帮你在接入 KIMI 流式 API 时少走几段弯路。本文还有配套的精品资源点击获取
简介面向 Android 开发者的 Kimi API 流式输出实现资源解决在 Android 端对接 Kimi 大模型 API 并处理流式文本输出的问题涵盖从发起请求到逐字展示返回内容的完整链路。适用于聊天机器人、智能助手等打字机效果的实时交互场景适合具备 Android 与 Kotlin 基础、希望快速掌握大模型 API 接入的开发者。压缩包共 813 个文件约 14.99MB以 Kotlin 源码、XML 布局与 JSON 数据配置为主同时包含 Gradle 构建脚本、JAR 依赖库及编译生成的 dex/class 字节码文件properties 文件记录参数配置txt 文件提供说明参考结构对应一个完整可运行的 Android 项目。已有 1231 人学习/下载。通过这份资源可获得网络请求封装、流式数据处理逻辑、界面刷新机制等核心实现便于理解 Kimi API 流式返回在多线程、协程与 UI 更新中的衔接方式配合 Gradle 配置可直接导入 IDE 阅读或二次开发已编译的 APK 与 class 文件可用于效果验证便于排查流式传输中的常见问题。1. KIMI API 流式输出让Android应用拥有“打字机”级响应体验做过大模型客户端的人应该都有感受如果用户问完问题屏幕要干等几秒甚至十几秒才一次性弹出全部文字那体验基本算是毁了。流式输出的价值不在于“炫技”而在于把首字延迟压到 1 秒以内让用户觉得对面的模型是在思考、在打字而不是卡死了。这套“KIMI API 流式输出”项目就是一套完整的 Android 端流式接入实现核心是围绕 SSEServer-Sent Events协议建立一条长连接通道逐行读取模型返回的增量 token并在 UI 上实时渲染。它适合两类人一类是想快速把 Kimi 模型接到自己 App 里的业务开发者另一类是正在做 ChatUI 但被流式解析、消息拼接、网络切换这类问题折磨的客户端工程师。看完这篇你可以直接拿这套代码做底子改改模型参数就能跑。2. 项目定位与技术选型为什么流式模式是移动端的必然选择2.1 流式输出和普通 JSON 返回的本质区别KIMI API 同时支持同步返回和流式返回两种模式两者的差异不只是“快一点”那么简单。同步模式下服务端要等完整内容生成完毕才一次性返回一个长回答可能耗时 15 秒到 30 秒期间客户端完全空转流式模式则通过 SSE 服务端推送服务端每生成一小段文本就立刻通过已建立的 HTTP 连接推给客户端。也就是说你看到的第一个字可能只花了 800ms后面每个 token 间隔只有几十毫秒整体感知速度完全不是一回事。从协议层面来看SSE 是单向的文本事件流它复用普通的 HTTP 连接不需要像 WebSocket 那样升级协议、处理帧掩码也没有重连时的复杂握手。在移动端弱网环境下SSE 的恢复成本比 WebSocket 低很多这也让我在实际项目中更倾向于在“模型对话”这个场景下使用它。Kimi 的流式接口本身就是标准 SSE 格式每条事件以event:开头标记事件类型随后是data:携带 JSON 数据。这个格式在 Android 端可以直接用 OkHttp 的 EventSource 接口处理不需要自己解析原始字节流。2.2 依赖选型与基础配置实现这套项目用到的依赖非常克制核心只有两个OkHttp 和 okhttp-sse 扩展库。前者负责 HTTP 连接、超时控制与连接池管理后者提供 EventSource 抽象帮你屏蔽掉 SSE 格式解析的底层细节。项目用的是 OkHttp 4.x 版本配合 Kotlin 协程使用网络层全部走挂起函数避免回调地狱。// build.gradle.kts (Module) dependencies { implementation(com.squareup.okhttp3:okhttp:4.12.0) implementation(com.squareup.okhttp3:okhttp-sse:4.12.0) implementation(org.jetbrains.kotlinx:kotlinx-coroutines-android:1.7.3) implementation(androidx.lifecycle:lifecycle-viewmodel-ktx:2.6.2) }有几个细节值得说明一下。okhttp-sse这个库是独立于 OkHttp 发布的版本号必须与主库保持一致否则会出现类找不到的运行时异常。另外协程库我选择androidx.lifecycle里的viewModelScope而不是自己裸建CoroutineScope这样 ViewModel 销毁时协程会自动取消不会有后台线程泄漏的问题。2.3 项目目录结构从入口到底层链路的模块划分拿到这份源码之后第一件事不是跑起来而是先看它目录是怎么切的。这套项目的划分方式很干净app/src/main/java/com/example/kimiapi/ ├── MainActivity.kt # 入口只做页面初始化和权限申请 ├── network/ # 网络层 │ ├── ApiClient.kt # OkHttp Client 单例配置超时和日志 │ ├── KimiApiService.kt # 请求封装定义 URL、Header 和 Body │ └── StreamParser.kt # SSE 事件流解析把 data 转成业务实体 ├── repository/ # 数据仓库层 │ └── ChatRepository.kt # 对话仓库上游拿数据下游抛状态 ├── viewmodel/ │ └── ChatViewModel.kt # UI 状态持有者管理 Loading/Success/Error └── ui/ ├── ChatAdapter.kt # RecyclerView 适配器负责气泡展示 └── ChatActivity.kt # 对话界面处理输入和事件绑定这里我想强调一下分层的动机。很多人做这种接入会直接把网络请求写在 Activity 里项目跑通是没问题但你一旦要加“多轮对话记忆”“换模型参数”“拦截消息做埋点”这些功能Activity 就会变成一片乱麻。这套代码把网络层拆到network把数据与 UI 的桥接放到repository和viewmodel你要做二次开发时只需要改其中一层其他层不用动。这个结构对新手友好对想加功能的熟手也留了足够的操作空间。3. 核心模块拆解一条流式消息从进入到上屏的旅程3.1 发起请求前的准备工作构建可复用的 OkHttp EventSource这一步是整套流式链路的地基。需要创建一个带 Tail 的OkHttpClient配置合理的超时时间同时把 API Key 作为拦截器统一附加到请求头。注意这里有个关键点超时时间千万不能套用普通 JSON 接口的 8 秒或 10 秒配置因为流式接口的连接时长本身就可能超过 30 秒特别是模型在思考阶段时中间可能长时间没有数据返回但连接仍然是健康的。如果超时设得太短会出现“长时间没有 token 就自动断开”的假故障。object ApiClient { private const val API_KEY Bearer sk-xxxxxxxxxxxx private const val BASE_URL https://api.example.com/v1/chat/completions val client: OkHttpClient by lazy { OkHttpClient.Builder() .connectTimeout(30, TimeUnit.SECONDS) .readTimeout(0, TimeUnit.MILLISECONDS) // 流式场景不设读超时 .writeTimeout(30, TimeUnit.SECONDS) .addInterceptor { chain - val request chain.request().newBuilder() .header(Authorization, API_KEY) .header(Content-Type, application/json) .build() chain.proceed(request) } .build() } }这段代码里最有价值的配置是readTimeout(0, TimeUnit.MILLISECONDS)。流式场景中每次数据返回的间隔完全由服务端生成速度决定不做读超时可以避免误杀慢速输出。缺点是如果网络假死连接不会自动断开这时需要依赖后面的“心跳检测机制”来兜底。另外注意 API Key 的拼接需要带Bearer前缀协议对 Header 的格式要求非常严格少了这个前缀会直接 401。3.2 发起流式请求并监听事件有了客户端配置下一步就是真正发出流式请求并接收事件。这里用的是okhttp-sse库的EventSources.createFactory方法它会帮我们解析 HTTP 响应里的 SSE 帧格式然后把解析好的事件回调到EventSourceListener中。class StreamParser { fun startStream( messages: ListMapString, String, onEvent: (String) - Unit, onError: (Throwable) - Unit, onFinished: () - Unit ) { val request Request.Builder() .url(ApiClient.BASE_URL) .post(generateBody(messages)) .build() val factory EventSources.createFactory(ApiClient.client) val eventSource factory.newEventSource(request, object : EventSourceListener() { override fun onEvent(eventSource: EventSource, id: String?, type: String?, data: String) { if (type completionEvent) { val content parseDeltaContent(data) onEvent(content) } else if (type errorEvent) { onError(RuntimeException(Stream error: $data)) } } override fun onFailure(eventSource: EventSource, t: Throwable?, response: Response?) { onError(t ?: IOException(Unknown stream failure)) } override fun onClosed(eventSource: EventSource) { onFinished() } }) } }completionEvent是 Kimi API 流式返回中最重要的一个事件类型。当服务端生成了一部分内容时就会推送这个事件data字段中携带的是一个完整的 JSON 字符串里面包含增量文本、消息ID、结束标记和 token 用量等信息。这里有个容易被忽略的细节onEvent回调里的type是事件类型名而data是 JSON 字符串不是纯文本。你需要在内部再解析一次提取出choices[0].delta.content字段才是真正的增量文本。// 服务端单帧推送的数据结构 { id: chatcmpl-7Zx1a2b3c, object: chat.completion.chunk, created: 1699999999, model: kimi-32k, choices: [ { index: 0, delta: { content: 这是一个增量token }, finish_reason: null } ] }3.3 事件体解析与消息状态更新拿到原始 JSON 后不能直接把它拼到 UI 上还需要做一层转化。这里我习惯的做法是定义一个StreamChunk数据类把 JSON 里的有效字段抽取出来然后交给 ViewModel 更新状态。这样做的好处是把底层协议与 UI 解耦后面如果换成其他大模型 API你只需要替换StreamParser的解析逻辑。data class StreamChunk( val contentDelta: String, // 增量文本 val isFinish: Boolean, // 是否生成完毕 val messageId: String, // 当前消息的唯一标识 val totalTokens: Int? // token 用量统计最后一帧才返回 ) fun parseDeltaContent(data: String): String { val json JSONObject(data) val choices json.optJSONArray(choices) if (choices null || choices.length() 0) return val delta choices.getJSONObject(0).optJSONObject(delta) ?: return return delta.optString(content, ) }这段解析逻辑有几个边界情况特别注意。第一当模型回答结束时服务端会推送最后一帧此时choices里delta可能是一个空对象但finish_reason字段是stop所以不能因为“解析不到 content 就丢掉最后一帧”否则你会漏掉finish_reason和 token 用量。第二在多轮对话中每条消息的id不同你需要用它来区分当前渲染的是哪条气泡而不是简单地把所有增量追加到同一个字符串里。第三totalTokens只在最后一帧返回如果你想做计费展示务必在收到isFinish为 true 的那一帧里去读。3.4 ViewModel 层如何把回调流安全地送到 UI 线程StreamParser的回调是跑在 OkHttp 的线程池里的直接拿它去更新 RecyclerView 会触发线程异常。正确的做法是让 ViewModel 持有一个MutableStateFlow在onEvent回调里通过viewModelScope.launch把数据切换到主线程并更新状态。这里我踩过一个坑如果每收到一个 token 就emit一次完整文本RecyclerView 会频繁触发局部刷新在低端机上会出现掉帧甚至卡死。优化手段是“节流合并”——把一小段时间内的多个增量拼成一条再刷新。class ChatViewModel : ViewModel() { private val _uiState MutableStateFlowChatUiState(ChatUiState.Initial) val uiState: StateFlowChatUiState _uiState // 用于拼接当前回答的临时缓冲 private val answerBuffer StringBuilder() fun startChat(userMessage: String) { answerBuffer.clear() val messages buildMessages(userMessage) _uiState.value ChatUiState.Loading viewModelScope.launch { val parser StreamParser() parser.startStream( messages messages, onEvent { content - answerBuffer.append(content) _uiState.value ChatUiState.Streaming(answerBuffer.toString()) }, onError { error - _uiState.value ChatUiState.Error(error.message ?: 网络异常) }, onFinished { _uiState.value ChatUiState.Success(answerBuffer.toString()) } ) } } private fun buildMessages(userMessage: String): ListMapString, String { return listOf( mapOf(role to user, content to userMessage) ) } }这段代码展示了一个最小的流式状态机Initial表示初始态Loading表示正在等待第一帧Streaming表示正在接收增量Success表示流式结束Error表示异常中断。UI 层只需要观察uiState这个 Flow根据状态切换加载动画、文本内容和错误提示。构建messages时目前这个实现只传了当前用户消息如果要做多轮对话你需要在这里把历史消息一并塞进去后面我会在二次开发章节专门讲。3.5 UI 展示层RecyclerView 的稳定增量刷新策略最后一步是把这个状态渲染到界面上本质上是 RecyclerView 的局部更新问题。我的实现是让 Adapter 暴露一个updatePartialText(position, newText)方法每次Streaming状态触发时只更新最后一个 item 的文本而不是调用notifyDataSetChanged全量刷新。另外还有一个小细节关于流光效果——如果你想让输出更像 ChatGPT 那样有一个光标在闪烁可以在 Adapter 里给最后一条消息单独加一个 View 的透明度动画动画只在Streaming状态运行一旦流式结束就停止并隐藏。这个视觉效果不算复杂但对产品体验的提升非常直接。4. 运行步骤把这份代码在本地跑起来的完整流程4.1 前置条件与开发环境要求开始之前确认你的开发环境满足下面几个条件。第一Android Studio 版本建议用最新稳定版Kotlin 插件版本 1.9 以上因为代码里用到了StateFlow和data object等较新的语法特性。第二AGPAndroid Gradle Plugin版本需要 7.4 以上build.gradle.kts里的配置才能原样运行。第三准备一个可以访问公网的环境因为 API 请求是直接走 HTTPS 的。如果你拿到的项目包自带gradle/wrapper目录建议直接使用项目指定版本的 Gradle避免因为版本不一致导致编译报错。代码需要用到网络权限记得在AndroidManifest.xml里声明uses-permission android:nameandroid.permission.INTERNET /还有一个调试期非常好用的配置。为了让每次请求的响应速度符合真实场景你在拿到 SDK 后应该顺手检查一下默认的 API 地址端口。如果 API 网关做了私有化部署地址会和项目默认值不同你只需要改ApiClient.BASE_URL这一处常量即可不用动其他业务代码。4.2 最小化改造不需要改业务代码就能完成换 Key 接入从仓库拉下来的代码默认带的是一个过期或不可用的测试 Key你需要在ApiClient里把它替换成自己的 Key。这个操作只需要改API_KEY常量。这里我给一个“先验证后集成的建议”先单独运行项目确认能收到流式文本再定制 UI 样式。// 在 MainActivity 中将其注释替换为自己的Key private val YOUR_API_KEY Bearer sk-your-key-here替换完 Key 后直接 RunApp 会进到一个最简单的聊天页面。试着问一句“用一句话介绍你自己”正常情况下页面会在 1 秒内出现打字机效果并逐字输出完成。如果出现 401先检查 Key 是否复制完整——很多人是复制 Key 时把末尾的空格或多出来的引号带进去了。如果 429说明账号配额不足要等一段时间再试。4.3 验证流式行为的关键标志怎么判断这套代码真正跑通了呢不看编译成功而是看下面这三个现象。第一页面上的文本是“逐字蹦出来”的而不是等待数秒后一次性出现完整回答。第二在系统网络监控工具里能看到同一个 URL 存在持续的长连接期间分数次推送数据。第三当你在生成中途锁屏或切到后台再回来文本还在持续累积没有被系统杀掉——这个体现的是协程对后台任务的处理能力。如果第一眼没看到逐字输出大概率是解析环节出了问题。最常见的错误是把StreamParser当成了“批量下载器”手动把data里的所有内容拼接起来再一次性传递给 UI。正确做法是每收到一个onEvent回调就立刻把content增量送出去。这里给出一个排查思路在onEvent回调的方法入口加一条Log.d(StreamParser, eventType$type content$content)如果日志里一条条信息开启说明链路是通的问题出在 ViewModel 拼接或 UI 刷新层。5. 常见问题排查流式接入期最容易踩的五个坑5.1 现象一直等不到第一帧数据这个是最常见的情况请求发出去Logcat 安静得像什么都没发生两三秒后才一次性返回所有内容。原因在于服务端在生成第一个 token 之前需要漫长的 Prefill预填充时间特别是你传入的 histories 很长、或者问题涉及大量背景知识时这个时间可能超过 5 秒。另一个可能是代理或网关层面把 SSE 响应缓冲了它不是边收边转而是等全部响应结束才一次性转给客户端。解决路径分两步。第一步确认不是代码问题在 OkHttp 的日志拦截器里看响应是否被 Buffer 了。如果日志输出是“一次性输出完整响应”那就是网络链路问题需要调整代理配置关闭缓冲。第二步做应用层兜底在 UI 上把“等待第一帧”的时间作为 Loading 状态展示超过 10 秒再提示超时而不是让用户干等。5.2 现象流式内容出现重复或拼接断裂这是比“拿不到数据”更诡异的问题。具体表现是文本输出过程中前一段 token 被重复追加了一次或者两条增量中间丢了一个字符导致最终答案语义不通。原因通常是事件帧解析时没有处理好\r\n与\n的混用。SSE 协议标准规定帧之间以空行分隔但不同服务端实现可能使用不同的换行符OkHttp 的 SSE 解析器对这种差异做了兼容但如果你自己在data里做了二次 split就很容易踩到拼接断裂的坑。解决的觉悟是永远不要在自定义代码里对data做“按行拆分再重组”的操作。你可以通过onEvent回调拿到的data是完整的一帧 JSON直接把它丢给解析函数。如果确实需要对超长文本分段截断截断位置必须选在 Unicode 字符的边界上不能用Byte长度切否则中文会被劈成乱码。5.3 现象点击停止后回调仍在触发用户点击“停止生成”按钮后理论上流式连接应该终止。但实际很多项目里按钮虽然置灰了onEvent却还在不停输出后台线程也没有释放。原因是只用EventSource.cancel()取消了连接但 OkHttp 底层的连接池和回调队列依然在工作协程的 Job 没有同时取消。我在这个项目里的解决方案是把EventSource对象和协程 Job 绑定在一起管理。点击停止按钮时先赋 Job.cancel() 再赋 eventSource.cancel()。顺序不能反过来因为如果先断连接OkHttp 会触发一次onFailure回调如果 Job 还没取消这次回调会进来一次意外状态更新。class ChatRepository { private var currentJob: Job? null private var currentEventSource: EventSource? null fun stopStream() { currentJob?.cancel() currentEventSource?.cancel() currentJob null currentEventSource null } }这个设计同时解决了另一个隐藏问题用户在快速连续发消息时上一次的请求可能会污染下一次的回答。每次startStream之前调用一次stopStream可以保证任意时刻只有一条流式连接在活跃状态。5.4 现象长对话出现明显卡顿和内存上涨当对话轮数超过 20 轮、文本长度累计到几万字符时UI 刷新会开始掉帧内存占用量也在持续上涨。原因不是 API 返回变慢了而是 Adapter 每次通知局部刷新时都要重建整条 item 的视图且历史消息文本全部被SpannableString缓存了下来。应对方案是给消息列表做“虚拟化”处理。RecyclerView 本身已经复用了 item 视图但对于超大文本你需要限制每个 item 的最大显示长度超出部分折叠起来点击展开查看完整内容。另外增量刷新时不要用notifyItemChanged(position)会触发 ViewHolder 的onBindViewHolder全量重绘而是通过自定义 View 暴露一个appendText(text)方法内部只拼接 Spannable 的新增部分。5.5 现象API 返回 401 或 429 导致整个流程崩掉这两个错误码是流式接入里出现频率最高的鉴权类报错处理方式必须做到“体面不可感知”。401 是 Key 无效或过期需要在收到这个状态时跳到设置页提示用户重新输入 Key。429 是请求被限流表示账号的每分钟请求数RPM或每分钟 Token 数TPM超了配额这种情况盲目重试只会加重限流。推荐的做法是用 OkHttp 的RetryAndFollowUpInterceptor配合自定义重试策略。对于 429读取响应头里的Retry-After字段按其指定的秒数延迟重试对于 401直接放弃重试抛出让用户处理的上层错误。不要试图在代码里硬循环“重试 5 次”那只会让你的 App 被网关封禁更长时间。6. 二次开发经验把 Demo 改造成可上线的对话产品如果只是把流式文本打印出来那这个项目只能算 demo。想真正用于生产我最建议你从下面三个方向做二次开发。第一个是引入“多轮上下文管理”把历史消息按对话轮次组装进请求上下文让模型能记忆前文第二个是给输出文本做 Markdown 渲染因为模型默认输出包含大量代码块和列表纯文本展示效果非常劝退第三个是加入“停止生成”和“重新生成”按钮对 Token 用量做统计展示这个对控制成本意义重大。多轮上下文的实现并不复杂核心是维护一个MutableListMapString, String作为消息历史。在buildMessages里把历史列表和当前用户问题合并fun buildMessagesWithHistory(history: ListChatRecord, newQuestion: String): ListMapString, String { return history.map { record - mapOf(role to record.role, content to record.content) } listOf(mapOf(role to user, content to newQuestion)) }注意这里有个“上下文窗口”问题把全部历史都塞进去最终会超过模型的 token 上限。你需要自己实现一个滑动窗口比如只保留最近 10 轮对话或者按字符数截断旧记录。这个截断策略直接影响模型的记忆效果——窗口太长会导致接口报错太短则让模型“失忆”。实际调优过程中不同业务的敏感度差异非常大代码里加一个可配置的参数比较好private val MAX_HISTORY_ROUNDS 10 private val MAX_HISTORY_CHARS 4000第二个方向是 Markdown 渲染。Android 生态中常用的方案是集成com.github.jeziellago:compose-markdown或io.noties.markwon但直接引入第三方库会带来包体积上升。这里我提供一个轻量思路增量渲染的风险比较大更稳妥的做法是在onFinished后才对完整文本做一次性 Markdown 转换流式期间只做纯文本展示。虽然代价是结束时有一瞬间的格式跳变但可以完美避免“半个代码块被解析成错误格式”的问题。在一次性输出中用 Markwon 绑定 TextView 即可val markwon Markwon.builder(context) .usePlugin(FencedCodePlugin.create()) .build() markwon.setMarkdown(binding.tvMessage, fullText)第三个方向是 Token 用量展示。finish_reason为stop的那一帧里带有usage.total_tokens字段把它存到StreamChunk里即可。这个数据的价值不只是展示给用户看你还可以用来做成本统计比如按天汇总用户消耗的 Token 数。这里的坑是SSE 流式响应中usage字段只出现在最后一帧如果中途出错或者用户手动停止你就要到错误事件的响应体里去找已经消耗的部分。说到线上环境的稳定性我最想分享的教训是永远要在客户端和服务端之间加一层“超时看门狗”。SSE 是一个长时间保持的连接虽然 OkHttp 禁用了读超时但如果网络全国范围内不可用连接不会自动断开。我习惯在ChatViewModel里起一个Debounce计时器比如每 15 秒检查一次——如果最近 15 秒没有任何新 token 到达就主动触发一次重连或通知用户“网络已断开”。这个检查和心跳不同它不是定期发 Ping而是观测“我方是否收到新数据”。实现起来只需要在onEvent回调里重置计时器即可。从那以后我每次接入任何大模型 SDK都会强制走一遍“首帧时延、断线重连、多余上下文截断”这三个维度的压测这套习惯让线上问题率直接降了一个等级。希望这篇拆解能帮你在接入 KIMI 流式 API 时少走几段弯路。本文还有配套的精品资源点击获取
平方复杂度无法被常规优化消除｜TaoToken 统一 Key 通道实测)
