L'endpoint de recherche de documents

Interroger vos bases de connaissances

Vous avez cree des collections et y avez ajoute des documents. L’etape suivante est la recherche. L’endpoint POST /v1/documents/search vous permet d’interroger vos collections avec des requetes en langage naturel et de recuperer les passages les plus pertinents.

Structure de la requete

L’endpoint utilise l’API standard (api.x.ai), pas la Management API. Voici la structure de base :

curl -X POST https://api.x.ai/v1/documents/search \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Comment configurer l'\''authentification OAuth ?",
    "source": {
      "collection_ids": ["col_xyz789"]
    },
    "retrieval_mode": {
      "type": "hybrid"
    }
  }'

Parametres principaux

• query : votre question en langage naturel. Plus la question est specifique, plus les resultats seront pertinents
• source.collection_ids : un tableau d’identifiants de collections a interroger. Vous pouvez chercher dans plusieurs collections en une seule requete
• retrieval_mode.type : le mode de recherche a utiliser (keyword, semantic ou hybrid)

La reponse

L’API retourne une liste de fragments (chunks) classes par pertinence :

{
  "results": [
    {
      "content": "Pour configurer OAuth, commencez par...",
      "score": 0.92,
      "document_id": "file_abc123",
      "metadata": {
        "filename": "guide-securite.pdf",
        "page": 12
      }
    },
    {
      "content": "Le flux OAuth 2.0 utilise...",
      "score": 0.87,
      "document_id": "file_def456",
      "metadata": {
        "filename": "reference-api.pdf",
        "page": 45
      }
    }
  ]
}

Chaque resultat contient :

• content : l’extrait textuel du document
• score : un score de pertinence entre 0 et 1
• document_id : l’identifiant du fichier source
• metadata : les metadonnees du document (nom, page, champs personnalises)

Chercher dans plusieurs collections

L’avantage du parametre collection_ids en tableau est de pouvoir interroger plusieurs bases simultanement :

{
  "query": "Politique de remboursement",
  "source": {
    "collection_ids": [
      "col_docs_produit",
      "col_faq",
      "col_conditions_generales"
    ]
  },
  "retrieval_mode": {
    "type": "hybrid"
  }
}

Les resultats sont fusionnes et tries par score de pertinence, quelle que soit la collection d’origine. Cela vous permet de croiser des sources heterogenes dans une seule recherche.

Cout de la recherche

La recherche dans les collections est facturee a $2.50 par 1 000 appels. Ce tarif est identique quel que soit le nombre de collections interrogees ou la taille des documents.

Comparativement, les file attachments (fichiers individuels via input_file) coutent $10 par 1 000 appels. La recherche dans les collections est donc quatre fois moins chere pour des requetes repetees sur les memes documents.

Points cles a retenir

• L’endpoint POST /v1/documents/search interroge vos collections en langage naturel
• Trois modes de recherche disponibles : keyword, semantic, hybrid
• Vous pouvez chercher dans plusieurs collections simultanement
• Les resultats sont classes par score de pertinence avec le contenu source
• Le cout est de $2.50 par 1 000 appels, quatre fois moins cher que les file attachments