![OmniRoute 模型目錄同步指南：/v1/models 如何用緩存、哈希與降級策略保持模型列表穩(wěn)定 [特殊字符]](http://pic.xiahunao.cn/yaotu/OmniRoute 模型目錄同步指南：/v1/models 如何用緩存、哈希與降級策略保持模型列表穩(wěn)定 [特殊字符])
OmniRoute 模型目錄同步指南/v1/models 如何用緩存、哈希與降級策略保持模型列表穩(wěn)定 【免費下載鏈接】OmniRouteNever stop coding. Free MIT AI gateway: one endpoint, 350 providers (90 free), 1200 models Kimi, Claude, GPT, Gemini, GLM, DeepSeek, MiniMax. Works with Claude Code, Codex, Cursor, OpenCode, Cline Copilot. Quota-aware auto-fallback, RTKCaveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 450 contributors項目地址: https://gitcode.com/GitHub_Trending/om/OmniRouteOmniRoute 是一個免費開源的 AI 網(wǎng)關(guān)通過統(tǒng)一的/v1/models端點聚合 350 供應(yīng)商、1200 模型的目錄列表。本文拆解 OmniRoute 模型目錄同步機(jī)制的核心響應(yīng)緩存、API Key 哈希指紋、版本號失效以及上游探測失敗時的降級策略幫助你理解為什么并發(fā)查詢不會雪崩、配置修改為何能即時生效。一、為什么 /v1/models 需要專門的同步機(jī)制/v1/models返回 OpenAI 兼容的模型列表。一次目錄構(gòu)建需要遍歷8 個模型注冊表并查詢 SQLite 中的連接、Combos、自定義模型與別名。在 Next.js 單線程 App Router 中N 個并發(fā)請求會被串行執(zhí)行第 N 個請求的延遲是單次構(gòu)建耗時的 N 倍生產(chǎn)環(huán)境曾測得一次構(gòu)建約 49 秒。因此 OmniRoute 為這個端點設(shè)計了獨立的緩存層響應(yīng)體構(gòu)建器src/app/api/v1/models/route.ts緩存核心模塊src/app/api/v1/models/catalogCache.ts并發(fā)請求會被合并到同一個進(jìn)行中的構(gòu)建上#6408共享一次結(jié)果而不是排隊執(zhí)行 N 次。二、緩存60 秒 TTL 與寫操作即時失效1. TTL 緩存窗口緩存默認(rèn) TTL 為60 秒CATALOG_CACHE_TTL_MS_DEFAULT可通過settings.cache.modelCatalogCacheTtlMs配置上限同為 60 秒。這個窗口解決的是沒有任何寫操作場景下重復(fù)請求的問題——重放幾秒前構(gòu)建好的響應(yīng)體正是緩存的價值所在。2. 版本號失效改配置立刻生效TTL 只控制沒人動過配置的情況。真正的實時性由版本號機(jī)制保證src/lib/db/readCache.ts 維護(hù)一個單調(diào)遞增的modelCatalogCacheVersion每次對settings、connections、combos、pricing的寫入都會觸發(fā)invalidateDbCache()使版本號 1緩存層在每次訪問和每次構(gòu)建完成時都會比對版本號一旦變化整個緩存 Map 被清空下一次讀取同步構(gòu)建新目錄這意味著你在 Dashboard 上增刪一個供應(yīng)商連接下一個/v1/models請求就能看到新模型——不需要等 60 秒。3. 代際隔離防止過期構(gòu)建污染新緩存進(jìn)行中的構(gòu)建會綁定它啟動時的版本號generation。如果構(gòu)建進(jìn)行中有寫操作使代際前移新請求不會加入這個過期構(gòu)建過期構(gòu)建完成后不會回填緩存只返回給原本等待它的那個請求這一設(shè)計杜絕了寫操作前狀態(tài)被緩存并長期服務(wù)的臟數(shù)據(jù)問題。三、哈希API Key 如何安全地進(jìn)入緩存鍵不同 API Key 看到的模型范圍不同權(quán)限隔離所以緩存鍵必須包含身份維度。但密鑰絕不能以明文進(jìn)入進(jìn)程內(nèi)存中的 Map 鍵。OmniRoute 的做法是用固定上下文標(biāo)簽omniroute-catalog-cache-fingerprint-v1對 Key 做HMAC-SHA256摘要截取前 16 位十六進(jìn)制作為指紋#10313避免原始憑據(jù)留在進(jìn)程堆中最終緩存鍵由 6 個維度拼接prefix、是否 Codex 客戶端、Key 指紋、configuredOnly、是否隱藏自動 Combo、是否隱藏 no-think 變體完整鍵構(gòu)建邏輯見 catalogCache.ts 的 buildCatalogCacheKey指紋函數(shù)在 fingerprintCatalogAuthKey。四、降級策略過期緩存與探測失敗的兩道保險1. Stale-While-Revalidate過期也能秒回Claude Code 等 CLI 客戶端的目錄發(fā)現(xiàn)超時只有 3 秒絕不允許它等待一次完整重建。因此緩存過期后還有一層30 秒的過期寬限窗口CATALOG_STALE_WHILE_REVALIDATE_MS窗口內(nèi)的過期條目立即原樣返回僅限成功狀態(tài) 200 的條目同時通過 Next.js 的after()調(diào)度后臺重建——after()保證響應(yīng)先沖刷到客戶端再執(zhí)行重建避免同步構(gòu)建器占滿事件循環(huán)、讓秒回名不副實#8728、#11574超過 30 秒窗口則退回冷路徑等待重建防止持續(xù)失敗的刷新永久釘住一份古老目錄2. 模型同步的三級回退與拒絕持久化在供應(yīng)商模型同步/api/providers/{id}/sync-models中遠(yuǎn)程探測失敗時按優(yōu)先級降級遠(yuǎn)程發(fā)現(xiàn)→ 失敗則 2.已緩存目錄附帶warning字段如 Models probe failed (401) — using cached catalog→ 仍無緩存則 3.本地靜態(tài)目錄local_catalog關(guān)鍵規(guī)則降級結(jié)果不得被持久化為同步目錄否則過期的 Key 會悄悄釘死一份陳舊目錄、掩蓋真實故障。判定邏輯在 degradedLocalCatalog.tsisDegradedLocalCataloglocal_catalog來源且非有意為之Reka 等本地目錄型供應(yīng)商標(biāo)記了intentional: true不受影響isDegradedCachedCatalogcache來源且攜帶warning普通緩存命中不帶警告同步路由 sync-models/route.ts 據(jù)此拒絕把降級發(fā)現(xiàn)當(dāng)作成功導(dǎo)入。3. HEAD 探測的輕量降級OpenAI SDK 等客戶端會用 HEAD 做健康探測。OmniRoute 提供顯式 HEAD 處理器直接返回空 200#6400避免自動推導(dǎo)的 HEAD 把 200 供應(yīng)商的完整目錄流式寫出導(dǎo)致約 6 秒掛起。五、如何驗證與調(diào)整場景建議操作修改供應(yīng)商后列表未更新正常不應(yīng)發(fā)生檢查寫操作是否走了invalidateDbCache()路徑目錄構(gòu)建慢、并發(fā)高確認(rèn)默認(rèn) 60s TTL 生效并發(fā)請求已合并為單次構(gòu)建CLI 客戶端發(fā)現(xiàn)超時30s 寬限窗口內(nèi)會自動秒回舊目錄并后臺刷新模型同步報無新模型檢查是否收到source: cache且?guī)arning的降級響應(yīng)相關(guān)測試覆蓋了并發(fā)合并v1-models-concurrent-6408.test.ts、TTL 行為v1-models-catalog-ttl.test.ts與緩存鍵哈希10313-catalog-cache-key-hashing.test.ts。六、總結(jié)OmniRoute 的/v1/models同步機(jī)制可以用一句話概括TTL 緩存扛并發(fā)、HMAC 哈希保安全、版本號保新鮮、寬限窗口?？捎谩⒔导墭?biāo)記保誠實。五層設(shè)計協(xié)同工作讓 1200 模型的目錄既快又準(zhǔn)。核心文件速查路由入口src/app/api/v1/models/route.ts緩存與哈希src/app/api/v1/models/catalogCache.ts版本號失效src/lib/db/readCache.ts降級判定src/app/api/providers/[id]/sync-models/degradedLocalCatalog.ts【免費下載鏈接】OmniRouteNever stop coding. Free MIT AI gateway: one endpoint, 350 providers (90 free), 1200 models Kimi, Claude, GPT, Gemini, GLM, DeepSeek, MiniMax. Works with Claude Code, Codex, Cursor, OpenCode, Cline Copilot. Quota-aware auto-fallback, RTKCaveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 450 contributors項目地址: https://gitcode.com/GitHub_Trending/om/OmniRoute創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考 OmniRoute 模型目錄同步指南：/v1/models 如何用緩存、哈希與降級策略保持模型列表穩(wěn)定 [特殊字符]
OmniRoute 模型目錄同步指南/v1/models 如何用緩存、哈希與降級策略保持模型列表穩(wěn)定 【免費下載鏈接】OmniRouteNever stop coding. Free MIT AI gateway: one endpoint, 350 providers (90 free), 1200 models Kimi, Claude, GPT, Gemini, GLM, DeepSeek, MiniMax. Works with Claude Code, Codex, Cursor, OpenCode, Cline Copilot. Quota-aware auto-fallback, RTKCaveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 450 contributors項目地址: https://gitcode.com/GitHub_Trending/om/OmniRouteOmniRoute 是一個免費開源的 AI 網(wǎng)關(guān)通過統(tǒng)一的/v1/models端點聚合 350 供應(yīng)商、1200 模型的目錄列表。本文拆解 OmniRoute 模型目錄同步機(jī)制的核心響應(yīng)緩存、API Key 哈希指紋、版本號失效以及上游探測失敗時的降級策略幫助你理解為什么并發(fā)查詢不會雪崩、配置修改為何能即時生效。一、為什么 /v1/models 需要專門的同步機(jī)制/v1/models返回 OpenAI 兼容的模型列表。一次目錄構(gòu)建需要遍歷8 個模型注冊表并查詢 SQLite 中的連接、Combos、自定義模型與別名。在 Next.js 單線程 App Router 中N 個并發(fā)請求會被串行執(zhí)行第 N 個請求的延遲是單次構(gòu)建耗時的 N 倍生產(chǎn)環(huán)境曾測得一次構(gòu)建約 49 秒。因此 OmniRoute 為這個端點設(shè)計了獨立的緩存層響應(yīng)體構(gòu)建器src/app/api/v1/models/route.ts緩存核心模塊src/app/api/v1/models/catalogCache.ts并發(fā)請求會被合并到同一個進(jìn)行中的構(gòu)建上#6408共享一次結(jié)果而不是排隊執(zhí)行 N 次。二、緩存60 秒 TTL 與寫操作即時失效1. TTL 緩存窗口緩存默認(rèn) TTL 為60 秒CATALOG_CACHE_TTL_MS_DEFAULT可通過settings.cache.modelCatalogCacheTtlMs配置上限同為 60 秒。這個窗口解決的是沒有任何寫操作場景下重復(fù)請求的問題——重放幾秒前構(gòu)建好的響應(yīng)體正是緩存的價值所在。2. 版本號失效改配置立刻生效TTL 只控制沒人動過配置的情況。真正的實時性由版本號機(jī)制保證src/lib/db/readCache.ts 維護(hù)一個單調(diào)遞增的modelCatalogCacheVersion每次對settings、connections、combos、pricing的寫入都會觸發(fā)invalidateDbCache()使版本號 1緩存層在每次訪問和每次構(gòu)建完成時都會比對版本號一旦變化整個緩存 Map 被清空下一次讀取同步構(gòu)建新目錄這意味著你在 Dashboard 上增刪一個供應(yīng)商連接下一個/v1/models請求就能看到新模型——不需要等 60 秒。3. 代際隔離防止過期構(gòu)建污染新緩存進(jìn)行中的構(gòu)建會綁定它啟動時的版本號generation。如果構(gòu)建進(jìn)行中有寫操作使代際前移新請求不會加入這個過期構(gòu)建過期構(gòu)建完成后不會回填緩存只返回給原本等待它的那個請求這一設(shè)計杜絕了寫操作前狀態(tài)被緩存并長期服務(wù)的臟數(shù)據(jù)問題。三、哈希API Key 如何安全地進(jìn)入緩存鍵不同 API Key 看到的模型范圍不同權(quán)限隔離所以緩存鍵必須包含身份維度。但密鑰絕不能以明文進(jìn)入進(jìn)程內(nèi)存中的 Map 鍵。OmniRoute 的做法是用固定上下文標(biāo)簽omniroute-catalog-cache-fingerprint-v1對 Key 做HMAC-SHA256摘要截取前 16 位十六進(jìn)制作為指紋#10313避免原始憑據(jù)留在進(jìn)程堆中最終緩存鍵由 6 個維度拼接prefix、是否 Codex 客戶端、Key 指紋、configuredOnly、是否隱藏自動 Combo、是否隱藏 no-think 變體完整鍵構(gòu)建邏輯見 catalogCache.ts 的 buildCatalogCacheKey指紋函數(shù)在 fingerprintCatalogAuthKey。四、降級策略過期緩存與探測失敗的兩道保險1. Stale-While-Revalidate過期也能秒回Claude Code 等 CLI 客戶端的目錄發(fā)現(xiàn)超時只有 3 秒絕不允許它等待一次完整重建。因此緩存過期后還有一層30 秒的過期寬限窗口CATALOG_STALE_WHILE_REVALIDATE_MS窗口內(nèi)的過期條目立即原樣返回僅限成功狀態(tài) 200 的條目同時通過 Next.js 的after()調(diào)度后臺重建——after()保證響應(yīng)先沖刷到客戶端再執(zhí)行重建避免同步構(gòu)建器占滿事件循環(huán)、讓秒回名不副實#8728、#11574超過 30 秒窗口則退回冷路徑等待重建防止持續(xù)失敗的刷新永久釘住一份古老目錄2. 模型同步的三級回退與拒絕持久化在供應(yīng)商模型同步/api/providers/{id}/sync-models中遠(yuǎn)程探測失敗時按優(yōu)先級降級遠(yuǎn)程發(fā)現(xiàn)→ 失敗則 2.已緩存目錄附帶warning字段如 Models probe failed (401) — using cached catalog→ 仍無緩存則 3.本地靜態(tài)目錄local_catalog關(guān)鍵規(guī)則降級結(jié)果不得被持久化為同步目錄否則過期的 Key 會悄悄釘死一份陳舊目錄、掩蓋真實故障。判定邏輯在 degradedLocalCatalog.tsisDegradedLocalCataloglocal_catalog來源且非有意為之Reka 等本地目錄型供應(yīng)商標(biāo)記了intentional: true不受影響isDegradedCachedCatalogcache來源且攜帶warning普通緩存命中不帶警告同步路由 sync-models/route.ts 據(jù)此拒絕把降級發(fā)現(xiàn)當(dāng)作成功導(dǎo)入。3. HEAD 探測的輕量降級OpenAI SDK 等客戶端會用 HEAD 做健康探測。OmniRoute 提供顯式 HEAD 處理器直接返回空 200#6400避免自動推導(dǎo)的 HEAD 把 200 供應(yīng)商的完整目錄流式寫出導(dǎo)致約 6 秒掛起。五、如何驗證與調(diào)整場景建議操作修改供應(yīng)商后列表未更新正常不應(yīng)發(fā)生檢查寫操作是否走了invalidateDbCache()路徑目錄構(gòu)建慢、并發(fā)高確認(rèn)默認(rèn) 60s TTL 生效并發(fā)請求已合并為單次構(gòu)建CLI 客戶端發(fā)現(xiàn)超時30s 寬限窗口內(nèi)會自動秒回舊目錄并后臺刷新模型同步報無新模型檢查是否收到source: cache且?guī)arning的降級響應(yīng)相關(guān)測試覆蓋了并發(fā)合并v1-models-concurrent-6408.test.ts、TTL 行為v1-models-catalog-ttl.test.ts與緩存鍵哈希10313-catalog-cache-key-hashing.test.ts。六、總結(jié)OmniRoute 的/v1/models同步機(jī)制可以用一句話概括TTL 緩存扛并發(fā)、HMAC 哈希保安全、版本號保新鮮、寬限窗口?？捎谩⒔导墭?biāo)記保誠實。五層設(shè)計協(xié)同工作讓 1200 模型的目錄既快又準(zhǔn)。核心文件速查路由入口src/app/api/v1/models/route.ts緩存與哈希src/app/api/v1/models/catalogCache.ts版本號失效src/lib/db/readCache.ts降級判定src/app/api/providers/[id]/sync-models/degradedLocalCatalog.ts【免費下載鏈接】OmniRouteNever stop coding. Free MIT AI gateway: one endpoint, 350 providers (90 free), 1200 models Kimi, Claude, GPT, Gemini, GLM, DeepSeek, MiniMax. Works with Claude Code, Codex, Cursor, OpenCode, Cline Copilot. Quota-aware auto-fallback, RTKCaveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 450 contributors項目地址: https://gitcode.com/GitHub_Trending/om/OmniRoute創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考