Aider 模型别名（Model Aliases）完全指南：用短名快速切换 LLM

Aider 模型别名（Model Aliases）完全指南：用短名快速切换 LLM

【免费下载链接】aideraider is AI pair programming in your terminal项目地址: https://gitcode.com/GitHub_Trending/ai/aider

Aider 支持为常用模型定义简短别名，通过--alias命令行参数或.aider.conf.yml配置文件把冗长的模型名映射成如fast、smart这类短名，从而在启动命令和会话中的/model命令里快速切换主模型。读完本文，你将掌握别名的两种定义方式、内置别名清单、优先级规则，以及别名在源码中的解析与生效链路，便于在团队中统一模型调用规范。

为什么需要模型别名

LLM 模型的全名往往很长且带版本号，例如claude-3-sonnet-20240229、openrouter/openrouter/optimus-alpha。模型别名（Model Aliases）允许你为高频使用的模型创建简写名，典型场景包括：

• 模型名太长，每次输入--model都很繁琐；
• 团队内部希望统一约定「快/慢」模型的角色，例如fast指代小模型、smart指代强推理模型，模型升级时只改一处别名定义；
• 覆盖 aider 内置别名，把sonnet、4o等短名指向团队偏好的具体模型版本。

对应文档：model-aliases.md。

通过命令行定义别名

使用--alias选项，格式为alias:model-name（别名与模型名之间用冒号分隔）。--alias可重复使用以定义多个别名：

aider --alias "fast:gpt-4o-mini" --alias "smart:o3-mini"

在参数定义中可以看到--alias的注册方式，它使用action="append"收集多次传入的值，metavar即提示了ALIAS:MODEL的取值格式（见 args.py）：

group.add_argument( "--alias", action="append", metavar="ALIAS:MODEL", help="Add a model alias (can be used multiple times)", )

通过配置文件定义别名

同样的别名也可以写在.aider.conf.yml文件中（aider 会按「家目录 → git 仓库根目录 → 当前目录」的顺序查找该文件，后加载的文件优先生效，详见 aider_conf.md）：

alias: - "fast:gpt-4o-mini" - "smart:o3-mini" - "hacker:claude-3-sonnet-20240229"

YAML 中的alias键是一个列表，每项同样是别名:模型名字符串。仓库中的完整配置样例 sample.aider.conf.yml 也包含对应条目：

## Add a model alias (can be used multiple times) #alias: xxx ## Specify multiple values like this: #alias: # - xxx # - yyy # - zzz

使用别名

别名定义后，即可在任何接受模型名的位置用别名替代完整模型名。

启动时指定：

aider --model fast # 实际使用 gpt-4o-mini aider --model smart # 实际使用 o3-mini

会话中用/model命令切换。/model的处理入口是Commands.cmd_model（见 commands.py），它会用你输入的名字直接构造一个新的models.Model对象，而Model的构造过程会自动做别名解析：

Aider v0.75.3 Main model: anthropic/claude-3-7-sonnet-20250219 with diff edit format, prompt cache, infinite output > /model fast Aider v0.75.3 Main model: gpt-4o-mini with diff edit format > /model smart Aider v0.75.3 Main model: o3-mini with diff edit format

内置别名清单

Aider 自带一批常用短名，开箱即用。以下清单与 model-aliases.md 保持一致，对应源码中的MODEL_ALIASES字典（见 models.py）：

别名优先级

当同一个别名在多处定义时，生效优先级从高到低为：

1. 命令行别名（--alias，最高优先级）
2. 配置文件别名（.aider.conf.yml中的alias列表）
3. 内置别名（MODEL_ALIASES默认值，最低优先级）

这意味着你总能用自己的定义覆盖内置别名，例如把sonnet指向团队固定的某个 Claude 快照版本。

源码视角：别名的解析链路

从源码结构看，别名的生效链路分为三步：

1. 命令行别名写入全局字典。main()在处理完模型注册后，遍历args.alias，对每个定义按第一个冒号拆分（alias_def.split(":", 1)，冒号后允许再含冒号，因此 OpenRouter 这类带/和层级前缀的模型名不受影响），校验格式后将结果写入models.MODEL_ALIASES（见 main.py）：

   if args.alias: for alias_def in args.alias: # Split on first colon only parts = alias_def.split(":", 1) if len(parts) != 2: io.tool_error(f"Invalid alias format: {alias_def}") io.tool_output("Format should be: alias:model-name") analytics.event("exit", reason="Invalid alias format error") return 1 alias, model = parts models.MODEL_ALIASES[alias.strip()] = model.strip()

   格式不合法（缺少冒号）时 aider 会直接报错并以非零码退出。

2. 模型构造时做一次查表。Model.__init__的第一步就是把传入名字在MODEL_ALIASES中查一次，命中则替换为规范名，未命中则原样使用（见 models.py）：

   class Model(ModelSettings): def __init__(self, model, weak_model=None, editor_model=None, editor_edit_format=None, verbose=False): # Map any alias to its canonical name model = MODEL_ALIASES.get(model, model) self.name = model

   由于--model选模型和/model切模型最终都会经过Model构造函数，别名在两个入口都自然生效。

3. 别名与废弃参数的联动。aider 已将--sonnet、--4o等旧式模型开关标记为废弃（deprecated），提示用户改用--model。在给出废弃警告时，代码会反向查找MODEL_ALIASES，优先建议用户使用短别名而不是全名（见 deprecated.py）。

需要注意的两点适用前提：

• 别名只改变「名字的解析」，并不改变 API key 要求。例如把别名指向openrouter/...模型后，仍需要配置 OpenRouter 的 API key，否则启动时会收到缺 key 的警告并尝试 OAuth 流程（见 main.py 中的检查逻辑）。
• 别名解析发生在启动阶段和每次Model构造时，指向的模型名最终仍要在 aider 的已知模型元数据（含 litellm 模型库与本地缓存的模型价格/上下文窗口数据）中可查，才能正常显示成本与上下文信息。

小结

• 用--alias "短名:模型全名"或.aider.conf.yml的alias列表定义别名；
• 之后--model 短名与会话内/model 短名均可直接切换；
• 内置别名覆盖 Claude、GPT、Gemini、DeepSeek、OpenRouter 等常用模型；
• 优先级：命令行 > 配置文件 > 内置，便于覆盖默认映射；
• 解析核心是MODEL_ALIASES字典与Model.__init__中的查表替换，改动一处即可全局生效。

【免费下载链接】aideraider is AI pair programming in your terminal项目地址: https://gitcode.com/GitHub_Trending/ai/aider