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

collections_search y file_search en la API de Responses

Lección 11 de 16 Actualizado el 29 de julio de 2026 Desarrollador
En esta página
  1. Integrar la búsqueda directamente en las conversaciones
  2. La herramienta collections_search
  3. La herramienta file_search
  4. Dos mecanismos, dos estructuras de costes
  5. Combinar múltiples herramientas
  6. Refinar el comportamiento de la herramienta
  7. Puntos clave

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.

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.

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

Aspectocollections_searchfile_search / attachment_search
FuenteColección(es) indexada(s)Archivo(s) individual(es)
DeclaraciónExplícita en toolsAutomática con input_file
IndexaciónPrecomputadaEn tiempo real
Coste2,50 € / 1.00010 € / 1.000
RendimientoRápido (índice existente)Más lento (indexación en tiempo real)
Caso de usoBase de conocimientos permanenteAná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_search permite que Grok consulte automáticamente tus colecciones durante una conversación
  • file_search / attachment_search se activa automáticamente para archivos individuales
  • Las colecciones son cuatro veces más baratas y rápidas que los archivos adjuntos
  • Puedes combinar collections_search con web_search y otras herramientas
  • Grok elige automáticamente qué herramientas usar en función de la pregunta