AI 模型配置与多 Provider 切换

如果你是从“AI 插件各自填 API Key”的年代过来的，第一次用 AI Models 会觉得挺意外：为什么装一个插件，Eagle 就知道该用哪个模型了？

这一篇讲这套统一模型中心怎么用、怎么配，以及怎么按自己的隐私和成本需求选 Provider。

统一模型中心解决的是什么问题

在没有统一配置中心的年代，痛点是这样的：

装插件 A——输一遍 API Key。装插件 B——再输一遍。装插件 C——发现它压根不支持你用的模型。

AI Models 是官方提供的统一 AI 模型配置中心。你在偏好设置里配一次，所有建立在它之上的 AI 插件都能直接用——包括官方的 AI Search 和 AI Action。

一句话概括：它是配置一次、处处可用。

支持的 Provider

目前支持八个 Provider，分三类。

商业模型：

OpenAI 兼容协议：

本地模型（完全离线）：

八个 Provider 不等于只能用八家服务。 OpenAI Compatible 那一项是关键——市面上绝大多数模型服务都提供 OpenAI 兼容接口，包括 Groq、Together AI、Fireworks、vLLM 等。只要你的服务支持 OpenAI 兼容模式，就能配进来。

换句话说：可用模型的实际范围比列表看起来宽得多。

设置步骤

1. 打开 Eagle 插件中心，搜索并安装 AI SDK（AI Models）插件。
2. 打开偏好设置，在左侧栏找到“AI 模型”。
3. 在右侧设置区里选择模型服务提供商，填入 API Key。
4. 分别设置默认语言模型和默认视觉模型。

第 4 步容易被漏掉，但它是整套配置里最关键的一环——下面单独讲。

另外一个省心的机制： 当你安装一个依赖 AI SDK 的插件时，Eagle 会自动提示你安装这个依赖插件。也就是说，你不需要手动去装，Eagle 会确保依赖到位才允许插件运行。

版本提示：AI SDK 相关能力需要 Eagle 4.0 Build 20 或更高版本。Build 20 的更新说明里提到，更新后偏好设置中已经出现了“AI Search”和”AI Models“两个面板。

语言模型和视觉模型要分开设

这是最需要理解的一点，也是最影响实际效果的一点。

为什么分开？ 因为“生成一段文字”和”看懂一张图“对模型的要求完全不同。

实践建议：

• 视觉模型要选强的。 它承担了 AI Action 的全部四个能力，是决定产出质量的核心变量。如果你的预算有限，宁可压缩文字生成的开销，也要把视觉模型配好。
• 语言模型可以用便宜的。 翻译标签、生成规则说明这类任务对模型要求不高。
• 两个都设默认值的意义在于： 不同插件可以各自选不同的模型，而不需要你再次输入 API Key。比如 AI Search 用视觉模型，某个翻译插件用语言模型，你各配一次就都解决了。

三种部署方式的取舍

关于隐私的一个要点： AI Search 的索引和分析是在你本机完成的，图片不上传云端，断网也能用。这是官方明确的设计。

但需要区分清楚：AI Search 本地运行，不等于所有 AI 功能都本地运行。 AI Action 需要视觉模型去理解图片内容，如果你配的是云端视觉模型，那图片是要发给模型服务的。

所以对敏感素材的态度应该是：

• 想完全离线 → 用 Ollama / LM Studio，接受速度慢一些
• 接受出本机 → 用云端视觉模型，质量更好

这个选择应该在配模型的时候就明确下来，而不是等到用了才发现有问题。

常见坑：以为“AI Search 是本地的”就推断”整个 AI 体系都不出本机“。AI Search 和 AI Action 的数据路径不同——前者的索引和分析是本地的，后者调用的视觉模型可能是云端的。对客户机密素材敏感的话，这一点必须先确认。

多个 Provider 切换的实际策略

配多个 Provider 的价值不是“多”，而是在不同场景换用。

场景一：主模型出问题时快速切换。 某个 Provider 限流、宕机、或者账上没钱了，切到备用的继续跑。每个 Provider 的配置是完全独立的，所以切换只是改默认模型，不需要重新填 Key。

场景二：按任务分配成本。 视觉任务用强的模型，文字任务用便宜的模型。批量跑 500 张时，这个差异是实打实的成本。

场景三：本地和云端互补。 日常小任务用本地模型跑，省钱；需要高质量产出的关键批次用云端模型。

场景四：验证产出质量。 同一批素材用两个不同模型各跑一次，对比结果。这其实是判断“你的指令写得好不好”的最直接方法——如果两个模型产出都差不多，说明瓶颈在指令；差距明显，说明瓶颈在模型。

如果你会写一点代码

AI SDK 对插件开发者开放了一套接口，普通用户了解一下也有价值——它能帮你理解 AI 插件的行为逻辑。

获取模块：

const ai = eagle.extraModule.ai;

取默认模型（推荐做法）：

// 语言模型；另有 "image" 可取默认视觉模型
const defaultLLM = ai.getDefaultModel("chat");

if (!defaultLLM) {
  // 用户还没设默认模型，直接打开设置面板
  ai.open();
  return;
}

const model = ai.getModel(defaultLLM);
const result = await ai.generateText({
  model,
  prompt: "请用一句话介绍数字艺术"
});

这里有一个值得学的思路：官方文档明确建议优先用 getDefaultModel()，而不是在代码里写死具体的 Provider 和模型名。 理由是——写死 openai("gpt-5")，如果用户没配 OpenAI 就直接报错；用默认模型则能保证用户已经配置并验证过。

这个思路对普通用户也有价值： 你的模型配置应该是“我在偏好设置里选的”，而不是”某个插件默认带的“。前者是你可控的，后者是别人替你决定的。

其他常用能力：

• ai.getProviders() — 获取全部 Provider（返回数组，不是对象）
• ai.getAvailableProviders() — 只返回你已完成配置的 Provider
• ai.getProvider(name) — 获取指定 Provider
• ai.open() — 打开模型设置面板

一个容易踩的坑：getProviders() 返回的是数组，不是对象。写成解构赋值 const { openai } = ai.getProviders() 是错的。另外如果写成 await ai.getProviders() 也不对——这个方法是同步的。

常见坑：Provider 和 Model 之间用双冒号 :: 分隔，比如 openai::gpt-5。用单冒号或斜杠会报错。这个格式错误的表现是“明明填了却读不到”。

一个配置检查清单

配完之后过一遍：

1. 语言模型和视觉模型都设了默认值吗？ 只设一个的话，某些功能会不可用。
2. 切到 AI Action 试跑 10 张，出结果了吗？ 这是验证视觉模型配置是否生效的最快方式。
3. 切到 AI Search 试搜一次，出结果了吗？ 验证索引和服务是否正常。
4. 云端模型的费用和隐私影响，你确认过吗？ 尤其是客户素材。
5. 有没有备用的 Provider 配置？ 主 Provider 挂掉时的保险。

第 4 条是最容易被忽略但最该先想清楚的。API Key 填完不会提醒你“这批图要发到外部服务”，所以这个判断要在配置之前做，而不是在跑完整批之后才做。

最后：配置决定的只是上限

模型配得再好，也弥补不了规则写得糊。

官方的说法很准确：重命名和描述的效果同样受模型能力、提示设计、素材类型和批量处理方式影响。模型理解不足，或者提示过于笼统，生成的描述就容易流于表面。

所以合理的期待是：好模型 + 好指令 = 好产出；两者只有一个好，结果都一般。 如果产出质量不满意，先判断是哪一环出了问题——换模型试一次，如果还是不行，那就是指令的问题。

整理人：WorkBuddy