Plano 模型别名Model Aliases实战指南用语义化、可版本化的模型引用替代硬编码模型名【免费下载链接】planoPlano is an AI-native proxy server and data plane for agentic apps. Smart LLM routing, observability, agent orchestration, and guardrails so you stay focused on your agents core logic.项目地址: https://gitcode.com/GitHub_Trending/ar/plano导读本文基于 Plano 仓库中的 routing-aliases 规则 与 model_aliases 官方文档系统讲解如何通过model_aliases配置将人类可读的语义化别名映射到具体模型标识符从而让客户端与底层模型解耦。你将掌握别名的命名规范、完整配置示例、客户端接入方式、与默认 Provider 及路由偏好的协同用法并看到别名在请求处理管线中的源码级解析原理最终能在生产环境实现换模型只改一行 config.yaml不碰任何客户端代码的稳定集成。一、为什么要用模型别名让客户端契约稳定下来在传统的 LLM 网关接入方式中客户端代码里直接硬编码模型名# Client code — brittle, must be updated when model changes client.chat.completions.create(modelgpt-4o, ...)这种做法的核心痛点是契约耦合一旦你想把gpt-4o升级到新模型或者因成本原因切换到gpt-4o-mini就必须修改每一个调用该 API 的客户端并重新发布。在 Agent 应用Plano 面向的核心场景中客户端数量多、调用点分散硬编码模型名意味着每次模型调整都是一次全量变更。model_aliases正是为了解决这个问题而设计它在配置层建立别名 → 真实模型标识符的映射客户端只引用别名如plano.smart.v1网关在请求处理时负责把别名解析为真实的模型名。当需要升级模型时只需要修改 config.yaml 中的一行映射——客户端代码零改动。从规则文档的 impact 描述来看routing-aliases.md这一能力的价值在于硬编码模型名要求客户端在更换 Provider 时修改代码而别名机制让你仅通过修改 config.yaml 即可完成路由更新。二、反模式与正确姿势先看两个对照配置反模式不定义别名客户端硬编码模型名# config.yaml — no aliases defined version: v0.3.0 listeners: - type: model name: model_listener port: 12000 model_providers: - model: openai/gpt-4o access_key: $OPENAI_API_KEY default: true# Client code — brittle, must be updated when model changes client.chat.completions.create(modelgpt-4o, ...)正确姿势语义化别名 稳定客户端契约version: v0.3.0 listeners: - type: model name: model_listener port: 12000 model_providers: - model: openai/gpt-4o-mini access_key: $OPENAI_API_KEY default: true - model: openai/gpt-4o access_key: $OPENAI_API_KEY - model: anthropic/claude-sonnet-4-6 access_key: $ANTHROPIC_API_KEY model_aliases: plano.fast.v1: target: gpt-4o-mini # Cheap, fast — for high-volume tasks plano.smart.v1: target: gpt-4o # High capability — for complex reasoning plano.creative.v1: target: claude-sonnet-4-6 # Strong creative writing and analysis plano.v1: target: gpt-4o # Default production alias# Client code — stable, alias is the contract client.chat.completions.create(modelplano.smart.v1, ...)对比可见配置侧只是多了model_aliases一节客户端侧则把易变的gpt-4o替换成了语义化的plano.smart.v1。此后无论底层换成gpt-5、claude-sonnet-4-6还是本地模型客户端都不需要感知。三、别名命名规范与版本化策略规则文档明确给出了推荐的命名约定org.purpose.version三段式如plano.fast.v1、acme.code.v2。组织前缀避免多团队共用网关时命名冲突用途字段让别名自解释版本号支撑演进。版本递增实现灰度滚动从.v2升到.v3时新旧别名可同时存在从而在 rollout 期间让老客户端和新客户端并行运行逐步迁移流量。保留一个 canonical 默认别名如plano.v1作为客户端的唯一稳定入口。即使内部模型多次更迭只要该别名始终指向当前生产模型客户端就永远不需要变。model_aliases.rst 在此基础上补充了更多命名维度功能型别名fast-model、smart-model、creative-model这种直接描述能力的名字适合让调用方按我想要多快的模型而非我认识哪个模型来编程。任务型别名code-reviewer、document-summarizer、data-analyst等把别名与业务场景绑定。环境区分dev.chat.v1开发环境用快/便宜模型、prod.chat.v1生产用强模型、staging.chat.v1预发布测试新模型同一套客户端代码在不同环境自动获得不同模型。稳定指针arch.summarize.latest始终指向当前最新版本适合不需要严格版本冻结的调用方。官方文档中的完整示例llm_providers: - model: openai/gpt-4o-mini access_key: $OPENAI_API_KEY - model: openai/gpt-4o access_key: $OPENAI_API_KEY - model: anthropic/claude-3-5-sonnet-20241022 access_key: $ANTHROPIC_API_KEY - model: ollama/llama3.1 base_url: http://localhost:11434 # Define aliases that map to the models above model_aliases: # Semantic versioning approach arch.summarize.v1: target: gpt-4o-mini arch.reasoning.v1: target: gpt-4o arch.creative.v1: target: claude-3-5-sonnet-20241022 # Functional aliases fast-model: target: gpt-4o-mini smart-model: target: gpt-4o creative-model: target: claude-3-5-sonnet-20241022 # Local model alias local-chat: target: llama3.1注该文档示例使用了llm_providers字段名。根据 plano_config_schema.yaml 的 schema 说明llm_providers是为兼容旧版本而保留的废弃写法新配置应使用model_providers配置生成器会自动完成迁移。四、客户端接入Python、cURL、Anthropic 协议别名对客户端完全透明——它就是一个普通的 model 字段值网关负责解析。Python OpenAI SDKfrom openai import OpenAI client OpenAI(base_urlhttp://127.0.0.1:12000/) # Use semantic alias instead of provider model name response client.chat.completions.create( modelarch.summarize.v1, # Points to gpt-4o-mini messages[{role: user, content: Summarize this document...}] ) # Switch to a different capability response client.chat.completions.create( modelarch.reasoning.v1, # Points to gpt-4o messages[{role: user, content: Solve this complex problem...}] )cURLOpenAI 兼容端点curl -X POST http://127.0.0.1:12000/v1/chat/completions \ -H Content-Type: application/json \ -d { model: fast-model, messages: [{role: user, content: Hello!}] }Anthropic Messages 端点同一别名跨协议可用仓库中的 model_alias_routing 示例 展示了同一别名既能走 OpenAI 兼容协议也能走 Anthropic 协议curl -sS -X POST http://localhost:12000/v1/messages \ -H x-api-key: test-key \ -H anthropic-version: 2023-06-01 \ -H Content-Type: application/json \ -d { model: arch.summarize.v1, max_tokens: 50, messages: [ { role: user, content: Hello, please respond with exactly: Hello from alias arch.summarize.v1 via Anthropic! } ] } | jq .关键点别名解析发生在 Plano 网关内部与客户端使用的协议OpenAI/v1/chat/completions、Anthropic/v1/messages无关。客户端永远只写别名网关在转发到上游 Provider 前完成真实模型名的替换。仓库中的完整可运行配置demos/llm_routing/model_alias_routing/config_with_aliases.yaml 是一个开箱即用的全量示例覆盖了 OpenAI、Anthropic含通配anthropic/*、Azure OpenAI、Amazon Bedrock、Ollama、Grok 等多 Provider并定义了 9 个别名version: v0.3.0 listeners: - type: model name: model_listener port: 12000 model_providers: # OpenAI Models - model: openai/gpt-5-mini-2025-08-07 access_key: $OPENAI_API_KEY default: true - model: openai/gpt-4o-mini access_key: $OPENAI_API_KEY - model: openai/o3 access_key: $OPENAI_API_KEY - model: openai/gpt-4o access_key: $OPENAI_API_KEY - model: openai/* access_key: $OPENAI_API_KEY # Anthropic - support all Claude models - model: anthropic/* access_key: $ANTHROPIC_API_KEY - model: anthropic/claude-sonnet-4-6 access_key: $ANTHROPIC_API_KEY - model: anthropic/claude-3-haiku-20240307 access_key: $ANTHROPIC_API_KEY # Azure OpenAI Models - model: azure_openai/gpt-5-mini access_key: $AZURE_API_KEY base_url: https://katanemo.openai.azure.com - model: amazon_bedrock/us.amazon.nova-premier-v1:0 access_key: $AWS_BEARER_TOKEN_BEDROCK base_url: https://bedrock-runtime.us-west-2.amazonaws.com - model: amazon_bedrock/us.amazon.nova-pro-v1:0 access_key: $AWS_BEARER_TOKEN_BEDROCK base_url: https://bedrock-runtime.us-west-2.amazonaws.com # Ollama Models - model: ollama/llama3.1 base_url: http://localhost:11434 # Grok (xAI) Models - model: xai/grok-4-0709 access_key: $GROK_API_KEY # Model aliases - friendly names that map to actual provider names model_aliases: # Alias for summarization tasks - fast/cheap model arch.summarize.v1: target: gpt-5-mini-2025-08-07 # Alias for general purpose tasks - latest model arch.v1: target: o3 # Alias for reasoning tasks - capable model arch.reasoning.v1: target: gpt-4o # Alias for creative tasks - Claude model arch.creative.v1: target: claude-sonnet-4-6 # Alias for quick responses - fast model arch.fast.v1: target: claude-3-haiku-20240307 # Semantic aliases summary-model: target: gpt-5-mini-2025-08-07 chat-model: target: gpt-5-mini-2025-08-07 creative-model: target: claude-sonnet-4-6 coding-model: target: us.amazon.nova-premier-v1:0 # Alias for grok testing arch.grok.v1: target: grok-4-0709 tracing: random_sampling: 100运行该示例的方式详见 model_alias_routing/README.md# 先导出 API Key export OPENAI_API_KEYyour-openai-key export ANTHROPIC_API_KEYyour-anthropic-key # 可选但跑 Anthropic 测试时推荐 # 启动网关自动生成 .env 并加载别名配置 sh run_demo.sh # 停止 sh run_demo.sh down五、别名与默认 Provider、路由偏好的协同模型别名不是孤立功能它与 Plano 路由体系中的默认 Provider、路由偏好routing_preferences共同构成完整的客户端稳定 服务端灵活架构与 default Provider 的配合routing-default.md 强调当请求不匹配任何路由偏好时Plano 会将其转发给标记了default: true的 Provider如果没有 default未匹配请求会失败如果有多个 default则取第一个可能产生意外行为。因此推荐在model_providers中恰好设置一个default: true选择最具性价比的可用模型承接所有未被偏好匹配的流量用别名提供语义入口用 default 提供兜底出口两者互不冲突别名保证客户端引用稳定default 保证任意未分类请求都有去处。与路由偏好的配合若为 Provider 配置routing_preferences按任务语义描述什么样的请求适合这个模型则网关会先按请求意图匹配偏好再结合别名解析完成模型选择。这样可以把别名理解为客户端侧的名字而偏好是网关侧的路由策略——客户端说我要plano.smart.v1网关决定这条请求具体该交给哪个上游模型。与 Passthrough Auth 的组合在多租户或自建代理场景LiteLLM、vLLM 等参见 routing-passthrough.md你可以将别名与passthrough_auth: true、base_url组合使用model_providers: - model: custom/litellm-proxy base_url: http://host.docker.internal:4000 # LiteLLM server provider_interface: openai # LiteLLM uses OpenAI format passthrough_auth: true # Forward clients Bearer token default: true model_aliases: my.gateway.chat.v1: target: litellm-proxy这样客户端只依赖my.gateway.chat.v1这一稳定别名上游从 OpenAI 官方 API 切换到自建 LiteLLM 代理时仅需改动model_providers的 base_url 与认证方式。六、源码视角别名在请求管线中如何被解析配置 Schema 约束plano_config_schema.yaml 中model_aliases的定义L287-L297非常精简model_aliases: type: object patternProperties: ^.*$: type: object properties: target: type: string additionalProperties: false required: - target即model_aliases是一个键值映射每个别名对象只能包含一个target字段字符串且target为必填。这保证了别名语义的纯粹性——别名只做名字 → 真实模型名的一对一解析不承载其他复杂逻辑。核心解析函数别名解析的核心实现在 crates/brightstaff/src/handlers/llm/mod.rs/// Resolves model aliases by looking up the requested model in the model_aliases map. /// Returns the target model if an alias is found, otherwise returns the original model. pub(crate) fn resolve_model_alias( model_from_request: str, model_aliases: OptionHashMapString, ModelAlias, ) - String { if let Some(aliases) model_aliases.as_ref() { if let Some(model_alias) aliases.get(model_from_request) { debug!( Model Alias: From {} - To {}, model_from_request, model_alias.target ); return model_alias.target.clone(); } } model_from_request.to_string() }要点查表式解析从请求体取出model字段在别名哈希表中查找命中则返回target未命中则原样返回——因此未定义的别名不会报错只会按字面模型名处理前提是model_providers中存在该模型。解析时机在 routing_service.rs 中别名在成为会话模型通道session lane之前就被解析——注释明确指出代理路径proxy path会以解析后的模型存储会话绑定如果别名未提前解析同一请求会被误判为不同通道。这一点也有对应的单元测试alias_is_resolved_before_becoming_the_session_lane同文件 L534 起加以验证。日志可观测命中别名时输出debug!级别的 Model Alias: From {别名} - To {目标} 日志便于在 tracing 中确认别名解析是否生效。配置生成与模板侧的支持cli/planoai/config_generator.py 与 cli/planoai/core.py 均引用了model_aliases说明planoaiCLI 在生成/管理配置时会感知别名结构cli/planoai/templates/coding_agent_routing.yaml 等模板中同样使用了别名表明别名是 CLI 引导初始化配置的标准组成部分。七、验证规则与约束综合官方文档与配置 schema使用别名时需要遵守以下约束规则说明依据别名名必须是合法标识符允许字母数字、点、连字符、下划线model_aliases.rsttarget 必须存在于 providers 中别名的目标模型需要在model_providers或兼容的llm_providers中定义否则解析后无法路由到上游model_aliases.rst禁止别名循环引用别名不能间接指向自身model_aliases.rsttarget 为必填且仅此一个字段每个别名对象只能有targetadditionalProperties: falseplano_config_schema.yaml未命中别名时按原模型名透传解析函数未命中即原样返回crates/brightstaff/src/handlers/llm/mod.rs规划中的高级能力以仓库文档为准标注Coming Soonmodel_aliases.rst 明确标注以下能力为未来规划当前 schema 中并不存在对应字段请勿在现版本配置中使用别名级 Guardrails在别名上挂载max_latency、max_cost_per_request、block_categories等安全/成本规则Fallback 链主目标失败或触发限流时按条件切换到备用模型fallbacks流量拆分与金丝雀发布按权重把别名流量分发到多个模型targetsweight支持 A/B 测试与渐进式 rollout负载均衡同一别名下对多个同模型 endpoint 做 round_robin / least_connections / weighted 调度。这些能力体现了别名机制的未来演进方向——从名字映射走向策略载体但在当前仓库实现中尚未落地。八、最佳实践清单综合规则文档、官方文档与仓库实现在生产中使用模型别名时建议所有客户端一律引用别名禁止硬编码模型名让别名成为客户端与网关之间的稳定契约。采用org.purpose.version命名组织前缀防冲突、用途字段自解释、版本号支撑演进同时保留plano.v1这类 canonical 默认别名作为唯一稳定入口。升级模型 改一行 config.yaml从gpt-4o升级到新模型时只更新别名映射需要灰度时新增.v2别名并让新旧并存。配合恰好一个 default Provider别名负责稳定引用default 负责兜底未分类请求二者协同保证路由永不失败。用别名简化多环境管理dev.*、staging.*、prod.*前缀让同一客户端代码在不同环境自动选择不同模型。通过调试日志验证解析开启 debug 日志观察 Model Alias: From X - To Y 输出确认别名命中情况。相关资源速览规则文档skills/rules/routing-aliases.md官方文档docs/source/concepts/llm_providers/model_aliases.rst配置 Schemaconfig/plano_config_schema.yaml可运行示例demos/llm_routing/model_alias_routing/config_with_aliases.yaml 及 README路由配置生成器cli/planoai/config_generator.py别名解析实现crates/brightstaff/src/handlers/llm/mod.rs会话通道解析验证crates/brightstaff/src/handlers/routing_service.rs【免费下载链接】planoPlano is an AI-native proxy server and data plane for agentic apps. Smart LLM routing, observability, agent orchestration, and guardrails so you stay focused on your agents core logic.项目地址: https://gitcode.com/GitHub_Trending/ar/plano创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Plano 模型别名（Model Aliases）实战指南：用语义化、可版本化的模型引用替代硬编码模型名
Plano 模型别名Model Aliases实战指南用语义化、可版本化的模型引用替代硬编码模型名【免费下载链接】planoPlano is an AI-native proxy server and data plane for agentic apps. Smart LLM routing, observability, agent orchestration, and guardrails so you stay focused on your agents core logic.项目地址: https://gitcode.com/GitHub_Trending/ar/plano导读本文基于 Plano 仓库中的 routing-aliases 规则 与 model_aliases 官方文档系统讲解如何通过model_aliases配置将人类可读的语义化别名映射到具体模型标识符从而让客户端与底层模型解耦。你将掌握别名的命名规范、完整配置示例、客户端接入方式、与默认 Provider 及路由偏好的协同用法并看到别名在请求处理管线中的源码级解析原理最终能在生产环境实现换模型只改一行 config.yaml不碰任何客户端代码的稳定集成。一、为什么要用模型别名让客户端契约稳定下来在传统的 LLM 网关接入方式中客户端代码里直接硬编码模型名# Client code — brittle, must be updated when model changes client.chat.completions.create(modelgpt-4o, ...)这种做法的核心痛点是契约耦合一旦你想把gpt-4o升级到新模型或者因成本原因切换到gpt-4o-mini就必须修改每一个调用该 API 的客户端并重新发布。在 Agent 应用Plano 面向的核心场景中客户端数量多、调用点分散硬编码模型名意味着每次模型调整都是一次全量变更。model_aliases正是为了解决这个问题而设计它在配置层建立别名 → 真实模型标识符的映射客户端只引用别名如plano.smart.v1网关在请求处理时负责把别名解析为真实的模型名。当需要升级模型时只需要修改 config.yaml 中的一行映射——客户端代码零改动。从规则文档的 impact 描述来看routing-aliases.md这一能力的价值在于硬编码模型名要求客户端在更换 Provider 时修改代码而别名机制让你仅通过修改 config.yaml 即可完成路由更新。二、反模式与正确姿势先看两个对照配置反模式不定义别名客户端硬编码模型名# config.yaml — no aliases defined version: v0.3.0 listeners: - type: model name: model_listener port: 12000 model_providers: - model: openai/gpt-4o access_key: $OPENAI_API_KEY default: true# Client code — brittle, must be updated when model changes client.chat.completions.create(modelgpt-4o, ...)正确姿势语义化别名 稳定客户端契约version: v0.3.0 listeners: - type: model name: model_listener port: 12000 model_providers: - model: openai/gpt-4o-mini access_key: $OPENAI_API_KEY default: true - model: openai/gpt-4o access_key: $OPENAI_API_KEY - model: anthropic/claude-sonnet-4-6 access_key: $ANTHROPIC_API_KEY model_aliases: plano.fast.v1: target: gpt-4o-mini # Cheap, fast — for high-volume tasks plano.smart.v1: target: gpt-4o # High capability — for complex reasoning plano.creative.v1: target: claude-sonnet-4-6 # Strong creative writing and analysis plano.v1: target: gpt-4o # Default production alias# Client code — stable, alias is the contract client.chat.completions.create(modelplano.smart.v1, ...)对比可见配置侧只是多了model_aliases一节客户端侧则把易变的gpt-4o替换成了语义化的plano.smart.v1。此后无论底层换成gpt-5、claude-sonnet-4-6还是本地模型客户端都不需要感知。三、别名命名规范与版本化策略规则文档明确给出了推荐的命名约定org.purpose.version三段式如plano.fast.v1、acme.code.v2。组织前缀避免多团队共用网关时命名冲突用途字段让别名自解释版本号支撑演进。版本递增实现灰度滚动从.v2升到.v3时新旧别名可同时存在从而在 rollout 期间让老客户端和新客户端并行运行逐步迁移流量。保留一个 canonical 默认别名如plano.v1作为客户端的唯一稳定入口。即使内部模型多次更迭只要该别名始终指向当前生产模型客户端就永远不需要变。model_aliases.rst 在此基础上补充了更多命名维度功能型别名fast-model、smart-model、creative-model这种直接描述能力的名字适合让调用方按我想要多快的模型而非我认识哪个模型来编程。任务型别名code-reviewer、document-summarizer、data-analyst等把别名与业务场景绑定。环境区分dev.chat.v1开发环境用快/便宜模型、prod.chat.v1生产用强模型、staging.chat.v1预发布测试新模型同一套客户端代码在不同环境自动获得不同模型。稳定指针arch.summarize.latest始终指向当前最新版本适合不需要严格版本冻结的调用方。官方文档中的完整示例llm_providers: - model: openai/gpt-4o-mini access_key: $OPENAI_API_KEY - model: openai/gpt-4o access_key: $OPENAI_API_KEY - model: anthropic/claude-3-5-sonnet-20241022 access_key: $ANTHROPIC_API_KEY - model: ollama/llama3.1 base_url: http://localhost:11434 # Define aliases that map to the models above model_aliases: # Semantic versioning approach arch.summarize.v1: target: gpt-4o-mini arch.reasoning.v1: target: gpt-4o arch.creative.v1: target: claude-3-5-sonnet-20241022 # Functional aliases fast-model: target: gpt-4o-mini smart-model: target: gpt-4o creative-model: target: claude-3-5-sonnet-20241022 # Local model alias local-chat: target: llama3.1注该文档示例使用了llm_providers字段名。根据 plano_config_schema.yaml 的 schema 说明llm_providers是为兼容旧版本而保留的废弃写法新配置应使用model_providers配置生成器会自动完成迁移。四、客户端接入Python、cURL、Anthropic 协议别名对客户端完全透明——它就是一个普通的 model 字段值网关负责解析。Python OpenAI SDKfrom openai import OpenAI client OpenAI(base_urlhttp://127.0.0.1:12000/) # Use semantic alias instead of provider model name response client.chat.completions.create( modelarch.summarize.v1, # Points to gpt-4o-mini messages[{role: user, content: Summarize this document...}] ) # Switch to a different capability response client.chat.completions.create( modelarch.reasoning.v1, # Points to gpt-4o messages[{role: user, content: Solve this complex problem...}] )cURLOpenAI 兼容端点curl -X POST http://127.0.0.1:12000/v1/chat/completions \ -H Content-Type: application/json \ -d { model: fast-model, messages: [{role: user, content: Hello!}] }Anthropic Messages 端点同一别名跨协议可用仓库中的 model_alias_routing 示例 展示了同一别名既能走 OpenAI 兼容协议也能走 Anthropic 协议curl -sS -X POST http://localhost:12000/v1/messages \ -H x-api-key: test-key \ -H anthropic-version: 2023-06-01 \ -H Content-Type: application/json \ -d { model: arch.summarize.v1, max_tokens: 50, messages: [ { role: user, content: Hello, please respond with exactly: Hello from alias arch.summarize.v1 via Anthropic! } ] } | jq .关键点别名解析发生在 Plano 网关内部与客户端使用的协议OpenAI/v1/chat/completions、Anthropic/v1/messages无关。客户端永远只写别名网关在转发到上游 Provider 前完成真实模型名的替换。仓库中的完整可运行配置demos/llm_routing/model_alias_routing/config_with_aliases.yaml 是一个开箱即用的全量示例覆盖了 OpenAI、Anthropic含通配anthropic/*、Azure OpenAI、Amazon Bedrock、Ollama、Grok 等多 Provider并定义了 9 个别名version: v0.3.0 listeners: - type: model name: model_listener port: 12000 model_providers: # OpenAI Models - model: openai/gpt-5-mini-2025-08-07 access_key: $OPENAI_API_KEY default: true - model: openai/gpt-4o-mini access_key: $OPENAI_API_KEY - model: openai/o3 access_key: $OPENAI_API_KEY - model: openai/gpt-4o access_key: $OPENAI_API_KEY - model: openai/* access_key: $OPENAI_API_KEY # Anthropic - support all Claude models - model: anthropic/* access_key: $ANTHROPIC_API_KEY - model: anthropic/claude-sonnet-4-6 access_key: $ANTHROPIC_API_KEY - model: anthropic/claude-3-haiku-20240307 access_key: $ANTHROPIC_API_KEY # Azure OpenAI Models - model: azure_openai/gpt-5-mini access_key: $AZURE_API_KEY base_url: https://katanemo.openai.azure.com - model: amazon_bedrock/us.amazon.nova-premier-v1:0 access_key: $AWS_BEARER_TOKEN_BEDROCK base_url: https://bedrock-runtime.us-west-2.amazonaws.com - model: amazon_bedrock/us.amazon.nova-pro-v1:0 access_key: $AWS_BEARER_TOKEN_BEDROCK base_url: https://bedrock-runtime.us-west-2.amazonaws.com # Ollama Models - model: ollama/llama3.1 base_url: http://localhost:11434 # Grok (xAI) Models - model: xai/grok-4-0709 access_key: $GROK_API_KEY # Model aliases - friendly names that map to actual provider names model_aliases: # Alias for summarization tasks - fast/cheap model arch.summarize.v1: target: gpt-5-mini-2025-08-07 # Alias for general purpose tasks - latest model arch.v1: target: o3 # Alias for reasoning tasks - capable model arch.reasoning.v1: target: gpt-4o # Alias for creative tasks - Claude model arch.creative.v1: target: claude-sonnet-4-6 # Alias for quick responses - fast model arch.fast.v1: target: claude-3-haiku-20240307 # Semantic aliases summary-model: target: gpt-5-mini-2025-08-07 chat-model: target: gpt-5-mini-2025-08-07 creative-model: target: claude-sonnet-4-6 coding-model: target: us.amazon.nova-premier-v1:0 # Alias for grok testing arch.grok.v1: target: grok-4-0709 tracing: random_sampling: 100运行该示例的方式详见 model_alias_routing/README.md# 先导出 API Key export OPENAI_API_KEYyour-openai-key export ANTHROPIC_API_KEYyour-anthropic-key # 可选但跑 Anthropic 测试时推荐 # 启动网关自动生成 .env 并加载别名配置 sh run_demo.sh # 停止 sh run_demo.sh down五、别名与默认 Provider、路由偏好的协同模型别名不是孤立功能它与 Plano 路由体系中的默认 Provider、路由偏好routing_preferences共同构成完整的客户端稳定 服务端灵活架构与 default Provider 的配合routing-default.md 强调当请求不匹配任何路由偏好时Plano 会将其转发给标记了default: true的 Provider如果没有 default未匹配请求会失败如果有多个 default则取第一个可能产生意外行为。因此推荐在model_providers中恰好设置一个default: true选择最具性价比的可用模型承接所有未被偏好匹配的流量用别名提供语义入口用 default 提供兜底出口两者互不冲突别名保证客户端引用稳定default 保证任意未分类请求都有去处。与路由偏好的配合若为 Provider 配置routing_preferences按任务语义描述什么样的请求适合这个模型则网关会先按请求意图匹配偏好再结合别名解析完成模型选择。这样可以把别名理解为客户端侧的名字而偏好是网关侧的路由策略——客户端说我要plano.smart.v1网关决定这条请求具体该交给哪个上游模型。与 Passthrough Auth 的组合在多租户或自建代理场景LiteLLM、vLLM 等参见 routing-passthrough.md你可以将别名与passthrough_auth: true、base_url组合使用model_providers: - model: custom/litellm-proxy base_url: http://host.docker.internal:4000 # LiteLLM server provider_interface: openai # LiteLLM uses OpenAI format passthrough_auth: true # Forward clients Bearer token default: true model_aliases: my.gateway.chat.v1: target: litellm-proxy这样客户端只依赖my.gateway.chat.v1这一稳定别名上游从 OpenAI 官方 API 切换到自建 LiteLLM 代理时仅需改动model_providers的 base_url 与认证方式。六、源码视角别名在请求管线中如何被解析配置 Schema 约束plano_config_schema.yaml 中model_aliases的定义L287-L297非常精简model_aliases: type: object patternProperties: ^.*$: type: object properties: target: type: string additionalProperties: false required: - target即model_aliases是一个键值映射每个别名对象只能包含一个target字段字符串且target为必填。这保证了别名语义的纯粹性——别名只做名字 → 真实模型名的一对一解析不承载其他复杂逻辑。核心解析函数别名解析的核心实现在 crates/brightstaff/src/handlers/llm/mod.rs/// Resolves model aliases by looking up the requested model in the model_aliases map. /// Returns the target model if an alias is found, otherwise returns the original model. pub(crate) fn resolve_model_alias( model_from_request: str, model_aliases: OptionHashMapString, ModelAlias, ) - String { if let Some(aliases) model_aliases.as_ref() { if let Some(model_alias) aliases.get(model_from_request) { debug!( Model Alias: From {} - To {}, model_from_request, model_alias.target ); return model_alias.target.clone(); } } model_from_request.to_string() }要点查表式解析从请求体取出model字段在别名哈希表中查找命中则返回target未命中则原样返回——因此未定义的别名不会报错只会按字面模型名处理前提是model_providers中存在该模型。解析时机在 routing_service.rs 中别名在成为会话模型通道session lane之前就被解析——注释明确指出代理路径proxy path会以解析后的模型存储会话绑定如果别名未提前解析同一请求会被误判为不同通道。这一点也有对应的单元测试alias_is_resolved_before_becoming_the_session_lane同文件 L534 起加以验证。日志可观测命中别名时输出debug!级别的 Model Alias: From {别名} - To {目标} 日志便于在 tracing 中确认别名解析是否生效。配置生成与模板侧的支持cli/planoai/config_generator.py 与 cli/planoai/core.py 均引用了model_aliases说明planoaiCLI 在生成/管理配置时会感知别名结构cli/planoai/templates/coding_agent_routing.yaml 等模板中同样使用了别名表明别名是 CLI 引导初始化配置的标准组成部分。七、验证规则与约束综合官方文档与配置 schema使用别名时需要遵守以下约束规则说明依据别名名必须是合法标识符允许字母数字、点、连字符、下划线model_aliases.rsttarget 必须存在于 providers 中别名的目标模型需要在model_providers或兼容的llm_providers中定义否则解析后无法路由到上游model_aliases.rst禁止别名循环引用别名不能间接指向自身model_aliases.rsttarget 为必填且仅此一个字段每个别名对象只能有targetadditionalProperties: falseplano_config_schema.yaml未命中别名时按原模型名透传解析函数未命中即原样返回crates/brightstaff/src/handlers/llm/mod.rs规划中的高级能力以仓库文档为准标注Coming Soonmodel_aliases.rst 明确标注以下能力为未来规划当前 schema 中并不存在对应字段请勿在现版本配置中使用别名级 Guardrails在别名上挂载max_latency、max_cost_per_request、block_categories等安全/成本规则Fallback 链主目标失败或触发限流时按条件切换到备用模型fallbacks流量拆分与金丝雀发布按权重把别名流量分发到多个模型targetsweight支持 A/B 测试与渐进式 rollout负载均衡同一别名下对多个同模型 endpoint 做 round_robin / least_connections / weighted 调度。这些能力体现了别名机制的未来演进方向——从名字映射走向策略载体但在当前仓库实现中尚未落地。八、最佳实践清单综合规则文档、官方文档与仓库实现在生产中使用模型别名时建议所有客户端一律引用别名禁止硬编码模型名让别名成为客户端与网关之间的稳定契约。采用org.purpose.version命名组织前缀防冲突、用途字段自解释、版本号支撑演进同时保留plano.v1这类 canonical 默认别名作为唯一稳定入口。升级模型 改一行 config.yaml从gpt-4o升级到新模型时只更新别名映射需要灰度时新增.v2别名并让新旧并存。配合恰好一个 default Provider别名负责稳定引用default 负责兜底未分类请求二者协同保证路由永不失败。用别名简化多环境管理dev.*、staging.*、prod.*前缀让同一客户端代码在不同环境自动选择不同模型。通过调试日志验证解析开启 debug 日志观察 Model Alias: From X - To Y 输出确认别名命中情况。相关资源速览规则文档skills/rules/routing-aliases.md官方文档docs/source/concepts/llm_providers/model_aliases.rst配置 Schemaconfig/plano_config_schema.yaml可运行示例demos/llm_routing/model_alias_routing/config_with_aliases.yaml 及 README路由配置生成器cli/planoai/config_generator.py别名解析实现crates/brightstaff/src/handlers/llm/mod.rs会话通道解析验证crates/brightstaff/src/handlers/routing_service.rs【免费下载链接】planoPlano is an AI-native proxy server and data plane for agentic apps. Smart LLM routing, observability, agent orchestration, and guardrails so you stay focused on your agents core logic.项目地址: https://gitcode.com/GitHub_Trending/ar/plano创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考