OmniRoute 模型目录同步指南/v1/models 如何用缓存、哈希与降级策略保持模型列表稳定 【免费下载链接】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 网关通过统一的/v1/models端点聚合 350 供应商、1200 模型的目录列表。本文拆解 OmniRoute 模型目录同步机制的核心响应缓存、API Key 哈希指纹、版本号失效以及上游探测失败时的降级策略帮助你理解为什么并发查询不会雪崩、配置修改为何能即时生效。一、为什么 /v1/models 需要专门的同步机制/v1/models返回 OpenAI 兼容的模型列表。一次目录构建需要遍历8 个模型注册表并查询 SQLite 中的连接、Combos、自定义模型与别名。在 Next.js 单线程 App Router 中N 个并发请求会被串行执行第 N 个请求的延迟是单次构建耗时的 N 倍生产环境曾测得一次构建约 49 秒。因此 OmniRoute 为这个端点设计了独立的缓存层响应体构建器src/app/api/v1/models/route.ts缓存核心模块src/app/api/v1/models/catalogCache.ts并发请求会被合并到同一个进行中的构建上#6408共享一次结果而不是排队执行 N 次。二、缓存60 秒 TTL 与写操作即时失效1. TTL 缓存窗口缓存默认 TTL 为60 秒CATALOG_CACHE_TTL_MS_DEFAULT可通过settings.cache.modelCatalogCacheTtlMs配置上限同为 60 秒。这个窗口解决的是没有任何写操作场景下重复请求的问题——重放几秒前构建好的响应体正是缓存的价值所在。2. 版本号失效改配置立刻生效TTL 只控制没人动过配置的情况。真正的实时性由版本号机制保证src/lib/db/readCache.ts 维护一个单调递增的modelCatalogCacheVersion每次对settings、connections、combos、pricing的写入都会触发invalidateDbCache()使版本号 1缓存层在每次访问和每次构建完成时都会比对版本号一旦变化整个缓存 Map 被清空下一次读取同步构建新目录这意味着你在 Dashboard 上增删一个供应商连接下一个/v1/models请求就能看到新模型——不需要等 60 秒。3. 代际隔离防止过期构建污染新缓存进行中的构建会绑定它启动时的版本号generation。如果构建进行中有写操作使代际前移新请求不会加入这个过期构建过期构建完成后不会回填缓存只返回给原本等待它的那个请求这一设计杜绝了写操作前状态被缓存并长期服务的脏数据问题。三、哈希API Key 如何安全地进入缓存键不同 API Key 看到的模型范围不同权限隔离所以缓存键必须包含身份维度。但密钥绝不能以明文进入进程内存中的 Map 键。OmniRoute 的做法是用固定上下文标签omniroute-catalog-cache-fingerprint-v1对 Key 做HMAC-SHA256摘要截取前 16 位十六进制作为指纹#10313避免原始凭据留在进程堆中最终缓存键由 6 个维度拼接prefix、是否 Codex 客户端、Key 指纹、configuredOnly、是否隐藏自动 Combo、是否隐藏 no-think 变体完整键构建逻辑见 catalogCache.ts 的 buildCatalogCacheKey指纹函数在 fingerprintCatalogAuthKey。四、降级策略过期缓存与探测失败的两道保险1. Stale-While-Revalidate过期也能秒回Claude Code 等 CLI 客户端的目录发现超时只有 3 秒绝不允许它等待一次完整重建。因此缓存过期后还有一层30 秒的过期宽限窗口CATALOG_STALE_WHILE_REVALIDATE_MS窗口内的过期条目立即原样返回仅限成功状态 200 的条目同时通过 Next.js 的after()调度后台重建——after()保证响应先冲刷到客户端再执行重建避免同步构建器占满事件循环、让秒回名不副实#8728、#11574超过 30 秒窗口则退回冷路径等待重建防止持续失败的刷新永久钉住一份古老目录2. 模型同步的三级回退与拒绝持久化在供应商模型同步/api/providers/{id}/sync-models中远程探测失败时按优先级降级远程发现→ 失败则 2.已缓存目录附带warning字段如 Models probe failed (401) — using cached catalog→ 仍无缓存则 3.本地静态目录local_catalog关键规则降级结果不得被持久化为同步目录否则过期的 Key 会悄悄钉死一份陈旧目录、掩盖真实故障。判定逻辑在 degradedLocalCatalog.tsisDegradedLocalCataloglocal_catalog来源且非有意为之Reka 等本地目录型供应商标记了intentional: true不受影响isDegradedCachedCatalogcache来源且携带warning普通缓存命中不带警告同步路由 sync-models/route.ts 据此拒绝把降级发现当作成功导入。3. HEAD 探测的轻量降级OpenAI SDK 等客户端会用 HEAD 做健康探测。OmniRoute 提供显式 HEAD 处理器直接返回空 200#6400避免自动推导的 HEAD 把 200 供应商的完整目录流式写出导致约 6 秒挂起。五、如何验证与调整场景建议操作修改供应商后列表未更新正常不应发生检查写操作是否走了invalidateDbCache()路径目录构建慢、并发高确认默认 60s TTL 生效并发请求已合并为单次构建CLI 客户端发现超时30s 宽限窗口内会自动秒回旧目录并后台刷新模型同步报无新模型检查是否收到source: cache且带warning的降级响应相关测试覆盖了并发合并v1-models-concurrent-6408.test.ts、TTL 行为v1-models-catalog-ttl.test.ts与缓存键哈希10313-catalog-cache-key-hashing.test.ts。六、总结OmniRoute 的/v1/models同步机制可以用一句话概括TTL 缓存扛并发、HMAC 哈希保安全、版本号保新鲜、宽限窗口保可用、降级标记保诚实。五层设计协同工作让 1200 模型的目录既快又准。核心文件速查路由入口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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考