定制 big-AGI派生应用开发与深度自定义实战指南【免费下载链接】big-AGIAI suite powered by state-of-the-art models and providing advanced AI/AGI functions. Includes AI personas, AGI functions, world-class Beam multi-model chats, text-to-image, voice, response streaming, code highlighting and execution, PDF import, presets for developers, much more. Deploy on-prem or in the cloud.项目地址: https://gitcode.com/GitHub_Trending/bi/big-AGI本指南基于仓库 docs/customizations.md 展开系统讲解如何基于 big-AGI 开源仓库定制品牌、UI、人设与功能并将其部署为面向自身业务场景的派生应用。读完本文你将掌握环境变量与源码改动两种定制路径的边界、人设/主题/导航的修改位置、Message of the DayMOTD横幅配置、Node.js Functions 超时调优、认证接入、调试技巧以及部署选型。定制方式的总体边界改代码还是设环境变量big-AGI 的定制遵循一条清晰的分界线文档在开头用表格做了明确划分理解这条边界是后续所有操作的前提需要改动源码构建前完成无需改动源码构建后配置即可人设Persona的增删改在环境变量中设置各类 API Key详见 docs/environment-variables.mdUI 主题定制通过环境变量开关功能如 MOTD、调试断点功能的新增或修改在本地机器或云端部署上、应用启动前设置关键结论目前 big-AGI没有面向企业级托管式定制的管理后台Admin Panel一切定制要么落在源码里要么落在环境变量里。凡涉及 UI 与功能的改动都必须 fork 仓库后改源码再构建而密钥与功能开关这类运行时配置则可以在构建产物镜像/部署之外随时注入。代码定制的基础Fork 与架构认知动手前先在 GitHub 上 Fork big-AGI 仓库建立个人开发空间。从源码结构看package.json、next.config.ts技术栈为Next.js应用框架与路由层页面定义在 pages/如index.tsx、call.tsx、draw.tsx、personas.tsx、tokens.tsx等React MUI Joy前端 UI主题基于mui/joy的extendTheme见 src/common/app.theme.tsNode.jsNext.js Edge Functions后端由 src/server/trpc/ 与 src/modules/ 下的 server 目录承载支持 Vercel/Cloudflare 等平台的 Edge Runtime。关于环境变量的完整清单与优先级UI 选项 后端环境变量 默认值参见 docs/environment-variables.md它明确与 src/server/env.server.ts 保持同步可作为定制时的变量字典。添加认证文件重命名式改动big-AGI 默认不内置认证。若要在应用层启用 HTTP Basic Authentication需要在构建前做一次文件重命名将仓库根目录下的middleware_BASIC_AUTH.ts重命名为middleware.ts再按常规构建流程参考 docs/installation.md 的本地生产构建或 docs/deploy-docker.md 的 Docker 构建打包最后在启动前配置两个环境变量HTTP_BASIC_AUTH_USERNAMEyour username HTTP_BASIC_AUTH_PASSWORDyour password这一机制在 docs/deploy-authentication.md 中有完整说明。若不想重建应用也可以利用云平台的认证能力如 Cloudflare Access/Zero Trust、Vercel 的 Authentication 或 Password Protection。调整 Vercel Functions 超时Node.js Functions 专用对于长时间运行的操作Vercel 付费部署允许调大 Functions 的超时时间。需要注意该设置只适用于旧式 Node.js Functions不适用于新的 Edge Functions。从当前仓库的调用链看运行在 Node.js Functions 上的核心操作只有两类浏览Browsing抓取网页内容由 src/modules/browse/browse.router.ts 提供 tRPC 路由分享SharingChat Link Sharing 相关的服务端逻辑src/modules/trade/link/ 与 src/modules/trade/server/。二者都可能超过默认的 10 秒——抓取大页面或等待慢网站完成时尤其明显。调优方式为进入 Vercel 项目Settings General Build Development Settings将 Build Command 设为next build修改人设Personas默认人设集中定义在 src/data.ts当前仓库中内置了 9 个系统人设SystemPurposeId类型枚举Generic默认人设id 为defaultSystemPurposeId、DeveloperPreview、Developer、Scientist、Catalyst、Executive、Designer、YouTubeTranscriber、Custom。每个人设由SystemPurposeData结构描述常见字段包括字段说明title人设显示名称description一句话描述可包含 JSX 元素systemMessage注入给 LLM 的系统提示词支持{{LLM.Cutoff}}、{{LocaleNow}}、{{RenderMermaid}}、{{RenderPlantUML}}、{{RenderSVG}}、{{PreferTables}}等模板变量symbol人设图标emojiexamples起始对话示例help me plan a trip to Japan 等call语音呼叫场景的 starter 语句voices关联的 ElevenLabs 默认语音 IDimageUri人设头像图片路径如DeveloperPreview指向/images/personas/dev_preview_icon_120x120.webp定制时可直接增删或修改SystemPurposes对象比如把systemMessage替换为符合你业务领域的提示词或新增一个SystemPurposeId并在SystemPurposes中补齐对应数据。注意在 v1.x 版本中人设定制只能通过修改 src/data.ts 完成这是构建期代码运行时无法热改。修改 UI主题、应用名与导航UI 定制集中在三个文件职责分明主题颜色、间距、按钮外观、动画等src/common/app.theme.ts。该文件通过createAppTheme()调用mui/joy的extendTheme生成主题核心定制点包括colorSchemes.light/colorSchemes.dark两套调色板可覆盖neutral、text、background等色阶例如surface、level1、level2、body、popup字体正文使用 InterthemeFontFamilyCss代码使用 JetBrains MonothemeCodeFontFamilyCsscomponents对 Joy 组件做 styleOverrides如去掉 Input/Select 的 box-shadow、调整 Switch 拇指大小、控制 Modal 的动画等themeScalingMapxs/sm/md三档内容缩放配置可整体调整代码字号、消息内边距、列表行高该文件还导出了一组themeZIndex*常量PageBar、Drawer、Nav、ChatBubble 等层级需要微调层级关系时也可以在此修改。应用名称src/common/app.release.ts。其中BaseProduct.ProductName为 Big-AGI同时TenantSlug注释明确标注 CHANGE ME用于标识部署租户Release.buildInfo()读取NEXT_PUBLIC_DEPLOYMENT_TYPE、NEXT_PUBLIC_BUILD_PKGVER、NEXT_PUBLIC_BUILD_HASH、NEXT_PUBLIC_BUILD_TIMESTAMP等构建期变量。注意品牌信息Title、Meta、URIs分散在 src/common/app.config.ts 的Brand对象中改应用名时建议连同public/manifest.json的name、short_name等一起替换。导航栏src/common/app.nav.ts。navItems分为appsChat、Call、Personas、Compare Text、Tokenize Text、Shared Chats、News 等、modalsConfigure AI Models、App Preferences与linksDiscord、GitHub 外链。每个NavItemApp支持route、icon、hideOnMobile、hideDrawer、hideBar、hideNav、isDev显示 dev 徽标、_delete从 UI 删除等开关文件末尾还通过navItems.apps.filter(app !app._delete || SHOW_ALL_APPS)统一过滤掉标记删除的项SHOW_ALL_APPS常量可在开发布局时强制显示全部。添加每日消息Message of the Day利用NEXT_PUBLIC_MOTD环境变量可以在应用顶部显示一条可关闭的临时公告横幅非常适合版本发布提醒、维护通知或新功能高亮。该变量为构建期前端变量必须随构建注入在 docs/environment-variables.md 中也有记录。模板变量支持由 src/common/layout/optima/OptimaMOTD.tsx 实际解析模板变量含义对应构建变量{{app_build_hash}}当前 Git 提交哈希NEXT_PUBLIC_BUILD_HASH{{app_build_pkgver}}包版本号NEXT_PUBLIC_BUILD_PKGVER{{app_build_time}}构建时间戳以相对时间 TimeAgo 渲染NEXT_PUBLIC_BUILD_TIMESTAMP{{app_deployment_type}}部署类型local、docker、vercel 等NEXT_PUBLIC_DEPLOYMENT_TYPE实现细节OptimaMOTD通过!!process.env.NEXT_PUBLIC_MOTD决定是否渲染optimaHasMOTD在useMemo中对{{app_build_*}}做正则替换{{app_build_time}}则被拆分为TimeAgo组件以相对时间展示横幅的关闭状态以motd-前缀 内容哈希存入 UI storeuiSetDismissed因此用户点击关闭后直到下次刷新前不再显示。示例配置NEXT_PUBLIC_MOTD New features available in {{app_build_pkgver}}! Try the improved Beam.测试与部署在本地开发环境充分测试后本地构建步骤见仓库根 README.md即可选择部署平台。big-AGI 支持 Vercel、Docker以及任何兼容 Node.js、尤其支持 Next.js Edge Runtime 的平台。针对不同平台的详细操作参见docs/deploy-cloudflare.mdCloudflare Pages 部署有限支持docs/deploy-docker.mdDocker 部署说明与示例配套 docker-compose.yamldocs/deploy-k8s.mdKubernetes 部署说明与示例配套 docs/k8s/ 清单文件。调试技巧查看客户端日志应用内置客户端日志系统可通过Settings Tools Logs在 UI 中查看最近的日志。日志基础设施集中在 src/common/logger/logger.client.ts、logger.factory.ts、store-logger.ts等。Debug 页面访问/dev/debug对应 pages/dev/debug.tsx可一览应用的环境信息、配置、各 API 状态以及客户端可用的环境变量是排查部署配置的首选入口。条件断点错误发生时自动暂停当控制台出现error、critical、DEV级别的关键日志时可让浏览器 DevTools 自动暂停以便在错误发生的瞬间检查应用状态。在本地.env.local中设置NEXT_PUBLIC_DEBUG_BREAKStrue然后重启开发服务器。该机制的底层实现在 src/common/util/errorUtils.ts 的maybeDebuggerBreak()只有当NEXT_PUBLIC_DEBUG_BREAKS true且Release.IsNodeDevBuild即NODE_ENV development同时成立时才触发debugger语句。也就是说该功能仅在开发模式npm run dev下生效环境变量必须显式设为字符串true生产构建中debugger语句通常会被构建工具移除因此不会影响线上性能。最佳实践与社区协作保持更新频繁从 big-AGI 主仓库合并更新以纳入 bug 修复与新功能派生仓库维护的常规做法保持开源考虑以开源方式维护派生项目便于获得社区贡献参与社区借助 GitHub、Discord 等渠道获取反馈、协作与推广分享派生项目部署完成后可更新自己派生仓库的 README 并提交 Pull Request申请加入社区项目列表帮助他人发现和学习你的成果原文档中的社区项目列表可在 docs/customizations.md 中查看。小结big-AGI 的定制路径非常明确环境变量负责运行时的密钥与功能开关构建后注入源码改动负责人设、主题、品牌与导航构建前完成。从本文给出的各文件锚点出发——src/data.ts 管人设、src/common/app.theme.ts 管视觉、src/common/app.release.ts 与 src/common/app.config.ts 管品牌、src/common/app.nav.ts 管导航、src/common/layout/optima/OptimaMOTD.tsx 管公告横幅——你可以快速定位每个定制点并配合 docs/environment-variables.md 完成一次完整的派生应用开发与部署。【免费下载链接】big-AGIAI suite powered by state-of-the-art models and providing advanced AI/AGI functions. Includes AI personas, AGI functions, world-class Beam multi-model chats, text-to-image, voice, response streaming, code highlighting and execution, PDF import, presets for developers, much more. Deploy on-prem or in the cloud.项目地址: https://gitcode.com/GitHub_Trending/bi/big-AGI创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/17 9:06:39 · 阅读 1.2k 定制 big-AGI：派生应用开发与深度自定义实战指南
定制 big-AGI派生应用开发与深度自定义实战指南【免费下载链接】big-AGIAI suite powered by state-of-the-art models and providing advanced AI/AGI functions. Includes AI personas, AGI functions, world-class Beam multi-model chats, text-to-image, voice, response streaming, code highlighting and execution, PDF import, presets for developers, much more. Deploy on-prem or in the cloud.项目地址: https://gitcode.com/GitHub_Trending/bi/big-AGI本指南基于仓库 docs/customizations.md 展开系统讲解如何基于 big-AGI 开源仓库定制品牌、UI、人设与功能并将其部署为面向自身业务场景的派生应用。读完本文你将掌握环境变量与源码改动两种定制路径的边界、人设/主题/导航的修改位置、Message of the DayMOTD横幅配置、Node.js Functions 超时调优、认证接入、调试技巧以及部署选型。定制方式的总体边界改代码还是设环境变量big-AGI 的定制遵循一条清晰的分界线文档在开头用表格做了明确划分理解这条边界是后续所有操作的前提需要改动源码构建前完成无需改动源码构建后配置即可人设Persona的增删改在环境变量中设置各类 API Key详见 docs/environment-variables.mdUI 主题定制通过环境变量开关功能如 MOTD、调试断点功能的新增或修改在本地机器或云端部署上、应用启动前设置关键结论目前 big-AGI没有面向企业级托管式定制的管理后台Admin Panel一切定制要么落在源码里要么落在环境变量里。凡涉及 UI 与功能的改动都必须 fork 仓库后改源码再构建而密钥与功能开关这类运行时配置则可以在构建产物镜像/部署之外随时注入。代码定制的基础Fork 与架构认知动手前先在 GitHub 上 Fork big-AGI 仓库建立个人开发空间。从源码结构看package.json、next.config.ts技术栈为Next.js应用框架与路由层页面定义在 pages/如index.tsx、call.tsx、draw.tsx、personas.tsx、tokens.tsx等React MUI Joy前端 UI主题基于mui/joy的extendTheme见 src/common/app.theme.tsNode.jsNext.js Edge Functions后端由 src/server/trpc/ 与 src/modules/ 下的 server 目录承载支持 Vercel/Cloudflare 等平台的 Edge Runtime。关于环境变量的完整清单与优先级UI 选项 后端环境变量 默认值参见 docs/environment-variables.md它明确与 src/server/env.server.ts 保持同步可作为定制时的变量字典。添加认证文件重命名式改动big-AGI 默认不内置认证。若要在应用层启用 HTTP Basic Authentication需要在构建前做一次文件重命名将仓库根目录下的middleware_BASIC_AUTH.ts重命名为middleware.ts再按常规构建流程参考 docs/installation.md 的本地生产构建或 docs/deploy-docker.md 的 Docker 构建打包最后在启动前配置两个环境变量HTTP_BASIC_AUTH_USERNAMEyour username HTTP_BASIC_AUTH_PASSWORDyour password这一机制在 docs/deploy-authentication.md 中有完整说明。若不想重建应用也可以利用云平台的认证能力如 Cloudflare Access/Zero Trust、Vercel 的 Authentication 或 Password Protection。调整 Vercel Functions 超时Node.js Functions 专用对于长时间运行的操作Vercel 付费部署允许调大 Functions 的超时时间。需要注意该设置只适用于旧式 Node.js Functions不适用于新的 Edge Functions。从当前仓库的调用链看运行在 Node.js Functions 上的核心操作只有两类浏览Browsing抓取网页内容由 src/modules/browse/browse.router.ts 提供 tRPC 路由分享SharingChat Link Sharing 相关的服务端逻辑src/modules/trade/link/ 与 src/modules/trade/server/。二者都可能超过默认的 10 秒——抓取大页面或等待慢网站完成时尤其明显。调优方式为进入 Vercel 项目Settings General Build Development Settings将 Build Command 设为next build修改人设Personas默认人设集中定义在 src/data.ts当前仓库中内置了 9 个系统人设SystemPurposeId类型枚举Generic默认人设id 为defaultSystemPurposeId、DeveloperPreview、Developer、Scientist、Catalyst、Executive、Designer、YouTubeTranscriber、Custom。每个人设由SystemPurposeData结构描述常见字段包括字段说明title人设显示名称description一句话描述可包含 JSX 元素systemMessage注入给 LLM 的系统提示词支持{{LLM.Cutoff}}、{{LocaleNow}}、{{RenderMermaid}}、{{RenderPlantUML}}、{{RenderSVG}}、{{PreferTables}}等模板变量symbol人设图标emojiexamples起始对话示例help me plan a trip to Japan 等call语音呼叫场景的 starter 语句voices关联的 ElevenLabs 默认语音 IDimageUri人设头像图片路径如DeveloperPreview指向/images/personas/dev_preview_icon_120x120.webp定制时可直接增删或修改SystemPurposes对象比如把systemMessage替换为符合你业务领域的提示词或新增一个SystemPurposeId并在SystemPurposes中补齐对应数据。注意在 v1.x 版本中人设定制只能通过修改 src/data.ts 完成这是构建期代码运行时无法热改。修改 UI主题、应用名与导航UI 定制集中在三个文件职责分明主题颜色、间距、按钮外观、动画等src/common/app.theme.ts。该文件通过createAppTheme()调用mui/joy的extendTheme生成主题核心定制点包括colorSchemes.light/colorSchemes.dark两套调色板可覆盖neutral、text、background等色阶例如surface、level1、level2、body、popup字体正文使用 InterthemeFontFamilyCss代码使用 JetBrains MonothemeCodeFontFamilyCsscomponents对 Joy 组件做 styleOverrides如去掉 Input/Select 的 box-shadow、调整 Switch 拇指大小、控制 Modal 的动画等themeScalingMapxs/sm/md三档内容缩放配置可整体调整代码字号、消息内边距、列表行高该文件还导出了一组themeZIndex*常量PageBar、Drawer、Nav、ChatBubble 等层级需要微调层级关系时也可以在此修改。应用名称src/common/app.release.ts。其中BaseProduct.ProductName为 Big-AGI同时TenantSlug注释明确标注 CHANGE ME用于标识部署租户Release.buildInfo()读取NEXT_PUBLIC_DEPLOYMENT_TYPE、NEXT_PUBLIC_BUILD_PKGVER、NEXT_PUBLIC_BUILD_HASH、NEXT_PUBLIC_BUILD_TIMESTAMP等构建期变量。注意品牌信息Title、Meta、URIs分散在 src/common/app.config.ts 的Brand对象中改应用名时建议连同public/manifest.json的name、short_name等一起替换。导航栏src/common/app.nav.ts。navItems分为appsChat、Call、Personas、Compare Text、Tokenize Text、Shared Chats、News 等、modalsConfigure AI Models、App Preferences与linksDiscord、GitHub 外链。每个NavItemApp支持route、icon、hideOnMobile、hideDrawer、hideBar、hideNav、isDev显示 dev 徽标、_delete从 UI 删除等开关文件末尾还通过navItems.apps.filter(app !app._delete || SHOW_ALL_APPS)统一过滤掉标记删除的项SHOW_ALL_APPS常量可在开发布局时强制显示全部。添加每日消息Message of the Day利用NEXT_PUBLIC_MOTD环境变量可以在应用顶部显示一条可关闭的临时公告横幅非常适合版本发布提醒、维护通知或新功能高亮。该变量为构建期前端变量必须随构建注入在 docs/environment-variables.md 中也有记录。模板变量支持由 src/common/layout/optima/OptimaMOTD.tsx 实际解析模板变量含义对应构建变量{{app_build_hash}}当前 Git 提交哈希NEXT_PUBLIC_BUILD_HASH{{app_build_pkgver}}包版本号NEXT_PUBLIC_BUILD_PKGVER{{app_build_time}}构建时间戳以相对时间 TimeAgo 渲染NEXT_PUBLIC_BUILD_TIMESTAMP{{app_deployment_type}}部署类型local、docker、vercel 等NEXT_PUBLIC_DEPLOYMENT_TYPE实现细节OptimaMOTD通过!!process.env.NEXT_PUBLIC_MOTD决定是否渲染optimaHasMOTD在useMemo中对{{app_build_*}}做正则替换{{app_build_time}}则被拆分为TimeAgo组件以相对时间展示横幅的关闭状态以motd-前缀 内容哈希存入 UI storeuiSetDismissed因此用户点击关闭后直到下次刷新前不再显示。示例配置NEXT_PUBLIC_MOTD New features available in {{app_build_pkgver}}! Try the improved Beam.测试与部署在本地开发环境充分测试后本地构建步骤见仓库根 README.md即可选择部署平台。big-AGI 支持 Vercel、Docker以及任何兼容 Node.js、尤其支持 Next.js Edge Runtime 的平台。针对不同平台的详细操作参见docs/deploy-cloudflare.mdCloudflare Pages 部署有限支持docs/deploy-docker.mdDocker 部署说明与示例配套 docker-compose.yamldocs/deploy-k8s.mdKubernetes 部署说明与示例配套 docs/k8s/ 清单文件。调试技巧查看客户端日志应用内置客户端日志系统可通过Settings Tools Logs在 UI 中查看最近的日志。日志基础设施集中在 src/common/logger/logger.client.ts、logger.factory.ts、store-logger.ts等。Debug 页面访问/dev/debug对应 pages/dev/debug.tsx可一览应用的环境信息、配置、各 API 状态以及客户端可用的环境变量是排查部署配置的首选入口。条件断点错误发生时自动暂停当控制台出现error、critical、DEV级别的关键日志时可让浏览器 DevTools 自动暂停以便在错误发生的瞬间检查应用状态。在本地.env.local中设置NEXT_PUBLIC_DEBUG_BREAKStrue然后重启开发服务器。该机制的底层实现在 src/common/util/errorUtils.ts 的maybeDebuggerBreak()只有当NEXT_PUBLIC_DEBUG_BREAKS true且Release.IsNodeDevBuild即NODE_ENV development同时成立时才触发debugger语句。也就是说该功能仅在开发模式npm run dev下生效环境变量必须显式设为字符串true生产构建中debugger语句通常会被构建工具移除因此不会影响线上性能。最佳实践与社区协作保持更新频繁从 big-AGI 主仓库合并更新以纳入 bug 修复与新功能派生仓库维护的常规做法保持开源考虑以开源方式维护派生项目便于获得社区贡献参与社区借助 GitHub、Discord 等渠道获取反馈、协作与推广分享派生项目部署完成后可更新自己派生仓库的 README 并提交 Pull Request申请加入社区项目列表帮助他人发现和学习你的成果原文档中的社区项目列表可在 docs/customizations.md 中查看。小结big-AGI 的定制路径非常明确环境变量负责运行时的密钥与功能开关构建后注入源码改动负责人设、主题、品牌与导航构建前完成。从本文给出的各文件锚点出发——src/data.ts 管人设、src/common/app.theme.ts 管视觉、src/common/app.release.ts 与 src/common/app.config.ts 管品牌、src/common/app.nav.ts 管导航、src/common/layout/optima/OptimaMOTD.tsx 管公告横幅——你可以快速定位每个定制点并配合 docs/environment-variables.md 完成一次完整的派生应用开发与部署。【免费下载链接】big-AGIAI suite powered by state-of-the-art models and providing advanced AI/AGI functions. Includes AI personas, AGI functions, world-class Beam multi-model chats, text-to-image, voice, response streaming, code highlighting and execution, PDF import, presets for developers, much more. Deploy on-prem or in the cloud.项目地址: https://gitcode.com/GitHub_Trending/bi/big-AGI创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考