Ir al contenido principal
Español— Elegir un idioma
Menú

Búsqueda de archivos: indexar y consultar documentos

Lección 7 de 20 Desarrollador
En esta página
  1. Búsqueda de archivos: indexar y consultar documentos
  2. Crear un almacén vectorial
  3. Subir e indexar archivos
  4. Consultar con la búsqueda de archivos
  5. Examinar los resultados de la búsqueda
  6. Configurar la búsqueda
  7. Gestionar el ciclo de vida del almacén vectorial
  8. Ejemplo completo: asistente de documentación
  9. Puntos clave

Búsqueda de archivos: indexar y consultar documentos

La búsqueda de archivos permite al modelo examinar tus documentos privados. Subes los archivos a un almacén vectorial y el modelo los consulta automáticamente siempre que necesite información específica. Esta es la base de la generación aumentada por recuperación (RAG) integrada directamente en la API de OpenAI.

Crear un almacén vectorial

El almacén vectorial es la unidad organizativa de la búsqueda de archivos, y la estructura que elijas aquí te acompañará durante mucho tiempo. Un único almacén para toda la empresa es fácil de administrar, pero mezcla documentos con vocabularios no relacionados, lo que degrada la relevancia. Separar los almacenes por equipo o dominio requiere un poco más de gestión, pero hace que cada búsqueda sea significativamente más precisa. En caso de duda, sepáralos: fusionarlos más tarde es más fácil que desenredar un caos.

from openai import OpenAI

client = OpenAI()

# Crear el almacén vectorial
vector_store = client.vector_stores.create(
    name="product-documentation"
)
print(f"Almacén vectorial creado: {vector_store.id}")

Subir e indexar archivos

La indexación es asíncrona, y esta es la fuente de errores más común en el primer intento: añades archivos, consultas inmediatamente y el modelo dice que no ha encontrado nada; no porque la búsqueda haya fallado, sino porque aún no se ha indexado nada. Comprueba siempre el estado antes de consultar, como se muestra en la sección sobre el ciclo de vida.

Una nota sobre los formatos: la lista es amplia, pero no todos los archivos son iguales. Un PDF generado desde un procesador de textos se extrae limpiamente; un PDF escaneado sin capa de texto no aporta nada, ya que literalmente no hay palabras que indexar.

import os

# Subir un único archivo
with open("user-guide.pdf", "rb") as f:
    file_obj = client.files.create(file=f, purpose="assistants")

# Adjuntar al almacén vectorial
client.vector_stores.files.create(
    vector_store_id=vector_store.id,
    file_id=file_obj.id
)

# Subida por lotes
folder = "./documentation/"
for filename in os.listdir(folder):
    path = os.path.join(folder, filename)
    if os.path.isfile(path):
        with open(path, "rb") as f:
            file_obj = client.files.create(file=f, purpose="assistants")
        client.vector_stores.files.create(
            vector_store_id=vector_store.id,
            file_id=file_obj.id
        )
        print(f"Indexado: {filename}")

Consultar con la búsqueda de archivos

La llamada es intencionadamente sencilla: declaras la herramienta, haces tu pregunta y el modelo decide si debe buscar. Todo el trabajo de RAG (fragmentación, vectorización, clasificación e inyección en el contexto) ocurre en el servidor. Esto ahorra un tiempo considerable en el arranque, y la siguiente lección cubre la configuración que necesitas conocer cuando los valores predeterminados no son suficientes.

response = client.responses.create(
    model="gpt-5.6-terra",
    input="What is the refund procedure for premium clients?",
    tools=[{
        "type": "file_search",
        "vector_store_ids": [vector_store.id]
    }]
)

print(response.output_text)

El modelo busca automáticamente en tus documentos y formula una respuesta basada en el contenido que encuentra.

Examinar los resultados de la búsqueda

Las anotaciones son lo que distingue una respuesta verificable de una mera afirmación. Muéstralas a tus usuarios: en una base de conocimientos interna, la capacidad de rastrear hasta el documento original cambia completamente el nivel de confianza en el sistema y te ayuda a detectar casos en los que el modelo se ha equivocado.

response = client.responses.create(
    model="gpt-5.6-terra",
    input="What SLAs are guaranteed in the contract?",
    tools=[{
        "type": "file_search",
        "vector_store_ids": [vector_store.id]
    }]
)

