Ever Gauzy 的 Gauzy AI Provider 插件:AI Chat 引擎中的占位提供者与未来路由设计

原创2026-09-29 15:05:031,696 阅读
文章标签:企业应用ERPCRM后端前端桌面应用微服务MCP 服务

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)"

也就是说,它目前并不提供任何真实的对话能力,只承担两件事:

  1. 在插件启动(bootstrap)时,把 gauzy-ai 这个提供者注册到 Chat 引擎的 AiProviderRegistry,使它在注册表和 UI(设置页的提供者目录)中可见;
  2. 明确宣告该提供者尚未实现——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 的约定),并可通过以下任一方式配置凭证:

  1. 租户 BYOK:租户在 AI Chat 设置页保存自己的上游密钥(经 /api/ai-chat/credentials,优先级最高);
  2. 服务端环境变量:运维人员为整个实例设置服务端级 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 环境变量),它才会成为开箱即用的服务端路由通道。

登录后查看全文
ever-gauzy