Generar JSON estructurado a partir de textos arquitectónicos con Gemini API

¿Qué aprenderás en esta guía?

Un brief de proyecto, una nota sobre materiales o una descripción de un espacio suelen llegar en forma de texto libre. Cuando es necesario extraer de esos textos datos estructurados, como el nombre de una estancia, un material o el uso previsto, recibir una respuesta únicamente en lenguaje natural puede dificultar los procesos posteriores. La función de salida estructurada de Gemini API permite pedir que la respuesta del modelo se ajuste a un JSON Schema definido previamente.

En esta guía abordamos tres aspectos: definir los campos esperados, describir la tarea y sus restricciones con instrucciones claras y, por último, añadir el esquema adecuado a la solicitud de la API. Los ejemplos están pensados para flujos de trabajo arquitectónicos; las instrucciones siguientes no aparecen tal cual en las fuentes, sino que son ejemplos originales basados en los métodos documentados.

Requisitos y alcance

La documentación de Google menciona la compatibilidad con JSON Schema en la API REST para generar salidas estructuradas. En los SDK de Google GenAI, se presentan Pydantic para Python y Zod para JavaScript como opciones para definir esquemas. Las fuentes también incluyen ejemplos para Java, Go y otros lenguajes; en esta guía usamos un borrador de JSON Schema fácil de adaptar, en lugar de código.

Los ejemplos de la documentación indican que es necesario instalar Zod para JavaScript, pero no ofrecen información sobre la versión del SDK, las condiciones de la cuenta ni los precios. Por eso, antes de empezar un proyecto, consulta la documentación vigente de Gemini API para comprobar los requisitos del SDK y el modelo que vas a utilizar. En la parte superior de la documentación se indica que Gemini 4 Argon está disponible, mientras que el código de ejemplo menciona el modelo gemini-3.8-flash. No des por hecho que el nombre del modelo del ejemplo está actualizado o que es adecuado para todos los casos.

1. Define los campos que quieres extraer

Antes de preparar el esquema, decide qué datos quieres extraer del texto y qué tipo debe tener cada uno. Por ejemplo, el siguiente borrador busca extraer el nombre del espacio, el material mencionado y una descripción de su función a partir de un brief de interiorismo. Estructuras básicas de JSON Schema como object, properties, string y required coinciden con los ejemplos de las fuentes.

{
  "type": "object",
  "properties": {
    "mekan_adi": { "type": "string" },
    "malzeme": { "type": "string" },
    "islev": { "type": "string" }
  },
  "required": ["mekan_adi", "malzeme", "islev"]
}

En este caso, los tres campos son obligatorios. Si la fuente no especifica uno de ellos, indica en las instrucciones qué debe hacerse; por ejemplo, puedes pedir que el campo quede vacío o que se escriba «no especificado». La decisión depende de cómo se vayan a procesar los datos del proyecto. Tomarla desde el principio al crear el esquema facilita la obtención de resultados coherentes en el equipo.

2. Describe claramente la tarea y la entrada

Una buena instrucción explica de forma comprensible qué hay que hacer, sobre qué texto se trabajará y en qué formato debe presentarse la respuesta. La guía de diseño de instrucciones de Google recomienda utilizar indicaciones claras y específicas y, cuando sea necesario, detallar las restricciones y el formato esperado. Puedes adaptar el siguiente ejemplo a los campos de tus briefs.

Aşağıdaki iç mekân proje brief’inden mekân adını, açıkça belirtilen malzemeyi ve mekânın işlevini çıkar. Yalnızca verilen metindeki bilgilere dayan. Bir bilgi metinde yoksa bunu “belirtilmemiş” olarak yaz. Yanıtı, sağlanan JSON şemasındaki alanlarla uyumlu bir JSON nesnesi olarak üret.

Brief: Zemin katta yer alan okuma alanında meşe kaplama yüzeyler ve ortak çalışma masaları bulunuyor.

Esta instrucción proporciona el texto de entrada, define la tarea de extracción y especifica cómo actuar cuando falta información. La función de salida estructurada, por su parte, permite que la respuesta se ajuste al esquema. La instrucción y el esquema deben describir los mismos campos: no pidas en la instrucción claves que no estén en el esquema ni omitas del esquema campos solicitados.

3. Ajusta las restricciones a las necesidades del proyecto

En la documentación arquitectónica es importante distinguir entre una interpretación y la información de la fuente. Si estás extrayendo una lista de materiales, indica claramente que no se añadan productos ni especificaciones técnicas que no aparezcan en el texto. Por ejemplo, la siguiente instrucción se centra únicamente en recopilar los materiales escritos en la descripción de un espacio.

Bu mahal açıklamasında adı geçen kaplama ve yüzey malzemelerini çıkar. Yeni malzeme önerme, eş anlamlı veya marka tahmini ekleme. Sonucu yalnızca malzeme adlarından oluşan bir liste olarak ver.

