big-AGI 的 AIX 子系统：类型安全的多模态 AI 客户端/服务器流式通信架构

big-AGI 的 AIX 子系统：类型安全的多模态 AI 客户端/服务器流式通信架构

【免费下载链接】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

AIX（Advanced AI eXchange）是 big-AGI 中一个以 tRPC 为骨架的客户端/服务器库，用于将先进 AI 能力集成进 Web 应用，为聊天、Beam 多模型对话、文本生成等功能提供实时的类型安全通信。本文以kb/modules/AIX.md为主体，结合仓库源码（src/modules/aix/）剖析其系统架构、ChatGenerate 完整工作流、供应商适配体系与端到端粒子协议，帮助读者理解 big-AGI 如何统一封装十余家 AI 提供商的流式与非流式接口，并掌握其扩展机制与适用边界。

AIX 概述：应用与 AI 提供商之间的实时、类型安全通道

AIX（客户端/服务器库）的核心职责是：在 TypeScript 应用与 AI 提供商之间建立实时、类型安全的通信。它构建在 tRPC 之上，负责管理 AI 生成内容从请求到渲染的完整生命周期，同时支持**流式（streaming）与非流式（non-streaming）**两类 AI 提供商。

从 big-AGI 的整体架构看，AIX 并非孤立模块，而是贯穿多个应用的关键基础设施：聊天（src/apps/chat/）、Beam 多模型并行（src/modules/beam/）、代码修复（aifn系列）、Auto Follow-ups、附件摘要、自动标题、Persona 生成等均通过 AIX 的三大核心函数发起调用。正如kb/modules/AIX-callers-analysis.md所归纳，AIX 采用"核心函数 → 工具层 → UI 层"的三层调用结构，UI 层享受最丰富的错误状态与占位符处理，核心层保持最小处理并向上传播错误。

特性清单

其中"服务端超时/重试"与"流式/非流式"两大机制在源码中有明确落点：服务端重试由chatGenerate.operation-retry.ts与chatGenerate.continuation.ts承载；客户端侧则存在AixStreamRetry（aix.client.retry.ts）与ContentReassembler的重组/续传机制，形成"客户端超时 + 服务端重试"的双保险（见下文的时序图说明）。

AIX 提供商支持矩阵

AIX 通过统一的内部协议对上屏蔽了各 AI 服务商的协议差异。截至文档记录时刻，各提供商的支持情况如下：

注记：

• (1)续传（Continuation）标记：a. 发送reason=max-tokens（流式/非流式）；b. TBA（待定）。
• (2)Ollama 尚未移植到 AIX：由于其自定义 API 的缘故。

此表中"✅ + Parallel"意味着该提供商除基础函数调用外还支持并行工具调用；📦 标记表示流式响应支持"装箱"（分块/批处理传输）；"续传"能力（续写被max-tokens截断的生成）由服务端的chatGenerate.continuation.ts实现。表内的差异（如 Perplexity/Deepseek 拒绝工具调用、OpenRouter 函数调用不稳定）直接影响了 big-AGI 在各提供商上默认启用的功能开关，是选型与排障的重要依据。

系统架构：三大组件

AIX 子系统由三个主要组件构成：

1. 客户端（例如 Next.js 前端）

   • 发起请求
   • 实时渲染 AI 生成内容
   • 重建流式数据（ContentReassembler）

2. 服务端（例如 Next.js 后端）

   • 作为客户端与 AI 提供商之间的中介
   • 处理请求准备、派发与响应处理
   • 将响应流式回传客户端

3. 上游 AI 提供商

   • 根据请求生成 AI 内容

在 big-AGI 中，客户端入口是aix.client.ts，服务端 tRPC 路由入口是aix.router.ts，两者间通过 Zod 校验的"线协议"（Wire Types）通信——这部分定义于aix.wiretypes.ts。路由注释中的架构说明言简意赅：Client <-- (intake) --> Server <-- (dispatch) --> AI Service，即"接收"与"派发"两段通道的分界线。

