通过 Apple 的 Foundation Models 框架访问 Gemini API 时的配置选项


本页中的示例假设您已完成使用入门：通过 Apple 的 Foundation Models 框架访问 Gemini API。


在向模型发送的每个请求中，您都可以同时发送一些配置设置，以控制模型如何生成回答。每种 Gemini 型号都提供不同的配置选项。

根据设置，配置在 geminiLanguageModel 或 LanguageModelSession 的生命周期内保持不变。如果您想使用其他配置，请使用该配置创建新模型或会话。

该页面介绍了以下配置选项：

指定系统指令

系统指令就像一段“序言”，在模型接收到最终用户的进一步指令之前添加。它可让您根据自己的特定需求和使用情形来控制模型的行为。

在 LanguageModelSession 中指定系统指令：

// ...

// Make sure you initialize your chosen Gemini API backend service
let model = FirebaseAI.firebaseAI().geminiLanguageModel(name: "GEMINI_MODEL_NAME")

// Specify the system instructions as part of creating the session
let session = LanguageModelSession(
    model: model,
    instructions: "You are a cat. Your name is Neko."
)

// ...


配置思考（也称为“推理”）

您可以配置 Gemini 模型在生成回答时可进行的思考（也称为推理）量。如需详细了解思考功能、最佳实践和使用场景，请参阅思考一般指南。

Apple 使用的是推理水平，而不是思考水平。您可以通过 LanguageModelSession 在每个请求中设置 ContextOptions 中的 reasoningLevel：

// ...

// Make sure you initialize your chosen Gemini API backend service
let model = FirebaseAI.firebaseAI().geminiLanguageModel(name: "GEMINI_MODEL_NAME")

let session = LanguageModelSession(model: model)

// Specify the reasoning level when generating a response
// Possible reasoningLevels: .light, .moderate, .deep, .custom("minimal")
let response = try await session.respond(
  to: "Write a story about a magic backpack.",
  contextOptions: ContextOptions(reasoningLevel: .REASONING_LEVEL)
)

// ...

支持的思考等级值

请注意以下几点：

  • Gemini 3.x 模型始终使用思维；您无法为这些模型停用或关闭思维。
  • Gemini 3.x 模型始终使用动态思考 - 模型会根据配置的金额来决定何时思考以及思考多少。

下表列出了您可以为每种 Gemini 模型设置的思维水平 (reasoningLevel)。请注意，如果您使用 Gemini 值（MINIMAL、LOW、MEDIUM、HIGH），系统会自动将其映射到 Apple 版本。

Apple：.custom("minimal")
Gemini：MINIMAL 		Apple：.light
Gemini：LOW 		Apple：.moderate
Gemini：MEDIUM 		Apple：.deep
Gemini：HIGH

模型使用的 token 数量尽可能少；几乎不进行思考

低复杂度任务

模型使用的令牌数量更少；可最大限度地缩短延迟时间并降低费用

简单任务和高吞吐量任务

模型采用均衡的方法

中等复杂程度的任务

模型使用的 token 数量达到上限

需要深度推理的复杂提示

Gemini 3.x Pro
gemini-3.1-pro-preview 		（默认）
Gemini 3.x Flash
gemini-3.5-flash 		（默认）
Gemini 3.x Flash‑Lite
gemini-3.1-flash-lite 		（默认）
Gemini 3.x Pro Image
gemini-3-pro-image
（“Nano Banana Pro”） 		（默认）
Gemini 3.x Flash Image
gemini-3.1-flash-image
("Nano Banana 2") 		（默认）


配置图片输出


常规配置


提供反馈 关于通过 Apple 的基础模型框架访问 Gemini API