Açıklama: Giriş holünde terrazzo döşeme ve boyalı alçı duvar yüzeyi kullanılacaktır.

En este ejemplo se pide una lista, así que no lo uses directamente para la misma tarea que el esquema anterior, que espera un objeto JSON. El formato de respuesta depende de las necesidades: si usas salida estructurada, el esquema debe coincidir con el resultado descrito en la instrucción. En lugar de reutilizar un único esquema para tareas distintas, vuelve a evaluar los campos y los tipos de datos de cada caso.

4. Muestra el formato con una respuesta de ejemplo

Cuando la clasificación o el patrón de redacción deseados pueden interpretarse de varias maneras si solo se describen con palabras, incluir ejemplos breves puede ayudar a definir el formato. La guía de Google explica que el enfoque few-shot permite mostrar al modelo ejemplos de entrada y el formato de respuesta esperado, y que conviene que los ejemplos sean claros y variados.

Aşağıdaki örnekteki alanları kullanarak yeni mahal notunu sınıflandır.

Örnek not: “Mutfak tezgâhı kuvars kompozit, dolap kapakları mat lake.”
Örnek çıktı: {"mekan": "Mutfak", "malzemeler": ["kuvars kompozit", "mat lake"]}

Yeni not: “Çalışma odasında ahşap parke ve sıva üzeri boya bulunuyor.”
Yalnızca aynı alan düzeninde yanıt ver.

Este ejemplo muestra la estructura de la respuesta, pero en la solicitud real a la API también tendrás que definir el esquema. La guía de las fuentes señala que se puede empezar con pocos ejemplos y que quizá sea necesario probar distintas cantidades según el caso de uso. También advierte que un número excesivo de ejemplos puede provocar un sobreajuste del modelo.

Errores frecuentes

Un problema habitual es incluir los requisitos solo en la instrucción y no especificar un esquema en la API. Google indica que se puede pedir en lenguaje natural un formato JSON sencillo, pero recomienda la función de salida estructurada cuando se necesitan JSON Schema más complejos. Otro problema es que la instrucción y el esquema pidan campos o formatos de respuesta diferentes. Primero define con claridad los campos y sus tipos; después, redacta la instrucción para que se ajuste a esa estructura.

Otro error es esperar que el modelo complete detalles que no están en la fuente cuando el texto es ambiguo. Especifica en la instrucción qué información debe extraerse, qué debe dejarse fuera y cómo representar los datos que faltan. El esquema ayuda a mantener la coherencia del formato, pero no garantiza por sí solo que la fuente del proyecto sea correcta o completa. Comparar los registros generados con el brief original es importante, sobre todo en procesos de entrega y documentación.

Uso en flujos de trabajo de arquitectura y visualización

Este enfoque puede ser útil para estudios de arquitectura, interioristas y estudiantes que necesitan organizar muchas notas de proyecto en los mismos campos. Extraer nombres de materiales, tipos de espacios o descripciones de uso a partir de descripciones de estancias proporciona un punto de partida ordenado para los flujos de trabajo en los que esos datos se transferirán después a otra herramienta. Las fuentes no describen la integración con ningún software BIM, CAD o de visualización en particular, así que la conexión y la compatibilidad deben evaluarse por separado.

Los estudios pueden empezar probando si los campos son adecuados con un pequeño conjunto de textos y, después, comprobar cómo responde el mismo esquema y la misma instrucción con distintos briefs. Para los estudiantes, este método combina de forma práctica la extracción de datos de texto libre y la comprensión de la estructura JSON. Las fuentes no ofrecen información sobre hardware, licencias ni costes de uso de la API; compruébalos en la documentación del servicio correspondiente antes de pasar a producción.

Próximos pasos

Empieza por elegir un único caso de uso; por ejemplo, extraer materiales de una nota sobre una estancia. Define los campos y crea el esquema; luego, pruébalo con una instrucción clara. Compara los resultados con el texto de origen, observa los errores recurrentes y añade ejemplos a la instrucción solo cuando sea realmente necesario. Si la aplicación usa Python, considera Pydantic; si usa JavaScript, evalúa la opción de definir esquemas con Zod. La documentación también indica que se puede utilizar la API REST.

Cuando el proyecto crezca, documenta los cambios en el esquema y los campos esperados para el equipo. Así será más fácil comprobar si se mantiene la misma estructura de datos en las distintas tareas que procesan briefs arquitectónicos. Al principio, el objetivo no es automatizarlo todo, sino probar un proceso de texto repetitivo con reglas claras y un formato de respuesta verificable.

Fuentes y licencia

Esta guía se ha adaptado al turco a partir de los documentos de Google “Structured outputs” y “Prompt design strategies”. Ambas fuentes están bajo la licencia CC BY 4.0.