Flutter AI 工具包

你好，欢迎使用 Flutter AI 工具包！

AI 工具包是一组 AI 聊天相关 widget，便于在 Flutter 应用中添加 AI 聊天窗口。工具包围绕抽象的 LLM 提供商 API 组织，便于更换聊天所用的 LLM 提供商。开箱即支持 Firebase AI Logic。

• 多轮聊天：在多次交互间保持上下文。

• 流式传输：在生成过程中实时显示 AI 回复。

• 富文本显示：支持聊天消息中的格式化文本。

• 语音输入：让用户通过语音输入提示词。

• 多媒体附件：支持发送与接收多种媒体类型。

• 函数调用：支持向 LLM 提供商发起工具调用。

• 自定义样式：提供丰富自定义以匹配应用设计。

• 聊天序列化/反序列化：在应用会话间存储与恢复对话。

• 自定义响应 widget：引入专用 UI 组件展示 LLM 回复。

• 可插拔 LLM 支持：实现简单接口以接入自有 LLM。

• 跨平台支持：兼容 Android、iOS、web 与 macOS。

托管 AI 工具包的演示示例如下：

该 演示源代码 可在 GitHub 仓库中获取。

1. 安装

   在 pubspec.yaml 中添加以下依赖：

   yaml

   dependencies:
     flutter_ai_toolkit: ^latest_version
     firebase_ai: ^latest_version
     firebase_core: ^latest_version
   

   content_copy
2. 配置

   AI 工具包同时支持 Gemini 端点（用于原型）与 Vertex 端点（用于生产）。两者均需 Firebase 项目并初始化 firebase_core package，详见 使用 Firebase AI Logic SDK 开始使用 Gemini API 文档。

   完成后，使用 flutterfire CLI 将新 Firebase 项目集成到 Flutter 应用，详见 将 Firebase 添加到你的 Flutter 应用 文档。

   按上述说明操作后，即可在 Flutter 应用中通过 Firebase 集成 AI。首先初始化 Firebase：

   dart

   import 'package:firebase_core/firebase_core.dart';
   import 'package:firebase_ai/firebase_ai.dart';
   import 'package:flutter_ai_toolkit/flutter_ai_toolkit.dart';
   ​
   // ... other imports
   ​
   import 'firebase_options.dart'; // from `flutterfire config`
   ​
   void main() async {
     WidgetsFlutterBinding.ensureInitialized();
     await Firebase.initializeApp(options: DefaultFirebaseOptions.currentPlatform);
     runApp(const App());
   }
   ​
   // ...app stuff here
   

   content_copy

   在 Flutter 应用中正确初始化 Firebase 后，即可创建 Firebase provider 实例。有两种方式。原型开发可考虑 Gemini AI 端点：

   dart

   import 'package:firebase_ai/firebase_ai.dart';
   import 'package:flutter_ai_toolkit/flutter_ai_toolkit.dart';
   ​
   // ... app stuff here
   ​
   class ChatPage extends StatelessWidget {
     const ChatPage({super.key});
   ​
     @override
     Widget build(BuildContext context) => Scaffold(
           appBar: AppBar(title: const Text(App.title)),
           // create the chat view, passing in the Firebase provider
           body: LlmChatView(
             provider: FirebaseProvider(
               // Use the Google AI endpoint
               model: FirebaseAI.googleAI().generativeModel(
                 model: 'gemini-2.5-flash',
               ),
             ),
           ),
         );
   }
   

   content_copy

   FirebaseProvider 类向 LlmChatView 暴露 Firebase AI Logic SDK。注意你需提供模型名称（有多种选项 可选），但无需提供 API 密钥，均由 Firebase 项目处理。

   生产工作负载可轻松切换为 Firebase Logic AI 端点：

   dart

   class ChatPage extends StatelessWidget {
     const ChatPage({super.key});
   ​
     @override
     Widget build(BuildContext context) => Scaffold(
           appBar: AppBar(title: const Text(App.title)),
           body: LlmChatView(
             provider: FirebaseProvider(
               // Use the Vertex AI endpoint
               model: FirebaseAI.vertexAI().generativeModel(
                 model: 'gemini-2.5-flash',
               ),
             ),
           ),
         );
   }
   

   content_copy

   完整示例请参阅 gemini.dart 与 vertex.dart 示例。

3. 配置设备权限

   要启用语音输入与媒体附件等功能，请确保应用具备必要权限：

   • 网络访问： 在 macOS 上，向 *.entitlements 文件添加：

     xml

     <plist version="1.0">
       <dict>
         ...
         <key>com.apple.security.network.client</key>
         <true/>
       </dict>
     </plist>
     

     content_copy

     在 Android 上，确保 AndroidManifest.xml 包含：

     xml

     <manifest xmlns:android="http://schemas.android.com/apk/res/android">
         ...
         <uses-permission android:name="android.permission.INTERNET"/>
     </manifest>
     

     content_copy

   • 麦克风访问：按 record package 权限设置说明 配置。

   • 文件选择：遵循 file_selector 插件说明。

   • 图片选择：拍照或从设备选图请参阅 image_picker 插件安装说明。

   • Web 拍照：在 Web 上拍照请按 camera 插件设置说明 配置应用。

firebase_options.dart

firebase_options.dart

要使用 Vertex AI 示例应用，将 Firebase 配置写入 example/lib/firebase_options.dart。可在 example 目录内 使用 flutterfire CLI，按 将 Firebase 添加到你的 Flutter 应用 文档操作。

使用本 package 时，请 记录 issue 与功能请求 并 提交你希望贡献的代码。我们希望你的反馈与贡献使 AI 工具包尽可能稳健实用，服务于你的真实应用。