這次我們來看一個(gè)面向 AI agent 的基礎(chǔ)設(shè)施項(xiàng)目Loopers。它發(fā)布于 Hacker News 的 Show HN核心定位是給 AI agent 調(diào)用鏈加一層可控的閘門——一個(gè)fail-closed故障關(guān)閉模式的反向代理同時(shí)內(nèi)置斷路器circuit breaker機(jī)制。簡單說它解決的不是怎么讓模型生成更好而是當(dāng)模型服務(wù)、API 網(wǎng)關(guān)或下游工具出現(xiàn)異常時(shí)你的 agent 系統(tǒng)應(yīng)該如何優(yōu)雅地停下來而不是帶著錯(cuò)誤繼續(xù)跑。很多人在本地搭過 agent 應(yīng)用通常的做法是直接把請求打到 OpenAI、Anthropic 或各類開源模型的 API 上。單機(jī) demo 沒問題但一旦進(jìn)入多用戶、多任務(wù)、多 Provider 切換的生產(chǎn)環(huán)境問題就來了API Key 怎么統(tǒng)一管理多個(gè)上游服務(wù)如何做路由某個(gè)模型服務(wù)開始超時(shí)或返回 5xx 時(shí)怎么避免請求全部堆積導(dǎo)致雪崩Loopers 這類工具就是為這些問題設(shè)計(jì)的。這篇文章會做四件事先講清楚 fail-closed 反向代理和斷路器在 AI agent 架構(gòu)里解決什么問題再給出一套環(huán)境準(zhǔn)備和部署驗(yàn)證流程然后重點(diǎn)演示如何測試斷路器的三種狀態(tài)以及 fail-closed 的攔截行為最后補(bǔ)充接口調(diào)用、批量任務(wù)、性能觀察和常見排錯(cuò)思路。如果你正在做 agent 的工程化或者負(fù)責(zé)把 LLM 服務(wù)接入公司內(nèi)部網(wǎng)關(guān)這篇文章可以直接參考落地。1. 核心能力速覽Loopers 的定位可以從名字和關(guān)鍵詞拆出來Loopers 指的是 agent 的循環(huán)執(zhí)行過程LLM 調(diào)用鏈、工具調(diào)用鏈、重試循環(huán)fail-closed reverse proxy 和 circuit breaker 則是它的兩個(gè)核心機(jī)制。先把這類項(xiàng)目通常具備的能力整理成一張速覽表方便快速判斷它適不適合你能力項(xiàng)說明項(xiàng)目類型AI agent 基礎(chǔ)設(shè)施層組件反向代理 斷路器核心機(jī)制Fail-closed默認(rèn)拒絕/關(guān)閉策略主要功能請求路由、上游服務(wù)管理、故障隔離、熔斷保護(hù)適用對象多模型/多 Provider 接入、Agent 生產(chǎn)化部署部署方式通常是獨(dú)立服務(wù)部署通過 HTTP 轉(zhuǎn)發(fā)請求是否支持 API自身提供代理接口和管理接口是否支持批量任務(wù)取決于調(diào)用方設(shè)計(jì)代理層可做隊(duì)列與限流顯存要求無純 CPU 服務(wù)與模型推理解耦支持平臺Linux / macOS / Windows 容器環(huán)境均可運(yùn)行適合場景生產(chǎn)環(huán)境 Agent 網(wǎng)關(guān)、多 API Key 管理、故障演練需要說明的是由于 Loopers 目前公開信息以項(xiàng)目定位為主文章里涉及具體參數(shù)、端口和配置項(xiàng)的地方我會給出這類組件的通用模板你需要按實(shí)際項(xiàng)目 README 和配置文件調(diào)整。這并不影響你理解它的設(shè)計(jì)思路和驗(yàn)證流程。2. 適用場景與使用邊界2.1 適合誰Loopers 適合的是一類比較明確的場景你已經(jīng)在用 LLM 做正經(jīng)業(yè)務(wù)而不是只跑實(shí)驗(yàn)。具體包括把 OpenAI、Anthropic、本地 vLLM 等多個(gè)上游服務(wù)統(tǒng)一收斂到一個(gè)入口方便切換和灰度。在 agent 的工具調(diào)用鏈里加了大量外部 API擔(dān)心某個(gè)下游服務(wù)故障拖垮整個(gè)任務(wù)。需要在代理層統(tǒng)一管理 API Key、做流控、做審計(jì)日志。做故障演練驗(yàn)證上游服務(wù)掛了之后agent 系統(tǒng)會不會失控。2.2 能解決什么問題一個(gè)典型的 agent 執(zhí)行循環(huán)里可能會發(fā)生這些故障模型服務(wù)超時(shí)、返回格式異常、工具調(diào)用接口 5xx、API Key 被限流。如果沒有代理層保護(hù)agent 可能會無限重試、不斷消耗 token、把錯(cuò)誤結(jié)果繼續(xù)往下一步傳。Loopers 的思路是給這些調(diào)用加一道保護(hù)層上游不正常時(shí)代理層直接快速失敗fail fast或拒絕放行fail-closed而不是把錯(cuò)誤轉(zhuǎn)發(fā)給下游。2.3 不適合什么場景單機(jī)本地跑個(gè) LangChain demo沒必要上代理層。想找一個(gè)能提升生成質(zhì)量或 prompt 編排的框架這不是它的定位。需要圖形化界面做 prompt 調(diào)試這類代理組件通常只有配置文件和 API沒有復(fù)雜的 WebUI。2.4 使用邊界與合規(guī)提醒代理層會經(jīng)過你的全部 LLM 請求。這意味著它能看到 prompt、返回內(nèi)容以及 API Key。接入使用時(shí)需要注意API Key 和敏感配置不要寫死在倉庫里用環(huán)境變量或密鑰管理服務(wù)注入。涉及人臉、聲音、個(gè)人隱私或版權(quán)素材的生成與調(diào)用必須確認(rèn)授權(quán)和合規(guī)邊界。代理日志如果記錄完整請求體要評估數(shù)據(jù)脫敏策略避免敏感信息落盤。生產(chǎn)環(huán)境部署時(shí)代理管理接口不要暴露到公網(wǎng)避免被惡意調(diào)用。3. 環(huán)境準(zhǔn)備與前置條件Loopers 本身是網(wǎng)絡(luò)服務(wù)組件不依賴 GPU也不涉及模型推理所以環(huán)境準(zhǔn)備相對輕量。下面是一套通用檢查清單檢查項(xiàng)建議操作系統(tǒng)Linux 服務(wù)器優(yōu)先macOS 本地開發(fā)可用運(yùn)行環(huán)境Docker / Docker Compose或直接運(yùn)行編譯后的二進(jìn)制目標(biāo)端口代理服務(wù)端口 管理/健康檢查端口確保未被占用上游服務(wù)至少準(zhǔn)備一個(gè)可用的 LLM API 服務(wù)用于測試網(wǎng)絡(luò)能訪問上游 API 服務(wù)容器環(huán)境注意 DNS 和代理配置配置文件YAML 或 JSON 格式的路由與熔斷策略配置檢查端口占用的通用命令# 檢查 8080 端口是否被占用 lsof -i :8080 # 或使用 ss ss -tlnp | grep 8080如果你的環(huán)境里沒有現(xiàn)成的 LLM 服務(wù)也可以先用一個(gè)簡單的本地 HTTP 測試服務(wù)模擬上游比如用 Python 起一個(gè)返回固定 JSON 的接口用來驗(yàn)證代理轉(zhuǎn)發(fā)和熔斷行為。后面會給出具體做法。4. 安裝部署與啟動方式Loopers 的部署方式取決于項(xiàng)目實(shí)際提供的產(chǎn)物。通常這類組件會有兩種分發(fā)形式Docker 鏡像和可直接執(zhí)行的二進(jìn)制。下面分別給出通用部署思路。4.1 Docker 部署模板如果項(xiàng)目提供 Docker 鏡像典型的啟動方式如下具體鏡像名需要按實(shí)際項(xiàng)目替換docker run -d \ --name looper-proxy \ -p 8080:8080 \ -p 9090:9090 \ -e LOOPERS_LOG_LEVELinfo \ -v $(pwd)/config.yaml:/etc/loopers/config.yaml \ looper-proxy:latest這里 8080 是代理入口端口9090 是健康檢查/管理端口。掛載配置文件后代理會按配置讀取路由規(guī)則和熔斷策略。4.2 二進(jìn)制啟動模板# 下載對應(yīng)平臺的壓縮包并解壓后 ./loopers --config config.yaml --port 8080啟動后觀察日志看到類似proxy listening on 0.0.0.0:8080的輸出說明服務(wù)已就緒。4.3 配置文件結(jié)構(gòu)模板下面是一份通用的 fail-closed 反向代理配置模板覆蓋路由、上游節(jié)點(diǎn)、斷路器和健康檢查。字段名和結(jié)構(gòu)以實(shí)際項(xiàng)目為準(zhǔn)這里用于說明配置思路proxy: listen: :8080 fail_closed: true # 關(guān)鍵開關(guān)默認(rèn)拒絕不放行 routes: - name: llm-openai match: path_prefix: /v1/chat/completions upstreams: - url: https://api.openai.com weight: 1 circuit_breaker: max_failures: 3 # 連續(xù)失敗次數(shù)閾值 cooldown_seconds: 30 # 熔斷后的冷卻時(shí)間 half_open_max_requests: 1 # 半開狀態(tài)放行探測請求數(shù) - name: llm-local match: path_prefix: /v1/models upstreams: - url: http://127.0.0.1:8001 weight: 1 circuit_breaker: max_failures: 5 cooldown_seconds: 60 half_open_max_requests: 2 health_check: listen: :9090 path: /healthz核心概念是三個(gè)fail-closed故障關(guān)閉請求在沒有明確放行規(guī)則、或上游健康狀態(tài)未知時(shí)默認(rèn)拒絕或返回安全響應(yīng)而不是盲目轉(zhuǎn)發(fā)。circuit breaker斷路器維護(hù)三種狀態(tài)——關(guān)閉closed、打開open、半開half-open。正常時(shí)關(guān)閉放行連續(xù)失敗達(dá)到閾值后打開直接快速失敗冷卻期后進(jìn)入半開放行少量探測請求若成功則恢復(fù)關(guān)閉。路由按請求路徑或 Header 分發(fā)到不同上游服務(wù)。5. 功能測試與效果驗(yàn)證部署完成后建議按下面的順序逐項(xiàng)驗(yàn)證。這是最關(guān)鍵的一部分直接決定你能不能信任這個(gè)代理層。5.1 驗(yàn)證 1基礎(chǔ)轉(zhuǎn)發(fā)先用最簡單的請求驗(yàn)證代理能否正確轉(zhuǎn)發(fā)到上游。假設(shè)代理監(jiān)聽 8080 端口上游是本地測試服務(wù)curl -X POST http://127.0.0.1:8080/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer test-key \ -d {model: gpt-4o-mini, messages: [{role: user, content: hello}]}預(yù)期結(jié)果代理把請求轉(zhuǎn)發(fā)到上游返回上游的響應(yīng)體。判斷標(biāo)準(zhǔn)響應(yīng)狀態(tài)碼 200且返回內(nèi)容與直連上游一致。5.2 驗(yàn)證 2fail-closed 行為fail-closed 驗(yàn)證的核心是當(dāng)代理無法判斷請求是否安全、或上游處于不可用狀態(tài)時(shí)它應(yīng)該拒絕放行而不是試著轉(zhuǎn)發(fā)看看。測試方法在配置里故意把上游地址改成一個(gè)不存在的端口然后發(fā)起請求curl -i -X POST http://127.0.0.1:8080/v1/chat/completions \ -H Content-Type: application/json \ -d {model: test, messages: []}預(yù)期結(jié)果代理返回 502/503 或自定義錯(cuò)誤響應(yīng)而不是長時(shí)間掛起等待。如果配置了 fail_closed: true即使沒有匹配到任何路由也應(yīng)該返回明確的拒絕響應(yīng)。另一個(gè)測試點(diǎn)是未匹配路由的請求發(fā)送一個(gè)不在任何 route 規(guī)則里的路徑確認(rèn)代理默認(rèn)拒絕而不是透傳到某個(gè)默認(rèn)后端。這是 fail-closed 和普通反向代理的明顯區(qū)別。判斷標(biāo)準(zhǔn)請求在幾秒內(nèi)快速失敗沒有長時(shí)間超時(shí)。錯(cuò)誤信息里能看出是代理層攔截而不是上游返回的錯(cuò)誤。日志記錄了拒絕原因。5.3 驗(yàn)證 3斷路器熔斷斷路器測試建議模擬上游連續(xù)失敗的場景。可以用一個(gè)簡單的 Python 服務(wù)來模擬故障上游# fail_server.py - 模擬故障上游 from http.server import HTTPServer, BaseHTTPRequestHandler import time class Handler(BaseHTTPRequestHandler): def do_POST(self): # 先連續(xù)返回 500模擬上游故障 self.send_response(500) self.send_header(Content-Type, application/json) self.end_headers() self.wfile.write(b{error: upstream failure}) def log_message(self, format, *args): pass if __name__ __main__: server HTTPServer((127.0.0.1, 8001), Handler) print(fail server listening on 8001) server.serve_forever()啟動這個(gè)故障服務(wù)后連續(xù)向代理發(fā)送請求for i in $(seq 1 10); do curl -s -o /dev/null -w %{http_code}\n -X POST \ http://127.0.0.1:8080/v1/chat/completions \ -H Content-Type: application/json \ -d {model: test, messages: []} done預(yù)期觀察前幾個(gè)請求返回 500上游故障。當(dāng)連續(xù)失敗次數(shù)達(dá)到max_failures閾值后斷路器打開后續(xù)請求被代理層直接攔截返回 503 或快速失敗不再打到上游。觀察代理日志可以看到斷路器狀態(tài)從 closed 變?yōu)?open。5.4 驗(yàn)證 4半開狀態(tài)恢復(fù)把故障服務(wù)停掉換成一個(gè)正常返回 200 的服務(wù)然后繼續(xù)發(fā)請求。斷路器在冷卻期結(jié)束后會進(jìn)入半開half-open狀態(tài)放行少量探測請求。判斷標(biāo)準(zhǔn)半開狀態(tài)下只有部分請求被放行到上游。如果探測請求成功斷路器恢復(fù)到 closed 狀態(tài)后續(xù)流量全部正常轉(zhuǎn)發(fā)。如果探測請求仍然失敗斷路器再次進(jìn)入 open 狀態(tài)并重新計(jì)時(shí)。這個(gè)測試很關(guān)鍵它驗(yàn)證了系統(tǒng)能壞也能恢復(fù)。5.5 驗(yàn)證 5長尾請求與超時(shí)在 agent 場景里L(fēng)LM 請求通常耗時(shí)較長。需要測試代理層對慢請求的處理配置上游服務(wù)在收到請求后 sleep 10 秒再返回。觀察代理是否設(shè)置了合理的讀/寫超時(shí)。確認(rèn)超時(shí)后代理返回的錯(cuò)誤碼是否正確以及是否計(jì)入斷路器失敗次數(shù)。6. 接口 API 與批量任務(wù)6.1 代理接口Loopers 對外暴露的代理接口通常直接兼容 OpenAI 或 Anthropic 的請求格式。調(diào)用方只需要把 base_url 改成代理地址即可。以 OpenAI SDK 為例from openai import OpenAI client OpenAI( base_urlhttp://127.0.0.1:8080/v1, # 代理入口 api_keyyour-api-key ) response client.chat.completions.create( modelgpt-4o-mini, messages[{role: user, content: hello}] ) print(response.choices[0].message.content)這在實(shí)際部署里非常有價(jià)值你的業(yè)務(wù)代碼不需要大改只需要換 base_url就能把流量切到代理層管理之下。6.2 管理接口與健康檢查代理服務(wù)一般還會提供管理接口用于查看狀態(tài)和主動觸發(fā)熔斷操作。常見接口包括GET /healthz存活檢查。GET /metricsPrometheus 指標(biāo)查看請求數(shù)、失敗率、斷路器狀態(tài)。GET /circuits查看所有路由的斷路器狀態(tài)。POST /circuits/{name}/open手動打開某條路由的斷路器用于故障演練。# 查看健康狀態(tài) curl http://127.0.0.1:9090/healthz # 查看斷路器狀態(tài) curl http://127.0.0.1:9090/circuits6.3 批量任務(wù)設(shè)計(jì)代理層本身不承擔(dān)業(yè)務(wù)批量調(diào)度但可以在代理層之上做批量任務(wù)的穩(wěn)定保障。典型的做法是批量任務(wù)逐個(gè)發(fā)送請求到代理。代理通過斷路器自動隔離故障上游避免批量任務(wù)因?yàn)閱蝹€(gè)上游故障全部失敗。調(diào)用方需要處理 429限流和 503熔斷中對這兩種狀態(tài)做重試或延遲策略。import requests import time def send_with_retry(prompt, max_retries3): url http://127.0.0.1:8080/v1/chat/completions payload { model: gpt-4o-mini, messages: [{role: user, content: prompt}] } for attempt in range(max_retries): resp requests.post(url, jsonpayload, timeout60) if resp.status_code 200: return resp.json() elif resp.status_code in (429, 503): # 熔斷或限流退避后重試 wait_time 2 ** attempt print(fattempt {attempt 1} failed: {resp.status_code}, waiting {wait_time}s) time.sleep(wait_time) else: resp.raise_for_status() raise RuntimeError(max retries exceeded) result send_with_retry(你好請介紹一下自己) print(result)這里給調(diào)用方的建議是不要對 5xx 做無限重試要區(qū)分上游臨時(shí)錯(cuò)誤和斷路器已打開。前者可以退避重試后者應(yīng)該等待冷卻期結(jié)束再繼續(xù)否則重試只是給代理層增加無效請求負(fù)擔(dān)。7. 資源占用與性能觀察Loopers 這類代理組件不跑模型資源占用主要來自網(wǎng)絡(luò)轉(zhuǎn)發(fā)和請求日志理論上非常輕量。但在生產(chǎn)環(huán)境中仍然需要關(guān)注幾個(gè)性能指標(biāo)。7.1 觀察指標(biāo)建議從四個(gè)維度觀察指標(biāo)觀察方式異常信號CPUtop / htop單核持續(xù) 100%協(xié)議解析或日志寫入成為瓶頸內(nèi)存top / free -h內(nèi)存持續(xù)增長不回落可能存在連接泄漏連接數(shù)ss -s / netstat連接數(shù)異常增長上游響應(yīng)慢導(dǎo)致連接堆積請求延遲curl -w 或 Prometheusp99 延遲顯著高于直連上游7.2 影響性能的關(guān)鍵點(diǎn)日志級別debug 級別會記錄完整請求體高并發(fā)下對磁盤和 CPU 都有壓力。生產(chǎn)環(huán)境建議 error 或 info。上游超時(shí)設(shè)置如果代理層超時(shí)時(shí)間設(shè)置得比上游還長斷路器無法及時(shí)觸發(fā)請求會長時(shí)間掛起。超時(shí)時(shí)間建議比上游 SLA 略短。連接池如果代理支持 HTTP 連接池配置需要根據(jù)上游服務(wù)的并發(fā)能力調(diào)整。連接池太小會導(dǎo)致請求排隊(duì)太大可能打滿上游。單條請求體大小agent 場景里工具返回結(jié)果、歷史消息可能很大。如果代理層對請求體大小做了限制需要按實(shí)際場景調(diào)整。7.3 降低資源占用的通用手段關(guān)閉訪問日志或采用采樣日志。開啟 gzip 響應(yīng)壓縮如果代理層支持。把管理接口和代理接口分開端口暴露管理接口限內(nèi)網(wǎng)訪問。批量任務(wù)在低峰時(shí)段運(yùn)行控制并發(fā)數(shù)。8. 常見問題與排查方法問題現(xiàn)象可能原因排查方式解決方案代理啟動后端口無法監(jiān)聽端口被占用或權(quán)限不足lsof -i :8080檢查占用更換端口或停止占用進(jìn)程請求一直超時(shí)上游服務(wù)不可達(dá)或代理超時(shí)設(shè)置過長curl 直連上游測試檢查網(wǎng)絡(luò)連通性適當(dāng)縮小代理超時(shí)上游已恢復(fù)但代理仍拒絕請求斷路器仍處于 open 狀態(tài)冷卻期未結(jié)束查看 /circuits 接口狀態(tài)等待冷卻結(jié)束或手動重置斷路器fail-closed 不生效配置中未開啟該開關(guān)或存在默認(rèn)路由檢查配置文件 fail_closed 字段明確設(shè)置 fail_closed: true移除默認(rèn)放行規(guī)則批量任務(wù)大量 503上游故障觸發(fā)了斷路器查看上游日志和斷路器狀態(tài)等待冷卻期或切換上游調(diào)用方增加退避重試API Key 泄露風(fēng)險(xiǎn)日志記錄了 Authorization 頭檢查日志脫敏配置開啟敏感頭脫敏禁止 debug 日志上線Docker 內(nèi)訪問不到宿主機(jī)服務(wù)容器網(wǎng)絡(luò)與宿主機(jī)隔離檢查容器網(wǎng)絡(luò)模式使用 host 網(wǎng)絡(luò)或配置正確的上游地址代理層重啟后配置丟失配置文件未掛載或使用默認(rèn)配置檢查啟動命令和掛載路徑確保配置文件持久化掛載排查通用思路先確認(rèn)上游本身是否正常再確認(rèn)代理配置是否生效最后看斷路器狀態(tài)和日志。大部分問題都能在這三步里定位。9. 最佳實(shí)踐與使用建議9.1 配置管理配置文件納入版本管理但密鑰用環(huán)境變量或密鑰管理服務(wù)注入不要寫進(jìn) YAML。為每個(gè)上游服務(wù)單獨(dú)配置路由和斷路器參數(shù)不要所有上游共用一套閾值。本地 vLLM 和 OpenAI 的失敗率差異很大統(tǒng)一閾值會導(dǎo)致誤熔斷或熔斷不及時(shí)。9.2 故障演練定期手動觸發(fā)斷路器驗(yàn)證熔斷后業(yè)務(wù)方的降級表現(xiàn)是否正常。用前面提到的 fail_server.py 模擬上游 500觀察 agent 系統(tǒng)在上游故障時(shí)的行為是否可控。演練后記錄熔斷時(shí)間、恢復(fù)時(shí)間、業(yè)務(wù)影響范圍。9.3 日志與審計(jì)代理層只記錄必要信息請求 ID、上游名稱、狀態(tài)碼、耗時(shí)、斷路器狀態(tài)。如果業(yè)務(wù)需要 debug 完整請求內(nèi)容建議臨時(shí)開啟并在完成后關(guān)閉。長期保存的日志要脫敏Prompt 里的用戶數(shù)據(jù)屬于敏感信息。9.4 安全加固代理管理接口綁定內(nèi)網(wǎng)地址或加認(rèn)證。代理入口如果需要公網(wǎng)暴露前面再疊加一層網(wǎng)關(guān)做認(rèn)證。避免代理層無限轉(zhuǎn)發(fā)設(shè)置最大請求體大小和單請求時(shí)長上限。對上游 API Key 做最小權(quán)限管理不要使用萬能 Key。9.5 Agent 業(yè)務(wù)側(cè)配合agent 的每個(gè) LLM 調(diào)用和工具調(diào)用都設(shè)置獨(dú)立超時(shí)。代理層熔斷打開的 503業(yè)務(wù)側(cè)要做降級換上游、走緩存、或終止任務(wù)而不是死循環(huán)重試。在 agent 循環(huán)里加入最大失敗次數(shù)限制防止單個(gè)故障任務(wù)無限消耗資源。善用請求 ID 串聯(lián)日志從代理層到業(yè)務(wù)層形成完整鏈路追蹤。這最后一點(diǎn)特別值得強(qiáng)調(diào)。如果你們的 agent 系統(tǒng)已經(jīng)出現(xiàn)了任務(wù)卡死、重試風(fēng)暴、token 費(fèi)用異常上漲這類問題根源往往不是模型能力而是調(diào)用鏈缺少故障隔離。代理層的價(jià)值就在這里它把上游可能失敗這件事變成了一個(gè)可預(yù)期、可觀測、可恢復(fù)的工程問題而不是靠運(yùn)氣。建議先把一個(gè)上游服務(wù)接入 Loopers 做灰度驗(yàn)證確認(rèn)故障切換和熔斷恢復(fù)都符合預(yù)期后再逐步擴(kuò)展路由規(guī)則。生產(chǎn)環(huán)境更換網(wǎng)關(guān)類的組件最忌諱一步到位小流量驗(yàn)證、觀察指標(biāo)、逐步放量才是穩(wěn)妥的路徑。