File API

Gestión de archivos

La File API de OpenAI actúa como un sistema de almacenamiento centralizado que permite subir y gestionar documentos para ser utilizados por diversos servicios de la plataforma, como el Fine-tuning, la Batch API o los Asistentes.

En lugar de enviar el contenido de los archivos en cada solicitud, esta API permite referenciarlos mediante un identificador único, optimizando el ancho de banda y facilitando la reutilización de recursos.

Los archivos subidos se almacenan de forma segura y están sujetos a políticas de retención específicas según su propósito. Por ejemplo, los archivos pueden tener un tamaño máximo de 512 MB cada uno, y cada organización dispone de un límite de almacenamiento total (actualmente hasta 100 GB o más según el plan). Es fundamental asignar correctamente el propósito del archivo al momento de subirlo, ya que esto determina qué modelos o herramientas podrán acceder a él.

Subida de archivos y propósitos

Para cargar un archivo en la plataforma, utilizamos el método files.create. Este método requiere dos argumentos principales: el archivo en sí (abierto en modo binario) y el purpose (propósito). El propósito valida el formato del archivo y habilita su uso en endpoints específicos.

Los propósitos más comunes incluyen:

• assistants: Para archivos que serán utilizados por Asistentes (Code Interpreter o File Search).
• fine-tune: Para conjuntos de datos de entrenamiento en formato JSONL.
• batch: Para archivos de solicitudes por lotes (Batch API).
• vision: Para imágenes que serán procesadas por modelos de visión.

A continuación, un ejemplo de cómo subir un archivo:

from openai import OpenAI
client = OpenAI()

# Subir un archivo
archivo = client.files.create(
  file=open("mi-archivo.pdf", "rb"),
  purpose="assistants"
)

print(f"Archivo subido con ID: {archivo.id}")

Listado y recuperación de metadatos

Una vez subidos, es posible consultar el inventario de archivos disponibles mediante files.list. Esto devuelve una lista de objetos FileObject que contienen metadatos como el nombre, tamaño, fecha de creación y propósito. Esta operación es útil para verificar subidas o gestionar limpiezas periódicas.

Para inspeccionar un archivo concreto sin descargar su contenido, utilizamos files.retrieve pasando su ID de archivo. Esto permite confirmar, por ejemplo, si un archivo ha terminado de procesarse o verificar su tamaño.

• Listar todos los archivos:

files = client.files.list()

for f in files.data:
    print(f"ID: {f.id}, Nombre: {f.filename}, Propósito: {f.purpose}")

• Recuperar metadatos de un archivo específico:

file_id = "file-XyZ123..."
archivo_info = client.files.retrieve(file_id)

print(f"Tamaño: {archivo_info.bytes} bytes")

Descarga de contenido y eliminación

La API permite descargar el contenido de los archivos generados por el sistema o subidos por el usuario mediante files.content. Sin embargo, existe una restricción de seguridad importante: no es posible descargar el contenido de archivos subidos con el propósito assistants (ni de archivos originales ni de adjuntos), para proteger la privacidad de los datos procesados por los asistentes.

Solo se permite la descarga de archivos con propósitos como fine-tune, batch.

Para mantener la higiene del almacenamiento y evitar alcanzar los límites de cuota, es recomendable eliminar los archivos que ya no son necesarios utilizando el método files.delete.

• Descargar el contenido de un archivo (si el propósito lo permite):

# Solo funciona para propósitos permitidos (ej. fine-tune-results)
content = client.files.content("file-RESULTADOS...")

# Guardar el contenido en disco
with open("resultados.jsonl", "wb") as f:
    f.write(content.read())

• Eliminar un archivo del sistema:

deleted_file = client.files.delete("file-XyZ123...")

if deleted_file.deleted:
    print("El archivo ha sido eliminado correctamente.")