最近一段时间我在折腾一个周末练手项目用 Flutter 做客户端接上大模型再套一层多智能体的编排做成一个能分工协作的知识库问答助手。整套走下来比预想的更有意思也踩了不少坑——从 Flutter 环境搭建时的 Gradle 警告到 LLM 请求返回provider rejected再到几个 Agent 之间参数互相打架每个环节都够单独写一篇复盘。这篇文章就是把这个实战入门过程完整记录下来。我会从为什么选 Flutter LLM 多智能体这个组合讲起然后拆解 Flutter 环境搭建、LLM 集成、RAG 知识库、多智能体协作最后给出一套可以直接抄作业的代码结构和最容易踩的坑。适合两类读者一是已经会 Flutter、想往 AI 应用方向走的客户端同学二是熟悉大模型但想找一个前端交互落点的后端同学。看完你至少能知道一条从零到可运行的完整链路长什么样。1. 为什么是 Flutter LLM 多智能体先把这个组合的真实意图说清楚。这三样东西分开看都不新鲜但组合起来解决的是一个非常具体的问题AI 应用不能只靠一个对话框和一个模型硬撑。1.1 单个模型不够用多智能体分工才是常态先说 LLM。大语言模型本质上是给定一段文本预测下一个词再把词连成完整回复。很多人纠结“LLM 是否属于深度学习”答案是肯定的它就是深度学习里的 Transformer 架构放大到海量参数之后的产物只是今天我们不再关心它的训练过程而是把它当做一个“推理核心”来用。但这个推理核心有一个很现实的问题它不擅长稳定地完成多步骤长任务。你让它写一首诗没问题让它“先分析用户问题再查知识库再比对多条资料最后写一份带引用的回答”它很容易做着做着就跳步骤或者把检索结果和自己的想象混在一起。这就是多智能体要解决的场景把复杂任务拆给多个各司其职的 LLM 实例每个只做一件小事然后用编排逻辑把它们串起来。我打的比方是一个全能杂工进厨房让他从备菜、炒菜到摆盘全包容易手忙脚乱换成一个团队切菜的人只切菜炒菜的人只炒菜传菜的人只传菜每个环节把结果交给下一棒整体就稳定得多。多智能体就是这个团队。1.2 为什么是 Flutter 做客户端客户端选型其实没太多悬念。要做 AI 助手类产品通常绕不开 iOS 和 Android 双端再加一个 Web 演示版。Flutter 一套代码覆盖这些平台而且还保留了接近原生的渲染性能尤其是新版 Impeller 渲染引擎全面默认开启之后掉帧和卡顿比早期 Skia 时代改善明显。更关键的是AI 应用交互层有大量自定义 UI流式输出的打字机效果、多轮对话卡片、知识来源折叠面板、Agent 执行过程可视化。Flutter 的组件组合能力在这一类界面开发上效率很高而且组件通信体系完整——MethodChannel 用来做原生能力调用EventChannel 做持续事件流PlatformView 则能直接把原生视图嵌进 Flutter 页面。后面做流式输出、端侧模型集成时都用得上。1.3 一条清晰的数据链路整个项目的核心链路是用户输入 → Flutter 页面 → LLM 网关 → 多智能体编排 → LLM 模型 工具调用 → 结果回传 → Flutter 渲染。这里把“多智能体编排”放在网关后面而不是放在 Flutter 端是刻意做的选择。一是 API 密钥不能放在客户端二是编排逻辑会越来越复杂放服务端更好迭代三是后续换模型、加 Agent 不需要重新发版。入门阶段可以先用 Flutter 直连模型跑通但心里一定要有这条向后迁移的路径。2. 从零搭建 Flutter 环境与创建项目不管多智能体设计得多漂亮第一步永远是脚手架。这一步看起来简单实际有一堆版本兼容问题。2.1 环境搭建版本、SDK 和几个绕不开的警告Flutter 环境的搭建方式很简单去官网下载对应系统的 SDK 压缩包解压后把bin目录加入PATH然后运行flutter doctor检查依赖。我这里用的是 Flutter 3.44 稳定版这也是当前迭代里比较新的版本Dart SDK 和 Android 工具链的匹配相对顺滑。但光是版本选择就有讲究。你在网上搜“flutter windows 3.47.5 下载”这类关键词时会发现Flutter 几乎每几个月就发一个新版本而 Android Studio、Gradle、AGP 插件之间经常互相要求版本匹配。新手最容易遇到的第一个报错是The current configured Flutter SDK is not known to be fully supported.这句话的意思是你项目里的 Android Gradle PluginAGP版本和 Flutter SDK 内置的兼容性校验表对不上。通常发生在你手工升级了 AGP或者用了某个刚发布的 Gradle 版本。解决思路不是盲目升级而是降到 Flutter 官方已经验证过的 AGP 版本组合能让项目先稳稳跑起来再考虑升级。另一个高频警告是You are applying Flutters main Gradle plugin imperatively using the apply这是项目里的build.gradle或settings.gradle在用旧式apply plugin方式加载 Flutter Gradle 插件而新版本推荐用plugins {}DSL 声明式引入。不是致命错误但新版 Flutter 会提示你迁移。我的建议是在全新项目里直接用模板生成的配置不要手抄网上老教程的 Gradle 配置能省掉一批这类问题。2.2 创建项目从flutter create到原生工程嵌入跑通环境后创建项目就一条命令flutter create my_ai_app模板生成完lib/main.dart里的计数页就能跑。接下来要规划的是做成纯 Flutter 项目还是安卓原生项目嵌入 Flutter 页面这个取决于你团队现状。如果你们已经有成熟的安卓/ iOS 原生 App想在设置页里嵌一个 AI 助手入口那就走“add-to-app”路线用flutter attach那一套如果是全新项目直接纯 Flutter 开发最省事。我这次练手选择的是纯 Flutter 项目但特意在项目里预留了原生交互层因为后面大概率要接端侧模型或系统能力。这里把三个交互接口理清MethodChannel 是“Flutter 发起、原生响应”的双向调用适合取设备信息、跳原生页面EventChannel 是“原生持续往 Flutter 推送事件”适合流式增量输出PlatformView 则是把原生控件塞到 Flutter 视图树里适合嵌入地图、WebView。2.3 项目结构规划创建完项目后第一件事是改目录结构。不要把所有代码堆在main.dart里。我的分层方式是lib/ pages/ // 页面层只负责 UI 和状态绑定 widgets/ // 复用组件比如消息气泡、引用卡片 services/ // 网络请求、LLM 网关封装 agents/ // 多智能体编排如果用 Flutter 端或客户端侧协调逻辑 models/ // 数据模型这样的好处是以后把多智能体编排从 Flutter 端换到后端网关只需改services层页面代码完全不用动。多数练手项目后期扩功能时被文件名混乱拖死的这个教训我踩过不止一次。3. LLM 集成从 Token 到 RAG把大模型拉进应用脚手架搭好后就到了最核心的部分怎么让 App 和 LLM 对话。这里要讲清楚几个概念别急着写代码。3.1 先搞懂 TokenKey、Query、Value 到底在说什么做 LLM 开发离不开 Token。Token 是模型处理文本的最小单位一个中文词或一个英文单词大概对应一个到几个 Token。所有计费、上下文长度限制都按 Token 算。很多人看到注意力机制的三个概念“Key、Query、Value”会觉得抽象我用一个句子把它们串起来Key 表示“我是谁、我有什么信息”Query 表示“我在找什么”Value 表示“我能提供什么”。模型在生成下一个词时会把当前诉求作为 Query在历史上下文里挨个匹配每个位置的 Key命中后再从对应的 Value 里提取信息来辅助决策。对应用开发者的现实意义在于Token 就是你的“上下文预算”。提示词越长、塞进的知识库片段越多开销越大而且当上下文窗口塞满时模型会丢弃最开头的信息。所以做 RAG 时不是把所有文档一股脑塞进提示词而是只挑最相关的片段为的就是省 Token、保精度。3.2 自己封装 HTTP 调用还是上 LLM 框架入门阶段我强烈建议先自己用 Dart 封装一个最朴素的 HTTP 调用不急着上 LangChain 这类框架。因为调试需要一条一条链路确认请求发出去没有响应回来没有解析有没有报错。框架在中间一包出了问题很难判断是网络、模型还是封装层。一个最简的 Dart 侧调用长这样直接用http包发POST /v1/chat/completionsimport dart:convert; import package:http/http.dart as http; FutureString chatCompletion({ required String apiKey, required String model, required ListMapString, String messages, }) async { final resp await http.post( Uri.parse(https://api.example.com/v1/chat/completions), headers: { Content-Type: application/json, Authorization: Bearer $apiKey, }, body: jsonEncode({ model: model, messages: messages, temperature: 0.7, max_tokens: 2048, }), ); if (resp.statusCode ! 200) { throw Exception(LLM request failed: ${resp.body}); } final data jsonDecode(utf8.decode(resp.bodyBytes)); return data[choices][0][message][content] as String; }这一步跑通后你会立刻遇到两个现实问题一是代码里直接写死了模型厂商切换模型要改代码二是密钥放客户端很不安全。这时就应该引入“LLM 网关”的概念——在服务端统一封装一层接口客户端只传消息列表服务端负责选模型、管密钥、做限流。做得再细一点网关还可以统计不同模型的 Token 消耗、统一流式输出格式、在多个模型之间做负载均衡。团队的正式项目里这一层基本是必需的。那 404 的 LLM 框架LangChain、LlamaIndex 这些在哪一步用是在你开始做复杂编排、需要大量插件化工具调用的时候。框架把“通用的请求拼接、常见的工具链流程”抽象出来好处是起步快坏处是调试黑盒化。我的建议是先手工把流程捋一遍再决定要不要框架而不是一上来就背着框架调试。3.3 给 LLM 装一个外挂RAG、LLM Wiki 和 GraphRAG如果只是对话接入一个通用模型就够了。但实际项目里你几乎一定会遇到这个问题模型没学过你的私有数据。解决办法就是 RAG检索增强生成。流程拆开就四步把文档切成片段 → 向量化后存到向量库 → 用户提问时在库里做相似度检索 → 把检索结果拼进提示词让模型作答。网上热门的“LLM Wiki 知识库”项目本质就是给团队 Wiki 文档加了一层 RAG让模型能引用公司内部沉淀来回答。我这次练手做的就是一个小型知识库问答把几十篇 Markdown 文档切片、向量化用户提问后先检索最相关的几段再让模型基于这些片段回答。这里有一个容易被忽略的重点RAG 的瓶颈十有八九在“切分”和“召回”不在模型。段落切得太碎语义就断了切得太大混入噪声又拉低召回精度。切分策略要根据文档类型反复调没有银弹。再进一步如果你要回答的问题涉及复杂的实体关系朴素 RAG 召回效果会很差。这时候就要关注 GraphRAG 或者本体Ontology方案把文档里的实体和关系抽出来构建知识图谱回答问题时先在图里沿关系路径检索再交给模型生成。这个方向信息密度高、实现难度也大入门阶段可以只了解概念不必硬上。3.4 端侧模型部署了解一下有个方向顺便提一下就是 ONNX 部署 LLM 模型。做法是把一个小型模型转成 ONNX 格式在手机端直接跑推理优点是隐私数据不出设备、不依赖网络缺点是模型能力弱、内存占用高。Flutter 端接这类能力时通常走 PlatformView 或 MethodChannel 调原生推理代码没有官方一体化插件。入门阶段先放着等你需要离线兜底的时候再深入。4. 多智能体架构设计与协作模式聊完 LLM 单点能力接下来是重头戏多智能体怎么设计、怎么协作。4.1 多智能体不是多个对话框而是一个团队先统一概念智能体Agent不是一个聊天机器人而是一个能够调用工具、根据目标自主决策的 LLM 实例。它比单纯的“提示词交互”多出了行动能力比如查数据库、调接口、做计算然后根据结果决定下一步怎么做。多智能体系统就是让多个各怀技能的 Agent 分工协作。以我的知识库问答为例设计了四个角色Agent职责输入输出IntentAgent识别用户意图判断是否走知识库、是否需要工具原始用户问题意图分类、关键实体RetrieverAgent检索知识库或调用检索工具意图和实体相关文档片段WriterAgent基于片段组织回答用户问题 片段完整回答GuardAgent审核回答是否基于片段、有无幻觉回答 片段通过 / 打回重写这就是一个“顺序监督”的协作模式。实际项目中还有人做“并行式”“反思循环式”。并行式适合多个 Agent 同时调研不同维度的信息再汇总反思循环式则让一个 Agent 写方案、另一个专门挑毛病循环几轮再定稿。模式本身没有优劣看任务复杂度。4.2 一次问答背后发生了什么完整 Agent 协作流程我把用户问题“我们团队对 API 限流的建议是什么”跑了一遍完整流程用文本描述给你看过程IntentAgent 先对问题做分类判断这属于“知识库检索类”并抽取关键词“API 限流、建议”。编排器根据意图把任务分给 RetrieverAgent。RetrieverAgent 调用检索工具在向量库中拿到 3 个相关片段每个片段带上出处标题和原文。WriterAgent 拿到用户问题 片段被提示词要求“只能基于片段作答并标注引用”。它生成了三段带引用的回答还把原文里两个矛盾的说法指了出来。GuardAgent 做最后审核逐条比对回答和片段发现第二段有一句话在片段里找不到依据于是打回给 WriterAgent重写后才返回。整个编排里最容易被忽略的是“工具注册”。Agent 说“我要调检索工具”你不能让它在自由文本里随便描述而要给它一套结构化的工具 Schema规定有哪几个参数、什么类型、成功和失败的输出格式。这就是热词里那个报错provider rejected the request schema or tool payload出现的地方——往往是你传的工具参数结构和模型厂商要求的 JSON Schema 不一致被网关直接拒绝。4.3 Flutter 端的状态管理与智能体之间的通信多智能体编排在服务端跑Flutter 端要做的就是状态管理。我这次用的是 Cubit轻量、好理解适合管理“加载中 / 返回结果 / 返回错误”这类状态。它只暴露emit和stream页面通过BlocBuilder监听状态刷新 UI代码量比完整 Bloc 少很多。有个体验问题特别值得说Navigator 切换页面后状态会不会丢。很多人发现跳转到详情页再返回问答历史没了是因为 Cubit 被页面生命周期里的dispose掉了。解决办法是把 Cubit 放到比页面更上层的作用域比如放在 MaterialApp 之上或者一个全局单例里让状态拥有者比页面活得更久。这一点做 LLM 对话应用时特别重要用户切出去回个消息回来整个对话没了是很劝退的。组件通信方面Flutter 的灵活度足够高父子页面用回调跨层用 Provider/InheritedWidget全局事件用 EventBus。多智能体执行过程中服务端会一路推送“当前正在让哪个 Agent 干活”的事件Flutter 端用 EventChannel 接收后在界面上做一个执行进度可视化用户能看到 AI 不是一次性憋答案而是一步步加工体验好很多。另外一个小细节Future.then()的回调是放进微任务队列的不是立刻执行。LLM 网络请求返回后后续的链式操作会排在微任务里如果页面同时在跑动画要注意时序问题别在 then 里直接改一个正在动画中的控制器状态。4.4 落地细节提示词模板与生成参数多智能体跑起来之后你会发现整个系统的“灵魂”不在模型而在提示词模板和参数配置。每个 Agent 的提示词模板都按同一套骨架维护角色设定、任务目标、输入格式、输出格式、限制条件。比如 RetrieverAgent 的限制条件就写了“只输出 JSON包含 fragments 和 scores 两个字段”方便编排器直接解析WriterAgent 的限制条件是“回答必须带[1]这类引用角标来源只能在给定片段里选”。生成参数上IntentAgent 我把temperature调到了 0.2因为分类任务要稳定WriterAgent 调到 0.7因为要一点创作空间。这些参数值得你多试几轮不同任务用同一套参数是偷懒不是风格。5. 实战演示做一个知识库问答小助手理论讲完上可落地的东西。这个项目就叫my_ai_app功能是用户输入问题服务端多智能体协作最终返回带引用的回答Flutter 端把 Agent 的执行过程动态展示在界面上。5.1 项目文件结构my_ai_app/ lib/ main.dart pages/home_page.dart widgets/answer_card.dart widgets/agent_progress_view.dart services/llm_gateway.dart models/chat_message.dartllm_gateway.dart是对后端 LLM 网关的封装页面层完全不知道背后有几个 Agent、用了什么模型它只负责提交对话、接收事件、展示结果。5.2 后端网关接口设计先约定网关 HTTP 接口就两个端点端点方法用途/v1/chatPOST提交完整会话消息返回最终回答/v1/chat/streamPOST SSE流式返回 Agent 执行事件和最终回答请求体长这样{ session_id: uuid, messages: [ {role: user, content: 团队对 API 限流的建议是什么} ] }流式响应里给三类事件agent_started表示某 Agent 开始执行、tool_used表示 Agent 调用了哪个工具、answer_chunk最终回答的增量文本。Flutter 端通过http包的 StreamedResponse 或者EventChannel接收 SSE 数据按事件类型更新界面。5.3 Flutter 端核心代码Cubit 与页面Cubit 就三个状态enum ChatStatus { idle, loading, streaming, done, error } class ChatState { final ChatStatus status; final ListChatMessage messages; final ListString agentEvents; final String? error; }页面提交问题后状态切到streaming然后AgentProgressView逐条显示 Agent 事件AnswerCard一句句地刷新回答文本。关键点在于Cubit 里必须保存整个messages列表因为后续的提问需要把完整历史交给后端否则模型会丢失上下文。5.4 多智能体编排的简化代码后端编排用伪代码描述核心循环FutureString runAgents(String userInput) async { final intent await intentAgent.classify(userInput); var contextFragments []; if (intent.needKnowledge) { contextFragments await retrieverAgent.search(intent.keywords); } var answer await writerAgent.generate( question: userInput, fragments: contextFragments, ); final guardResult await guardAgent.review(answer, contextFragments); if (!guardResult.passed) { answer await writerAgent.rewrite(guardResult.comments); } return answer; }这个循环很短但它代表了多智能体的核心范式拆分、调用、审查、回退。你可以在每个await前发一个事件Flutter 端就能实时看到进度。5.5 流式输出与体验优化最后一步是让回答像 ChatGPT 一样逐字出现。服务端把最终回答按 token 切段推给 FlutterFlutter 用一个StreamBuilder或手动setState拼接文本。注意别在build方法里做字符串拼接会造成大量无效重建合理的做法是只在收到新的answer_chunk时分包追加文本再标记一次刷新。6. 常见问题排查实录练手项目最大的收获是踩坑。整理一下这个组合里最容易翻车的几个问题都是实操现场记录。6.1 Flutter 构建与打包类问题gradle 兼容性警告。前面提到的current configured Flutter SDK is not known to be fully supported本质是 AGP 版本和 Flutter 内置兼容表不匹配。处理办法查 Flutter 官方渠道发布的对应 AGP 版本号改项目里的settings.gradle或build.gradle然后flutter clean再构建。Gradle 插件旧式应用警告。You are applying Flutters main Gradle plugin imperatively using the apply不要焦虑项目能跑。但你如果引用了较新的第三方插件它会要求你改成plugins {}方式。在全新项目里直接复制当前模板的配置比你在老项目里手动迁移省力得多。打包报错。热词里有一条Could not close ... AssertionError。这个多出现在 Windows/Linux 桌面端打包时原因是资源文件被占用或路径太长也可能是杀毒软件拦截了临时文件。做法关闭相关程序缩短项目路径清理build目录后重试。Xcode 27 下包版本低。新 Xcode 对 iOS 构建工具链更新后很多老版本 Flutter 包会出现编译报错或 version 检测过低。最简单的方法是升级 Flutter SDK 到支持新 Xcode 的稳定版不要跟工具链硬刚。6.2 LLM 请求与解析类问题请求被拒。llm request failed: provider rejected the request schema or tool payload是典型的工具调用 Schema 不匹配。先看服务端网关记录的错误响应体里面会指出哪个字段不兼容常见是type写错、enum值没对齐、参数缺必填项。按模型厂商的文档逐字段核对 JSON Schema 就能定位。超时与重试。多智能体编排时一个用户请求内部要多次调用模型网络超时概率会被放大。一定要做超时分级和重试策略。我的做法是单次模型调用 60 秒超时失败重试 1 次整个编排 120 秒超时到点直接返回“正在处理请稍后查看”给用户避免白屏。JSON 解析失败。让模型输出严格 JSON 十次有八次会出现尾逗号、多余换行、Markdown 代码块包裹。不要信任模型的“我一定会按格式输出”代码里做冗余清理剥掉 json 标记、截取第一个{到最后一个}、再交给解码器。6.3 性能与渲染类问题Flutter Web 引擎启动慢。这属于 Web 平台的老毛病CanvasKit 资源加载耗时大。可以考虑用--web-renderer html做兼容方案如果你的功能不需要复杂绘制或者在首屏加骨架页。新版本 Flutter 已经逐渐把 CanvasKit 变为默认启动速度也在改善。Impeller 渲染问题。Flutter 新版默认启用 ImpelleriOS 上表现稳定部分 Android 老机型偶发兼容问题。如果遇到个别设备文字模糊或绘制异常可以在AndroidManifest.xml里临时关掉 Impeller 验证确认后再决定是否升级引擎版本。端侧模型推理慢。如果做了 ONNX 端侧部署首包加载和推理都会吃内存。建议只在闲置时预加载模型避免在用户输入时才初始化否则首问体验会非常糟糕。最后分享一个小习惯这个项目让我最大的改变是每接一个模型、每加一个 Agent我都会先把“输入输出格式”写在一个文档里再写任何代码。多智能体系统最大的复杂度不是某个模型能力不够而是十几个模块之间的“接口契约”没人管。Token、Schema、状态事件这些概念如果不是一开始就当成接口设计来做后面改起来真的要命。如果你正准备起步我建议按这条路径走先 Flutter 直连一个模型跑通对话再加知识库 RAG再加一个网关层最后才上多智能体。每一步都确认稳定再往前走而不是一上来就搭建一个四 Agent 系统——否则你都不知道出了问题该找谁。