collections_search y file_search en la API de Responses
En esta página
Integrar la búsqueda directamente en las conversaciones
El punto de conexión POST /v1/documents/search funciona bien para preguntas aisladas, pero te deja toda la labor de orquestación: formular la consulta, recuperar los extractos, inyectarlos en un prompt y llamar al modelo. La API de Responses invierte esta carga. Al declarar tus colecciones como una herramienta, permites que Grok decida cuándo buscar, qué buscar y cómo convertirlo en una respuesta. Pasas de gestionar un pipeline tú mismo a contar con un asistente que busca en tus documentos por sí solo.
La herramienta collections_search
Solo necesitas añadir un objeto a la lista tools para habilitar este acceso:
response = await client.responses.create(
model="grok-4.5",
input="¿Cuál es nuestra política de permiso de paternidad?",
tools=[
{
"type": "collections_search",
"collection_ids": ["col_rh_policies"]
}
]
)
Detrás de esta única llamada, Grok analiza la pregunta, formula una consulta de búsqueda adaptada a la colección, recupera los pasajes relevantes, los resume y cita los documentos utilizados. En la práctica, para la pregunta anterior, traducirá «permiso de paternidad» a una búsqueda en col_rh_policies, retendrá los párrafos del convenio de empresa y devolverá el número de días junto con su fuente, sin que tengas que escribir ni una línea de lógica de recuperación.
La herramienta file_search
Existe un equivalente para archivos individuales, aquellos que no están almacenados en una colección. No hace falta declararla: se activa automáticamente en cuanto tu solicitud contiene un input_file.
response = await client.responses.create(
model="grok-4.5",
input=[
{
"type": "input_file",
"file_id": "file_contrat_abc"
},
{
"type": "input_text",
"text": "¿Contiene este contrato una cláusula de no competencia?"
}
]
)
Es la herramienta attachment_search, equivalente a file_search, la que se activa en segundo plano. Este comportamiento implícito explica una confusión habitual: los usuarios se preguntan por qué declarar file_search en tools parece no tener efecto, cuando simplemente es redundante.
Dos mecanismos, dos estructuras de costes
| Aspecto | collections_search | file_search / attachment_search |
|---|---|---|
| Fuente | Colección(es) indexada(s) | Archivo(s) individual(es) |
| Declaración | Explícita en tools | Automática con input_file |
| Indexación | Precomputada | En tiempo real |
| Coste | 2,50 € / 1.000 | 10 € / 1.000 |
| Rendimiento | Rápido (índice existente) | Más lento (indexación en tiempo real) |
| Caso de uso | Base de conocimientos permanente | Análisis puntual |
La línea de «indexación» determina todas las demás. Una colección se indexa una única vez y para siempre, por lo que cada pregunta reutiliza ese trabajo: es rápido y se factura a 2,50 € por cada mil llamadas. Un archivo adjunto se indexa con cada solicitud, de ahí la latencia adicional y los 10 € por cada mil. El contrato que tu asesor jurídico analiza una vez entra en la segunda categoría; el repositorio de RR. HH. consultado cien veces al día pertenece claramente a la primera.
Combinar múltiples herramientas
La verdadera ventaja de este enfoque aparece cuando proporcionas a Grok varias de ellas, permitiéndole seleccionar las que sirvan a la pregunta.
response = await client.responses.create(
model="grok-4.5",
input="Compara nuestra política interna con la última normativa europea sobre el tema.",
tools=[
{
"type": "collections_search",
"collection_ids": ["col_politiques_internes"]
},
{
"type": "web_search"
}
]
)
Esta pregunta requiere dos movimientos sucesivos: Grok consulta primero la colección para encontrar tu política interna, luego lanza una búsqueda web para la normativa europea vigente y, finalmente, contrasta ambas en su respuesta. Sin orquestación por tu parte, sin ninguna sentencia if para decidir cuál de las dos fuentes es relevante; y si la pregunta se hubiera centrado únicamente en tu política interna, no se habría utilizado la web.
Refinar el comportamiento de la herramienta
Tres parámetros te permiten ajustar la búsqueda declarada en tools.
tools=[
{
"type": "collections_search",
"collection_ids": ["col_docs_1", "col_docs_2"],
"max_results": 10,
"retrieval_mode": "hybrid"
}
]
- collection_ids: consultar varias colecciones simultáneamente
- max_results: limitar el número de resultados para reducir el contexto inyectado
- retrieval_mode: elegir el modo de búsqueda (híbrido por defecto)
max_results merece una atención especial: cada extracto devuelto ocupa contexto y consume tokens. En un asistente de soporte donde las respuestas suelen caber en dos o tres pasajes, bajar del valor predeterminado a cinco resultados reduce el coste sin degradar la calidad percibida.
Precios a 5 de agosto de 2026: los precios cambian con regularidad; antes de calcular cualquier presupuesto, consulta la tarifa actual en la página oficial de modelos y precios de xAI.
Puntos clave
collections_searchpermite que Grok consulte automáticamente tus colecciones durante una conversaciónfile_search/attachment_searchse activa automáticamente para archivos individuales- Las colecciones son cuatro veces más baratas y rápidas que los archivos adjuntos
- Puedes combinar
collections_searchconweb_searchy otras herramientas - Grok elige automáticamente qué herramientas usar en función de la pregunta