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

El extremo de búsqueda de documentos

Lección 9 de 16 Actualizado el 29 de julio de 2026 Desarrollador
En esta página
  1. Consultar tus bases de conocimiento
  2. Estructura de la solicitud
  3. Leer la respuesta
  4. Buscar en varias colecciones
  5. Coste
  6. Puntos clave

Consultar tus bases de conocimiento

Hasta ahora has construido el contenedor: colecciones, documentos indexados y metadatos. Nada de esto sirve de nada si no sabes cómo formular una pregunta. Esa es la función de POST /v1/documents/search, que toma una consulta en lenguaje natural y devuelve los pasajes de tus documentos que mejor la responden. Imagina un equipo de soporte que recibe la pregunta «¿Cuál es el plazo de desistimiento?». En lugar de hacer que un agente lea los términos y condiciones, envías la pregunta al extremo y recuperas los tres párrafos útiles, completos con su puntuación y su fuente.

POST
/v1/documents/search
3 modos
palabra clave, semántico, híbrido
2,50 $
Por cada 1.000 llamadas
Múltiple
Varias colecciones

Estructura de la solicitud

Lo primero que debes recordar, y esto es una fuente común de errores: este extremo reside en la API estándar (api.x.ai), no en la API de gestión que utilizaste para crear las colecciones. Te autenticas con tu clave de API habitual. La solicitud mínima se reduce a tres campos.

curl -X POST https://api.x.ai/v1/documents/search \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "¿Cómo configuro la autenticación OAuth?",
    "source": {
      "collection_ids": ["col_xyz789"]
    },
    "retrieval_mode": {
      "type": "hybrid"
    }
  }'

Parámetros principales

  • query: tu pregunta en lenguaje natural. Cuanto más específica sea la pregunta, más relevantes serán los resultados.
  • source.collection_ids: un array de ID de colecciones que consultar. Puedes buscar en varias colecciones en una única solicitud.
  • retrieval_mode.type: el modo de búsqueda que deseas utilizar (keyword, semantic o hybrid).

Leer la respuesta

La API no devuelve documentos enteros, sino fragmentos: los trozos creados durante la indexación, ordenados de mayor a menor relevancia.

{
  "results": [
    {
      "content": "Para configurar OAuth, comienza por...",
      "score": 0.92,
      "document_id": "file_abc123",
      "metadata": {
        "filename": "security-guide.pdf",
        "page": 12
      }
    },
    {
      "content": "El flujo OAuth 2.0 utiliza...",
      "score": 0.87,
      "document_id": "file_def456",
      "metadata": {
        "filename": "api-reference.pdf",
        "page": 45
      }
    }
  ]
}

Cada entrada contiene cuatro piezas de información:

  • content: el extracto de texto del documento.
  • score: una puntuación de relevancia entre 0 y 1.
  • document_id: el ID del archivo fuente.
  • metadata: los metadatos del documento (nombre, página, campos personalizados).

En el ejemplo anterior, el primer extracto proviene de la página 12 de security-guide.pdf con una puntuación de 0,92; el segundo, de la página 45 de otro archivo con 0,87. Estos dos valores son suficientes para construir una interfaz que muestre la respuesta y, justo debajo, un enlace «ver pasaje original, página 12». La puntuación actúa como umbral: muchos equipos descartan cualquier resultado por debajo de 0,5 en lugar de dejar que el modelo razone sobre ruido.

Buscar en varias colecciones

Si collection_ids es un array, no es casualidad. Una pregunta de un cliente a menudo mezcla varios universos documentales, y no querrás hacer tres llamadas para luego fusionar los resultados a mano.

{
  "query": "Política de reembolsos",
  "source": {
    "collection_ids": [
      "col_docs_produit",
      "col_faq",
      "col_conditions_generales"
    ]
  },
  "retrieval_mode": {
    "type": "hybrid"
  }
}

Aquí se consultan conjuntamente la documentación del producto, las preguntas frecuentes y los términos y condiciones. Los resultados vuelven fusionados y ordenados por puntuación, independientemente de su colección original: un extracto de las preguntas frecuentes con 0,94 se situará por encima de uno de los términos y condiciones con 0,71. Cruzas fuentes heterogéneas en una única ida y vuelta de red.

Coste

Buscar en colecciones cuesta 2,50 $ por cada 1.000 llamadas, y esta tarifa no cambia según el número de colecciones consultadas ni el tamaño de los documentos indexados. Compáralo con los archivos adjuntos, esos archivos individuales pasados mediante input_file, facturados a 10 $ por cada 1.000 llamadas: en cuanto consultas los mismos documentos repetidamente, las colecciones cuestan cuatro veces menos. Un asistente interno que gestione 20.000 preguntas al mes pagará 50 $ con colecciones frente a 200 $ con archivos adjuntos, y obtendrá resultados más rápidos de paso, ya que el índice ya existe.

Precios vigentes a 5 de agosto de 2026: los precios cambian con regularidad; antes de cualquier cálculo presupuestario, consulta la tarifa actual en la página oficial de modelos y precios de xAI.

Puntos clave

  • El extremo POST /v1/documents/search consulta tus colecciones en lenguaje natural.
  • Tres modos de búsqueda disponibles: palabra clave, semántico e híbrido.
  • Puedes buscar en varias colecciones simultáneamente.
  • Los resultados se ordenan por puntuación de relevancia con el contenido de origen.
  • El coste es de 2,50 $ por cada 1.000 llamadas, cuatro veces más barato que los archivos adjuntos.