GuidesOneMux

Extracción estructurada segura con OpenAI: claves, registros, permisos y rotación

Flujo de trabajo práctico para extraer datos estructurados con OpenAI: aislar credenciales, restringir permisos, validar la salida JSON, redactar registros y rotar claves de forma segura.

AI

Resumen · TL;DR

Para la extracción estructurada, guarda la clave de aplicación de OpenAI en una capa de aplicación de confianza, no en código generado por agentes ni en registros. Solicita una salida restringida por esquema, vuelve a validarla en tu aplicación y trata los errores de validación como errores recuperables, no como datos fiables. Separa las credenciales según su propósito, redacta el contenido sensible de los registros y documenta un procedimiento para rotar y revocar claves.

Puntos clave

  • Mantén la clave API de la aplicación fuera de los entornos de agentes o de sandbox; concede a cada carga de trabajo solo el acceso que necesita.
  • Un esquema JSON restringe el formato de salida, pero sigue siendo necesario validar en la aplicación y comprobar las reglas de negocio.
  • Cuando sea útil, registra identificadores de solicitud y resultados de validación, no credenciales sin proteger ni texto sensible extraído.
  • Mantén un procedimiento documentado para rotar claves que contemple el despliegue, la verificación y la revocación inmediata si se sospecha una exposición.
En esta página (7)

El patrón seguro para la extracción estructurada

Para extraer campos de documentos, divide el trabajo en tres partes: una aplicación de confianza envía la solicitud, el modelo devuelve datos con la estructura definida por el esquema y tu aplicación los valida y decide qué almacenar o cómo actuar. Mantén las credenciales en la capa de aplicación de confianza. No incluyas la clave de aplicación en instrucciones, código generado, imágenes de contenedor ni registros.

La guía de seguridad de sandbox de OpenAI indica que el código generado por agentes puede acceder a archivos, credenciales y recursos de red disponibles en su entorno. Recomienda cargas de trabajo aisladas, acceso a la red restringido, credenciales separadas y mantener la clave API de la aplicación fuera del entorno. También recomienda rotar o revocar las claves cuando sea necesario. Consulta la guía de seguridad de sandbox de OpenAI.

Los ejemplos siguientes son ilustrativos; no se han probado con una cuenta activa. Consulta la documentación actual de la API para comprobar la compatibilidad del endpoint y los parámetros con el SDK o proveedor que hayas elegido. No des por hecho que un endpoint compatible admite todos los parámetros de OpenAI.

Requisitos previos y límites de confianza

Antes de implementar la extracción, identifica dónde se encuentra cada dato y credencial:

  • Aplicación: contiene la clave de aplicación de OpenAI y realiza la solicitud al modelo.
  • Modelo o entorno de sandbox: recibe únicamente los datos de la tarea y las herramientas que necesita; no debería recibir la clave de aplicación.
  • Registros y supervisión: conservan metadatos operativos sin guardar secretos ni contenido documental innecesario.
  • Almacenamiento o acciones posteriores: aceptan los valores extraídos únicamente después de comprobar el esquema y las reglas de negocio.

Cuando sea práctico, usa un proyecto o una credencial específicos para la aplicación o carga de trabajo. Restringe los permisos a las acciones de API necesarias. La guía de OpenAI indica api.responses.write para inferencia y, en las sesiones de su Agents API, api.agents.read y api.agents.write; la gestión de vaults también requiere permisos de vault. Estos permisos corresponden a las funciones documentadas, no constituyen una receta universal. Concede únicamente los ámbitos pertinentes para tu implementación.

Solicita datos con la estructura del esquema y luego valídalos

Define los campos de salida y sus tipos antes de redactar la instrucción de extracción. Por ejemplo, un flujo de trabajo para recibos podría requerir el nombre del comercio, la fecha, la divisa y el total. El esquema siguiente es ilustrativo; adapta los campos obligatorios y los formatos a tus datos y al subconjunto de esquemas que admita actualmente la API.

{
  "type": "object",
  "properties": {
    "merchant": { "type": "string" },
    "date": { "type": "string" },
    "currency": { "type": "string" },
    "total": { "type": "number" }
  },
  "required": ["merchant", "date", "currency", "total"],
  "additionalProperties": false
}

Configura la solicitud para utilizar un modo de salida con esquema JSON si el endpoint seleccionado lo admite. Céntrate en la extracción al redactar la instrucción y dile al modelo que represente la información no disponible según una política definida, en lugar de inventar un valor. Si se permiten campos ausentes, indícalo expresamente en el esquema y en el procesamiento posterior.

La salida restringida por esquema no sustituye a la validación. Analiza la respuesta como JSON, valida el resultado con el esquema en tu aplicación y aplica comprobaciones de dominio; por ejemplo, verifica que la fecha se pueda analizar y que el total no sea negativo. Rechaza o aísla los resultados no válidos, en lugar de convertirlos silenciosamente en registros fiables. Conserva el documento original solo si tu política de retención lo permite.

Redacta los registros sin perder capacidad de diagnóstico

Como norma general, evita registrar claves API, encabezados de autorización, instrucciones completas, respuestas completas del modelo o documentos originales. Los campos extraídos también pueden contener información personal o confidencial, por lo que registrar la respuesta JSON «correcta» podría crear igualmente un repositorio de datos sensibles.

