CloudWeGo 作為字節跳動開源的高性能微服務框架體系，核心組件 Kitex 與 Hertz 以其原生的流式處理能力，已成為大模型應用開發的核心技術支撐。兩者通過 SSE、gRPC 及自研 TTHeader Streaming 等多協議適配，完美契合大模型 "一問多答" 的交互需求，廣泛應用於 Chat、語音交互等各類大模型場景。
本文基於 Kitex / Hertz 項目 Maintainer 王宇軒在 CloudWeGo 四週年技術沙龍演講內容整理，系統闡述過去一年裏 CloudWeGo 開源的微服務框架 Kitex 和 Hertz，如何提升流式開發效率與易用性，為大模型應用保駕護航。
圖為 Kitex / Hertz 項目 Maintainer 王宇軒
一、大模型應用框架概覽：流式能力與經典鏈路
隨着大模型應用的快速發展，微服務架構已成為其核心支撐模式，而 CloudWeGo 開源的 Kitex 與 Hertz 兩大微服務框架，通過原生流式能力為大模型應用提供了關鍵技術支撐。
Kitex 與 Hertz 緊跟技術趨勢，針對大模型交互場景提供了流式處理能力，以幫助用户高效構建應用：Hertz 支持 SSE 協議，負責與端上直接交互；Kitex Streaming 則支持廣為人知的 gRPC 協議及自研流式協議 TTHeader Streaming，專注處理服務間的流式通信，兩者均能完美適配大模型"一問多答"交互模式。
在微服務架構中，基於 Kitex 與 Hertz 的大模型應用鏈路具備清晰的邏輯架構，以經典 Chat 場景為例，API 服務、Chat 服務與 LLM 通過流式接口實現串聯，最終達成一問多答的交互效果：
- API 服務通過 SSE 接口與端上交互，藉助 Kitex 流式 Client 訪問 Chat 服務；
- LLM 根據部署環境差異，靈活暴露 SSE 接口或 RPC 流式接口，Chat 服務對應使用 SSE Client 或 Kitex 流式 Client 對接。
該架構設計滿足了大模型應用的交互需求，邏輯清晰流暢。但在實際開發落地過程中，流式能力所帶來的工程實踐問題接踵而至。
二、流式工程實踐增強：保障應用穩定落地
為應對大模型應用在流式開發中遇到的實際挑戰，服務框架團隊圍繞會話中斷、流式異常與流式監控這三個核心場景，對 Kitex 和 Hertz 的流式工程實踐進行了強化，全方位保障應用的穩定運行。
1.會話中斷控制：強化 Stream 生命週期管理
實際場景中可能會因為用户中途修改 Prompt 終止會話、響應超時導致用户放棄、網絡不穩定引發連接斷開等因素導致會話中斷。及時感知並終止無效會話，能有效節省 LLM 資源。對此，Kitex 與 Hertz 的流式接口通過實現統一的 golang context cancel 語義，達成 Stream 生命週期的精準控制：
- Kitex gRPC 支持跨服務與同服務場景的 Stream 生命週期管理：跨服務場景下，上游服務主動調用 cancel 後，會通過 HTTP/2 Rst Frame 終止下游 Stream；同服務場景下，下游 Stream 的生命週期完全受上游 Stream 控制，上游 cancel 會觸發下游級聯終止。
- Hertz 原生支持 SSE 協議，對齊 Kitex gRPC 的 context cancel 能力：讓流式鏈路從端上到服務、服務到大模型的生命週期控制形成閉環。
2.流式異常優化：提升問題定位效率
流式交互中，gRPC-Go 經典報錯 "rpc error: code = 1, context is canceled" 存在明顯侷限性 ------ 僅能描述結果，無法明確具體錯誤原因，易導致問題誤判（如誤歸因為 LLM 服務故障）。該報錯可能對應用户主動終止會話，級聯 cancel 等多種場景，排查難度較大。為解決這一問題，服務框架團隊優化了 Kitex gRPC 的錯誤描述機制，明確報錯誘因，幫助開發者快速定位異常根源，大幅降低問題排查成本。
- 錯誤細分為流級別錯誤和連接級別錯誤
- 豐富錯誤描述，精確對應具體錯誤場景
- 新增 "triggered by" 字段，明確觸發錯誤的服務
3.流式監控升級：完善消息觀測能力
傳統 Ping-Pong 模型的監控指標（QPS、Latency）雖可統一適配為 "Stream 創建至生命週期結束" 的指標，但難以滿足流式場景的精細化觀測需求。對此，服務框架團隊對監控能力進行雙重升級：
- 新增 Recv/Send QPS 指標：通過 StreamEventReport 接口擴展，每次調用 Recv 或 Send 方法時自動觸發打點，精準捕捉流式消息交互頻率。
- 增強流式Trace 能力：新增 StreamSendHeader/StreamRecvHeader、StreamSendRst/StreamRecvRst、StreamSendTrailer/StreamRecvTrailer 等關鍵狀態事件，清晰刻畫 Stream 狀態流轉，為建流失敗、非預期報錯等疑難問題提供排查依據。
通過會話中斷控制、流式異常優化、流式監控升級三大實踐增強，Kitex 與 Hertz 有效解決了大模型應用的核心落地阻礙。但隨着用户規模與實踐案例的增加，服務框架團隊發現現有流式接口仍存在學習使用成本高、複雜級聯 cancel 鏈路排查難等問題。因此，進一步優化流式接口、推出自研流式協議並增強流式生態，推動流式能力的易用性與用户體驗邁上新台階。
三、流式能力與生態升級：從可用到好用
為解決現有流式接口的使用痛點，推動流式能力從 "可用" 向 "好用" 跨越，服務框架團隊從接口設計優化、自研協議研發、生態工具補充三個維度，對 Kitex 與 Hertz 的流式能力及生態進行全面升級。
1. 現有流式接口的核心痛點
當前流式接口在設計與使用中存在兩類關鍵問題，導致用户學習和使用成本偏高：
- gRPC-Go 接口設計的侷限性：Server 側流式 Handler 未直接暴露 context 參數，需通過 Stream.Context () 獲取；Stream 的 Recv、Send 方法也未暴露 context 參數，無法細粒度控制超時等邏輯。雖然 gRPC-Go 官方認可統一 context 設計，但未計劃推出 v2 接口優化，Kitex gRPC 因遵循該設計也存在相同問題。
- Kitex 自身能力透出的適配問題：Kitex 最初基於 Ping-Pong 模型設計，未充分考慮流式接口需求。一方面 Options 配置作用域模糊，部分配置僅對 Unary 接口生效，需用户在實踐中探索確認；另一方面，中間件只適配 Unary 接口語義（接收請求→處理→返回響應），流式場景中 resp 始終為 nil，語義差異增加理解成本，導致流式接口未能得到完全支持。
2. StreamX 接口優化：降低使用門檻
針對上述痛點，服務框架團隊推出 StreamX 流式接口，通過設計革新與能力升級提升易用性：
- 統一 context 設計：Server 側 Unary 接口與流式接口一致暴露 context 參數，Stream 對象的 Recv、Send 方法也新增 context 參數，支持細粒度控制（如超時設置），符合用户使用直覺。
- 流式接口 "適應性" 升級：拆分 Options 配置為 WithUnary（僅 Unary 接口生效）與 WithStream（僅流式接口生效）兩類，保持原有配置兼容性；同時提供 Stream、Recv、Send 三種專屬中間件，參數與作用域直觀清晰，適配流式場景語義。
3.自研協議 TT Header Streaming改變 gRPC 痛點
gRPC 難以排查複雜級聯 cancel 鏈路，也無法有效支持 context.WithCancelCause，本質在於 gRPC 基於 HTTP/2 Rst Stream Frame 實現 context cancel 功能，只支持傳遞 ErrCode，無法攜帶其它元信息。
服務框架團隊為了改善 gRPC 痛點，推出自研協議 TTHeader Streaming，允許 Rst Frame 攜帶 Header 與 Payload。
- Rst Frame 攜帶鏈路追蹤信息，高效應對級聯 cancel：類似 HTTP via，TTHeader Streaming 在 Rst Frame 頭部會攜帶 ttscp(ttheader streaming cancel path)，跟蹤完整的 cancel 鏈路，從而精確定位發起 cancel 的第一跳服務。
- 支持 context.WithCancelCause，傳遞自定義 cancel 異常：TTHeader Streaming 支持在 Rst Frame 中攜帶 payload，從而承載由 context.WithCancelCause 注入的自定義 cancel 異常，用户可以實現更為豐富的 cancel 語義。
4. 完備的生態支持：流式泛化能力增強
在原有流式調用能力的基礎上，Kitex 進一步完善了泛化生態支持，使流式交互在本地調試、壓測及多協議網關等場景下也能無縫使用。
- 支持流式泛化 Client，一個泛化 Client 搞定流式/非流式場景
- 支持流式泛化 Server，高效處理 二進制/JSON/Map 數據
- Kitexcall 支持流式調用，方便本地調試流式接口
四、總結與展望
本次分享圍繞三大板塊展開：一是大模型應用框架的流式能力與經典鏈路，明確 Kitex 與 Hertz 的核心支撐作用；二是流式工程實踐增強，通過會話中斷控制、異常定位優化、監控能力升級，保障大模型應用穩定落地；三是流式能力與生態升級，以 StreamX 新接口、自研 TTHeader Streaming 協議、完善流式生態，實現流式能力從 "可用" 到 "好用" 的跨越。展望未來，服務框架團隊將開源流式最佳工程實踐併發布配套使用指南，推出 Metrics/Trace 的 open-telemetry 版本，持續迭代 TTHeader Streaming 協議、優化 WebSocket 支持，進一步完善流式生態，為更多大模型應用提供高效、可靠的技術支撐。
活動回顧資料
- 視頻回看 ：https://space.bilibili.com/3494360534485730/lists/6518781?type=season
- 演講PPT下載 ：https://github.com/cloudwego/community/tree/main/meetup/2025-09-20
