Vai al contenuto principale
Italiano— Scegli una lingua
Menu

L'endpoint di ricerca documenti

Lezione 9 di 16 Aggiornata il 29 luglio 2026 Sviluppatore
In questa pagina
  1. Interrogare le tue basi di conoscenza
  2. Struttura della richiesta
  3. Leggere la risposta
  4. Cercare su più collezioni
  5. Costo
  6. Punti chiave

Interrogare le tue basi di conoscenza

Finora hai costruito il contenitore: collezioni, documenti indicizzati, metadati. Nulla di tutto ciò ha importanza se non sai come porre una domanda. È questo il compito di POST /v1/documents/search, che accetta una query in linguaggio naturale e restituisce i passaggi dei tuoi documenti che rispondono nel modo migliore. Immagina un team di supporto che riceve la domanda “Qual è il periodo di recesso?”. Invece di far leggere all’agente i termini e le condizioni, invii la domanda all’endpoint e recuperi i tre paragrafi utili, completi del loro punteggio e della fonte.

POST
/v1/documents/search
3 modalità
keyword, semantic, hybrid
$2.50
Per 1.000 chiamate
Multi
Collezioni multiple

Struttura della richiesta

La prima cosa da ricordare, e questa è una fonte comune di errori: questo endpoint risiede sull’API standard (api.x.ai), non sull’API di gestione che hai usato per creare le collezioni. Ti autentichi con la tua solita chiave API. La richiesta minima si riduce a tre campi.

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

Parametri principali

  • query: la tua domanda in linguaggio naturale. Più specifica è la domanda, più rilevanti saranno i risultati.
  • source.collection_ids: un array di ID collezione da interrogare. Puoi cercare su più collezioni in una singola richiesta.
  • retrieval_mode.type: la modalità di ricerca da utilizzare (keyword, semantic o hybrid).

Leggere la risposta

L’API non restituisce interi documenti ma frammenti, i chunk creati durante l’indicizzazione, classificati dal più al meno rilevante.

{
  "results": [
    {
      "content": "To configure OAuth, start by...",
      "score": 0.92,
      "document_id": "file_abc123",
      "metadata": {
        "filename": "security-guide.pdf",
        "page": 12
      }
    },
    {
      "content": "The OAuth 2.0 flow uses...",
      "score": 0.87,
      "document_id": "file_def456",
      "metadata": {
        "filename": "api-reference.pdf",
        "page": 45
      }
    }
  ]
}

Ogni voce contiene quattro informazioni:

  • content: l’estratto di testo dal documento.
  • score: un punteggio di rilevanza tra 0 e 1.
  • document_id: l’ID del file sorgente.
  • metadata: i metadati del documento (nome, pagina, campi personalizzati).

Nell’esempio sopra, il primo estratto proviene dalla pagina 12 di security-guide.pdf con un punteggio di 0,92, il secondo dalla pagina 45 di un altro file a 0,87. Questi due valori sono sufficienti per costruire un’interfaccia che mostri la risposta e, subito sotto, un link “visualizza passaggio originale, pagina 12”. Il punteggio funge da soglia: molti team scartano qualsiasi risultato inferiore a 0,5 invece di lasciare che il modello ragioni sul rumore.

Cercare su più collezioni

Se collection_ids è un array, non è un caso. Una domanda del cliente spesso mescola diversi universi documentali e non vuoi fare tre chiamate per poi unire i risultati a mano.

{
  "query": "Refund policy",
  "source": {
    "collection_ids": [
      "col_docs_produit",
      "col_faq",
      "col_conditions_generales"
    ]
  },
  "retrieval_mode": {
    "type": "hybrid"
  }
}

Qui vengono interrogate insieme la documentazione del prodotto, le FAQ e i termini e condizioni. I risultati tornano uniti e ordinati per punteggio, indipendentemente dalla collezione di origine: un estratto delle FAQ a 0,94 si classificherà sopra un estratto dei T&C a 0,71. Incroci fonti eterogenee in un singolo round-trip di rete.

Costo

La ricerca nelle collezioni costa $2,50 per 1.000 chiamate e questa tariffa non cambia in base al numero di collezioni interrogate o alla dimensione dei documenti indicizzati. Confrontalo con gli allegati di file, quei singoli file passati tramite input_file, fatturati a $10 per 1.000 chiamate: non appena interroghi ripetutamente gli stessi documenti, le collezioni costano quattro volte meno. Un assistente interno che gestisce 20.000 domande al mese paga $50 con le collezioni contro $200 con gli allegati, ottenendo per di più risultati più veloci, poiché l’indice esiste già.

Prezzi aggiornati al 5 agosto 2026 — i prezzi cambiano regolarmente: prima di qualsiasi calcolo di budget, controlla il listino prezzi attuale sulla pagina ufficiale dei modelli e dei prezzi xAI.

Punti chiave

  • L’endpoint POST /v1/documents/search interroga le tue collezioni in linguaggio naturale.
  • Tre modalità di ricerca disponibili: keyword, semantic, hybrid.
  • Puoi cercare su più collezioni simultaneamente.
  • I risultati sono classificati per punteggio di rilevanza con il contenuto sorgente.
  • Il costo è di $2,50 per 1.000 chiamate, quattro volte meno degli allegati di file.