Búsqueda de archivos: indexar y consultar documentos
En esta página
- Búsqueda de archivos: indexar y consultar documentos
- Crear un almacén vectorial
- Subir e indexar archivos
- Consultar con la búsqueda de archivos
- Examinar los resultados de la búsqueda
- Configurar la búsqueda
- Gestionar el ciclo de vida del almacén vectorial
- Ejemplo completo: asistente de documentación
- 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_resultscontrola 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