企业官网建设流程全解析

PI-Desktop 模型别名功能详解：给你的常用模型起一个快捷名字的完整指南

【免费下载链接】PI-DesktopLocal-first AI coding agent desktop: Electron + Rust host core + pi Agent Harness + user-installable plugins项目地址: https://gitcode.com/GitHub_Trending/pid/PI-Desktop

PI-Desktop 是一款本地优先的 AI 编程智能体桌面应用，它的模型别名功能让你可以为配置中的模型起一个简短的个人名字（如 "fast"、"pro"）。别名会显示在输入框、模型选择器等所有提到模型名的位置，而实际请求仍使用真实模型 ID，完全不影响调用。下面带你快速上手这个实用功能。

为什么需要模型别名？

日常使用中，一个服务商下往往挂着好几个名字非常相似的模型（比如同一系列的 mini / pro / max），在输入框的模型下拉菜单里很容易混淆。而模型目录里发布的显示名是"只读"的，你没法改。

模型别名（Model Alias）就是来解决这个问题的：给某个模型绑一个你自己的短标签，一眼就能认出它。这是由 docs/adr/0192-model-alias.md 这份架构决策文档正式确定的功能设计。

三步设置模型别名

第 1 步：打开模型配置页

进入设置 → 智能体 → 模型，你会看到服务商列表。点击某个服务商行展开，选择你想起名的模型。

第 2 步：展开"高级"选项

在选中的模型行右侧点击"高级"（Advanced）展开详细配置区，第一个字段就是"别名"（Alias），占位提示是"例如 fast"。

第 3 步：输入别名，自动保存

输入你想要的名字（最多 60 个字符），别名会作为服务商模型配置的一部分自动持久化。清掉这个字段，就会恢复目录里的原始显示名。

别名输入框的实现位于 ModelSelectionPanes.tsx，输入时会按 Unicode 码点截断到 60 字符，与后端校验保持一致。

别名在哪里生效？

按设计约定，别名的显示遵循一条清晰的规则——"面向人的地方显示别名，面向机器的地方保持真实 ID"：

这条规则的好处是：即使别名起得再随意，你也永远不会搞错"到底会调用哪个模型"。显示名的解析逻辑见 composer-models.ts：别名非空时用别名，否则用目录显示名，最后回退到模型 ID。

别名规则与限制一览

• 长度上限 60 个字符：后端 Rust 核心会校验，超长时返回MODEL_ALIAS_TOO_LONG错误，校验代码见 validation.rs
• 纯显示标签：id永远是发给服务商的请求标识，别名不会改变任何请求行为
• 空白即删除：空别名会被直接丢弃并恢复目录命名，不存在"残留的空标签"
• 零架构成本：别名存在现有的服务商配置 JSON 里，无需协议或数据库结构变更

一个典型使用场景

假设你在同一服务商下配了两个模型：

1. 把日常快速问答的模型别名设为fast
2. 把处理复杂重构的模型别名设为deep

之后在输入框的模型选择器里，你会看到清爽的fast/deep，而不是一串长得几乎一样的发布名。切换模型、搜索模型都更快，多服务商、多模型的管理成本大幅下降。

💡 小贴士：配置页的模型 ID 现在也支持直接拖选复制（.selectable样式），不用再手动重打一长串 ID 了。

模型别名的国际化文案（各语言的"别名"标签与提示语）维护在 packages/i18n/src/locales/zh-CN/index.ts，功能细节更多可参考 13-model-catalog-and-selection.md 规格文档。

【免费下载链接】PI-DesktopLocal-first AI coding agent desktop: Electron + Rust host core + pi Agent Harness + user-installable plugins项目地址: https://gitcode.com/GitHub_Trending/pid/PI-Desktop