ChatGenerate 工作流（七步闭环）

ChatGenerate是 AIX 的核心内容生成流程，完整步骤如下：

1. 请求初始化：AIX 客户端准备并发送请求（systemInstruction、messages=AixWire_Parts[]等）到 AIX 服务端；
2. 派发准备：AIX 服务端为上游通信做准备；
3. AI 提供商交互：AIX 服务端与 AI 提供商通信（流式或非流式）；
4. 数据解码、转换与传输：AIX 服务端向 AIX 客户端发送AixWire_Particles；
5. 客户端处理：客户端的ContentReassembler将AixWire_Particles处理为一系列（通常为单个）多片段消息（DMessageContentFragment[]）；
6. 完成：AIX 服务端发送done控制消息，AIX 客户端完成数据更新；
7. 错误处理：AIX 服务端在必要时发送特定错误消息。

需要区分文档中反复出现的两个线协议名词：AixWire_Parts（入站，客户端 → 服务端，描述待发送的内容/消息结构，定义于aix.wiretypes.ts的AixWire_Parts/AixWire_Content命名空间）与AixWire_Particles（出站，服务端 → 客户端，描述增量粒子操作，如文本追加、部分开始、指标设置、结束信号等）。DMessageContentFragment则是 big-AGI 前端消息模型中的内容片段类型（文本、图片引用、工具调用、错误等）。

端到端时序图

以下 Mermaid 时序图完整刻画了从客户端发起请求到最终渲染的粒子级交互，是理解 AIX 内部协议的最直观材料（与kb/modules/AIX.md中的原图一致）：

图中的几个要点值得注意：PartTransmitter 是协议的核心抽象——它负责将解析后的增量事件"节流"序列化为AixWire_PartParticle，服务端不一次性发送全量响应，而是按批次累积传输；客户端ContentReassembler则按收到的粒子批次增量重建DMessage*Part，从而实现边生成边渲染的实时体验。错误处理同时存在于两处：派发准备期错误（dispatch-prepare）、派发期错误（dispatch-fetch/dispatch-read/dispatch-parse）由服务端以控制消息下发，客户端另设有无响应超时兜底。

源码级解析：文件与目录结构

AIX 在仓库中的实际位置是src/modules/aix/，与文档描述一一对应，组织如下：

1. 客户端（client/）

• aix.client.ts：AIX 操作的主要客户端入口。导出三大核心函数aixChatGenerateContent_DMessage_FromConversation（会话流式生成）、aixChatGenerateContent_DMessage_orThrow（直接请求/响应）、aixChatGenerateText_Simple（纯文本工具类生成），并负责模型参数组装（aixCreateModelFromLLMOptions，支持 temperature、maxTokens、topP、reasoningEffort 及各厂商vnd*参数）与流式调用（apiStream）。
• aix.client.chatGenerateRequest.ts：将聊天消息转换为 AIX 兼容格式（AixWire_Content、AixWire_Parts等），并应用客户端"热修复"（hotfix）。
• ContentReassembler.ts：核心重组器，将AixWire_Particles流式重组成DMessage*Part（文本、图片、工具调用、错误、文档、占位符），支持检查点恢复与续传重置。
• 其他：aix.client.errors.ts（流式错误分类）、aix.client.retry.ts（AixStreamRetry）、aix.client.direct-chatGenerate.ts（客户端直连 CSF 模式）、debugger/（AI 检查器调试面板）、withDecimator.ts（粒子抽取/节流辅助）。

2. 服务端（server/）

