Ever Gauzy 的 Gauzy AI Provider 插件:AI Chat 引擎中的占位提供者与未来路由设计
Ever Gauzy 的 Gauzy AI Provider 插件:AI Chat 引擎中的占位提供者与未来路由设计
本文基于 ai-provider-gauzy-ai/README.md 与仓库源码,剖析
@gauzy/plugin-ai-provider-gauzy-ai插件的设计定位:它目前是一个注册到 Ever Gauzy AI Chat 引擎(@gauzy/plugin-ai-chat)提供者注册表中的占位符(placeholder)。读完本文你将理解:该插件如何把gauzy-ai提供者注册进AiProviderRegistry并呈现在 UI 中、为什么createModel会主动抛错、GAUZY_AI_API_KEY/GAUZY_AI_BASE_URL两个环境变量的真实归属,以及 Gauzy AI 服务端路由代理的未来规划与 BYOK(自带密钥)机制的关系。
插件定位:一个"看得见、用不了"的占位提供者
@gauzy/plugin-ai-provider-gauzy-ai 是 Ever Gauzy AI Chat 引擎(@gauzy/plugin-ai-chat)的 AI 提供者插件。从 package.json 的描述可以看出它的真实状态:
"registers the Gauzy AI provider placeholder with the @gauzy/plugin-ai-chat provider registry (chat routing through Gauzy AI is not implemented yet)"
也就是说,它目前并不提供任何真实的对话能力,只承担两件事:
- 在插件启动(bootstrap)时,把
gauzy-ai这个提供者注册到 Chat 引擎的AiProviderRegistry,使它在注册表和 UI(设置页的提供者目录)中可见; - 明确宣告该提供者尚未实现——
createModel会抛出异常,且不暴露任何模型。
这样做的设计意图是:让 Ever Gauzy 的架构从第一天起就拥有 "Gauzy AI" 这个稳定的提供者 ID 与 UI 入口,但避免把尚未实现的通道暴露给用户造成误用。在它真正落地之前,应当改用直接提供者插件(@gauzy/plugin-ai-provider-anthropic、@gauzy/plugin-ai-provider-openai、@gauzy/plugin-ai-provider-openrouter、@gauzy/plugin-ai-provider-vercel-gateway)。
注册链路:从插件生命周期到静态注册表
该插件的实现非常精简,核心只有两个文件:
插件类:一行定义即完成注册
import { GauzyCorePlugin as Plugin } from '@gauzy/plugin';
import { BaseAiProviderPlugin } from '@gauzy/plugin-ai-chat';
import { gauzyAiProviderDefinition } from './ai-provider-gauzy-ai.provider';
@Plugin({})
export class AiProviderGauzyAiPlugin extends BaseAiProviderPlugin {
protected readonly definition = gauzyAiProviderDefinition;
}
插件类继承自 BaseAiProviderPlugin(定义见 base-ai-provider.plugin.ts),这个抽象基类为所有 @gauzy/plugin-ai-provider-* 插件统一了生命周期行为:
onPluginBootstrap(): void | Promise<void> {
AiProviderRegistry.register(this.definition);
// ...
}
onPluginDestroy(): void | Promise<void> {
AiProviderRegistry.unregister(this.definition.id);
// ...
}
即:启动时注册、销毁时注销,插件作者只需要提供一份 IAiChatProviderDefinition 定义即可,无需关心 Chat 模块的 Nest 依赖图。
注册表:进程级静态 Map
AiProviderRegistry(见 provider-registry.ts)是一个静态注册表而非 Nest DI 注入,这样提供者插件无需导入 Chat 模块的依赖图,与后端插件通过扁平的 plugins.ts 列表组合的方式保持一致:
static register(definition: IAiChatProviderDefinition): void { ... }
static unregister(id: string): void { ... }
static get(id: string): IAiChatProviderDefinition | undefined { ... }
static list(): IAiChatProviderDefinition[] { ... } // 按 order 升序排序
register在 ID 已存在时会打出一条替换警告(was already registered — replacing);list()按order字段升序排列,未设置order的排在最后;- Chat 引擎在请求时读取该注册表来解析提供者。
因此,只要 AiProviderGauzyAiPlugin 出现在 Ever Gauzy 的插件组合列表(后端 plugins.ts)中,gauzy-ai 就会出现在提供者目录与 UI 中——但它并不是一个可用的聊天提供者。
提供者定义源码剖析:字段逐一解读
gauzyAiProviderDefinition 实现了 Chat 引擎定义的 IAiChatProviderDefinition 契约(完整契约见 provider.types.ts),其关键字段如下:
| 字段 | 当前值 | 含义 |
|---|---|---|
id |
AiProviderEnum.GAUZY_AI(即 'gauzy-ai') |
注册表、UI 与 BYOK 凭证共用的稳定提供者 ID,定义于 ai-chat.model.ts |
label |
'Gauzy AI' |
UI 中展示的人类可读名称 |
apiKeyEnvVars |
[](空数组) |
服务端 API Key 环境变量列表,刻意留空 |
chatCapable |
false |
明确标记"不具备聊天能力",独立于凭证是否存在的开关 |
baseUrlEnvVar |
'GAUZY_AI_BASE_URL' |
可选的自定义 Gauzy AI API Base URL 环境变量 |
models |
[] |
不暴露任何模型 |
defaultModel |
'' |
无默认模型 |
order |
10 |
注册表升序排序时排在最前(数值小优先) |
websiteUrl |
https://gauzy.ai |
设置页展示的提供者主页 |
apiKeysUrl |
https://app.gauzy.ai |
"获取 API Key"链接 |
createModel |
总是抛错 | 见下文"刻意抛错"设计 |
为什么 apiKeyEnvVars 被刻意留空
源码注释记录了一个重要的历史教训:apiKeyEnvVars 曾经是 ['GAUZY_AI_API_KEY'],这会让该提供者把自己报告为 configured: true(已配置)。但问题在于:
GAUZY_AI_API_KEY实际上属于另一个无关插件@gauzy/plugin-integration-ai(配置定义见 integration-ai/src/lib/config/gauzy-ai.ts,该文件同时使用GAUZY_AI_GRAPHQL_ENDPOINT、GAUZY_AI_REST_ENDPOINT、GAUZY_AI_REQUEST_TIMEOUT、GAUZY_AI_API_KEY、GAUZY_AI_API_SECRET等变量)。
也就是说,任何使用 integration-ai 集成的运维人员,都会无意中让这个"不可用"的聊天提供者看起来可用。再加上 order: 10(注册表升序排序第一名),它甚至可能赢得默认选择,然后每一轮对话都因 "not implemented yet" 失败。
因此源码明确注释:只有在 createModel 真正返回真实模型的那次改动中,才应恢复该环境变量。
chatCapable: false:能力与凭证是两个独立问题
清空 apiKeyEnvVars 只能堵住"环境变量"这一条路。因为凭证解析是**租户优先(tenant-first)**的:一个租户如果在 BYOK 设置页手动保存了 Gauzy AI 的密钥,该提供者仍会被标记为 configured、赢得默认选择(排序第一),随后每轮对话都失败。所以 chatCapable 被设计为独立于凭证的"能力"开关(见 provider.types.ts 中对该字段的文档注释):在 createModel 返回真实模型之前,该字段必须保持 false。
createModel 刻意抛错
async createModel(_modelId: string, _credentials: IAiProviderCredentials): Promise<never> {
throw new Error(
'Chat via Gauzy AI is not implemented yet — configure another provider. See @gauzy/plugin-ai-provider-gauzy-ai README.'
);
}
createModel 的返回类型是 Promise<never>——永远不返回,只抛异常。这是"占位符"最直接的表现:Chat 引擎一旦为该提供者创建模型就会收到明确的错误提示,指引用户配置其他提供者。
环境变量:两个保留变量及其真实归属
原文档给出的环境变量如下:
| 变量 | 描述 |
|---|---|
GAUZY_AI_API_KEY |
服务端级 Gauzy AI API Key(为未来保留) |
GAUZY_AI_BASE_URL |
可选的 Gauzy AI API 自定义 Base URL |
需要特别说明的是它们的真实归属:
GAUZY_AI_API_KEY:当前实际被@gauzy/plugin-integration-ai的配置读取(见 integration-ai/src/lib/config/gauzy-ai.ts),用于该集成而非本聊天提供者。本插件将其标记为"reserved for future use"(为未来保留)——这正是其apiKeyEnvVars被清空的原因。GAUZY_AI_BASE_URL:被本插件声明为baseUrlEnvVar,为将来指向自定义 Gauzy AI API 端点预留。
也就是说:现阶段不要为 gauzy-ai 提供者配置任何上游 API Key——它没有任何模型可调用,配置了反而会在 UI 中造成"已配置"的假象。
规划中的设计:服务端代理路由
原文档明确给出了该插件的未来设计(Planned design):
当租户启用了 Gauzy AI 集成(@gauzy/plugin-integration-ai)时,gauzy-ai 提供者的聊天请求将被代理到 Gauzy AI API。由 Gauzy AI 服务端统一负责:
- 上游提供者 API Key 的管理(租户无需配置任何上游密钥);
- 模型选择与路由(model selection and routing);
- 服务端侧的模型编排。
这样做的收益是:租户无需配置任何上游提供者密钥即可获得聊天能力,密钥的保存、选择与路由全部收敛到服务端。
BYOK 机制与代理路由的关系
原文档同时强调:BYOK(自带密钥)机制保持不变——租户通过 /api/ai-chat/credentials 接口(对应 ai-provider-credential.controller.ts 的 GET/PUT/POST /credentials 端点)按租户保存密钥,用于直接提供者(anthropic、openai、openrouter 等)。凭证的保存与加密逻辑见 ai-provider-credential.service.ts:每个 (tenant, provider) 一行、API Key 加密存储、isDefault 标记聊天默认提供者、isVoiceDefault 标记语音/听写默认提供者(实体定义见 ai-provider-credential.entity.ts)。
凭证解析的优先级是租户优先:先解析租户 BYOK 密钥,其次才是服务端环境变量(IAiProviderCredentials.source 为 'tenant' | 'environment' | 'platform',见 provider.types.ts)。因此对于直接提供者,租户密钥始终优先于服务端环境变量——这一优先级在 Gauzy AI 代理落地后也不会改变。
当前应如何使用:改用直接提供者
在 Gauzy AI 聊天路由实现之前,正确的使用方式是启用直接提供者插件:
@gauzy/plugin-ai-provider-anthropic@gauzy/plugin-ai-provider-openai@gauzy/plugin-ai-provider-openrouter@gauzy/plugin-ai-provider-vercel-gateway
它们各自实现自己的 createModel(通常惰性导入 ESM-only 的 Vercel AI SDK 提供者包,见 provider.types.ts 中 createModel 的约定),并可通过以下任一方式配置凭证:
- 租户 BYOK:租户在 AI Chat 设置页保存自己的上游密钥(经
/api/ai-chat/credentials,优先级最高); - 服务端环境变量:运维人员为整个实例设置服务端级 API Key。
小结
@gauzy/plugin-ai-provider-gauzy-ai 是 Ever Gauzy AI Chat 引擎中一个"先占位、后实现"的提供者插件:
- 它通过
BaseAiProviderPlugin生命周期把gauzy-ai提供者注册进进程级AiProviderRegistry,让其在 UI 中可见; apiKeyEnvVars清空、chatCapable: false、createModel抛错三个机制共同确保它不会被误配置、误选为默认后导致每轮对话失败;GAUZY_AI_API_KEY目前归属@gauzy/plugin-integration-ai,仅为该聊天提供者保留;- 未来它将把租户聊天请求代理到 Gauzy AI 服务端,统一管理上游密钥、模型选择与路由,同时 BYOK 机制与"租户密钥优先于环境变量"的解析顺序保持不变。
对开发者和运维人员而言,现阶段的关键结论是:把 gauzy-ai 提供者当作 UI 占位符看待,实际对话请选择并配置一个直接提供者插件;当 createModel 返回真实模型时(同时会恢复 GAUZY_AI_API_KEY 环境变量),它才会成为开箱即用的服务端路由通道。