企业官网建设流程全解析

深入解读 firebase-ios-sdk 中的 FirebaseAI（Firebase AI Logic）模块：构建、测试与 Mock 数据维护实战

【免费下载链接】firebase-ios-sdkFirebase SDK for Apple App Development项目地址: https://gitcode.com/GitHub_Trending/fi/firebase-ios-sdk

导读

本文以 firebase-ios-sdk 仓库中 FirebaseAI/README.md 为骨架，结合仓库内的源码、测试与脚本，系统讲解 Firebase AI SDK（现已更名为 Firebase AILogic）的开发构建流程、单元测试前置条件、Mock 响应数据的下载与更新机制。读完本文，你将掌握：如何通过 Swift Package Manager 选择FirebaseAIscheme 完成 SDK 构建、如何正确准备并运行FirebaseAIUnit单元测试、如何借助scripts/update_vertexai_responses.sh拉取/更新测试所需的 Mock 数据，以及该模块的整体架构与版本演进脉络。

FirebaseAI 模块是什么

FirebaseAI 是 firebase-ios-sdk 中负责将 Gemini 模型能力带入 Apple 平台的客户端 SDK。它的核心定位可以从两个层面理解：

• 能力层面：SDK 提供了文本/多模态内容生成、流式生成、多轮对话、函数调用（Function Calling）、Grounding（Google Search / Google Maps）、代码执行、URL 上下文工具、实时双向通信（Live API）、结构化输出（配合 Foundation Models 的@Generable/@Guide宏）以及图像生成等一系列能力；
• 命名层面：根据 FirebaseAI/CHANGELOG.md，自 12.5.0 起，FirebaseAI模块被重命名为FirebaseAILogic（非破坏性变更，旧引用暂时仍可用），并在 12.13.0 引入的 Firebase 13.0.0 大版本计划中逐步移除旧名。因此新代码应使用import FirebaseAILogic并选择FirebaseAILogicSwift Package 依赖。

在 Package.swift 中可以看到产品层同时暴露FirebaseAI与FirebaseAILogic两个可选项，其中 Package.swift 将真正的实现代码指向FirebaseAI/Sources（即FirebaseAILogictarget），而FirebaseAI则由FirebaseAI/Wrapper/Sources的轻量包装层提供，其 Unit 测试 target 位于FirebaseAI/Wrapper/Tests。

开发环境与构建：选择 FirebaseAI scheme

README 的 Development 一节给出了最核心的开发流程：完成 Swift Package Manager 的 setup instructions 后，在 Xcode 中选择FirebaseAIscheme 即可构建 SDK。

从仓库证据看，这一流程有两个值得注意的实现细节：

1. 构建入口是FirebaseAI而不是FirebaseAILogic：README 明确要求使用FirebaseAIscheme 构建。仓库中同时存在两个 Scheme 文件——scripts/spm_test_schemes/FirebaseAIUnit.xcscheme 与 scripts/spm_test_schemes/FirebaseAILogicUnit.xcscheme，分别对应包装层与实现层的测试。

2. 底层实现入口在FirebaseAI/Sources/FirebaseAI.swift：模块的对外入口是一个public final class FirebaseAI（FirebaseAI/Sources/FirebaseAI.swift），它通过工厂方法创建各类模型实例：

   • firebaseAI(app:backend:useLimitedUseAppCheckTokens:)：创建FirebaseAI实例，默认使用Backend.googleAI()（Gemini Developer API），并支持开启 App Check 的 limited-use tokens；
   • generativeModel(modelName:generationConfig:safetySettings:tools:toolConfig:systemInstruction:requestOptions:)：创建常规生成模型，且会对非gemini-/gemma-前缀的模型名发出警告日志；
   • liveModel(...)：创建支持双向流式通信的LiveGenerativeModel（watchOS 不可用）；
   • templateGenerativeModel()：创建基于服务端 Prompt 模板的模型；
   • generativeModelSession(...)/geminiModel(...)：Public Preview 能力，分别提供结构化输出会话与 Foundation Models 集成。

   从源码结构看，FirebaseAI实例还会按(appName, apiConfig, useLimitedUseAppCheckTokens)作为 key 进行实例缓存（FirebaseAI/Sources/FirebaseAI.swift），并通过os_unfair_lock保证线程安全。