• API 层（server/api/）——客户端到服务端通信：

  • aix.router.ts：定义 AIX 的 tRPC 路由，包含chatGenerateContent（流式生成主入口，输入access/model/chatGenerate/context/streaming/connectionOptions）、upstreamReattachContent（按 handle 重连进行中的上游运行，如 OpenAI Responses 断网恢复、Gemini Deep Research 跨刷新续跑）与upstreamDeleteContent（删除上游存储的运行）。此外内置"慢请求看门狗"，在 Vercel 边缘函数 300 秒硬杀前约 15 秒记录超时请求的模型/上下文。
  • aix.wiretypes.ts：以 Zod 模式定义客户端入站类型（AixWire_Parts、AixWire_Content、AixWire_Tooling、AixWire_API等）与出站类型（AixWire_Particles）。从源码看，AixWire_Parts覆盖 DocPart、InlineAudioPart、InlineImagePart、MediaUrlPart、ModelAuxPart 等片段，并携带各厂商的_vnd状态命名空间（如 Anthropic 容器、Responses 厂商的 reasoning 续传句柄）。
  • 辅助：aix.resilience.ts、aix.security.ts、aix.wiretypes.openrouter.ts。

• 派发层（server/dispatch/）——服务端到 AI 提供商通信：

  • chatGenerate/：内容生成（聊天风格输入）：
    • adapters/：为不同 AI 协议创建 API 请求的适配器（Anthropic、Bedrock、Gemini、OpenAI Chat Completions、OpenAI Responses、xAI Responses）。
    • parsers/：解析不同 AI 协议的流式/非流式响应（Anthropic、Bedrock Converse、Gemini、OpenAI、OpenAI Responses）。
    • chatGenerate.dispatch.ts：创建针对特定提供商的 Chat 生成执行管线（createChatGenerateDispatch）。
    • ChatGenerateTransmitter.ts：序列化并传输AixWire_Particles到客户端（实现IParticleTransmitter接口，维护文本/部分粒子队列、终止原因、token 停止原因与指标累积）。
    • 其他：chatGenerate.continuation.ts（续传）、chatGenerate.operation-retry.ts（重试）、chatGenerate.executor.ts（执行器）、chatGenerate.debug.ts（调试）。
  • wiretypes/：各 AI 提供商/协议的线类型定义（Anthropic、Bedrock Converse、Gemini、OpenAI、xAI），并含_upstream/上游协议规格文档。
  • stream.demuxers.ts：处理不同流格式的解复用（SSE、fast-SSE、AWS EventStream），对应文件为stream.demuxer.sse.ts、stream.demuxer.fastsse.ts、stream.demuxer.aws-eventstream.ts。

3. 派发管线的方言选择逻辑

createChatGenerateDispatch（chatGenerate.dispatch.ts）是理解"多供应商支持"的关键：它根据access.dialect（如anthropic、bedrock、gemini、openai等）将统一请求特化为对应厂商的适配器与解析器，并输出ChatGenerateDispatch（含请求体、demuxer 格式、解析函数、粒子变换）。例如：

• Anthropic：通过aixToAnthropicMessageCreate构建请求体，支持推理地理路由（inference_geo），流式走fast-sse解复用，非流式走createAnthropicMessageParserNS；若启用内联文件变换，还会附加createAnthropicFileInlineTransform。
• Bedrock：按vndBedrockAPI细分converse（Bedrock 原生）、invoke-anthropic（Anthropic 原生 InvokeModel，需将 header 参数搬入 body 并携带anthropic-version）、mantle（OpenAI Chat Completions 兼容）、mantle-responses（OpenAI Responses 兼容，供 GPT-5.x 等前沿模型使用）；流式响应体需经aws-eventstream-binary变换。
• OpenAI 体系：RESPONSES_ONLY_DIALECTS（metaai、sakanaai、xai）强制走 Responses API。

由此可见，AIX 的"适配器 + 解析器 + demuxer"三段式抽象，正是支撑表格中十余家服务商"一张矩阵"的根本设计。

客户端重组与调用方生态

ContentReassembler：粒子 → 消息片段的增量重建

ContentReassembler.ts是客户端的协议终点。它维护ReassemblyState（含当前打开的文本片段游标、待决消息 phase、终止原因、token 停止原因），对每批收到的AixWire_Particles.ChatGenerateOp执行增量处理；支持在继续生成（continuation）时基于检查点重置，且可通过ReassemblerParticleTransforms在重组前对粒子做 1:1 异步变换（如图片压缩、厂商内联文件处理）。文档时序图中"ContentReassembler processes particles into DMessage*Part"分支（文本更新、图片加载显示、工具调用处理、错误显示、文档处理、占位符处理）在此文件中均有对应实现。

