默认情况下,Gemini API 会以非结构化文本的形式返回响应。不过,某些用例需要结构化文本,例如 JSON。例如,您可能需要将响应用于需要已建立的数据架构的其他下游任务。
为确保模型生成的输出始终遵循特定架构,您可以定义响应架构,该架构类似于模型响应的蓝图。然后,您可以直接从模型的输出中提取数据,而无需进行太多的后期处理。
下面是一些示例:
确保模型的响应生成有效的 JSON 并符合您提供的架构。
例如,该模型可以为食谱生成结构化条目,其中始终包含食谱名称、成分列表和步骤。这样,您就可以更轻松地解析这些信息,并在应用界面中显示这些信息。限制模型在分类任务期间的响应方式。
例如,您可以让模型使用一组特定的标签(例如一组特定的枚举,如positive
和negative
)为文本添加注解,而不是使用模型生成的标签(这些标签可能会有一定程度的可变性,如good
、positive
、negative
或bad
)。
本指南介绍了如何在调用 generateContent
时提供 responseSchema
以生成 JSON 输出。它专注于纯文本输入,但 Gemini 还可以针对包含图片、视频和音频作为输入的多模态请求生成结构化回答。
本页面底部提供了更多示例,例如如何生成枚举值作为输出。如需查看有关如何生成结构化输出的更多示例,请参阅 Google Cloud 文档中的示例架构和模型响应列表。
使用 Gemini API 的其他方式
可选择试用 Gemini API 的替代“Google AI”版本
使用 Google AI Studio 和 Google AI 客户端 SDK 免费访问(在可用的情况下,且受限)。 这些 SDK 应仅用于移动应用和 Web 应用中的原型设计。熟悉 Gemini API 的运作方式后,请迁移到我们的 Vertex AI in Firebase SDK(本文档)。这些 SDK 提供了许多对移动应用和 Web 应用至关重要的其他功能,例如使用 Firebase App Check 保护 API 免遭滥用,以及支持请求中的大型媒体文件。
可选地在服务器端调用 Vertex AI Gemini API(例如使用 Python、Node.js 或 Go)
对于 Gemini API,请使用服务器端 Vertex AI SDK、Firebase Genkit 或 Firebase Extensions。
准备工作
请完成 Vertex AI in Firebase SDK 入门指南(如果尚未完成)。请确保您已执行以下所有操作:
设置新的或现有的 Firebase 项目,包括使用 Blaze 定价方案和启用所需的 API。
将您的应用与 Firebase 相关联,包括注册您的应用并将 Firebase 配置添加到您的应用。
在应用中添加 SDK 并初始化 Vertex AI 服务和生成式模型。
将应用连接到 Firebase、添加 SDK 并初始化 Vertex AI 服务和生成式模型后,您就可以调用 Gemini API 了。
第 1 步:定义响应架构
通过定义响应架构指定模型输出的结构、字段名称以及每个字段的预期数据类型。
模型生成响应时,会使用提示中的字段名称和上下文。为了让您的意图清晰明了,我们建议您使用清晰的结构、明确的字段名称,甚至根据需要添加说明。
响应架构注意事项
编写回答架构时,请注意以下事项:
响应架构的大小会占用输入词元限额。
响应架构功能支持以下响应 MIME 类型:
application/json
:输出响应架构中定义的 JSON(适用于结构化输出要求)text/x.enum
:输出响应架构中定义的枚举值(对分类任务很有用)
响应架构功能支持以下架构字段:
enum
items
maxItems
nullable
properties
required
如果您使用不受支持的字段,模型仍可以处理您的请求,但会忽略该字段。请注意,上述列表是 OpenAPI 3.0 架构对象的子集(请参阅 Vertex AI 架构参考文档)。
默认情况下,对于 Vertex AI in Firebase SDK,除非您在
optionalProperties
数组中将其指定为可选,否则所有字段都被视为必填字段。对于这些可选字段,模型可以填充这些字段或跳过这些字段。请注意,这与 Vertex AI Gemini API 的默认行为相反。
第 2 步:发送包含响应架构的问题以生成 JSON
以下示例展示了如何生成结构化 JSON 输出。
如需生成结构化输出,您需要在模型初始化期间指定适当的 responseMimeType
(在此示例中为 application/json
)以及您希望模型使用的 responseSchema
。
所有 Gemini 模型(Gemini 1.0 模型除外)都支持使用 responseSchema
。
import FirebaseVertexAI
// Provide a JSON schema object using a standard format.
// Later, pass this schema object into `responseSchema` in the generation config.
let jsonSchema = Schema.object(
properties: [
"characters": Schema.array(
items: .object(
properties: [
"name": .string(),
"age": .integer(),
"species": .string(),
"accessory": .enumeration(values: ["hat", "belt", "shoes"]),
],
optionalProperties: ["accessory"]
)
),
]
)
// Initialize the Vertex AI service and the generative model.
let model = VertexAI.vertexAI().generativeModel(
modelName: "gemini-2.0-flash",
// In the generation config, set the `responseMimeType` to `application/json`
// and pass the JSON schema object into `responseSchema`.
generationConfig: GenerationConfig(
responseMIMEType: "application/json",
responseSchema: jsonSchema
)
)
let prompt = "For use in a children's card game, generate 10 animal-based characters."
let response = try await model.generateContent(prompt)
print(response.text ?? "No text in response.")
了解如何选择适合您的用例和应用的 Gemini 模型和(可选)位置。
更多示例
如需查看有关如何使用和生成结构化输出的更多示例,请参阅 Google Cloud 文档中的示例架构和模型响应列表。
生成枚举值作为输出
以下示例展示了如何针对分类任务使用响应架构。要求模型根据电影的说明来识别电影的类型。输出是模型从所提供的响应架构中定义的列表值中选择的一个纯文本枚举值。
如需执行此结构化分类任务,您需要在模型初始化期间指定适当的 responseMimeType
(在此示例中为 text/x.enum
)以及您希望模型使用的 responseSchema
。
import FirebaseVertexAI
// Provide an enum schema object using a standard format.
// Later, pass this schema object into `responseSchema` in the generation config.
let enumSchema = Schema.enumeration(values: ["drama", "comedy", "documentary"])
// Initialize the Vertex AI service and the generative model.
let model = VertexAI.vertexAI().generativeModel(
modelName: "gemini-2.0-flash",
// In the generation config, set the `responseMimeType` to `text/x.enum`
// and pass the enum schema object into `responseSchema`.
generationConfig: GenerationConfig(
responseMIMEType: "text/x.enum",
responseSchema: enumSchema
)
)
let prompt = """
The film aims to educate and inform viewers about real-life subjects, events, or people.
It offers a factual record of a particular topic by combining interviews, historical footage,
and narration. The primary purpose of a film is to present information and provide insights
into various aspects of reality.
"""
let response = try await model.generateContent(prompt)
print(response.text ?? "No text in response.")
了解如何选择适合您的用例和应用的 Gemini 模型和(可选)位置。
用于控制内容生成的其他选项
- 详细了解问题设计,以便影响模型生成符合您需求的输出。
- 配置模型参数,以控制模型如何生成回答。这些参数包括输出 token 数上限、温度、topK 和 topP。
- 使用安全设置调整系统提供可能被视为有害的回答(包括仇恨言论和露骨色情内容)的可能性。
- 设置系统指令来引导模型的行为。此功能类似于您在模型接触到来自最终用户的任何进一步指令之前添加的“序言”。
提供有关 Vertex AI in Firebase 使用体验的反馈