模型别名重复或成环，怎样在网关启动前用离线表检查

启动前检查模型映射，可以把重复名称、悬空目标和循环依赖挡在流量进入之前。本文先定义一份自有规范化表，再做离线解析；它不是New API或LiteLLM可直接导入的配置，也不宣称这些产品都允许递归别名。

用行数组保留重复键证据

附件每行是一对逻辑名和目标，真实目标集合另列。正常输入basic指向real-small，vip指向basic，最终两者都解析到real-small。使用行数组很重要：如果先把JSON对象读成普通字典，重复的a可能已被后值覆盖，检查器就失去发现“同名两行”的机会。

重复负例给a两个不同目标，解析前就拒绝；悬空负例让a指向不存在的absent；循环负例让a到b再回a。错误报告应包含类型和涉及路径，便于找到配置来源，不能只返回一个笼统的“模型不可用”。参考器对三类负例分别断言duplicate、dangling和cycle。

逐条解析时保存访问路径

从每个逻辑名出发，若目标是真实目标就结束；若还是别名就继续，同时把已访问的名称放进集合。再次遇到已访问名称说明成环，遇到既不是目标又没有映射的名称说明悬空。不要用一个没有上限的while等到服务卡住才判断出错，也不要把遇到错误的别名悄悄指向默认模型。

更完整的检查器可记录原文件与行号，并缓存已经解析的尾部，提高大表效率。本文小样本重视可读性，不做性能基准。若别名里允许大小写、空白或不同规范化形式，应先写明是否等价，再加入相应负例，不能在解析时任意lower导致原本不同的名字合并。

将产品导出与规范表之间的转换单独验收

真实网关可能用模型组、渠道、部署名或其他结构表达路由。应先从固定部署版本导出非敏感配置，写适配层转换成本表，再核对每个最终目标是否对应真实对象。适配器漏字段会让离线表看似正确却与生产不符，因此映射行数、稳定标识和版本都需要保留。

变更一个末端目标时，还可以反向找出所有依赖该目标的业务别名，作为权限和缓存更新的复核范围。本文没有执行产品导入，没有调用模型，也没有比较输出质量。LiteLLM虚拟Key资料仅提供模型访问控制的背景，递归结构与错误处理全部是本文声明的参考契约。交付三类最小反例和明确最终目标，比在启动失败后逐条猜哪行配置有问题更容易复现。

配套样本与复核入口

下载本篇独立合成输入和实验运行器。上述文件放在同一目录后运行 python run_lab.py C030。完整运行需要全部四十四份输入及相关配置。结果中的method区分离线计算、静态参考检查与回环实测，不能把前两者当成真实网关已通过。

资料核对日期：2026-10-24。官方依据1。

与本站相关基础教程的区别：旧文介绍模型路由解耦；本文输入人工整理的映射规范表，检出重复、悬空与环，不宣称New API允许递归别名，不讲模型质量与分流。