后端API網(wǎng)關(guān)模型推理服務(wù)AI Agent【免費下載鏈接】semantic-routerAn open, programmable decision layer for models and compute.項目地址https://gitcode.com/gh_mirrors/sem/semantic-router點擊查看免費下載本文是 semantic-router 中 VSRVector Semantic Router決策跟蹤響應(yīng)頭x-vsr-selected-category、x-vsr-selected-reasoning、x-vsr-selected-model的實戰(zhàn)技術(shù)指南。它面向需要調(diào)試路由結(jié)果、監(jiān)控模型選擇與推理模式、以及基于路由元數(shù)據(jù)做成本核算的開發(fā)者與運維人員。讀完本文你將掌握這些頭字段的完整取值語義、觸發(fā)條件與排除條件并理解它們?nèi)绾斡烧Z義路由器ext_proc 流水線在響應(yīng)頭階段寫入以及如何在真實請求中驗證與消費這些元數(shù)據(jù)。概述什么是 VSR 決策跟蹤響應(yīng)頭semantic-router 作為模型與算力之間的可編程決策層會在請求處理過程中執(zhí)行分類domain classification、推理模式判定reasoning mode與模型選擇model selection等一系列路由決策。為了讓這些看不見的決策過程變得可觀測路由器會自動在成功的響應(yīng)上附加一組以x-vsr-selected-為前綴的響應(yīng)頭用于跟蹤 VSR 的決策信息。這些頭幫助開發(fā)與運維團隊回答三個核心問題這個請求被 VSR 歸到了哪個類別category這個請求是否啟用了推理模式reasoning這個請求最終由哪個模型model處理在源碼中這些響應(yīng)頭的名稱以常量形式集中定義在 src/semantic-router/pkg/headers/headers.go 的 VSR Decision Tracking Headers 區(qū)塊VSRSelectedCategory x-vsr-selected-category—— 領(lǐng)域分類器domain classifierMMLU 類別選出的類別VSRSelectedReasoning x-vsr-selected-reasoning—— 推理模式判定結(jié)果on/offVSRSelectedModel x-vsr-selected-model—— VSR 為該請求選定的模型。三個核心頭的字段語義x-vsr-selected-category屬性說明描述VSR 在領(lǐng)域分類domain classification階段為該請求選定的類別示例值math、business、biology、computer_science何時添加VSR 成功將請求分類到某個類別時該值來源于領(lǐng)域分類器MMLU 類別體系。從源碼看類別信息既可能來自請求體分類階段也可能在決策匹配階段通過extractDecisionCategory從命中的規(guī)則中提取——見 src/semantic-router/pkg/extproc/req_filter_classification_runtime.go它掃描形如domain:xxx的匹配規(guī)則取出domain:前綴之后的類別名寫入ctx.VSRSelectedCategory。x-vsr-selected-reasoning屬性說明描述該請求是否被判定為需要啟用推理模式取值on—— 啟用推理模式off—— 關(guān)閉推理模式何時添加VSR 做出推理模式?jīng)Q策時自動模式與顯式模型選擇均適用在 src/semantic-router/pkg/extproc/recorder.go 的trackVSRDecision中可以看到寫入邏輯當(dāng)useReasoning為真時置on否則置off。推理模式的最終決策由模型選擇算法如 entropy 推理判定產(chǎn)出并通過決策記錄、指標與鏈路追蹤routing.backend.resolved事件一并暴露。x-vsr-selected-model屬性說明描述VSR 為處理該請求而選定的模型示例值deepseek-v31、phi4、gpt-4何時添加VSR 完成模型選擇時自動路由或顯式模型指定均可觸發(fā)頭字段的添加條件三個前提同時滿足根據(jù)文檔與源碼實現(xiàn)只有同時滿足以下三個條件時決策跟蹤響應(yīng)頭才會被附加請求成功上游返回 HTTP 200-299未命中緩存響應(yīng)不是從響應(yīng)緩存response cache直接返回的VSR 實際執(zhí)行了路由決策在請求處理過程中 VSR 做出了路由判斷分類、推理模式或模型選擇。這三個條件的判斷邏輯集中在響應(yīng)頭處理階段。在 src/semantic-router/pkg/extproc/processor_res_header.go 中handleResponseHeaders會先從 Envoy 的響應(yīng)頭中解析上游狀態(tài)碼:status隨后調(diào)用 src/semantic-router/pkg/extproc/processor_res_header_mutation.go 的buildResponseHeaderMutation來組裝要寫入的響應(yīng)頭。其關(guān)鍵分支如下ctx.VSRCacheHit為真時直接跳過全部 VSR 決策頭緩存命中意味著沒有重新執(zhí)行路由isSuccessful為假4xx/5xx時只保留基礎(chǔ)契約頭不輸出決策跟蹤頭成功且未命中緩存時先輸出最終路由事實decision/algorithm/model 等再根據(jù)調(diào)試開關(guān)決定是否輸出中間細節(jié)頭。示例響應(yīng)一個真實的路由決策跟蹤響應(yīng)頭示例如下文檔原始示例HTTP/1.1 200 OK Content-Type: application/json x-vsr-selected-category: math x-vsr-selected-reasoning: on x-vsr-selected-model: deepseek-v31 { id: chatcmpl-123, object: chat.completion, created: 1677652288, model: deepseek-v31, choices: [ { index: 0, message: { role: assistant, content: The derivative of x^2 3x 1 is 2x 3. }, finish_reason: stop } ] }注意響應(yīng)體中的model字段反映的是實際推理模型而x-vsr-selected-model頭則是路由器在決策階段選定的模型二者通常一致但通過頭字段你能確認路由決策時的模型選擇而不是請求方自行指定的模型。響應(yīng)頭不會被添加的情形文檔明確了三種不會添加決策跟蹤頭的典型場景緩存命中Cache Hit響應(yīng)直接來自緩存沒有發(fā)生 VSR 處理。此時連決策頭也不會輸出在 v0.4 契約下緩存命中響應(yīng)也不攜帶x-vsr-schema-version/x-vsr-response-path基礎(chǔ)頭緩存載荷原樣透傳。錯誤響應(yīng)Error Responses上游返回 4xx 或 5xx 狀態(tài)碼。缺少 VSR 信息Missing VSR InformationVSR 決策信息不可用——正常運行時不應(yīng)發(fā)生例如請求被跳過處理或決策階段未執(zhí)行。這些分支在源碼測試中有逐一對應(yīng)的斷言。例如 src/semantic-router/pkg/extproc/extproc_test.go 的TestVSRHeadersNotAddedOnCacheHit構(gòu)造了VSRCacheHit: true的上下文斷言headerMutation.GetSetHeaders()為空src/semantic-router/pkg/extproc/extproc_test.go 的TestVSRHeadersNotAddedOnErrorResponse構(gòu)造 500 狀態(tài)碼斷言錯誤響應(yīng)上只保留 2 個基礎(chǔ)契約頭x-vsr-schema-version與x-vsr-response-path而x-vsr-selected-category、x-vsr-selected-model等決策頭一律不出現(xiàn)。源碼級實現(xiàn)剖析響應(yīng)頭從決策到落盤1. 頭常量定義所有自定義 HTTP 頭遵循非標準頭的x-前綴約定統(tǒng)一維護在 src/semantic-router/pkg/headers/headers.go。每個常量都有明確的 Go 注釋說明取值語義與示例并被 src/semantic-router/pkg/headers/headers_test.go 的TestHeaderConstants斷言鎖定——防止頭名字符串被意外改寫。2. 響應(yīng)頭組裝responseHeaderMutationBuildersrc/semantic-router/pkg/extproc/processor_res_header_mutation.go 中的responseHeaderMutationBuilder是響應(yīng)頭的組裝器核心方法addString有兩個值得注意的行為空值跳過value 為空字符串時不輸出該頭所以部分信息場景下空字段不會以空值頭出現(xiàn)去重同一 key 只寫入一次防止重復(fù)頭。在此基礎(chǔ)上addFinalDecisionHeaders 負責(zé)在每次成功響應(yīng)上輸出最終路由事實決策名、算法、所選模型、路由延遲毫秒數(shù)、回退嘗試次數(shù)等其中包括x-vsr-selected-model而 addDecisionDetailHeaders 負責(zé)輸出中間細節(jié)頭x-vsr-selected-category、x-vsr-selected-reasoning、x-vsr-selected-modality等。3. v0.4 契約下的默認面與調(diào)試面需要特別說明當(dāng)前倉庫源碼v0.4 響應(yīng)頭契約已經(jīng)對三類頭做了分級這與 v0.2 文檔描述一律附加的語義存在演進差異x-vsr-selected-model屬于默認面default surface每次成功、未命中緩存的響應(yīng)都會攜帶x-vsr-selected-category與x-vsr-selected-reasoning屬于調(diào)試面debug surface默認被降級demote只有請求顯式攜帶x-vsr-debug: true時才內(nèi)聯(lián)輸出否則這些中間細節(jié)可通過x-vsr-replay-id在 Router Replay 記錄中找回。該開關(guān)的判定實現(xiàn)在 src/semantic-router/pkg/extproc/debug_mode.go 的debugHeadersRequested對x-vsr-debug頭取值做大小寫不敏感、去空白的true匹配。對應(yīng)測試 src/semantic-router/pkg/extproc/extproc_test.go 的TestVSRHeadersAddedOnSuccessfulNonCachedResponse明確斷言未開 debug 時x-vsr-selected-category、x-vsr-selected-reasoning不出現(xiàn)在響應(yīng)頭中而 TestVSRDebugHeadersOnSuccessfulResponse 斷言帶上x-vsr-debug: true后它們恢復(fù)內(nèi)聯(lián)輸出。同時TestVSRHeadersPartialInformation 還驗證了空字段被正確省略。如果你在 v0.2 版本上做調(diào)試直接使用文檔所述的三個頭即可如果你面對的是更新版本v0.4記得在調(diào)試請求中追加x-vsr-debug: true才能看到分類與推理模式的中間細節(jié)。4. 決策信息的來源trackVSRDecision無論是自動路由還是顯式模型選擇決策信息最終都會匯聚到 src/semantic-router/pkg/extproc/recorder.go 的trackVSRDecisionfunc (r *OpenAIRouter) trackVSRDecision(ctx *RequestContext, categoryName string, decisionName string, matchedModel string, useReasoning bool) { ctx.VSRSelectedCategory categoryName ctx.VSRSelectedDecisionName decisionName ctx.VSRSelectedModel matchedModel if useReasoning { ctx.VSRReasoningMode on } else { ctx.VSRReasoningMode off } }這段代碼印證了文檔中的核心語義分類來自領(lǐng)域分類結(jié)果推理模式被映射為on/off兩個枚舉值模型選擇記錄最終選定的模型。實戰(zhàn)場景一請求調(diào)試Debugging調(diào)試時你關(guān)心的是這個請求為什么被這樣處理。此時你可以攜帶x-vsr-debug: true發(fā)起請求在支持 debug 面的新版本上用curl -i或瀏覽器開發(fā)者工具查看響應(yīng)頭對照三個核心字段判斷分類、推理模式與模型是否符合預(yù)期。例如curl -i -H Content-Type: application/json \ -H x-vsr-debug: true \ -d {model:auto,messages:[{role:user,content:求 x^2 3x 1 的導(dǎo)數(shù)}]} \ http://router-address/v1/chat/completions響應(yīng)頭中如果出現(xiàn)x-vsr-selected-category: math與x-vsr-selected-reasoning: on說明領(lǐng)域分類把該數(shù)學(xué)問題歸入math類別并啟用了推理模型——這正是路由器的預(yù)期行為。實戰(zhàn)場景二可觀測與監(jiān)控Monitoring運維團隊可以利用這些頭做面向請求的路由可觀測性類別分布跟蹤聚合x-vsr-selected-category的值分布了解請求的領(lǐng)域構(gòu)成推理模式使用模式統(tǒng)計x-vsr-selected-reasoning: on/off的比例評估推理模型的啟用成本模型選擇模式分析跟蹤x-vsr-selected-model的取值判斷各模型被選中的頻率輔助容量規(guī)劃與配額設(shè)計。倉庫中的基準測試工具直接消費這些頭來做路由與成本核算。例如 bench/reasoning/router_accounting.py 定義了SELECTED_MODEL_HEADER x-vsr-selected-model、COST_HEADER x-vsr-cost等常量其注釋明確指出每請求的路由與成本字段來自路由器響應(yīng)頭并通過response_accounting函數(shù)把selected_model、routing_latency_ms、cost等信息寫入基準報告——這就是監(jiān)控與分析場景在真實項目中的落地方式。實戰(zhàn)場景三分析與產(chǎn)品洞察Analytics產(chǎn)品團隊可以利用路由元數(shù)據(jù)回答以下問題請求分類準確性對照真實業(yè)務(wù)標簽評估領(lǐng)域分類器的準確率推理模式有效性結(jié)合下游任務(wù)質(zhì)量指標分析推理模式開/關(guān)的收益差異按類別評估模型表現(xiàn)以x-vsr-selected-category為維度切分模型性能與成本數(shù)據(jù)。端到端測試也把響應(yīng)頭當(dāng)作斷言事實來使用。例如 e2e/testcases/domain_classify.go 通過resp.Header.Get(x-vsr-selected-category)讀取實際分類結(jié)果與期望類別比對來計算分類準確率result.ActualCategory resp.Header.Get(x-vsr-selected-category) result.ActualReasoning resp.Header.Get(x-vsr-selected-reasoning) result.Correct (result.ActualCategory expectedCategory)同樣e2e/testcases/metadata_routing.go 斷言x-vsr-selected-decision與x-vsr-selected-recipe的具體取值來驗證元數(shù)據(jù)路由策略。這說明響應(yīng)頭本身就是該項目可驗證的對外契約——頭缺失或取值不對測試就會失敗。兼容性解讀與使用建議按版本區(qū)分頭面在 v0.2 語義下三個決策頭在成功非緩存響應(yīng)上都會出現(xiàn)在更新的 v0.4 契約下x-vsr-selected-category與x-vsr-selected-reasoning被降級到調(diào)試面需要x-vsr-debug: true才能內(nèi)聯(lián)看到。消費方應(yīng)優(yōu)先依賴默認面的最終路由事實如x-vsr-selected-model把中間細節(jié)當(dāng)作診斷信息?？罩导词÷栽创a中addString對空值直接跳過因此缺失該頭可能意味著該決策未執(zhí)行或信息不可用而不是解析錯誤。不要只依賴單頭完整的路由故事決策名、置信度、算法、路由延遲、回退嘗試次數(shù)分散在x-vsr-selected-decision、x-vsr-selected-confidence、x-vsr-selected-algorithm、x-vsr-routing-latency-ms、x-vsr-fallback-attempts等多個默認面頭中建議組合消費需要細粒度中間軌跡時通過x-vsr-replay-id關(guān)聯(lián) Router Replay 記錄。成本核算注意事項x-vsr-selected-model反映的是路由決策選定的模型若要按該模型計算費用應(yīng)結(jié)合響應(yīng)體中的 usage 信息與路由器提供的成本頭如x-vsr-cost、x-vsr-cost-currency一起使用——如 bench/reasoning/router_accounting.py 所示其成本基數(shù)是配置價格configured pricing而非供應(yīng)商賬單?？偨Y(jié)x-vsr-selected-category、x-vsr-selected-reasoning、x-vsr-selected-model是 semantic-router 路由決策的黑盒探針把分類、推理與模型選擇三個關(guān)鍵決策以標準 HTTP 頭的形式暴露在成功響應(yīng)上。它們既服務(wù)于開發(fā)者的請求級調(diào)試也支撐運維的類別/模式/模型分布監(jiān)控還能作為產(chǎn)品分析與成本核算的原始數(shù)據(jù)。理解其觸發(fā)條件成功、未命中緩存、執(zhí)行了決策、源碼寫入鏈路trackVSRDecision→buildResponseHeaderMutation→ Envoy HeaderMutation以及版本間的頭面差異默認面 vs 調(diào)試面你就能在真實部署中準確解讀每一次路由決策。贊分享后端API網(wǎng)關(guān)模型推理服務(wù)AI Agent【免費下載鏈接】semantic-routerAn open, programmable decision layer for models and compute.項目地址https://gitcode.com/gh_mirrors/sem/semantic-router點擊查看免費下載相關(guān)推薦Semantic Router VSR 決策追蹤 Header 完全指南從三個核心響應(yīng)頭到 v0.4 雙層合約Semantic Router VSR 決策追蹤 Header 完全指南從三個核心響應(yīng)頭到 v0.4 雙層合約 導(dǎo)讀 本文圍繞 Semantic Router后端API網(wǎng)關(guān)模型推理服務(wù)AI Agentsemantic-router VSR 決策追蹤 Header 完整指南類別、推理模式與模型選擇的可觀測性semantic router VSR 決策追蹤 Header 完整指南類別、推理模式與模型選擇的可觀測性 導(dǎo)讀 VSRVector Semantic Ro后端API網(wǎng)關(guān)模型推理服務(wù)AI AgentBetterDiscordPanel高級技巧自定義翻譯、主題切換與消息格式化指南BetterDiscordPanel高級技巧自定義翻譯、主題切換與消息格式化指南 BetterDiscordPanel是一款強大的自托管Discord機器人消創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考