Gemini 3 结构化输出

Every LLM user knows the pain: "return JSON" and the model replies with a paragraph, a markdown code fence, and a JSON block wearing a hat. Gemini3StructuredOutput kills that failure mode at the API level. You give it a JSON schema, the model is constrained to produce matching JSON via Google's responseMimeType: "application/json" + responseJsonSchema mechanism, and the node validates the result before handing it over. What comes out of the json_output socket is parseable JSON, full stop.

This is the node to reach for when the output has to feed other nodes - a config object for a batch, parameters for a sampler, a manifest for a pipeline. ComfyUI's plumbing layer is string-centric, so a node that reliably emits well-formed JSON saves you a regex-cleanup stage in every workflow that needs one (comfyui-node-plumbing.md).

How it works

The json_schema input is a standard JSON Schema document - the default is a football-match example (winner, final_score, scorers). It's passed straight into Google's generation config as responseJsonSchema, so the model itself is constrained to the shape, not just instructed to follow it. After the call, the node parses the returned text with json.loads and refuses to pass it through if it isn't valid JSON - you get an error string instead of a broken blob.

What makes it more than a glorified formatter: the three optional boolean toggles, enable_google_search, enable_code_execution, and enable_url_context. Each one adds the corresponding built-in Google tool to the request, so the schema-constrained output can be grounded in a live search or computed with executed code in the same call. The default prompt ("search the latest Euro results") is built around exactly that combination.

Inputs and outputs that matter

• prompt - what you want done.
• json_schema - the shape you demand. Required properties should include required arrays; the node passes your schema through verbatim, so a sloppy schema gets you a sloppy contract.
• The three boolean toggles - flip on search/code/URL-context only when the prompt needs them; they cost extra and add latency.

Outputs: json_output (validated JSON as a string) and usage_metadata (token counts). Wire json_output into any node that can consume a JSON string.

Install

Standard for the pack. ComfyUI Manager (search "ComfyUI-Gemini-3") or:

cd ComfyUI/custom_nodes
git clone https://github.com/xuchenxu168/ComfyUI-Gemini-3
cd ComfyUI-Gemini-3
pip install -r requirements.txt

No downloads. Google AI Studio key via api_key field, config.json, or GEMINI_API_KEY.

Common issues

• "输出不是有效的JSON" - the validation-failure message (Chinese, matching the node's defaults). It means the model returned text the schema constraint didn't catch; usually a prompt-too-vague problem. Make the prompt ask for exactly the fields you listed.
• Schema too loose - responseJsonSchema guarantees shape, not content correctness. If your schema doesn't declare required, the model may omit keys.
• Tool toggles don't stack cleanly - enabling Google Search and Code Execution at once is supported, but the model decides how to spend them; for a deterministic pipeline, enable only the tool you need.
• It's schema-first, not freeform - if you just want prose, use the pack's text generation node instead. This node's whole value is the constraint, and it leans on it hard.