 约束 Gemini 结构化输出)
开发工具后端【免费下载链接】firebase-js-sdkFirebase Javascript SDK项目地址https://gitcode.com/gh_mirrors/fi/firebase-js-sdk点击查看免费下载BooleanSchema是 Firebase AI Web SDKfirebase/ai中用于描述布尔类型字段的 Schema 类它在使用 Gemini 模型做结构化输出、函数调用参数声明等场景中负责约束模型只能生成true/false这样的布尔值。本文以官方 API 参考文档 docs-devsite/ai.booleanschema.md 为主体结合仓库内 schema-builder.ts 源码与测试用例带你掌握BooleanSchema的类结构、构造参数、序列化原理以及它在responseSchema与函数声明中的实战用法。一、BooleanSchema 在 SDK 中的定位在 Firebase AI SDK 的 Schema 体系中BooleanSchema是面向boolean类型的专用 Schema 类。它的官方定义只有一句话Schema class for boolean types.它属于 SDK 提供的七种具体 Schema 类型之一TypedSchema联合类型IntegerSchema、NumberSchema、StringSchema、BooleanSchema、ObjectSchema、ArraySchema、AnyOfSchema完整定义见 schema-builder.tsexport type TypedSchema | IntegerSchema | NumberSchema | StringSchema | BooleanSchema | ObjectSchema | ArraySchema | AnyOfSchema;所有 Schema 类型最终都可以通过JSON.stringify()转换成 Agent Platform Gemini API 与 Gemini Developer API REST 端点认可的 JSON 字符串且这一转换在调用 SDK 方法时会自动完成。二、类签名与继承关系根据参考文档BooleanSchema的完整类型签名为export declare class BooleanSchema extends Schema即它继承自抽象基类 Schema而Schema实现了SchemaInterfaceSchemaInterface extends SchemaSharedSchemaInterface。继承链中每一层贡献的能力如下SchemaShared提供anyOf、format、description、title、items、minItems、maxItems、properties、propertyOrdering、enum、example、nullable、minimum、maximum等共享属性见 types/schema.tsSchemaInterface追加可选的type字段SchemaType见 types/schema.tsSchema抽象基类实现属性存储、默认值填充与toJSON()序列化逻辑并提供一组静态工厂方法Schema.boolean()、Schema.string()、Schema.object()等。SchemaType.BOOLEAN的常量值为字符串boolean见 types/schema.ts它与 OpenAPI 规范中的布尔数据类型一一对应。三、构造函数与 SchemaParams 参数详解BooleanSchema唯一的公开入口是构造函数签名如下constructor(schemaParams?: SchemaParams);schemaParams类型为 SchemaParams它继承自SchemaSharedSchemaInterface因此创建布尔 Schema 时可以传入以下常用参数均来自SchemaShared定义见 types/schema.ts参数类型说明nullableboolean该字段是否可空。默认值为false未显式传入时由基类构造函数强制填充descriptionstring字段描述帮助模型理解该字段的语义titlestring字段标题用于说明字段意图可在一定程度上引导模型exampleunknown字段示例值例如trueformatstring字段格式注意使用 Gemini Developer APIGoogleAIBackend时format只能取enum或date-time否则请求会失败anyOfSchemaInterface[]允许该字段匹配多个子 Schema 之一与布尔类型并存时用于表达多态字段enumstring[]枚举值对布尔类型通常不使用任意自定义键unknownSDK 允许传入尚未正式收录的其他 Schema 属性基类Schema的构造函数schema-builder.ts在初始化时做了两件关键事情类型校验如果既没有type也没有anyOf会抛出AIError错误码AIErrorCode.INVALID_SCHEMA消息为A schema must have either a type or an anyOf array of sub-schemas.默认值填充nullable未显式指定时被强制置为false保证序列化输出中始终包含该字段。由于BooleanSchema的构造函数内部会合并type: SchemaType.BOOLEANexport class BooleanSchema extends Schema { constructor(schemaParams?: SchemaParams) { super({ type: SchemaType.BOOLEAN, ...schemaParams }); } }所以调用方不需要也不能手动指定type只需传入描述性参数即可。四、创建方式一直接 new BooleanSchema()虽然BooleanSchema是公开导出的类可以直接实例化但更推荐使用Schema的静态工厂方法见下文。直接实例化时等价写法为import { BooleanSchema } from firebase/ai; const schema new BooleanSchema({ nullable: false, description: Whether the user is active., title: Is Active });五、创建方式二Schema.boolean() 静态方法推荐参考文档中 Schema.boolean() 的签名是static boolean(booleanParams?: SchemaParams): BooleanSchema;其源码实现schema-builder.ts仅仅是对new BooleanSchema()的一层封装static boolean(booleanParams?: SchemaParams): BooleanSchema { return new BooleanSchema(booleanParams); }仓库测试用例 schema-builder.test.ts 验证了最简单的用法及其序列化结果it(builds boolean schema, () { const schema Schema.boolean({ title: Is Active }); expect(schema.toJSON()).to.eql({ type: boolean, nullable: false, title: Is Active }); });可以看到即使只传了title序列化结果也会自动带上type: boolean和默认的nullable: false。六、序列化原理toJSON() 与 SchemaRequestBooleanSchema本身没有覆写toJSON()直接复用基类 Schema.toJSON() 的逻辑。其序列化规则为始终输出type字段遍历实例自身的可枚举属性凡是值不为undefined的属性都会写入结果唯一的例外是required字段只有在type object时才输出避免非对象 Schema 携带无意义的required。最终产物符合SchemaRequest接口types/schema.ts即后端请求所要求的最终 Schema 格式。因此你可以在调试时直接调用schema.toJSON()查看即将发送给后端的完整 JSON{ type: boolean, nullable: false, title: Is Active }七、实战在结构化输出与函数声明中使用布尔 Schema7.1 作为 responseSchema 约束模型输出BooleanSchema最常见的用途是配合GenerationConfig.responseSchema使用类型定义见 types/requests.ts。responseSchema接受TypedSchema | SchemaRequest并且只有当responseMimeType为application/json或text/x.enum时才生效。例如让模型直接返回一个布尔判定结果const ai getAI(app, { backend: new GoogleAIBackend() }); const model getGenerativeModel(ai, { model: gemini-2.0-flash, generationConfig: { responseMimeType: application/json, responseSchema: Schema.boolean({ description: Whether the product review is positive. }) } }); const result await model.generateContent(The product is amazing!); // result 的文本内容将被约束为 true 或 false需要注意的是若同时设置responseSchema与responseJsonSchemaSDK 的配置校验会直接抛错对应测试用例见 generative-model.test.ts二者只能取其一。7.2 作为对象/数组 Schema 的字段布尔 Schema 更常见的是嵌套在Schema.object()或Schema.array()中描述复合结构的字段。仓库测试用例 schema-builder.test.ts 展示了在对象中混合使用布尔字段const schema Schema.object({ properties: { someInput: Schema.string(), someBool: Schema.boolean(), anotherInput: Schema.integer() }, optionalProperties: [someBool], title: Ordered Object });在更复杂的嵌套示例中布尔 Schema 还可以携带description与nullableschema-builder.test.tsisCapital: Schema.boolean({ nullable: false, description: This doesnt make a lot of sense but its a demo, title: Is it a capital? })序列化后布尔字段会以type: boolean出现在对应properties中如果该字段不在optionalProperties列表里还会被写入对象的required数组。7.3 在函数调用Function Calling参数中声明布尔入参BooleanSchema同样可用于FunctionDeclaration.parameters让模型在调用函数时严格传入布尔参数。例如在chat-session.test.ts中出现过的函数声明模式chat-session.test.tsconst model getGenerativeModel(ai, { model: gemini-2.0-flash, tools: [{ functionDeclarations: [{ name: set_feature_flag, description: Enable or disable a feature flag., parameters: Schema.object({ properties: { enabled: Schema.boolean({ description: Whether to turn the flag on. }) } }) }] }] });八、相关文档与源码导航若想继续深入可以参考以下仓库内的对应资料类参考文档ai.booleanschema.md、基类 ai.schema.md、参数接口 ai.schemaparams.md、共享属性 ai.schemashared.md、最终请求格式 ai.schemarequest.md核心实现packages/ai/src/requests/schema-builder.tsBooleanSchema定义位于第 200-211 行Schema.boolean()工厂方法位于第 150-152 行类型定义packages/ai/src/types/schema.tsSchemaType、SchemaParams、SchemaRequest、SchemaInterface测试用例packages/ai/src/requests/schema-builder.test.ts覆盖布尔 Schema 的独立构造、数组元素、对象字段与复杂嵌套场景。小结BooleanSchema虽小却是 Firebase AI SDK Schema 体系中不可或缺的一环它通过继承Schema获得了类型校验、默认值填充与 JSON 序列化能力通过Schema.boolean()工厂方法可以零成本创建并能在responseSchema、对象属性与函数声明三个层面约束模型输出。掌握它的构造参数与序列化行为是准确控制 Gemini 结构化输出的第一步。赞分享开发工具后端【免费下载链接】firebase-js-sdkFirebase Javascript SDK项目地址https://gitcode.com/gh_mirrors/fi/firebase-js-sdk点击查看免费下载相关推荐用 Guidance 约束大模型输出LlamaIndex GuidancePydanticProgram 结构化输出实战指南用 Guidance 约束大模型输出LlamaIndex GuidancePydanticProgram 结构化输出实战指南 GuidancePydantic人工智能RAG大模型Firebase AI SDK ArraySchema 详解用 Schema.array 声明数组结构化输出Firebase AI SDK ArraySchema 详解用 Schema.array 声明数组结构化输出 本篇指南聚焦 Firebase AI Web S开发工具后端Guardrails Formatters 完全指南通过 BaseFormatter 与 JsonFormatter 实现结构化输出的约束解码Guardrails Formatters 完全指南通过 BaseFormatter 与 JsonFormatter 实现结构化输出的约束解码 导读 FormAI 安全治理模型安全AI 应用上一篇3步搞定演唱会抢票难题DamaiHelper从入门到精通实战指南下一篇KK-HF Patch完整指南Koikatu/Koikatsu Party增强补丁深度解析创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/10/15 3:13:35 · 阅读 1.2k Firebase AI SDK 中 BooleanSchema 完全指南：用 Schema.boolean() 约束 Gemini 结构化输出
开发工具后端【免费下载链接】firebase-js-sdkFirebase Javascript SDK项目地址https://gitcode.com/gh_mirrors/fi/firebase-js-sdk点击查看免费下载BooleanSchema是 Firebase AI Web SDKfirebase/ai中用于描述布尔类型字段的 Schema 类它在使用 Gemini 模型做结构化输出、函数调用参数声明等场景中负责约束模型只能生成true/false这样的布尔值。本文以官方 API 参考文档 docs-devsite/ai.booleanschema.md 为主体结合仓库内 schema-builder.ts 源码与测试用例带你掌握BooleanSchema的类结构、构造参数、序列化原理以及它在responseSchema与函数声明中的实战用法。一、BooleanSchema 在 SDK 中的定位在 Firebase AI SDK 的 Schema 体系中BooleanSchema是面向boolean类型的专用 Schema 类。它的官方定义只有一句话Schema class for boolean types.它属于 SDK 提供的七种具体 Schema 类型之一TypedSchema联合类型IntegerSchema、NumberSchema、StringSchema、BooleanSchema、ObjectSchema、ArraySchema、AnyOfSchema完整定义见 schema-builder.tsexport type TypedSchema | IntegerSchema | NumberSchema | StringSchema | BooleanSchema | ObjectSchema | ArraySchema | AnyOfSchema;所有 Schema 类型最终都可以通过JSON.stringify()转换成 Agent Platform Gemini API 与 Gemini Developer API REST 端点认可的 JSON 字符串且这一转换在调用 SDK 方法时会自动完成。二、类签名与继承关系根据参考文档BooleanSchema的完整类型签名为export declare class BooleanSchema extends Schema即它继承自抽象基类 Schema而Schema实现了SchemaInterfaceSchemaInterface extends SchemaSharedSchemaInterface。继承链中每一层贡献的能力如下SchemaShared提供anyOf、format、description、title、items、minItems、maxItems、properties、propertyOrdering、enum、example、nullable、minimum、maximum等共享属性见 types/schema.tsSchemaInterface追加可选的type字段SchemaType见 types/schema.tsSchema抽象基类实现属性存储、默认值填充与toJSON()序列化逻辑并提供一组静态工厂方法Schema.boolean()、Schema.string()、Schema.object()等。SchemaType.BOOLEAN的常量值为字符串boolean见 types/schema.ts它与 OpenAPI 规范中的布尔数据类型一一对应。三、构造函数与 SchemaParams 参数详解BooleanSchema唯一的公开入口是构造函数签名如下constructor(schemaParams?: SchemaParams);schemaParams类型为 SchemaParams它继承自SchemaSharedSchemaInterface因此创建布尔 Schema 时可以传入以下常用参数均来自SchemaShared定义见 types/schema.ts参数类型说明nullableboolean该字段是否可空。默认值为false未显式传入时由基类构造函数强制填充descriptionstring字段描述帮助模型理解该字段的语义titlestring字段标题用于说明字段意图可在一定程度上引导模型exampleunknown字段示例值例如trueformatstring字段格式注意使用 Gemini Developer APIGoogleAIBackend时format只能取enum或date-time否则请求会失败anyOfSchemaInterface[]允许该字段匹配多个子 Schema 之一与布尔类型并存时用于表达多态字段enumstring[]枚举值对布尔类型通常不使用任意自定义键unknownSDK 允许传入尚未正式收录的其他 Schema 属性基类Schema的构造函数schema-builder.ts在初始化时做了两件关键事情类型校验如果既没有type也没有anyOf会抛出AIError错误码AIErrorCode.INVALID_SCHEMA消息为A schema must have either a type or an anyOf array of sub-schemas.默认值填充nullable未显式指定时被强制置为false保证序列化输出中始终包含该字段。由于BooleanSchema的构造函数内部会合并type: SchemaType.BOOLEANexport class BooleanSchema extends Schema { constructor(schemaParams?: SchemaParams) { super({ type: SchemaType.BOOLEAN, ...schemaParams }); } }所以调用方不需要也不能手动指定type只需传入描述性参数即可。四、创建方式一直接 new BooleanSchema()虽然BooleanSchema是公开导出的类可以直接实例化但更推荐使用Schema的静态工厂方法见下文。直接实例化时等价写法为import { BooleanSchema } from firebase/ai; const schema new BooleanSchema({ nullable: false, description: Whether the user is active., title: Is Active });五、创建方式二Schema.boolean() 静态方法推荐参考文档中 Schema.boolean() 的签名是static boolean(booleanParams?: SchemaParams): BooleanSchema;其源码实现schema-builder.ts仅仅是对new BooleanSchema()的一层封装static boolean(booleanParams?: SchemaParams): BooleanSchema { return new BooleanSchema(booleanParams); }仓库测试用例 schema-builder.test.ts 验证了最简单的用法及其序列化结果it(builds boolean schema, () { const schema Schema.boolean({ title: Is Active }); expect(schema.toJSON()).to.eql({ type: boolean, nullable: false, title: Is Active }); });可以看到即使只传了title序列化结果也会自动带上type: boolean和默认的nullable: false。六、序列化原理toJSON() 与 SchemaRequestBooleanSchema本身没有覆写toJSON()直接复用基类 Schema.toJSON() 的逻辑。其序列化规则为始终输出type字段遍历实例自身的可枚举属性凡是值不为undefined的属性都会写入结果唯一的例外是required字段只有在type object时才输出避免非对象 Schema 携带无意义的required。最终产物符合SchemaRequest接口types/schema.ts即后端请求所要求的最终 Schema 格式。因此你可以在调试时直接调用schema.toJSON()查看即将发送给后端的完整 JSON{ type: boolean, nullable: false, title: Is Active }七、实战在结构化输出与函数声明中使用布尔 Schema7.1 作为 responseSchema 约束模型输出BooleanSchema最常见的用途是配合GenerationConfig.responseSchema使用类型定义见 types/requests.ts。responseSchema接受TypedSchema | SchemaRequest并且只有当responseMimeType为application/json或text/x.enum时才生效。例如让模型直接返回一个布尔判定结果const ai getAI(app, { backend: new GoogleAIBackend() }); const model getGenerativeModel(ai, { model: gemini-2.0-flash, generationConfig: { responseMimeType: application/json, responseSchema: Schema.boolean({ description: Whether the product review is positive. }) } }); const result await model.generateContent(The product is amazing!); // result 的文本内容将被约束为 true 或 false需要注意的是若同时设置responseSchema与responseJsonSchemaSDK 的配置校验会直接抛错对应测试用例见 generative-model.test.ts二者只能取其一。7.2 作为对象/数组 Schema 的字段布尔 Schema 更常见的是嵌套在Schema.object()或Schema.array()中描述复合结构的字段。仓库测试用例 schema-builder.test.ts 展示了在对象中混合使用布尔字段const schema Schema.object({ properties: { someInput: Schema.string(), someBool: Schema.boolean(), anotherInput: Schema.integer() }, optionalProperties: [someBool], title: Ordered Object });在更复杂的嵌套示例中布尔 Schema 还可以携带description与nullableschema-builder.test.tsisCapital: Schema.boolean({ nullable: false, description: This doesnt make a lot of sense but its a demo, title: Is it a capital? })序列化后布尔字段会以type: boolean出现在对应properties中如果该字段不在optionalProperties列表里还会被写入对象的required数组。7.3 在函数调用Function Calling参数中声明布尔入参BooleanSchema同样可用于FunctionDeclaration.parameters让模型在调用函数时严格传入布尔参数。例如在chat-session.test.ts中出现过的函数声明模式chat-session.test.tsconst model getGenerativeModel(ai, { model: gemini-2.0-flash, tools: [{ functionDeclarations: [{ name: set_feature_flag, description: Enable or disable a feature flag., parameters: Schema.object({ properties: { enabled: Schema.boolean({ description: Whether to turn the flag on. }) } }) }] }] });八、相关文档与源码导航若想继续深入可以参考以下仓库内的对应资料类参考文档ai.booleanschema.md、基类 ai.schema.md、参数接口 ai.schemaparams.md、共享属性 ai.schemashared.md、最终请求格式 ai.schemarequest.md核心实现packages/ai/src/requests/schema-builder.tsBooleanSchema定义位于第 200-211 行Schema.boolean()工厂方法位于第 150-152 行类型定义packages/ai/src/types/schema.tsSchemaType、SchemaParams、SchemaRequest、SchemaInterface测试用例packages/ai/src/requests/schema-builder.test.ts覆盖布尔 Schema 的独立构造、数组元素、对象字段与复杂嵌套场景。小结BooleanSchema虽小却是 Firebase AI SDK Schema 体系中不可或缺的一环它通过继承Schema获得了类型校验、默认值填充与 JSON 序列化能力通过Schema.boolean()工厂方法可以零成本创建并能在responseSchema、对象属性与函数声明三个层面约束模型输出。掌握它的构造参数与序列化行为是准确控制 Gemini 结构化输出的第一步。赞分享开发工具后端【免费下载链接】firebase-js-sdkFirebase Javascript SDK项目地址https://gitcode.com/gh_mirrors/fi/firebase-js-sdk点击查看免费下载相关推荐用 Guidance 约束大模型输出LlamaIndex GuidancePydanticProgram 结构化输出实战指南用 Guidance 约束大模型输出LlamaIndex GuidancePydanticProgram 结构化输出实战指南 GuidancePydantic人工智能RAG大模型Firebase AI SDK ArraySchema 详解用 Schema.array 声明数组结构化输出Firebase AI SDK ArraySchema 详解用 Schema.array 声明数组结构化输出 本篇指南聚焦 Firebase AI Web S开发工具后端Guardrails Formatters 完全指南通过 BaseFormatter 与 JsonFormatter 实现结构化输出的约束解码Guardrails Formatters 完全指南通过 BaseFormatter 与 JsonFormatter 实现结构化输出的约束解码 导读 FormAI 安全治理模型安全AI 应用上一篇3步搞定演唱会抢票难题DamaiHelper从入门到精通实战指南下一篇KK-HF Patch完整指南Koikatu/Koikatsu Party增强补丁深度解析创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考