调用方模式与错误/占位符策略

kb/modules/AIX-callers-analysis.md记录了 AIX 三大核心函数的全部调用方及其消息处理模式，值得作为二次开发参考：

• 会话流式（_FromConversation）：Chat Persona、XE Chat Generate、Beam Scatter/Gather/Follow-up、ScratchChat、Telephone、ReAct Agent、Variform 等。典型策略是"生成开始前被中断则移除整条消息"（messageWasInterruptedAtStart()，判断条件为tokenStopReason === 'client-abort'且无片段），或使用占位符（createPlaceholderVoidFragment）维持 UI 结构。
• 直接请求（orThrow）：Auto Follow-ups、Gen CR Diffs、Code Fixup、Attachment Prompts 等，失败时多向上抛错或做片段级替换。
• 纯文本工具（_Simple）：conversationTitle、conversationSummary、useStreamChatText、useLLMChain、imaginePromptFromText 等，采用 try/catch 回退值或错误状态，静默降级。

错误处理的复杂度从核心层向 UI 层递增：核心层最小处理并向上传播，工具层优雅降级，UI 层（如 DiagramsModal、FlattenerModal）提供重试、回退 UI 与加载态。这一分层设计让 Beam 与 Chat Persona 获得最完善的恢复能力。

生产状态、使用边界与代码执行扩展

生产使用声明与生态边界

文档末尾（2025-03-14 更新）明确说明：AIX 已在 big-AGI 生产环境中使用，稳定且性能良好；但其代码与 tRPC 框架及本仓库其余代码高度耦合，不建议在本生态之外使用。对于寻求独立 TypeScript 方案的项目，文档推荐 Vercel AI SDK。因此，将 AIX 定位为"big-AGI 生态内的核心通信层"而非通用 SDK，是准确的边界认知。

从 AIX 延伸：Anthropic 代码执行与沙箱

仓库中另有kb/modules/AIX-anthropic-code-execution.md记录 AIX 对 Anthropic 代码执行（code_execution_20260120容器）的接入方向，可视为 AIX 能力在"函数调用/代码执行"维度上的延伸：单一事实来源位于adapters/anthropic.messageCreate.ts的aixAnthropicHostedFeatures()，它同时驱动工具清单与 beta headers；enableCodeExecution由独立沙箱开关（vndAntCodeSandbox）、Skills（vndAntSkills）与程序化工具调用（PTC）三方汇聚，且刻意与动态 Web 搜索解耦（即 #1087 修复：不因动态 Web 自动启用独立代码执行工具，避免模型从脚本中调用 Web 工具引发死循环）。客户端侧，容器状态经svs粒子由ContentReassembler.onSetVendorState提升至DMessageGenerator.upstreamContainer，实现了跨轮次的容器续接——这正是 AIX 粒子协议在复杂工具场景下的实际运用案例。

小结

AIX 是 big-AGI 内部承担"最后一公里"的核心基础设施：以 tRPC + Zod 保证类型安全，以"适配器/解析器/demuxer"抽象统一十余家 AI 提供商，以AixWire_Parts（入站）与AixWire_Particles（出站）粒子协议打通流式全链路，并以ContentReassembler在客户端完成增量重建。理解这套架构，有助于在 big-AGI 中定位生成链路问题、扩展新供应商适配器（adapters/+parsers/+wiretypes/三处改动），以及评估其与 Vercel AI SDK 等通用方案在生态耦合度上的差异。

延伸阅读：本文主体文档kb/modules/AIX.md；调用方分析kb/modules/AIX-callers-analysis.md；代码执行扩展kb/modules/AIX-anthropic-code-execution.md；核心实现 客户端入口、tRPC 路由、派发管线、粒子传输器、线协议定义、客户端重组器。

【免费下载链接】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