File Search OpenAI API: busca información en tus propios archivos
File Search OpenAI API permite que modelos compatibles de OpenAI busquen información relevante dentro de tus propios documentos. Mediante vector stores, archivos procesados y búsqueda semántica, puedes crear asistentes y agentes capaces de responder utilizando conocimiento privado, documentación interna, manuales, políticas, PDFs y otras fuentes propias.
¿Qué es File Search OpenAI API?
File Search OpenAI API es una herramienta integrada de Responses API que permite buscar fragmentos relevantes dentro de archivos almacenados en un vector store. OpenAI procesa los archivos, los divide en fragmentos y permite que el modelo recupere únicamente la información relacionada con la consulta.
Qué permite hacer File Search OpenAI API
File Search convierte tus propios documentos en una fuente de conocimiento recuperable por el modelo.
Buscar en documentos
Recupera información relevante desde tus propios archivos.
Vector stores
Los archivos se organizan en almacenes preparados para búsqueda semántica.
Búsqueda semántica
No depende únicamente de coincidencias exactas de palabras.
RAG gestionado
Facilita aplicaciones de retrieval augmented generation sin construir toda la capa de recuperación.
Filtros
Los vector stores pueden utilizar atributos para filtrar resultados.
Respuestas fundamentadas
El modelo utiliza fragmentos recuperados como contexto para generar respuestas.
Cómo funciona File Search OpenAI API
El proceso combina archivos, vector stores, recuperación semántica y generación de respuestas.
Cargas los archivos
Incorporas documentos que contienen tu conocimiento.
Se indexan
Los archivos se procesan y quedan disponibles para recuperación.
El modelo busca
File Search recupera fragmentos relevantes para la consulta.
File Search OpenAI API utiliza vector stores
Un vector store agrupa archivos que pueden ser consultados posteriormente mediante búsqueda semántica.
Base de conocimiento para el modelo
Cuando adjuntas un archivo a un vector store, OpenAI lo procesa para que su contenido pueda recuperarse posteriormente mediante File Search.
El archivo debe alcanzar
el estado completed
antes de considerarse
listo para utilizarse
en búsquedas.
Cómo añadir un archivo a un vector store
El vector store necesita conocer qué archivos debe utilizar como fuente.
Adjuntar un archivo
POST /v1/vector_stores/{vector_store_id}/files
{
"file_id": "file_abc123"
}Para ingestión masiva, OpenAI recomienda utilizar file batches en lugar de realizar numerosas escrituras individuales.
Estados de un archivo dentro del vector store
Los archivos pasan por diferentes estados mientras se procesan.
| Estado | Significado |
|---|---|
in_progress |
El archivo todavía se está procesando |
completed |
El archivo está listo para utilizarse |
failed |
El procesamiento terminó con error |
cancelled |
El procesamiento fue cancelado |
Cómo utilizar File Search OpenAI API
Una vez preparado el vector store, puedes habilitar File Search en una respuesta.
Ejemplo conceptual
{
"model": "gpt-5.6-sol",
"tools": [
{
"type": "file_search",
"vector_store_ids": [
"vs_1234567890"
],
"max_num_results": 10
}
],
"input": "¿Cuál es la política de devoluciones?"
}La herramienta necesita conocer qué vector stores contienen la información que puede consultar.
max_num_results
File Search permite limitar cuántos resultados se recuperan para una consulta.
No recuperes más fragmentos de los necesarios
Reducir el número de resultados puede ayudar a limitar contexto, latencia y ruido cuando la búsqueda ya encuentra contenido relevante.
Cómo incluir los resultados de File Search
Responses API permite solicitar información adicional sobre los resultados recuperados por la herramienta.
file_search_call.results
{
"include": [
"file_search_call.results"
]
}Ver los resultados recuperados permite comprobar si el vector store está encontrando los fragmentos adecuados.
Buscar directamente dentro de un vector store
OpenAI también dispone de un endpoint específico para consultar un vector store sin pasar primero por la respuesta del modelo.
Search vector store
POST /v1/vector_stores/{vector_store_id}/search
{
"query": "política de devoluciones"
}Qué devuelve una búsqueda de vector store
Cada resultado contiene información que permite conocer su origen y relevancia.
| Campo | Descripción |
|---|---|
file_id |
Archivo del que procede el fragmento |
filename |
Nombre del archivo |
content |
Contenido recuperado |
score |
Puntuación de similitud del resultado |
attributes |
Metadatos asociados al archivo |
El score ayuda a evaluar los resultados
La búsqueda directa del vector store devuelve una puntuación de similitud para cada resultado.
Valor entre 0 y 1
OpenAI documenta
el campo score
como una puntuación
de similitud entre
cero y uno.
Un resultado puede tener buena similitud semántica y aun así no contener la evidencia necesaria para responder correctamente.
Filtrar archivos mediante atributos
Los archivos de un vector store pueden incluir atributos que posteriormente ayudan a restringir una búsqueda.
Metadatos consultables
Los atributos pueden representar información como categoría, año, región, departamento o tipo de documento.
En una base documental grande, puedes limitar una búsqueda a documentos de Recursos Humanos o a políticas de un año determinado.
Atributos disponibles en los archivos
OpenAI permite adjuntar pares clave-valor a los archivos dentro de un vector store.
| Elemento | Límite actual documentado |
|---|---|
| Atributos por archivo | Hasta 16 pares clave-valor |
| Longitud de la clave | Hasta 64 caracteres |
| Valores string | Hasta 512 caracteres |
| Tipos de valor | String, número o booleano |
Ranking y relevancia en File Search
La búsqueda directa del vector store también permite configurar opciones relacionadas con ranking.
Ajustar cómo se seleccionan resultados
Puedes utilizar las opciones disponibles para adaptar la recuperación al comportamiento que necesita tu aplicación.
Reescritura de consultas
La búsqueda directa del vector store dispone de una opción para reescribir consultas en lenguaje natural.
Optimizar la búsqueda
Activar la reescritura puede ayudar a transformar la consulta original antes de ejecutar la recuperación semántica.
Cómo se divide un archivo para buscarlo
File Search no necesita introducir el documento completo en cada consulta.
Fragmentos recuperables
Cuando un archivo entra en el vector store, se prepara en fragmentos que posteriormente pueden recuperarse según su relevancia.
Al adjuntar un archivo al vector store, la API contempla estrategias de chunking automáticas o configurables según las opciones disponibles.
Recuperar el contenido procesado de un archivo
La API también dispone de una operación para consultar el contenido parseado de un archivo dentro del vector store.
Contenido del archivo
GET /v1/vector_stores/{vector_store_id}/files/{file_id}/contentFile Search vs Web Search
Ambas herramientas recuperan información externa al modelo, pero desde fuentes completamente diferentes.
| Aspecto | File Search | Web Search |
|---|---|---|
| Fuente | Tus propios archivos | Información disponible en Internet |
| Conocimiento privado | Sí | No es su objetivo principal |
| Información reciente | Depende de tus documentos | Puede recuperar información web actual |
| Base documental | Vector store | Búsqueda web |
| Uso típico | Knowledge base interna | Investigación externa |
Un agente puede consultar documentación interna mediante File Search y posteriormente buscar información pública mediante Web Search.
Ver Web Search →File Search vs Function Calling
File Search recupera información, mientras Function Calling permite solicitar lógica y acciones de tu aplicación.
| Aspecto | File Search | Function Calling |
|---|---|---|
| Objetivo | Recuperar conocimiento | Ejecutar lógica externa |
| Fuente | Vector stores | Tu backend |
| Acciones | Principalmente lectura | Puede producir efectos reales |
| Ejemplo | Consultar un manual | Crear un pedido |
Un asistente puede primero buscar una política en File Search y después ejecutar una función dependiendo del resultado.
Ver Function Calling →File Search OpenAI API para sistemas RAG
File Search permite construir experiencias de retrieval augmented generation utilizando infraestructura administrada por OpenAI.
El usuario formula una pregunta.
El sistema recupera fragmentos relevantes.
Los fragmentos se incorporan al contexto.
El modelo genera una respuesta utilizando esa evidencia.
Casos de uso de File Search OpenAI API
La herramienta resulta útil siempre que una aplicación necesite responder utilizando documentación propia.
Soporte: manuales, FAQs y documentación técnica.
Empresas: políticas internas, procedimientos y normativas.
Educación: apuntes, materiales y documentos de cursos.
Legal: contratos, documentos y referencias para recuperación asistida.
Productos: catálogos, especificaciones y documentación.
Agentes: utilizar conocimiento privado dentro de workflows de varios pasos.
File Search para chatbots con conocimiento propio
Esta arquitectura resulta especialmente útil cuando un chatbot debe responder sobre información específica de una empresa.
El modelo no necesita memorizar tu documentación
La información se mantiene en los archivos y se recupera únicamente cuando la consulta la necesita.
File Search como herramienta de un agente
Un agente puede combinar distintas fuentes y capacidades dentro del mismo workflow.
Conocimiento privado
Consulta documentos propios de la organización.
Información pública
Recupera información reciente desde Internet.
Acciones
Ejecuta lógica proporcionada por tu aplicación.
Modelos actuales con soporte para File Search
OpenAI publica File Search entre las herramientas compatibles de sus principales modelos actuales.
| Modelo | File Search | Orientación |
|---|---|---|
| GPT-6 Astra | Compatible | Máxima capacidad |
| GPT-5.6 Sol | Compatible | Trabajo profesional complejo |
| GPT-5.6 Terra | Compatible | Equilibrio capacidad/costo |
| GPT-5.6 Luna | Compatible | Alto volumen y bajo costo |
Puedes seleccionar el modelo de acuerdo con la complejidad, volumen y presupuesto de tu aplicación.
Comparar modelos →Precio de File Search OpenAI API
El costo de File Search no se limita a los tokens utilizados por el modelo.
| Concepto | Tarifa publicada |
|---|---|
| Vector store storage | US$0,10 por GB / día |
| Primer GB | Gratis |
| File Search tool calls | US$2,50 por 1.000 llamadas |
El almacenamiento se calcula sobre el tamaño resultante del vector store después de que el archivo es procesado, dividido en chunks y convertido en representaciones para recuperación.
Una respuesta con File Search sigue utilizando tokens del modelo seleccionado.
Ver precios OpenAI API →Monitorizar llamadas de File Search
OpenAI dispone de métricas específicas para analizar el uso de File Search dentro de una organización.
Analiza el consumo por vector store
Las métricas pueden agruparse por elementos como proyecto, usuario, API key o vector store.
Buenas prácticas con documentos privados
File Search puede trabajar con información interna, por lo que la arquitectura debe considerar control de acceso y separación de datos.
Separa información por proyectos cuando corresponda.
No mezcles documentos de clientes diferentes sin controles adecuados.
Utiliza filtros y atributos para limitar búsquedas.
Controla qué usuarios pueden consultar cada base documental.
Elimina archivos que ya no deberían formar parte del conocimiento.
Cómo mejorar los resultados de File Search
La calidad de recuperación depende tanto de los documentos como de la forma en que se organizan.
Mantén los documentos actualizados.
Evita duplicados innecesarios.
Añade atributos útiles para filtros.
Revisa los resultados
mediante
file_search_call.results.
Ajusta
max_num_results
según la tarea.
Evalúa búsqueda, no solamente la respuesta final.
Documentación oficial de File Search OpenAI API
La plataforma y sus parámetros pueden evolucionar, por lo que la referencia oficial debe considerarse la fuente final para una implementación.
File Search y Vector Stores
Consulta la referencia de Responses API, vector stores, archivos, búsquedas y filtros.
Consultar Responses API →Guías relacionadas con File Search OpenAI API
Continúa explorando herramientas y capacidades de Responses API.
FAQ sobre File Search OpenAI API
Respuestas sobre vector stores, archivos, búsqueda, precios y Responses API.
Es una herramienta de Responses API que permite recuperar contenido relevante desde archivos almacenados en vector stores.
Es un recurso que contiene archivos preparados para búsqueda y recuperación semántica.
Sí. File Search es una herramienta integrada disponible mediante Responses API para modelos compatibles.
Primero debes disponer de un archivo en la API y posteriormente adjuntarlo a un vector store para que pueda procesarse y utilizarse en búsquedas.
Permite limitar la cantidad de resultados que File Search recupera para una consulta.
Sí. Los archivos pueden incorporar atributos y la búsqueda del vector store permite utilizar filtros compatibles.
No. File Search trabaja con archivos propios, mientras Web Search recupera información desde Internet.
OpenAI publica actualmente US$0,10 por GB de almacenamiento de vector store al día, con el primer GB gratuito, además de US$2,50 por cada 1.000 llamadas de File Search.
Sí. OpenAI publica File Search entre las herramientas compatibles de GPT-5.6 Sol, Terra y Luna.
Sí. Permite recuperar información relevante desde una base documental y proporcionarla al modelo como contexto para generar una respuesta.
Continúa con MCP en OpenAI API
Ya sabes cómo conectar los modelos con tus documentos. El siguiente paso es aprender cómo integrarlos con herramientas y sistemas externos mediante MCP.
Ver MCP en OpenAI API →