Entre los datos de diagnóstico de menor riesgo que pueden resultar útiles se incluyen un ID de correlación de la solicitud, la marca de tiempo, el identificador del modelo, la categoría del resultado, si la validación se superó o falló y la latencia. Si necesitas ejemplos para depurar, utiliza datos sintéticos o entradas redactadas intencionadamente, y aplica controles de acceso y límites de retención. Asegúrate de que las excepciones no serialicen automáticamente los encabezados de solicitud ni los cuerpos de respuesta.

En la extracción estructurada, registra qué campo no superó la validación, no su valor sensible. Mantén el acceso a cualquier documento fuente conservado separado de los registros operativos y define quién puede consultarlo y durante cuánto tiempo se conserva.

Rota y revoca las credenciales de forma planificada

Redacta el procedimiento de rotación antes de que ocurra un incidente. Un procedimiento práctico debe especificar quién puede crear y desplegar una clave de sustitución, dónde se almacena, cómo se actualizan los servicios dependientes, cómo se verifica la nueva clave y cómo se revoca la anterior. Si es posible que la credencial haya quedado expuesta, prioriza la revocación y la contención en lugar de esperar al siguiente periodo de rotación programada.

Almacena las credenciales de larga duración en un gestor de secretos. La guía de OpenAI advierte que inyectar un secreto almacenado en un entorno sigue dejándolo expuesto al código generado por agentes. Para los entornos de sandbox alojados, describe el uso de secretos de vault mediante un proxy para los hosts aprobados; para los entornos autohospedados, recomienda un proxy o servidor de confianza que proporcione los secretos desde fuera del entorno. En el caso de las herramientas de funciones, conserva las credenciales en la aplicación que gestiona la llamada y devuelve únicamente el resultado.

Después de la rotación, comprueba que la aplicación use la nueva credencial y que la anterior ya no funcione. Revisa los registros de acceso y el historial de despliegues para detectar usos inesperados, y actualiza los registros del incidente si se sospechó una exposición. No copies claves en tickets ni chats mientras coordinas el cambio.

Fallos habituales y cómo responder

  • La salida es JSON válido, pero contiene un valor incorrecto: que el JSON sea válido confirma la estructura, no la exactitud de los datos. Añade comprobaciones de negocio por campo y una vía de revisión para las decisiones importantes.
  • Falta un campo obligatorio o tiene un formato incorrecto: trata el resultado como una extracción fallida; vuelve a intentarlo solo con una política limitada o envíalo a revisión.
  • Aparece una clave en un registro o en un sandbox: revócala, sustitúyela mediante el procedimiento documentado e investiga dónde quedó expuesta.
  • Una solicitud falla después de cambiar de proveedor o endpoint: comprueba la compatibilidad documentada del endpoint y de los parámetros de esquema. El acceso compatible con OpenAI no implica por sí solo que todas las funciones tengan el mismo soporte.

Lista breve de comprobación previa al lanzamiento

  • La clave de aplicación se mantiene fuera del código generado por agentes y de los entornos de sandbox.
  • Las credenciales están restringidas y, cuando sea práctico, separadas por carga de trabajo o propósito.
  • El acceso a la red está limitado a destinos aprobados.
  • Se han implementado las comprobaciones del esquema, el análisis y las reglas de negocio.
  • Los registros excluyen claves, documentos originales y valores extraídos innecesarios.
  • Hay una persona responsable de los pasos de rotación, verificación y revocación de emergencia.
  • Se ha confirmado la compatibilidad del proveedor y del endpoint con los parámetros de salida estructurada elegidos.

La seguridad de la extracción estructurada depende de todo el flujo, no solo del formato de respuesta: protege las credenciales, reduce al mínimo los datos que llegan a los registros y entornos, valida cada resultado y facilita la revocación.

FAQ

¿La validación con un esquema JSON garantiza que los datos extraídos sean correctos?

No. Un esquema puede restringir la estructura y los tipos de una respuesta, pero no puede confirmar que un valor coincida con el documento fuente. Analiza y valida la respuesta en tu aplicación, añade comprobaciones específicas del dominio e incorpora una revisión humana cuando las consecuencias lo justifiquen.

¿Debería estar disponible una clave API de OpenAI dentro de un sandbox de agente?

Evita exponer la clave de aplicación al código generado por agentes. La guía de seguridad de sandbox de OpenAI indica que ese código puede acceder a las credenciales disponibles en su entorno y recomienda mantener fuera de él la clave API de la aplicación. En su lugar, utiliza una capa de aplicación de confianza o un mecanismo adecuado de intermediación de credenciales.

¿Qué debería registrar un servicio de extracción?

Es preferible registrar metadatos operativos como un ID de correlación, la categoría del resultado y el estado de validación. Como norma general, no registres claves, encabezados de autorización, instrucciones completas, documentos originales ni registros extraídos completos.

¿Cuándo debería revocarse una clave en lugar de esperar a la rotación programada?

Revócala cuanto antes si sospechas que ha quedado expuesta; por ejemplo, si la encuentras en un registro, un archivo de código fuente, una imagen o un entorno accesible para código no confiable. Después, despliega una clave de sustitución mediante el proceso aprobado e investiga la exposición.

Artículos relacionados