Puedes garantizar que el resultado generado por un modelo siempre cumpla con un esquema específico para que recibas respuestas con formato coherente. Por ejemplo, es posible que tengas un esquema de datos establecido que usas para otras tareas. Si haces que el modelo siga el mismo esquema, puedes extraer datos directamente del resultado del modelo sin ningún procesamiento posterior.
Para especificar la estructura del resultado de un modelo, define un esquema de respuesta, que funciona como un modelo para las respuestas del modelo. Cuando envías una instrucción y, además, incluyes el esquema de respuesta, la respuesta del modelo siempre sigue el esquema que definiste.
Puedes controlar el resultado generado cuando usas los siguientes modelos:
- Vertex AI Model Optimizer
Experimental - Gemini 2.5 Pro
- Gemini 2.5 Flash
- Gemini 2.0 Flash
- Gemini 2.0 Flash-Lite
Ejemplos de casos de uso
Un caso de uso para aplicar un esquema de respuesta es garantizar que la respuesta de un modelo genere un JSON válido y cumpla con tu esquema. Los resultados del modelo generativo pueden tener cierto grado de variabilidad, por lo que incluir un esquema de respuesta garantiza que siempre recibas un JSON válido. Por lo tanto, tus tareas descendentes pueden esperar de forma confiable una entrada JSON válida de las respuestas generadas.
Otro ejemplo es restringir la forma en que un modelo puede responder. Por ejemplo, puedes hacer que un modelo annote texto con etiquetas definidas por el usuario, no con etiquetas que produce el modelo. Esta restricción es útil cuando esperas un conjunto específico de etiquetas, como positive
o negative
, y no quieres recibir una combinación de otras etiquetas que podría generar el modelo, como good
, positive
, negative
o bad
.
Consideraciones
En las siguientes consideraciones, se analizan las posibles limitaciones si planeas usar un esquema de respuesta:
- Debes usar la API para definir y usar un esquema de respuesta. No hay compatibilidad con consolas.
- El tamaño del esquema de respuesta se considera para el límite de tokens de entrada.
- Solo se admiten ciertos formatos de salida, como
application/json
otext/x.enum
. Para obtener más información, consulta el parámetroresponseMimeType
en la referencia de la API de Gemini. - La salida estructurada admite un subconjunto de la referencia del esquema de Vertex AI. Para obtener más información, consulta Campos de esquema admitidos.
Un esquema complejo puede generar un error
InvalidArgument: 400
. La complejidad puede deberse a nombres de propiedades largos, límites de longitud de arrays largos, enumeraciones con muchos valores, objetos con muchas propiedades opcionales o una combinación de estos factores.Si recibes este error con un esquema válido, realiza uno o más de los siguientes cambios para resolverlo:
- Acortar los nombres de las propiedades o los nombres de las enumeraciones
- Compacta los arrays anidados.
- Reduce la cantidad de propiedades con restricciones, como los números con límites mínimos y máximos.
- Reduce la cantidad de propiedades con restricciones complejas, como las que tienen formatos complejos, como
date-time
. - Reduce la cantidad de propiedades opcionales.
- Reduce la cantidad de valores válidos para las enumeraciones.
Campos de esquema admitidos
El resultado estructurado admite los siguientes campos del esquema de Vertex AI. Si usas un campo no compatible, Vertex AI puede controlar tu solicitud, pero ignora el campo.
anyOf
enum
format
items
maximum
maxItems
minimum
minItems
nullable
properties
propertyOrdering
*required
* propertyOrdering
es específico para el resultado estructurado y no forma parte del esquema de Vertex AI. Este campo define el orden en el que se generan las propiedades. Las propiedades enumeradas deben ser únicas y deben ser claves válidas en el diccionario properties
.
En el campo format
, Vertex AI admite los siguientes valores: date
, date-time
, duration
y time
. La descripción y el formato de cada valor se describen en el Registro de la Iniciativa de OpenAPI.
Antes de comenzar
Define un esquema de respuesta para especificar la estructura del resultado de un modelo, los nombres de los campos y el tipo de datos esperado para cada campo. Usa solo los campos compatibles que se indican en la sección Consideraciones. Se ignorará el resto de los campos.
Incluye tu esquema de respuesta solo como parte del campo responseSchema
. No dupliques el esquema en tu instrucción de entrada. Si lo haces, es posible que el resultado generado sea de menor calidad.
Para ver ejemplos de esquemas, consulta la sección Ejemplos de esquemas y respuestas de modelos.
Comportamiento del modelo y esquema de respuesta
Cuando un modelo genera una respuesta, usa el nombre del campo y el contexto de tu instrucción. Por lo tanto, te recomendamos que uses una estructura clara y nombres de campo inequívocos para que tu intención sea clara.
De forma predeterminada, los campos son opcionales, lo que significa que el modelo puede propagar los campos o omitirlos. Puedes configurar los campos según sea necesario para forzar al modelo a proporcionar un valor. Si no hay suficiente contexto en la instrucción de entrada asociada, el modelo genera respuestas principalmente en función de los datos con los que se entrenó.
Si no ves los resultados que esperas, agrega más contexto a tus instrucciones de entrada o revisa tu esquema de respuesta. Por ejemplo, revisa la respuesta del modelo sin un resultado estructurado para ver cómo responde. Luego, puedes actualizar el esquema de respuesta que mejor se adapte al resultado del modelo.
Envía una instrucción con un esquema de respuesta
De forma predeterminada, todos los campos son opcionales, lo que significa que un modelo puede generar una respuesta a un campo. Para forzar al modelo a que siempre genere una respuesta para un campo, configúralo como se requiera.
Python
Instalar
pip install --upgrade google-genai
Para obtener más información, consulta la documentación de referencia del SDK.
Establece variables de entorno para usar el SDK de IA generativa con Vertex AI:
# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values # with appropriate values for your project. export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT export GOOGLE_CLOUD_LOCATION=global export GOOGLE_GENAI_USE_VERTEXAI=True
Go
Obtén información para instalar o actualizar Go.
Para obtener más información, consulta la documentación de referencia del SDK.
Establece variables de entorno para usar el SDK de IA generativa con Vertex AI:
# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values # with appropriate values for your project. export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT export GOOGLE_CLOUD_LOCATION=global export GOOGLE_GENAI_USE_VERTEXAI=True
REST
Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:
- GENERATE_RESPONSE_METHOD: El tipo de respuesta que quieres que genere el modelo.
Elige un método que genere cómo quieres que se muestre la respuesta del modelo:
streamGenerateContent
: La respuesta se transmite a medida que se genera para reducir la percepción de latencia para un público humano.generateContent
: La respuesta se muestra después de que se genera por completo.
- LOCATION: La región para procesar la solicitud.
- PROJECT_ID: El ID del proyecto.
- MODEL_ID: Es el ID del modelo multimodal que deseas usar.
- ROLE:
El rol en una conversación asociada con el contenido. Especificar un rol es obligatorio incluso en
casos de uso de un solo turno.
Los valores aceptables son los siguientes:
USER
: especifica el contenido que envías.
- TEXT: Las instrucciones de texto que se incluirán en el mensaje.
- RESPONSE_MIME_TYPE: Es el tipo de formato del texto candidato generado. Para obtener una lista de los valores admitidos, consulta el parámetro
responseMimeType
en la API de Gemini. - RESPONSE_SCHEMA: Es el esquema que debe seguir el modelo cuando genera respuestas. Para obtener más información, consulta la referencia de Esquema.
Método HTTP y URL:
POST https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:GENERATE_RESPONSE_METHOD
Cuerpo JSON de la solicitud:
{ "contents": { "role": "ROLE", "parts": { "text": "TEXT" } }, "generation_config": { "responseMimeType": "RESPONSE_MIME_TYPE", "responseSchema": RESPONSE_SCHEMA, } }
Para enviar tu solicitud, elige una de estas opciones:
curl
Guarda el cuerpo de la solicitud en un archivo llamado request.json
y ejecuta el siguiente comando:
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:GENERATE_RESPONSE_METHOD"
PowerShell
Guarda el cuerpo de la solicitud en un archivo llamado request.json
y ejecuta el siguiente comando:
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:GENERATE_RESPONSE_METHOD" | Select-Object -Expand Content
Deberías recibir una respuesta JSON similar a la que se muestra a continuación:
Ejemplo del comando curl
LOCATION="us-central1"
MODEL_ID="gemini-2.5-flash"
PROJECT_ID="test-project"
GENERATE_RESPONSE_METHOD="generateContent"
cat << EOF > request.json
{
"contents": {
"role": "user",
"parts": {
"text": "List a few popular cookie recipes."
}
},
"generation_config": {
"maxOutputTokens": 2048,
"responseMimeType": "application/json",
"responseSchema": {
"type": "array",
"items": {
"type": "object",
"properties": {
"recipe_name": {
"type": "string",
},
},
"required": ["recipe_name"],
},
}
}
}
EOF
curl \
-X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
https://${LOCATION}-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/publishers/google/models/${MODEL_ID}:${GENERATE_RESPONSE_METHOD} \
-d '@request.json'
Ejemplos de esquemas para la salida JSON
En las siguientes secciones, se muestra una variedad de instrucciones y esquemas de respuesta de muestra. También se incluye una respuesta de modelo de muestra después de cada muestra de código.
- Pronostica el clima para cada día de la semana en un array
- Clasifica un producto con una enumeración bien definida
Pronostica el clima para cada día de la semana
En el siguiente ejemplo, se muestra un objeto forecast
para cada día de la semana que incluye un array de propiedades, como la temperatura y el nivel de humedad esperados para el día. Algunas propiedades se establecen como anulables para que el modelo pueda mostrar un valor nulo cuando no tenga suficiente contexto para generar una respuesta significativa. Esta estrategia ayuda a reducir las alucinaciones.
Python
Instalar
pip install --upgrade google-genai
Para obtener más información, consulta la documentación de referencia del SDK.
Establece variables de entorno para usar el SDK de IA generativa con Vertex AI:
# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values # with appropriate values for your project. export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT export GOOGLE_CLOUD_LOCATION=global export GOOGLE_GENAI_USE_VERTEXAI=True
Go
Obtén información para instalar o actualizar Go.
Para obtener más información, consulta la documentación de referencia del SDK.
Establece variables de entorno para usar el SDK de IA generativa con Vertex AI:
# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values # with appropriate values for your project. export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT export GOOGLE_CLOUD_LOCATION=global export GOOGLE_GENAI_USE_VERTEXAI=True
Clasifica un producto
En el siguiente ejemplo, se incluyen enums en las que el modelo debe clasificar el tipo y la condición de un objeto a partir de una lista de valores determinados.
Python
Instalar
pip install --upgrade google-genai
Para obtener más información, consulta la documentación de referencia del SDK.
Establece variables de entorno para usar el SDK de IA generativa con Vertex AI:
# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values # with appropriate values for your project. export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT export GOOGLE_CLOUD_LOCATION=global export GOOGLE_GENAI_USE_VERTEXAI=True
Go
Obtén información para instalar o actualizar Go.
Para obtener más información, consulta la documentación de referencia del SDK.
Establece variables de entorno para usar el SDK de IA generativa con Vertex AI:
# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values # with appropriate values for your project. export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT export GOOGLE_CLOUD_LOCATION=global export GOOGLE_GENAI_USE_VERTEXAI=True
Node.js
Instalar
npm install @google/genai
Para obtener más información, consulta la documentación de referencia del SDK.
Establece variables de entorno para usar el SDK de IA generativa con Vertex AI:
# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values # with appropriate values for your project. export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT export GOOGLE_CLOUD_LOCATION=global export GOOGLE_GENAI_USE_VERTEXAI=True
Java
Obtén información para instalar o actualizar Java.
Para obtener más información, consulta la documentación de referencia del SDK.
Establece variables de entorno para usar el SDK de IA generativa con Vertex AI:
# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values # with appropriate values for your project. export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT export GOOGLE_CLOUD_LOCATION=global export GOOGLE_GENAI_USE_VERTEXAI=True