建LLM推理網(wǎng)關(guān)：SSE流式轉(zhuǎn)發(fā)、級(jí)聯(lián)取消與背壓控制實(shí)戰(zhàn))
1. 為什么我要自己造一個(gè) LLM 推理網(wǎng)關(guān)1.1 從一次線上事故說起去年年底我在幫一個(gè)內(nèi)部工具做 AI 能力接入。架構(gòu)很簡(jiǎn)單前端一個(gè)聊天框后端一個(gè) Go 服務(wù)收到請(qǐng)求后轉(zhuǎn)發(fā)給上游的大模型接口拿到流式響應(yīng)再吐回給瀏覽器。上線第一周沒什么問題第二周開始陸續(xù)有用戶反饋“回答到一半就卡住了”“刷新之后重新問一遍才行”。我去翻日志發(fā)現(xiàn)兩類報(bào)錯(cuò)反復(fù)出現(xiàn)。一類是stream disconnected before completion: idle timeout waiting for SSE另一類是上游返回400: {type:missing_session_id,message:error from provider}。前者說明流式連接在傳輸過程中被靜默掐斷了后者說明會(huì)話狀態(tài)在轉(zhuǎn)發(fā)鏈路上丟了。這兩個(gè)問題單獨(dú)看都不復(fù)雜但它們暴露的是同一個(gè)根因我把“轉(zhuǎn)發(fā)”這件事想得太簡(jiǎn)單了。一個(gè)真正能扛住生產(chǎn)流量的 LLM 推理網(wǎng)關(guān)至少要解決四件事SSE 流式轉(zhuǎn)發(fā)的正確性、客戶端斷開時(shí)的級(jí)聯(lián)取消、上游生產(chǎn)速度超過下游消費(fèi)速度時(shí)的背壓控制、以及會(huì)話與錯(cuò)誤狀態(tài)的一致性維護(hù)。這四件事在普通 HTTP 轉(zhuǎn)發(fā)里幾乎不用考慮但在 LLM 場(chǎng)景下全部變成了一等公民。這篇文章就是我把這套網(wǎng)關(guān)從零重寫一遍的完整記錄包含設(shè)計(jì)取舍、關(guān)鍵代碼結(jié)構(gòu)、參數(shù)計(jì)算和踩過的坑。1.2 這個(gè)網(wǎng)關(guān)到底解決什么問題先把定位說清楚。它不是模型推理框架不負(fù)責(zé)加載權(quán)重、不做 batch 調(diào)度它站在客戶端和上游推理服務(wù)之間干的是“流量治理”的活。你可以把它理解成一個(gè)專門為流式 LLM 響應(yīng)優(yōu)化的反向代理層。它要解決的核心痛點(diǎn)有這么幾個(gè)。第一LLM 響應(yīng)是逐 token 生成的一個(gè)請(qǐng)求可能持續(xù)幾十秒甚至幾分鐘傳統(tǒng)的“收完再轉(zhuǎn)發(fā)”模式完全不可用必須邊收邊轉(zhuǎn)。第二用戶隨時(shí)可能關(guān)掉頁(yè)面或點(diǎn)“停止生成”這時(shí)候如果網(wǎng)關(guān)不主動(dòng)取消上游請(qǐng)求上游會(huì)繼續(xù)燒算力成本直接翻倍。第三上游生成速度快、下游網(wǎng)絡(luò)慢的時(shí)候如果沒有背壓機(jī)制內(nèi)存里的緩沖區(qū)會(huì)無限膨脹最后 OOM。第四SSE 協(xié)議本身對(duì)連接中斷很敏感任何中間環(huán)節(jié)的超時(shí)設(shè)置不當(dāng)都會(huì)導(dǎo)致“流斷在半路”。適合讀這篇的人正在做 AI 應(yīng)用后端、需要自己搭一層網(wǎng)關(guān)的 Go 開發(fā)者被 SSE 斷流問題折磨過的同學(xué)以及想理解“級(jí)聯(lián)取消”和“背壓”這兩個(gè)詞在真實(shí)系統(tǒng)里到底怎么落地的人。不需要你是 Go 專家但至少要寫過 HTTP 服務(wù)知道 goroutine 和 channel 大概是怎么回事。1.3 技術(shù)選型為什么是 Go為什么是 SSE選 Go 的理由很直接。這個(gè)網(wǎng)關(guān)的本質(zhì)是高并發(fā) I/O 密集型轉(zhuǎn)發(fā)每個(gè)請(qǐng)求都要維持一條長(zhǎng)連接同時(shí)可能有成百上千個(gè)請(qǐng)求在飛。Go 的 goroutine 在這種場(chǎng)景下幾乎是降維打擊——每個(gè)連接一個(gè) goroutine寫起來像同步代碼跑起來是異步性能內(nèi)存占用還低。換成 Java 要處理線程池和回調(diào)地獄換成 Node 單線程又怕 CPU 密集的解析拖垮事件循環(huán)。Go 的net/http標(biāo)準(zhǔn)庫(kù)對(duì)流式響應(yīng)的支持也很成熟Flusher接口直接就能把緩沖區(qū)刷給客戶端。選 SSE 而不是 WebSocket是因?yàn)?LLM 的場(chǎng)景是單向流式推送?？蛻舳税l(fā)一次請(qǐng)求服務(wù)端持續(xù)推 token不需要雙向?qū)崟r(shí)通信。SSE 基于普通 HTTP天然穿透各種代理和負(fù)載均衡實(shí)現(xiàn)成本低瀏覽器端EventSource或者fetch加流讀取都能處理。WebSocket 雖然更靈活但要處理握手升級(jí)、心跳保活、幀解析對(duì)這個(gè)場(chǎng)景來說是過度設(shè)計(jì)。熱搜詞里有人問“web socket 和 sse”的區(qū)別一句話總結(jié)需要服務(wù)端主動(dòng)推、且只需要單向推選 SSE需要雙向低延遲交互選 WebSocket。2. 整體架構(gòu)與核心設(shè)計(jì)思路2.1 三層結(jié)構(gòu)接入層、轉(zhuǎn)發(fā)層、上游適配層我把網(wǎng)關(guān)拆成三層每層職責(zé)單一方便單獨(dú)測(cè)試和替換。接入層負(fù)責(zé)和客戶端打交道解析請(qǐng)求、校驗(yàn)參數(shù)、建立 SSE 響應(yīng)頭、管理客戶端連接的生命周期。這一層最關(guān)鍵的是拿到一個(gè)context.Context它會(huì)在客戶端斷開時(shí)被 cancel這個(gè) context 會(huì)一路往下傳成為級(jí)聯(lián)取消的源頭。轉(zhuǎn)發(fā)層是核心負(fù)責(zé)從上游讀取流、解析 SSE 事件、寫入下游。它要同時(shí)監(jiān)聽兩個(gè)方向上游的數(shù)據(jù)到達(dá)、下游的寫入完成。這里我用一個(gè)io.Pipe或者帶緩沖的 channel 來解耦讀寫速率背壓邏輯就藏在這個(gè)緩沖區(qū)的大小和阻塞行為里。上游適配層負(fù)責(zé)和具體的推理服務(wù)對(duì)接拼裝請(qǐng)求體、處理鑒權(quán)、解析不同廠商的響應(yīng)格式。因?yàn)椴煌嫌蔚?SSE 事件格式不一樣有的用data:有的用event:加data:這一層做歸一化把上游格式轉(zhuǎn)成統(tǒng)一的內(nèi)部事件結(jié)構(gòu)再交給轉(zhuǎn)發(fā)層。這樣分層的好處是換上游只需要改適配層背壓和取消邏輯完全不用動(dòng)。我實(shí)測(cè)下來接一個(gè)新的上游服務(wù)適配層大概 100 行代碼就能搞定。2.2 級(jí)聯(lián)取消一個(gè) context 串起整條鏈路級(jí)聯(lián)取消這個(gè)詞聽起來玄乎本質(zhì)就是一個(gè)取消信號(hào)沿著調(diào)用鏈往下傳每一層都響應(yīng)它。在 Go 里就是context.Context的 cancel 機(jī)制。具體到我的網(wǎng)關(guān)客戶端發(fā)起請(qǐng)求接入層用r.Context()作為根 context。這個(gè) context 在客戶端斷開連接時(shí)會(huì)被 HTTP server 自動(dòng) cancel。轉(zhuǎn)發(fā)層拿著這個(gè) context 去請(qǐng)求上游用的是http.NewRequestWithContext。于是當(dāng)客戶端斷開根 context 被 cancel上游請(qǐng)求的 context 也跟著 cancelhttp.Client會(huì)立即關(guān)閉到上游的連接。上游服務(wù)收到連接關(guān)閉也就停止生成了。這里有個(gè)坑我踩過如果你用的是自己管理的http.Client并且設(shè)置了連接池cancel 之后連接不一定會(huì)立刻關(guān)閉可能會(huì)被復(fù)用。解決辦法是在請(qǐng)求上游時(shí)給 context 加一個(gè)明確的超時(shí)并且確保Transport的DisableKeepAlives在長(zhǎng)連接場(chǎng)景下配置正確。另外goroutine 泄漏是級(jí)聯(lián)取消沒做好的典型癥狀——客戶端斷了但讀上游的 goroutine 還阻塞在Read上。我的做法是每個(gè)轉(zhuǎn)發(fā) goroutine 都select監(jiān)聽ctx.Done()一旦收到信號(hào)立即返回。2.3 背壓讓快的一方等一等慢的一方背壓是流式系統(tǒng)里最容易被忽略、出問題又最致命的一環(huán)。想象一個(gè)場(chǎng)景上游模型生成速度是每秒 100 個(gè) token下游用戶的網(wǎng)絡(luò)只能每秒接收 20 個(gè) token。如果沒有背壓網(wǎng)關(guān)內(nèi)存里會(huì)堆積越來越多的未發(fā)送數(shù)據(jù)一個(gè)請(qǐng)求堆幾 MB一千個(gè)并發(fā)就是幾個(gè) GBOOM 是遲早的事。背壓的核心思想是用阻塞傳遞壓力。當(dāng)緩沖區(qū)滿了寫入方就應(yīng)該阻塞直到消費(fèi)方騰出空間。在 Go 里帶緩沖的 channel 天然支持這個(gè)語義ch - data在緩沖滿時(shí)會(huì)阻塞當(dāng)前 goroutine。我把上游讀到的每個(gè) SSE 事件寫進(jìn)一個(gè)容量固定的 channel下游從 channel 里讀并寫回客戶端。channel 滿了上游讀取 goroutine 就阻塞自然就“背壓”到了上游——因?yàn)槲也辉購(gòu)纳嫌?socket 讀數(shù)據(jù)TCP 接收窗口會(huì)逐漸縮小最終上游的發(fā)送也會(huì)被阻塞。緩沖區(qū)容量怎么定這是個(gè)需要計(jì)算的參數(shù)。我按“單事件平均大小 × 期望緩沖事件數(shù)”來估。實(shí)測(cè)一個(gè) token 事件大約 200 字節(jié)到 1KB我取 512 字節(jié)均值。如果希望緩沖 64 個(gè)事件容量就是 32KB 左右。但 channel 存的是事件對(duì)象不是字節(jié)所以我按事件個(gè)數(shù)設(shè)容量64 到 128 之間比較合適。太小會(huì)導(dǎo)致頻繁阻塞、吞吐下降太大則失去背壓意義、內(nèi)存風(fēng)險(xiǎn)上升。3. SSE 流式轉(zhuǎn)發(fā)的核心實(shí)現(xiàn)細(xì)節(jié)3.1 SSE 協(xié)議要點(diǎn)與常見誤區(qū)SSE 的協(xié)議格式其實(shí)很簡(jiǎn)單但細(xì)節(jié)坑很多。一個(gè)標(biāo)準(zhǔn)的事件長(zhǎng)這樣event: message data: {content: 你好} data: {content: 世界}注意幾個(gè)點(diǎn)。第一每個(gè)字段后面跟一個(gè)冒號(hào)和空格然后才是值。第二事件之間用空行分隔也就是連續(xù)兩個(gè)換行符。第三data:可以出現(xiàn)多次會(huì)被拼接成多行數(shù)據(jù)。第四注釋行以冒號(hào)開頭常用來做心跳?；睢Ｗ畛Ｒ姷恼`區(qū)是換行符處理。SSE 規(guī)范要求用\n但有些上游用\r\n如果你解析時(shí)不兼容就會(huì)把\r當(dāng)成數(shù)據(jù)的一部分導(dǎo)致 JSON 解析失敗。我的做法是解析前統(tǒng)一把\r\n替換成\n。另一個(gè)誤區(qū)是忘記 flush。Go 的http.ResponseWriter默認(rèn)會(huì)緩沖你不調(diào)用Flusher.Flush()數(shù)據(jù)就卡在緩沖區(qū)里客戶端一直收不到表現(xiàn)就是“流不動(dòng)”。每個(gè)事件寫完后必須 flush這是硬性要求。還有一個(gè)容易被忽略的點(diǎn)響應(yīng)頭必須設(shè)置Content-Type: text/event-stream并且要禁用各種中間層的緩沖。我一般還會(huì)加上Cache-Control: no-cache和X-Accel-Buffering: no后者是給 Nginx 看的告訴它不要緩沖這個(gè)響應(yīng)。熱搜里那個(gè)curl sse的調(diào)試方法很實(shí)用用curl -N就能看到實(shí)時(shí)的流式輸出-N是禁用 curl 自己的緩沖。3.2 上游讀取逐行掃描與事件組裝從上游讀 SSE 流我用的是bufio.Scanner逐行讀。為什么不一次性ReadAll因?yàn)榱魇浅掷m(xù)的ReadAll會(huì)一直等到連接關(guān)閉那就完全失去流式意義了。掃描的邏輯是讀一行如果是空行說明一個(gè)事件結(jié)束把累積的data字段組裝成完整事件發(fā)出去如果是以data:開頭去掉前綴存起來如果是event:開頭記錄事件類型其他行忽略。這里要注意bufio.Scanner默認(rèn)的單行長(zhǎng)度上限是 64KB如果上游某個(gè)事件特別大比如返回了很長(zhǎng)的 JSON會(huì)報(bào)token too long。解決辦法是用scanner.Buffer把上限調(diào)大我一般設(shè)成 1MB。組裝事件時(shí)有個(gè)細(xì)節(jié)多個(gè)data:行要用\n連接這是規(guī)范要求。我見過有人直接用拼接不加換行結(jié)果 JSON 里少了換行導(dǎo)致解析出錯(cuò)。另外上游可能在流中間插入心跳注釋行以:開頭這些要直接跳過不能當(dāng)成數(shù)據(jù)。3.3 下游寫入錯(cuò)誤處理與優(yōu)雅收尾往下游寫的時(shí)候最怕的是寫了一半客戶端斷了。這時(shí)候Write會(huì)返回錯(cuò)誤你必須立即停止并且觸發(fā)取消上游。我的處理是每次Write都檢查 error一旦非 nil就 cancel 根 context 并 return。同時(shí)Flush也可能出錯(cuò)同樣要檢查。優(yōu)雅收尾指的是流正常結(jié)束時(shí)要發(fā)一個(gè)明確的結(jié)束事件。有些客戶端依賴特定的結(jié)束標(biāo)記來判斷“生成完成”。我一般會(huì)發(fā)一個(gè)event: done加空 data或者直接關(guān)閉連接。但要注意關(guān)閉連接前要確保所有緩沖數(shù)據(jù)都 flush 出去了否則最后幾個(gè) token 會(huì)丟。我踩過一次坑上游發(fā)完最后一個(gè) token 后立即關(guān)閉連接我的掃描循環(huán)退出但最后一個(gè)事件還在 channel 里沒被下游消費(fèi)結(jié)果用戶看到的是“回答少了一個(gè)字”。解決辦法是掃描循環(huán)退出后先關(guān)閉 channel讓下游把剩余事件消費(fèi)完再結(jié)束響應(yīng)。4. 級(jí)聯(lián)取消與背壓的落地實(shí)現(xiàn)4.1 取消信號(hào)的傳播路徑與 goroutine 管理一個(gè)請(qǐng)求進(jìn)來我至少會(huì)起兩個(gè) goroutine一個(gè)讀上游一個(gè)寫下游。這兩個(gè) goroutine 通過 channel 通信。取消信號(hào)要從根 context 傳到這兩個(gè) goroutine。讀上游的 goroutine 里scanner.Scan()是阻塞的它不響應(yīng) context。所以我不能只靠select ctx.Done()因?yàn)?Scan 卡住的時(shí)候 select 根本沒機(jī)會(huì)執(zhí)行。解決辦法是在單獨(dú)的 goroutine 里做 Scan主循環(huán) select 監(jiān)聽結(jié)果 channel 和 ctx.Done()?；蛘吒?jiǎn)單給上游請(qǐng)求設(shè)置 context當(dāng) context cancel 時(shí)底層的resp.Body會(huì)被關(guān)閉Scan()會(huì)返回 false循環(huán)自然退出。這是最干凈的做法依賴http.Client對(duì) context 的支持。寫下游的 goroutine 里Write和Flush也可能阻塞下游網(wǎng)絡(luò)慢。這時(shí)候如果客戶端斷開Write會(huì)返回錯(cuò)誤goroutine 退出。但如果它阻塞在 Write 上context cancel 不會(huì)直接中斷它。所以我在寫之前會(huì)先select檢查一次 ctx寫完再檢查一次盡量縮短阻塞窗口。極端情況下依賴 HTTP server 的連接關(guān)閉來中斷 Write。goroutine 泄漏的排查我用go tool pprof看 goroutine profile如果發(fā)現(xiàn)某個(gè)函數(shù)對(duì)應(yīng)的 goroutine 數(shù)量持續(xù)增長(zhǎng)基本就是泄漏了。常見原因是 channel 沒人讀導(dǎo)致發(fā)送方永久阻塞或者 context 沒傳到位。4.2 背壓緩沖區(qū)的容量計(jì)算與動(dòng)態(tài)調(diào)整前面說了用帶緩沖 channel 做背壓容量我定在 64。但這個(gè)值不是拍腦袋來的我做了個(gè)簡(jiǎn)單的計(jì)算。假設(shè)單個(gè)事件平均 512 字節(jié)64 個(gè)事件就是 32KB。單請(qǐng)求內(nèi)存占用 32KB 緩沖 goroutine 棧約 8KB 其他開銷算 50KB。1000 并發(fā)就是 50MB完全可控。如果容量設(shè)成 1024單請(qǐng)求就是 512KB1000 并發(fā) 512MB風(fēng)險(xiǎn)就大了。所以 64 是個(gè)內(nèi)存和吞吐的平衡點(diǎn)。但固定容量有個(gè)問題不同上游的生成速度差異很大。有的模型每秒吐 200 個(gè) token有的只有 10 個(gè)。對(duì)慢上游64 的緩沖綽綽有余對(duì)快上游可能頻繁觸發(fā)背壓。我的優(yōu)化思路是根據(jù)上游響應(yīng)頭里的速率提示或者前 N 個(gè)事件的到達(dá)間隔動(dòng)態(tài)調(diào)整容量。不過實(shí)測(cè)下來固定 64 在大多數(shù)場(chǎng)景已經(jīng)夠用動(dòng)態(tài)調(diào)整的復(fù)雜度收益比不高我就沒上。如果你要接的上游特別快可以調(diào)到 128 或 256但要同步監(jiān)控內(nèi)存。還有一個(gè)細(xì)節(jié)channel 關(guān)閉的時(shí)機(jī)。讀上游的 goroutine 結(jié)束時(shí)關(guān)閉 channel寫下游的 goroutine 用for range ch消費(fèi)channel 關(guān)閉后循環(huán)自動(dòng)退出。這樣不需要額外的 done 信號(hào)邏輯很干凈。但要注意關(guān)閉 channel 的只能是發(fā)送方多個(gè)發(fā)送方時(shí)要用sync.Once或者 WaitGroup 保證只關(guān)一次。4.3 超時(shí)策略idle timeout 與總超時(shí)的配合熱搜里那個(gè)idle timeout waiting for SSE報(bào)錯(cuò)根因就是超時(shí)設(shè)置不當(dāng)。LLM 流式響應(yīng)有個(gè)特點(diǎn)首 token 可能等很久但 token 之間間隔很短。如果你設(shè)一個(gè)總超時(shí) 30 秒那長(zhǎng)回答直接被砍如果你設(shè)一個(gè) idle 超時(shí)多久沒數(shù)據(jù)就斷那首 token 等待期可能誤傷。我的策略是雙超時(shí)。一個(gè) idle timeout比如 60 秒只要 60 秒內(nèi)有任何數(shù)據(jù)到達(dá)就重置一個(gè)總超時(shí)比如 10 分鐘兜底防止請(qǐng)求永遠(yuǎn)掛著。idle timeout 用time.Timer實(shí)現(xiàn)每次讀到數(shù)據(jù)就Reset?？偝瑫r(shí)直接用 context 的WithTimeout。這里有個(gè)坑time.Timer的Reset在 Go 1.23 之前有競(jìng)態(tài)問題需要先Stop再 drain channel。Go 1.23 之后Reset語義修正了可以直接用。如果你用的是老版本記得處理這個(gè)細(xì)節(jié)。另外idle timeout 觸發(fā)后要發(fā)一個(gè)明確的錯(cuò)誤事件給客戶端而不是直接斷連這樣前端能給出友好提示。5. 常見問題排查與避坑實(shí)錄5.1 流斷在半路從現(xiàn)象到根因的排查路徑“流斷在半路”是我遇到最多的問題排查起來有一套固定路徑。第一步確認(rèn)是上游斷還是下游斷?？慈罩纠镒詈笠粭l成功轉(zhuǎn)發(fā)的事件如果上游還在發(fā)但下游沒收到問題在下游寫入或網(wǎng)絡(luò)如果上游本身就不發(fā)了問題在上游或網(wǎng)關(guān)到上游的連接。第二步檢查超時(shí)配置。idle timeout和中間層Nginx、負(fù)載均衡的超時(shí)都要看。Nginx 默認(rèn)proxy_read_timeout是 60 秒如果你的 idle timeout 也是 60 秒兩者疊加可能提前觸發(fā)。我一般把網(wǎng)關(guān)的 idle timeout 設(shè)得比中間層小讓網(wǎng)關(guān)先感知、先處理。第三步看連接是否被復(fù)用。HTTP/1.1 的 keep-alive 在長(zhǎng)連接場(chǎng)景下可能導(dǎo)致連接被錯(cuò)誤復(fù)用尤其是上游返回了不完整的響應(yīng)時(shí)。我一般對(duì)上游請(qǐng)求設(shè)置Connection: close或者禁用 keep-alive犧牲一點(diǎn)性能換穩(wěn)定性。第四步抓包確認(rèn)。用tcpdump或者 Go 的httptrace看 TCP 層的 FIN/RST 是誰先發(fā)的。這一步能定位到具體是哪一端的連接被關(guān)閉。5.2 會(huì)話丟失與 400 錯(cuò)誤的處理熱搜里那個(gè)missing_session_id的 400 錯(cuò)誤本質(zhì)是會(huì)話狀態(tài)在轉(zhuǎn)發(fā)鏈路上沒有正確傳遞。LLM 服務(wù)通常用 session id 來關(guān)聯(lián)多輪對(duì)話的上下文。如果網(wǎng)關(guān)在轉(zhuǎn)發(fā)時(shí)丟了 header 或者 cookie上游就找不到會(huì)話。我的處理是接入層把所有和會(huì)話相關(guān)的 header比如X-Session-Id、Authorization、Cookie原樣透?jìng)鞯缴嫌尾蛔鋈魏芜^濾。同時(shí)如果上游返回 400 且錯(cuò)誤信息里提到 session我會(huì)在網(wǎng)關(guān)層記錄一條明確的日志包含請(qǐng)求 id 和原始 header方便排查。還有一種情況是上游要求 session id 在請(qǐng)求體里而不是 header 里。這時(shí)候適配層要做轉(zhuǎn)換從 header 提取出來塞進(jìn) body。這個(gè)邏輯因上游而異我把它做成可配置的用配置文件描述“從哪取、放到哪”。5.3 常見問題速查表現(xiàn)象可能原因排查方法解決方向流不動(dòng)客戶端無數(shù)據(jù)忘記 Flush檢查寫入后是否調(diào)用 Flush每個(gè)事件后強(qiáng)制 Flush流斷在半路idle timeout 或中間層超時(shí)對(duì)比網(wǎng)關(guān)和 Nginx 超時(shí)配置網(wǎng)關(guān)超時(shí)設(shè)小先感知回答少最后一個(gè)字channel 關(guān)閉時(shí)機(jī)不對(duì)檢查掃描退出后是否消費(fèi)完剩余事件先關(guān) channel 再結(jié)束響應(yīng)內(nèi)存持續(xù)增長(zhǎng)背壓失效或 goroutine 泄漏pprof 看 goroutine 和 heap檢查 channel 容量和 context 傳遞400 missing session會(huì)話 header 丟失對(duì)比客戶端和上游收到的 header透?jìng)鲿?huì)話相關(guān) headerJSON 解析失敗換行符或 data 拼接問題打印原始事件內(nèi)容統(tǒng)一換行符多行 data 用 \n 連接上游不停止生成級(jí)聯(lián)取消未生效檢查上游請(qǐng)求是否用了根 context用 NewRequestWithContext5.4 幾個(gè)我踩過的獨(dú)家坑第一個(gè)坑bufio.Scanner的默認(rèn)緩沖太小。上游返回一個(gè)大的 JSON 事件時(shí)直接報(bào)錯(cuò)退出表現(xiàn)就是流突然斷。調(diào)大scanner.Buffer的 max 到 1MB 解決。第二個(gè)坑http.Flusher不是所有 ResponseWriter 都支持。如果你用了某些中間件包裝了 ResponseWriter可能拿不到 Flusher。我的做法是在接入層用類型斷言檢查拿不到就報(bào)錯(cuò)絕不靜默降級(jí)。第三個(gè)坑context 傳遞時(shí)被意外覆蓋。有一次我在適配層里用context.Background()新建了請(qǐng)求結(jié)果級(jí)聯(lián)取消完全失效客戶端斷了上游還在跑。排查了半天才發(fā)現(xiàn)是這里。教訓(xùn)是任何地方新建 context 都要問自己“這個(gè) context 的父級(jí)是誰”。第四個(gè)坑channel 容量設(shè)太大反而更慢。我一度把容量調(diào)到 1024 想提升吞吐結(jié)果發(fā)現(xiàn)延遲反而上升了因?yàn)閿?shù)據(jù)在緩沖區(qū)里排隊(duì)客戶端要等更久才看到第一個(gè) token。背壓緩沖區(qū)不是越大越好它影響的是延遲和內(nèi)存的權(quán)衡。6. 性能驗(yàn)證與后續(xù)可擴(kuò)展方向6.1 壓測(cè)方法與關(guān)鍵指標(biāo)驗(yàn)證網(wǎng)關(guān)性能我用的是自己寫的一個(gè)壓測(cè)工具模擬 N 個(gè)并發(fā)客戶端每個(gè)客戶端發(fā)一個(gè)請(qǐng)求并持續(xù)讀取流直到結(jié)束。關(guān)鍵指標(biāo)有三個(gè)首 token 延遲TTFT、吞吐每秒完成請(qǐng)求數(shù)、內(nèi)存占用。TTFT 反映的是網(wǎng)關(guān)引入的額外延遲。理想情況下網(wǎng)關(guān)的 TTFT 應(yīng)該和直連上游差不多額外開銷在毫秒級(jí)。我實(shí)測(cè)下來網(wǎng)關(guān)引入的 TTFT 增加在 5ms 以內(nèi)可以接受。吞吐方面單機(jī) 8 核跑 1000 并發(fā)CPU 占用在 40% 左右瓶頸主要在上游的生成速度而不是網(wǎng)關(guān)本身。這說明網(wǎng)關(guān)的轉(zhuǎn)發(fā)邏輯沒有成為瓶頸。內(nèi)存占用是重點(diǎn)觀察對(duì)象。1000 并發(fā)下RSS 穩(wěn)定在 200MB 左右沒有持續(xù)增長(zhǎng)說明背壓和 goroutine 管理是有效的。如果看到內(nèi)存曲線一直往上走那一定是哪里泄漏了。6.2 可以繼續(xù)做的優(yōu)化第一個(gè)方向是連接池優(yōu)化。目前對(duì)上游用的是默認(rèn) Transport連接復(fù)用策略可以調(diào)優(yōu)比如設(shè)置MaxIdleConnsPerHost來匹配并發(fā)量減少建連開銷。第二個(gè)方向是多上游負(fù)載均衡?，F(xiàn)在只接一個(gè)上游如果要做高可用需要加一層選擇邏輯根據(jù)上游的健康狀態(tài)和負(fù)載來分發(fā)請(qǐng)求。這塊可以結(jié)合健康檢查和加權(quán)輪詢。第三個(gè)方向是可觀測(cè)性增強(qiáng)。目前只有基礎(chǔ)日志可以加 Prometheus 指標(biāo)暴露活躍連接數(shù)、背壓觸發(fā)次數(shù)、取消次數(shù)等方便做容量規(guī)劃和告警。第四個(gè)方向是請(qǐng)求級(jí)別的限流。防止單個(gè)用戶占用過多并發(fā)影響其他人?？梢杂昧钆仆八惴ò从脩艟S度限流。這套網(wǎng)關(guān)我從零寫到現(xiàn)在大概迭代了三個(gè)版本第一版只做了基本轉(zhuǎn)發(fā)第二版加了取消和背壓第三版做了分層重構(gòu)和錯(cuò)誤處理完善。每一版都是被真實(shí)問題逼出來的。如果你也在做類似的東西我的建議是先把級(jí)聯(lián)取消和背壓這兩個(gè)基礎(chǔ)打牢它們決定了系統(tǒng)的下限SSE 的細(xì)節(jié)處理決定了上限。別急著加功能先把流的正確性做扎實(shí)后面擴(kuò)展起來才不痛苦。 從零構(gòu)建LLM推理網(wǎng)關(guān)：SSE流式轉(zhuǎn)發(fā)、級(jí)聯(lián)取消與背壓控制實(shí)戰(zhàn)
1. 為什么我要自己造一個(gè) LLM 推理網(wǎng)關(guān)1.1 從一次線上事故說起去年年底我在幫一個(gè)內(nèi)部工具做 AI 能力接入。架構(gòu)很簡(jiǎn)單前端一個(gè)聊天框后端一個(gè) Go 服務(wù)收到請(qǐng)求后轉(zhuǎn)發(fā)給上游的大模型接口拿到流式響應(yīng)再吐回給瀏覽器。上線第一周沒什么問題第二周開始陸續(xù)有用戶反饋“回答到一半就卡住了”“刷新之后重新問一遍才行”。我去翻日志發(fā)現(xiàn)兩類報(bào)錯(cuò)反復(fù)出現(xiàn)。一類是stream disconnected before completion: idle timeout waiting for SSE另一類是上游返回400: {type:missing_session_id,message:error from provider}。前者說明流式連接在傳輸過程中被靜默掐斷了后者說明會(huì)話狀態(tài)在轉(zhuǎn)發(fā)鏈路上丟了。這兩個(gè)問題單獨(dú)看都不復(fù)雜但它們暴露的是同一個(gè)根因我把“轉(zhuǎn)發(fā)”這件事想得太簡(jiǎn)單了。一個(gè)真正能扛住生產(chǎn)流量的 LLM 推理網(wǎng)關(guān)至少要解決四件事SSE 流式轉(zhuǎn)發(fā)的正確性、客戶端斷開時(shí)的級(jí)聯(lián)取消、上游生產(chǎn)速度超過下游消費(fèi)速度時(shí)的背壓控制、以及會(huì)話與錯(cuò)誤狀態(tài)的一致性維護(hù)。這四件事在普通 HTTP 轉(zhuǎn)發(fā)里幾乎不用考慮但在 LLM 場(chǎng)景下全部變成了一等公民。這篇文章就是我把這套網(wǎng)關(guān)從零重寫一遍的完整記錄包含設(shè)計(jì)取舍、關(guān)鍵代碼結(jié)構(gòu)、參數(shù)計(jì)算和踩過的坑。1.2 這個(gè)網(wǎng)關(guān)到底解決什么問題先把定位說清楚。它不是模型推理框架不負(fù)責(zé)加載權(quán)重、不做 batch 調(diào)度它站在客戶端和上游推理服務(wù)之間干的是“流量治理”的活。你可以把它理解成一個(gè)專門為流式 LLM 響應(yīng)優(yōu)化的反向代理層。它要解決的核心痛點(diǎn)有這么幾個(gè)。第一LLM 響應(yīng)是逐 token 生成的一個(gè)請(qǐng)求可能持續(xù)幾十秒甚至幾分鐘傳統(tǒng)的“收完再轉(zhuǎn)發(fā)”模式完全不可用必須邊收邊轉(zhuǎn)。第二用戶隨時(shí)可能關(guān)掉頁(yè)面或點(diǎn)“停止生成”這時(shí)候如果網(wǎng)關(guān)不主動(dòng)取消上游請(qǐng)求上游會(huì)繼續(xù)燒算力成本直接翻倍。第三上游生成速度快、下游網(wǎng)絡(luò)慢的時(shí)候如果沒有背壓機(jī)制內(nèi)存里的緩沖區(qū)會(huì)無限膨脹最后 OOM。第四SSE 協(xié)議本身對(duì)連接中斷很敏感任何中間環(huán)節(jié)的超時(shí)設(shè)置不當(dāng)都會(huì)導(dǎo)致“流斷在半路”。適合讀這篇的人正在做 AI 應(yīng)用后端、需要自己搭一層網(wǎng)關(guān)的 Go 開發(fā)者被 SSE 斷流問題折磨過的同學(xué)以及想理解“級(jí)聯(lián)取消”和“背壓”這兩個(gè)詞在真實(shí)系統(tǒng)里到底怎么落地的人。不需要你是 Go 專家但至少要寫過 HTTP 服務(wù)知道 goroutine 和 channel 大概是怎么回事。1.3 技術(shù)選型為什么是 Go為什么是 SSE選 Go 的理由很直接。這個(gè)網(wǎng)關(guān)的本質(zhì)是高并發(fā) I/O 密集型轉(zhuǎn)發(fā)每個(gè)請(qǐng)求都要維持一條長(zhǎng)連接同時(shí)可能有成百上千個(gè)請(qǐng)求在飛。Go 的 goroutine 在這種場(chǎng)景下幾乎是降維打擊——每個(gè)連接一個(gè) goroutine寫起來像同步代碼跑起來是異步性能內(nèi)存占用還低。換成 Java 要處理線程池和回調(diào)地獄換成 Node 單線程又怕 CPU 密集的解析拖垮事件循環(huán)。Go 的net/http標(biāo)準(zhǔn)庫(kù)對(duì)流式響應(yīng)的支持也很成熟Flusher接口直接就能把緩沖區(qū)刷給客戶端。選 SSE 而不是 WebSocket是因?yàn)?LLM 的場(chǎng)景是單向流式推送?？蛻舳税l(fā)一次請(qǐng)求服務(wù)端持續(xù)推 token不需要雙向?qū)崟r(shí)通信。SSE 基于普通 HTTP天然穿透各種代理和負(fù)載均衡實(shí)現(xiàn)成本低瀏覽器端EventSource或者fetch加流讀取都能處理。WebSocket 雖然更靈活但要處理握手升級(jí)、心跳保活、幀解析對(duì)這個(gè)場(chǎng)景來說是過度設(shè)計(jì)。熱搜詞里有人問“web socket 和 sse”的區(qū)別一句話總結(jié)需要服務(wù)端主動(dòng)推、且只需要單向推選 SSE需要雙向低延遲交互選 WebSocket。2. 整體架構(gòu)與核心設(shè)計(jì)思路2.1 三層結(jié)構(gòu)接入層、轉(zhuǎn)發(fā)層、上游適配層我把網(wǎng)關(guān)拆成三層每層職責(zé)單一方便單獨(dú)測(cè)試和替換。接入層負(fù)責(zé)和客戶端打交道解析請(qǐng)求、校驗(yàn)參數(shù)、建立 SSE 響應(yīng)頭、管理客戶端連接的生命周期。這一層最關(guān)鍵的是拿到一個(gè)context.Context它會(huì)在客戶端斷開時(shí)被 cancel這個(gè) context 會(huì)一路往下傳成為級(jí)聯(lián)取消的源頭。轉(zhuǎn)發(fā)層是核心負(fù)責(zé)從上游讀取流、解析 SSE 事件、寫入下游。它要同時(shí)監(jiān)聽兩個(gè)方向上游的數(shù)據(jù)到達(dá)、下游的寫入完成。這里我用一個(gè)io.Pipe或者帶緩沖的 channel 來解耦讀寫速率背壓邏輯就藏在這個(gè)緩沖區(qū)的大小和阻塞行為里。上游適配層負(fù)責(zé)和具體的推理服務(wù)對(duì)接拼裝請(qǐng)求體、處理鑒權(quán)、解析不同廠商的響應(yīng)格式。因?yàn)椴煌嫌蔚?SSE 事件格式不一樣有的用data:有的用event:加data:這一層做歸一化把上游格式轉(zhuǎn)成統(tǒng)一的內(nèi)部事件結(jié)構(gòu)再交給轉(zhuǎn)發(fā)層。這樣分層的好處是換上游只需要改適配層背壓和取消邏輯完全不用動(dòng)。我實(shí)測(cè)下來接一個(gè)新的上游服務(wù)適配層大概 100 行代碼就能搞定。2.2 級(jí)聯(lián)取消一個(gè) context 串起整條鏈路級(jí)聯(lián)取消這個(gè)詞聽起來玄乎本質(zhì)就是一個(gè)取消信號(hào)沿著調(diào)用鏈往下傳每一層都響應(yīng)它。在 Go 里就是context.Context的 cancel 機(jī)制。具體到我的網(wǎng)關(guān)客戶端發(fā)起請(qǐng)求接入層用r.Context()作為根 context。這個(gè) context 在客戶端斷開連接時(shí)會(huì)被 HTTP server 自動(dòng) cancel。轉(zhuǎn)發(fā)層拿著這個(gè) context 去請(qǐng)求上游用的是http.NewRequestWithContext。于是當(dāng)客戶端斷開根 context 被 cancel上游請(qǐng)求的 context 也跟著 cancelhttp.Client會(huì)立即關(guān)閉到上游的連接。上游服務(wù)收到連接關(guān)閉也就停止生成了。這里有個(gè)坑我踩過如果你用的是自己管理的http.Client并且設(shè)置了連接池cancel 之后連接不一定會(huì)立刻關(guān)閉可能會(huì)被復(fù)用。解決辦法是在請(qǐng)求上游時(shí)給 context 加一個(gè)明確的超時(shí)并且確保Transport的DisableKeepAlives在長(zhǎng)連接場(chǎng)景下配置正確。另外goroutine 泄漏是級(jí)聯(lián)取消沒做好的典型癥狀——客戶端斷了但讀上游的 goroutine 還阻塞在Read上。我的做法是每個(gè)轉(zhuǎn)發(fā) goroutine 都select監(jiān)聽ctx.Done()一旦收到信號(hào)立即返回。2.3 背壓讓快的一方等一等慢的一方背壓是流式系統(tǒng)里最容易被忽略、出問題又最致命的一環(huán)。想象一個(gè)場(chǎng)景上游模型生成速度是每秒 100 個(gè) token下游用戶的網(wǎng)絡(luò)只能每秒接收 20 個(gè) token。如果沒有背壓網(wǎng)關(guān)內(nèi)存里會(huì)堆積越來越多的未發(fā)送數(shù)據(jù)一個(gè)請(qǐng)求堆幾 MB一千個(gè)并發(fā)就是幾個(gè) GBOOM 是遲早的事。背壓的核心思想是用阻塞傳遞壓力。當(dāng)緩沖區(qū)滿了寫入方就應(yīng)該阻塞直到消費(fèi)方騰出空間。在 Go 里帶緩沖的 channel 天然支持這個(gè)語義ch - data在緩沖滿時(shí)會(huì)阻塞當(dāng)前 goroutine。我把上游讀到的每個(gè) SSE 事件寫進(jìn)一個(gè)容量固定的 channel下游從 channel 里讀并寫回客戶端。channel 滿了上游讀取 goroutine 就阻塞自然就“背壓”到了上游——因?yàn)槲也辉購(gòu)纳嫌?socket 讀數(shù)據(jù)TCP 接收窗口會(huì)逐漸縮小最終上游的發(fā)送也會(huì)被阻塞。緩沖區(qū)容量怎么定這是個(gè)需要計(jì)算的參數(shù)。我按“單事件平均大小 × 期望緩沖事件數(shù)”來估。實(shí)測(cè)一個(gè) token 事件大約 200 字節(jié)到 1KB我取 512 字節(jié)均值。如果希望緩沖 64 個(gè)事件容量就是 32KB 左右。但 channel 存的是事件對(duì)象不是字節(jié)所以我按事件個(gè)數(shù)設(shè)容量64 到 128 之間比較合適。太小會(huì)導(dǎo)致頻繁阻塞、吞吐下降太大則失去背壓意義、內(nèi)存風(fēng)險(xiǎn)上升。3. SSE 流式轉(zhuǎn)發(fā)的核心實(shí)現(xiàn)細(xì)節(jié)3.1 SSE 協(xié)議要點(diǎn)與常見誤區(qū)SSE 的協(xié)議格式其實(shí)很簡(jiǎn)單但細(xì)節(jié)坑很多。一個(gè)標(biāo)準(zhǔn)的事件長(zhǎng)這樣event: message data: {content: 你好} data: {content: 世界}注意幾個(gè)點(diǎn)。第一每個(gè)字段后面跟一個(gè)冒號(hào)和空格然后才是值。第二事件之間用空行分隔也就是連續(xù)兩個(gè)換行符。第三data:可以出現(xiàn)多次會(huì)被拼接成多行數(shù)據(jù)。第四注釋行以冒號(hào)開頭常用來做心跳?；睢Ｗ畛Ｒ姷恼`區(qū)是換行符處理。SSE 規(guī)范要求用\n但有些上游用\r\n如果你解析時(shí)不兼容就會(huì)把\r當(dāng)成數(shù)據(jù)的一部分導(dǎo)致 JSON 解析失敗。我的做法是解析前統(tǒng)一把\r\n替換成\n。另一個(gè)誤區(qū)是忘記 flush。Go 的http.ResponseWriter默認(rèn)會(huì)緩沖你不調(diào)用Flusher.Flush()數(shù)據(jù)就卡在緩沖區(qū)里客戶端一直收不到表現(xiàn)就是“流不動(dòng)”。每個(gè)事件寫完后必須 flush這是硬性要求。還有一個(gè)容易被忽略的點(diǎn)響應(yīng)頭必須設(shè)置Content-Type: text/event-stream并且要禁用各種中間層的緩沖。我一般還會(huì)加上Cache-Control: no-cache和X-Accel-Buffering: no后者是給 Nginx 看的告訴它不要緩沖這個(gè)響應(yīng)。熱搜里那個(gè)curl sse的調(diào)試方法很實(shí)用用curl -N就能看到實(shí)時(shí)的流式輸出-N是禁用 curl 自己的緩沖。3.2 上游讀取逐行掃描與事件組裝從上游讀 SSE 流我用的是bufio.Scanner逐行讀。為什么不一次性ReadAll因?yàn)榱魇浅掷m(xù)的ReadAll會(huì)一直等到連接關(guān)閉那就完全失去流式意義了。掃描的邏輯是讀一行如果是空行說明一個(gè)事件結(jié)束把累積的data字段組裝成完整事件發(fā)出去如果是以data:開頭去掉前綴存起來如果是event:開頭記錄事件類型其他行忽略。這里要注意bufio.Scanner默認(rèn)的單行長(zhǎng)度上限是 64KB如果上游某個(gè)事件特別大比如返回了很長(zhǎng)的 JSON會(huì)報(bào)token too long。解決辦法是用scanner.Buffer把上限調(diào)大我一般設(shè)成 1MB。組裝事件時(shí)有個(gè)細(xì)節(jié)多個(gè)data:行要用\n連接這是規(guī)范要求。我見過有人直接用拼接不加換行結(jié)果 JSON 里少了換行導(dǎo)致解析出錯(cuò)。另外上游可能在流中間插入心跳注釋行以:開頭這些要直接跳過不能當(dāng)成數(shù)據(jù)。3.3 下游寫入錯(cuò)誤處理與優(yōu)雅收尾往下游寫的時(shí)候最怕的是寫了一半客戶端斷了。這時(shí)候Write會(huì)返回錯(cuò)誤你必須立即停止并且觸發(fā)取消上游。我的處理是每次Write都檢查 error一旦非 nil就 cancel 根 context 并 return。同時(shí)Flush也可能出錯(cuò)同樣要檢查。優(yōu)雅收尾指的是流正常結(jié)束時(shí)要發(fā)一個(gè)明確的結(jié)束事件。有些客戶端依賴特定的結(jié)束標(biāo)記來判斷“生成完成”。我一般會(huì)發(fā)一個(gè)event: done加空 data或者直接關(guān)閉連接。但要注意關(guān)閉連接前要確保所有緩沖數(shù)據(jù)都 flush 出去了否則最后幾個(gè) token 會(huì)丟。我踩過一次坑上游發(fā)完最后一個(gè) token 后立即關(guān)閉連接我的掃描循環(huán)退出但最后一個(gè)事件還在 channel 里沒被下游消費(fèi)結(jié)果用戶看到的是“回答少了一個(gè)字”。解決辦法是掃描循環(huán)退出后先關(guān)閉 channel讓下游把剩余事件消費(fèi)完再結(jié)束響應(yīng)。4. 級(jí)聯(lián)取消與背壓的落地實(shí)現(xiàn)4.1 取消信號(hào)的傳播路徑與 goroutine 管理一個(gè)請(qǐng)求進(jìn)來我至少會(huì)起兩個(gè) goroutine一個(gè)讀上游一個(gè)寫下游。這兩個(gè) goroutine 通過 channel 通信。取消信號(hào)要從根 context 傳到這兩個(gè) goroutine。讀上游的 goroutine 里scanner.Scan()是阻塞的它不響應(yīng) context。所以我不能只靠select ctx.Done()因?yàn)?Scan 卡住的時(shí)候 select 根本沒機(jī)會(huì)執(zhí)行。解決辦法是在單獨(dú)的 goroutine 里做 Scan主循環(huán) select 監(jiān)聽結(jié)果 channel 和 ctx.Done()?；蛘吒?jiǎn)單給上游請(qǐng)求設(shè)置 context當(dāng) context cancel 時(shí)底層的resp.Body會(huì)被關(guān)閉Scan()會(huì)返回 false循環(huán)自然退出。這是最干凈的做法依賴http.Client對(duì) context 的支持。寫下游的 goroutine 里Write和Flush也可能阻塞下游網(wǎng)絡(luò)慢。這時(shí)候如果客戶端斷開Write會(huì)返回錯(cuò)誤goroutine 退出。但如果它阻塞在 Write 上context cancel 不會(huì)直接中斷它。所以我在寫之前會(huì)先select檢查一次 ctx寫完再檢查一次盡量縮短阻塞窗口。極端情況下依賴 HTTP server 的連接關(guān)閉來中斷 Write。goroutine 泄漏的排查我用go tool pprof看 goroutine profile如果發(fā)現(xiàn)某個(gè)函數(shù)對(duì)應(yīng)的 goroutine 數(shù)量持續(xù)增長(zhǎng)基本就是泄漏了。常見原因是 channel 沒人讀導(dǎo)致發(fā)送方永久阻塞或者 context 沒傳到位。4.2 背壓緩沖區(qū)的容量計(jì)算與動(dòng)態(tài)調(diào)整前面說了用帶緩沖 channel 做背壓容量我定在 64。但這個(gè)值不是拍腦袋來的我做了個(gè)簡(jiǎn)單的計(jì)算。假設(shè)單個(gè)事件平均 512 字節(jié)64 個(gè)事件就是 32KB。單請(qǐng)求內(nèi)存占用 32KB 緩沖 goroutine 棧約 8KB 其他開銷算 50KB。1000 并發(fā)就是 50MB完全可控。如果容量設(shè)成 1024單請(qǐng)求就是 512KB1000 并發(fā) 512MB風(fēng)險(xiǎn)就大了。所以 64 是個(gè)內(nèi)存和吞吐的平衡點(diǎn)。但固定容量有個(gè)問題不同上游的生成速度差異很大。有的模型每秒吐 200 個(gè) token有的只有 10 個(gè)。對(duì)慢上游64 的緩沖綽綽有余對(duì)快上游可能頻繁觸發(fā)背壓。我的優(yōu)化思路是根據(jù)上游響應(yīng)頭里的速率提示或者前 N 個(gè)事件的到達(dá)間隔動(dòng)態(tài)調(diào)整容量。不過實(shí)測(cè)下來固定 64 在大多數(shù)場(chǎng)景已經(jīng)夠用動(dòng)態(tài)調(diào)整的復(fù)雜度收益比不高我就沒上。如果你要接的上游特別快可以調(diào)到 128 或 256但要同步監(jiān)控內(nèi)存。還有一個(gè)細(xì)節(jié)channel 關(guān)閉的時(shí)機(jī)。讀上游的 goroutine 結(jié)束時(shí)關(guān)閉 channel寫下游的 goroutine 用for range ch消費(fèi)channel 關(guān)閉后循環(huán)自動(dòng)退出。這樣不需要額外的 done 信號(hào)邏輯很干凈。但要注意關(guān)閉 channel 的只能是發(fā)送方多個(gè)發(fā)送方時(shí)要用sync.Once或者 WaitGroup 保證只關(guān)一次。4.3 超時(shí)策略idle timeout 與總超時(shí)的配合熱搜里那個(gè)idle timeout waiting for SSE報(bào)錯(cuò)根因就是超時(shí)設(shè)置不當(dāng)。LLM 流式響應(yīng)有個(gè)特點(diǎn)首 token 可能等很久但 token 之間間隔很短。如果你設(shè)一個(gè)總超時(shí) 30 秒那長(zhǎng)回答直接被砍如果你設(shè)一個(gè) idle 超時(shí)多久沒數(shù)據(jù)就斷那首 token 等待期可能誤傷。我的策略是雙超時(shí)。一個(gè) idle timeout比如 60 秒只要 60 秒內(nèi)有任何數(shù)據(jù)到達(dá)就重置一個(gè)總超時(shí)比如 10 分鐘兜底防止請(qǐng)求永遠(yuǎn)掛著。idle timeout 用time.Timer實(shí)現(xiàn)每次讀到數(shù)據(jù)就Reset?？偝瑫r(shí)直接用 context 的WithTimeout。這里有個(gè)坑time.Timer的Reset在 Go 1.23 之前有競(jìng)態(tài)問題需要先Stop再 drain channel。Go 1.23 之后Reset語義修正了可以直接用。如果你用的是老版本記得處理這個(gè)細(xì)節(jié)。另外idle timeout 觸發(fā)后要發(fā)一個(gè)明確的錯(cuò)誤事件給客戶端而不是直接斷連這樣前端能給出友好提示。5. 常見問題排查與避坑實(shí)錄5.1 流斷在半路從現(xiàn)象到根因的排查路徑“流斷在半路”是我遇到最多的問題排查起來有一套固定路徑。第一步確認(rèn)是上游斷還是下游斷?？慈罩纠镒詈笠粭l成功轉(zhuǎn)發(fā)的事件如果上游還在發(fā)但下游沒收到問題在下游寫入或網(wǎng)絡(luò)如果上游本身就不發(fā)了問題在上游或網(wǎng)關(guān)到上游的連接。第二步檢查超時(shí)配置。idle timeout和中間層Nginx、負(fù)載均衡的超時(shí)都要看。Nginx 默認(rèn)proxy_read_timeout是 60 秒如果你的 idle timeout 也是 60 秒兩者疊加可能提前觸發(fā)。我一般把網(wǎng)關(guān)的 idle timeout 設(shè)得比中間層小讓網(wǎng)關(guān)先感知、先處理。第三步看連接是否被復(fù)用。HTTP/1.1 的 keep-alive 在長(zhǎng)連接場(chǎng)景下可能導(dǎo)致連接被錯(cuò)誤復(fù)用尤其是上游返回了不完整的響應(yīng)時(shí)。我一般對(duì)上游請(qǐng)求設(shè)置Connection: close或者禁用 keep-alive犧牲一點(diǎn)性能換穩(wěn)定性。第四步抓包確認(rèn)。用tcpdump或者 Go 的httptrace看 TCP 層的 FIN/RST 是誰先發(fā)的。這一步能定位到具體是哪一端的連接被關(guān)閉。5.2 會(huì)話丟失與 400 錯(cuò)誤的處理熱搜里那個(gè)missing_session_id的 400 錯(cuò)誤本質(zhì)是會(huì)話狀態(tài)在轉(zhuǎn)發(fā)鏈路上沒有正確傳遞。LLM 服務(wù)通常用 session id 來關(guān)聯(lián)多輪對(duì)話的上下文。如果網(wǎng)關(guān)在轉(zhuǎn)發(fā)時(shí)丟了 header 或者 cookie上游就找不到會(huì)話。我的處理是接入層把所有和會(huì)話相關(guān)的 header比如X-Session-Id、Authorization、Cookie原樣透?jìng)鞯缴嫌尾蛔鋈魏芜^濾。同時(shí)如果上游返回 400 且錯(cuò)誤信息里提到 session我會(huì)在網(wǎng)關(guān)層記錄一條明確的日志包含請(qǐng)求 id 和原始 header方便排查。還有一種情況是上游要求 session id 在請(qǐng)求體里而不是 header 里。這時(shí)候適配層要做轉(zhuǎn)換從 header 提取出來塞進(jìn) body。這個(gè)邏輯因上游而異我把它做成可配置的用配置文件描述“從哪取、放到哪”。5.3 常見問題速查表現(xiàn)象可能原因排查方法解決方向流不動(dòng)客戶端無數(shù)據(jù)忘記 Flush檢查寫入后是否調(diào)用 Flush每個(gè)事件后強(qiáng)制 Flush流斷在半路idle timeout 或中間層超時(shí)對(duì)比網(wǎng)關(guān)和 Nginx 超時(shí)配置網(wǎng)關(guān)超時(shí)設(shè)小先感知回答少最后一個(gè)字channel 關(guān)閉時(shí)機(jī)不對(duì)檢查掃描退出后是否消費(fèi)完剩余事件先關(guān) channel 再結(jié)束響應(yīng)內(nèi)存持續(xù)增長(zhǎng)背壓失效或 goroutine 泄漏pprof 看 goroutine 和 heap檢查 channel 容量和 context 傳遞400 missing session會(huì)話 header 丟失對(duì)比客戶端和上游收到的 header透?jìng)鲿?huì)話相關(guān) headerJSON 解析失敗換行符或 data 拼接問題打印原始事件內(nèi)容統(tǒng)一換行符多行 data 用 \n 連接上游不停止生成級(jí)聯(lián)取消未生效檢查上游請(qǐng)求是否用了根 context用 NewRequestWithContext5.4 幾個(gè)我踩過的獨(dú)家坑第一個(gè)坑bufio.Scanner的默認(rèn)緩沖太小。上游返回一個(gè)大的 JSON 事件時(shí)直接報(bào)錯(cuò)退出表現(xiàn)就是流突然斷。調(diào)大scanner.Buffer的 max 到 1MB 解決。第二個(gè)坑http.Flusher不是所有 ResponseWriter 都支持。如果你用了某些中間件包裝了 ResponseWriter可能拿不到 Flusher。我的做法是在接入層用類型斷言檢查拿不到就報(bào)錯(cuò)絕不靜默降級(jí)。第三個(gè)坑context 傳遞時(shí)被意外覆蓋。有一次我在適配層里用context.Background()新建了請(qǐng)求結(jié)果級(jí)聯(lián)取消完全失效客戶端斷了上游還在跑。排查了半天才發(fā)現(xiàn)是這里。教訓(xùn)是任何地方新建 context 都要問自己“這個(gè) context 的父級(jí)是誰”。第四個(gè)坑channel 容量設(shè)太大反而更慢。我一度把容量調(diào)到 1024 想提升吞吐結(jié)果發(fā)現(xiàn)延遲反而上升了因?yàn)閿?shù)據(jù)在緩沖區(qū)里排隊(duì)客戶端要等更久才看到第一個(gè) token。背壓緩沖區(qū)不是越大越好它影響的是延遲和內(nèi)存的權(quán)衡。6. 性能驗(yàn)證與后續(xù)可擴(kuò)展方向6.1 壓測(cè)方法與關(guān)鍵指標(biāo)驗(yàn)證網(wǎng)關(guān)性能我用的是自己寫的一個(gè)壓測(cè)工具模擬 N 個(gè)并發(fā)客戶端每個(gè)客戶端發(fā)一個(gè)請(qǐng)求并持續(xù)讀取流直到結(jié)束。關(guān)鍵指標(biāo)有三個(gè)首 token 延遲TTFT、吞吐每秒完成請(qǐng)求數(shù)、內(nèi)存占用。TTFT 反映的是網(wǎng)關(guān)引入的額外延遲。理想情況下網(wǎng)關(guān)的 TTFT 應(yīng)該和直連上游差不多額外開銷在毫秒級(jí)。我實(shí)測(cè)下來網(wǎng)關(guān)引入的 TTFT 增加在 5ms 以內(nèi)可以接受。吞吐方面單機(jī) 8 核跑 1000 并發(fā)CPU 占用在 40% 左右瓶頸主要在上游的生成速度而不是網(wǎng)關(guān)本身。這說明網(wǎng)關(guān)的轉(zhuǎn)發(fā)邏輯沒有成為瓶頸。內(nèi)存占用是重點(diǎn)觀察對(duì)象。1000 并發(fā)下RSS 穩(wěn)定在 200MB 左右沒有持續(xù)增長(zhǎng)說明背壓和 goroutine 管理是有效的。如果看到內(nèi)存曲線一直往上走那一定是哪里泄漏了。6.2 可以繼續(xù)做的優(yōu)化第一個(gè)方向是連接池優(yōu)化。目前對(duì)上游用的是默認(rèn) Transport連接復(fù)用策略可以調(diào)優(yōu)比如設(shè)置MaxIdleConnsPerHost來匹配并發(fā)量減少建連開銷。第二個(gè)方向是多上游負(fù)載均衡?，F(xiàn)在只接一個(gè)上游如果要做高可用需要加一層選擇邏輯根據(jù)上游的健康狀態(tài)和負(fù)載來分發(fā)請(qǐng)求。這塊可以結(jié)合健康檢查和加權(quán)輪詢。第三個(gè)方向是可觀測(cè)性增強(qiáng)。目前只有基礎(chǔ)日志可以加 Prometheus 指標(biāo)暴露活躍連接數(shù)、背壓觸發(fā)次數(shù)、取消次數(shù)等方便做容量規(guī)劃和告警。第四個(gè)方向是請(qǐng)求級(jí)別的限流。防止單個(gè)用戶占用過多并發(fā)影響其他人?？梢杂昧钆仆八惴ò从脩艟S度限流。這套網(wǎng)關(guān)我從零寫到現(xiàn)在大概迭代了三個(gè)版本第一版只做了基本轉(zhuǎn)發(fā)第二版加了取消和背壓第三版做了分層重構(gòu)和錯(cuò)誤處理完善。每一版都是被真實(shí)問題逼出來的。如果你也在做類似的東西我的建議是先把級(jí)聯(lián)取消和背壓這兩個(gè)基礎(chǔ)打牢它們決定了系統(tǒng)的下限SSE 的細(xì)節(jié)處理決定了上限。別急著加功能先把流的正確性做扎實(shí)后面擴(kuò)展起來才不痛苦。