模型资源名与 Backend 配置

构建完成后，模型请求的组装逻辑也值得关注。在 FirebaseAI/Sources/FirebaseAI.swift 中，modelResourceName(modelName:)会根据apiConfig.service分支构造资源名：

• Agent Platform Gemini API（原 Vertex AI）：形如projects/{projectID}/locations/{location}/publishers/google/models/{modelName}，其中 location 默认是global（见 FirebaseAI/Sources/Types/Public/Backend.swift）；
• Gemini Developer API：形如projects/{projectID}/models/{modelName}（生产环境经 Firebase 代理）。

Backend的配置演变（FirebaseAI/Sources/Types/Public/Backend.swift）是理解版本变化的关键：旧的vertexAI()/vertexAI(location:)已废弃，建议改用agentPlatform(location:)（默认global，如需维持us-central1需显式传参）；googleAI()对应 Gemini Developer API。

单元测试：FirebaseAIUnit 与 Mock 响应文件

README 的 Unit Tests 一节（含> [!IMPORTANT]警示）明确：FirebaseAI 的单元测试依赖 Mock 响应文件，必须先运行根目录下的scripts/update_vertexai_responses.sh下载这些文件，随后选择FirebaseAIUnitscheme 构建并运行测试。

从仓库结构可以印证这一依赖关系：

• 测试代码位于 FirebaseAI/Tests/Unit，包含GenerativeModelGoogleAITests.swift、GenerativeModelVertexAITests.swift、GenerativeModelVertexAICachingTests.swift、LiveGenerationConfigTests.swift、ChatTests.swift、SafetyTests.swift、MapsGroundingTests.swift、HybridModelTests.swift等针对不同能力面的测试；
• Mock 数据位于FirebaseAI/Tests/Unit/vertexai-sdk-test-data/mock-responses/目录，按后端分为developerapi（Gemini Developer API）与vertexai（Agent Platform Gemini API）两个子目录；
• 测试通过MockURLProtocol.swift拦截URLSession请求并用 Mock 文件回放响应，从而不依赖真实网络即可验证请求/响应编解码逻辑。

运行单元测试的命令与 Scheme

在 Xcode 中操作时，按 README 指引依次：

1. 确保已按 SPM setup 说明将仓库作为本地包打开；
2. 选择FirebaseAIUnitscheme（对应文件 scripts/spm_test_schemes/FirebaseAIUnit.xcscheme）；
3. 先运行下载脚本准备 Mock 数据；
4. 构建并运行测试。

如果希望绕过 Xcode 直接在命令行跑测试，也可以使用 SwiftPM 测试 target：FirebaseAILogicUnit（对应 Package.swift 与 scripts/spm_test_schemes/FirebaseAILogicUnit.xcscheme）。需要注意测试数据的准备是共同前提，缺少 Mock 文件会导致用例因拿不到预期响应而失败。

更新 Mock 响应：脚本机制与工作流

README 的 Updating Mock Responses 一节描述了 Mock 数据更新的完整闭环：

1. 在vertexai-sdk-test-data仓库（Firebase 官方维护的共享 Mock 测试数据仓库）中创建 PR 提交新的响应文件；
2. PR 合并后，重新运行scripts/update_vertexai_responses.sh脚本下载更新后的文件。

脚本本身的实现（scripts/update_vertexai_responses.sh）非常简洁，其注释点明了设计意图："replaces mock response files ... with a fresh clone of the shared repository of mock test data"：

cd "$(dirname "$0")/../FirebaseAI/Tests/Unit" || exit rm -rf vertexai-sdk-test-data || exit git clone --depth 1 https://github.com/FirebaseExtended/vertexai-sdk-test-data.git

也就是说，该脚本会把FirebaseAI/Tests/Unit/vertexai-sdk-test-data目录整体替换为外部测试数据仓库的最新克隆（--depth 1浅克隆，仅取最新一次提交）。这解释了为什么 README 要求"从仓库根目录运行"：脚本内部通过$(dirname "$0")/../FirebaseAI/Tests/Unit定位目标目录，因此无论从仓库根目录还是 scripts 目录下执行，目标路径都指向同一位置。

执行方式（在仓库根目录）：

