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


本页中的示例假定您已完成 入门：通过 Apple 的基础模型框架访问 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 较少；最大限度地减少延迟和费用

简单任务和高吞吐量任务

模型采用平衡的方法

中等复杂度的任务

模型使用的 token 达到其最大级别

需要深入推理的复杂提示

gemini-3.1-pro-preview （默认）
gemini-3.5-flash （默认）
gemini-3.1-flash-lite （默认）
gemini-3-pro-image-preview（“Nano Banana Pro”） （默认）
gemini-3.1-flash-image-preview（“Nano Banana 2”） （默认）


配置图片输出


常规配置


提供反馈 ，说明如何通过 Apple 的基础模型框架访问 Gemini API