# Iterar sobre las anotaciones
for item in response.output:
    if item.type == "message":
        for block in item.content:
            if hasattr(block, "annotations"):
                for ann in block.annotations:
                    if ann.type == "file_citation":
                        print(f"Archivo: {ann.file_id}")
                        print(f"Posición: {ann.start_index}-{ann.end_index}")

Configurar la búsqueda

Número de resultados

Aumentar el número de pasajes no mejora mecánicamente la respuesta. Más allá de unos diez, los extractos poco relevantes diluyen los buenos y consumen contexto facturable. Eleva este valor solo cuando la respuesta sea visiblemente incompleta, no como principio general.

response = client.responses.create(
    model="gpt-5.6-terra",
    input="List all penalty clauses in the contract",
    tools=[{
        "type": "file_search",
        "vector_store_ids": [vector_store.id],
        "max_num_results": 20  # Predeterminado: 5, máximo: 50
    }]
)

Filtrado por metadatos

Los metadatos son la palanca más infrautilizada para lograr precisión. Filtrar por año, departamento o tipo de documento antes de la búsqueda vectorial elimina el ruido de antemano que, de otro modo, tendría que filtrar la clasificación. Esto también te permite responder «según el procedimiento actual» en lugar de mezclar tres versiones sucesivas del mismo documento.

# Subir con metadatos
with open("contract-2026.pdf", "rb") as f:
    file_obj = client.files.create(file=f, purpose="assistants")

client.vector_stores.files.create(
    vector_store_id=vector_store.id,
    file_id=file_obj.id,
    attributes={
        "doc_type": "contract",
        "year": 2026,
        "client": "acme-corp"
    }
)

# Búsqueda filtrada
response = client.responses.create(
    model="gpt-5.6-terra",
    input="What is the due date?",
    tools=[{
        "type": "file_search",
        "vector_store_ids": [vector_store.id],
        "filters": {
            "type": "eq",
            "key": "doc_type",
            "value": "contract"
        }
    }]
)

Filtros compuestos

Combina múltiples criterios utilizando operadores lógicos:

response = client.responses.create(
    model="gpt-5.6-terra",
    input="Summarize contractual obligations for 2026",
    tools=[{
        "type": "file_search",
        "vector_store_ids": [vector_store.id],
        "filters": {
            "type": "and",
            "filters": [
                {"type": "eq", "key": "doc_type", "value": "contract"},
                {"type": "gte", "key": "year", "value": 2026}
            ]
        }
    }]
)

Gestionar el ciclo de vida del almacén vectorial

Supervisar la indexación

# Comprobar el estado del almacén vectorial
vs = client.vector_stores.retrieve(vector_store.id)
print(f"Estado: {vs.status}")
print(f"Archivos: {vs.file_counts.completed} indexados, "
      f"{vs.file_counts.in_progress} en curso, "
      f"{vs.file_counts.failed} fallidos")

Eliminar archivos obsoletos

# Listar archivos en el almacén vectorial
files = client.vector_stores.files.list(vector_store.id)
for f in files.data:
    print(f"{f.id} - {f.status}")

# Desadjuntar un archivo
client.vector_stores.files.delete(
    vector_store_id=vector_store.id,
    file_id="file_abc123"
)

Ejemplo completo: asistente de documentación

def documentation_assistant(question: str, vs_id: str) -> dict:
    """Asistente que responde basándose en la documentación interna."""
    response = client.responses.create(
        model="gpt-5.6-terra",
        instructions=(
            "Eres un asistente de documentación. Responde únicamente basándote en los "
            "documentos proporcionados. Si la información no está en los documentos, "
            "indícalo claramente. Cita tus fuentes."
        ),
        input=question,
        tools=[{
            "type": "file_search",
            "vector_store_ids": [vs_id],
            "max_num_results": 10
        }]
    )

    return {
        "answer": response.output_text,
        "model": response.model,
        "tokens": response.usage.total_tokens
    }

Puntos clave

  • Crea un almacén vectorial y sube tus archivos para habilitar la búsqueda de archivos
  • El modelo decide por sí mismo cuándo buscar en los documentos
  • max_num_results controla la profundidad de la búsqueda
  • Los metadatos y los filtros permiten búsquedas dirigidas
  • Supervisa el estado de la indexación antes de consultar