./scripts/update_vertexai_responses.sh

适用前提与注意事项：

• 该脚本会删除并重建FirebaseAI/Tests/Unit/vertexai-sdk-test-data目录，因此不要在该目录中手工放置未纳入外部仓库的自定义文件，否则会被覆盖；
• 需要网络访问 GitHub（git clone 外部测试数据仓库）；
• Mock 数据是按后端分层的（developerapi与vertexai），新增用例时应把响应样本放进与后端对应的子目录，并确保外部数据仓库中的文件名与测试代码引用的资源名一致。

源码地图：从文件到能力的映射

想要深入参与 SDK 开发，FirebaseAI/AGENTS.md 提供了一份完整的代码地图，它把Sources/下的每个文件与职责一一对应，可与 README 的开发说明配合使用。几个关键文件的作用如下：

需要特别提醒的是：由于FirebaseAI已更名为FirebaseAILogic，AGENTS.md中标注的Sources/目录在仓库中实际位于 FirebaseAI/Sources，其中Protocols/、Types/、Extensions/子目录分别存放公共协议、数据类型与内部扩展，具体结构可以查阅 FirebaseAI/AGENTS.md 的完整清单。

版本演进：从 Vertex AI 到 Firebase AI Logic

README 虽未展开介绍功能清单，但 FirebaseAI/CHANGELOG.md 完整记录了该模块的演进历史，可作为开发决策与兼容性排查的参考：

• 11.13.0：FirebaseAI首次发布，取代旧版 Vertex AI in Firebase SDK（FirebaseVertexAI），提供 Gemini Developer API（含免费额度）的 preview 支持，同时保持 Vertex AI Gemini API 的 GA 状态；
• 12.4.0：Live API（实时双向流）加入，Gemini Developer API 与 Imagen 生成 API 转正 GA；
• 12.5.0：模块改名FirebaseAILogic，新增 Live API 视频帧发送能力；
• 12.6.0 / 12.9.0：Server Prompt Templates 与 URL 上下文工具（后转 GA），隐式缓存（context caching）元数据支持；
• 12.11.0 ~ 12.13.0：GenerativeModelSession（结构化输出）、自动函数调用、混合推理（端侧 Foundation Models 与云端 Gemini 回退）、Live API 会话恢复与上下文窗口压缩、ImageConfig图像生成配置；
• 12.15.0 ~ 12.17.0：App Check 成为依赖简化配置、SpeechConfig语音配置、Backend.vertexAI废弃并改名Backend.agentPlatform、默认位置从us-central1改为global；
• 12.18.0 ~ 12.19.0：移除已关闭的 Imagen 方法、Live API 增加RealtimeInputConfig与 start/stop activity 支持、Public Preview 引入GeminiLanguageModel（与 Apple Foundation Models 框架集成），并预告FirebaseAI库将在 Firebase 13.0.0 中移除，GenerationConfig/LiveGenerationConfig中的模型调参参数（temperature、topP、topK、candidateCount、presencePenalty、frequencyPenalty）在 Gemini 3.x 及以后不再受支持。

这些信息对迁移升级（尤其涉及import改名、默认后端位置变化、废弃 API 替换）至关重要，建议作为 README 开发指引的配套参考文档阅读。

小结

围绕 FirebaseAI/README.md，本文完整还原了 FirebaseAI（FirebaseAILogic）模块的本地开发链路：SPM 集成 → 选择FirebaseAIscheme 构建 → 运行scripts/update_vertexai_responses.sh准备 Mock 数据 → 通过FirebaseAIUnitscheme 执行单元测试 → 通过外部测试数据仓库 PR 与脚本重跑完成 Mock 数据更新。同时结合 FirebaseAI/Sources/FirebaseAI.swift、Backend.swift 等源码与 FirebaseAI/CHANGELOG.md 的版本记录，说明了模块入口、模型资源名组装与命名/后端演进等关键实现细节。无论你是准备为该 SDK 贡献代码的开发者，还是需要维护依赖此模块的测试基建的工程师，以上流程与源码证据都能作为可直接落地的操作手册。

【免费下载链接】firebase-ios-sdkFirebase SDK for Apple App Development项目地址: https://gitcode.com/GitHub_Trending/fi/firebase-ios-sdk