Method: projects.locations.dataStores.documents.search

Cerca nei documenti di un singolo datastore.

Restituisce segmenti di sottodocumenti classificati, ognuno dei quali fa riferimento al documento da cui proviene e contiene la provenienza necessaria per citarlo.

Richiesta HTTP

POST https://vectorsearch.googleapis.com/v1beta/{parent}/documents:search

Parametri di percorso

Parametri
parent

string

Obbligatorio. Il datastore in cui eseguire la ricerca. Formato: projects/{project}/locations/{location}/dataStores/{dataStore}

Corpo della richiesta

Il corpo della richiesta contiene dati con la seguente struttura:

Rappresentazione JSON 
{
  "topK": integer,
  "documentIds": [
    string
  ],
  "rankingSpec": {
    object (RankingSpec)
  },
  "filter": {
    object
  },
  "outputFields": {
    object (OutputFields)
  },

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "textQuery": {
    object (TextQuery)
  }
  // End of mutually exclusive fields.
}
Campi
topK

integer

Facoltativo. Numero di risultati da restituire. Il valore predefinito è 10. I valori superiori a 100 vengono forzati a 100.
documentIds[]

string

Facoltativo. Limita la ricerca a questi ID documento. Max 100. Se il campo è vuoto, viene eseguita la ricerca nell'intero datastore.
rankingSpec

object (RankingSpec)

Facoltativo. Controlla il modo in cui vengono classificati i risultati.
filter

object (Struct format)

Facoltativo. Limita la ricerca ai segmenti che corrispondono a questo filtro, un oggetto JSON sui percorsi dei campi di un DocumentSearchResult:

  • metadata.<property>: una proprietà dichiarata nel documentMetadataSchema di DataStore, ad esempio metadata.category.
  • unstructured_details.page_range.start_page e .end_page: per un datastore UNSTRUCTURED. Non tutti i segmenti hanno un intervallo di pagine; consulta UnstructuredSegmentDetails.page_range.
  • video_details.start_offset e .end_offset: in secondi, per un datastore VIDEO.

Confronti: $eq, $ne, $lt, $lte, $gt, $gte, $in, $nin, $all e $exists. Combinali con $and, $or e $not, nidificati al massimo su due livelli. Ad esempio:

{"$and": [{"metadata.year": {"$gte": 2025}}, {"unstructured_details.page_range.start_page": {"$lte": 20}}]}
outputFields

object (OutputFields)

Facoltativo. Campi da restituire per ogni risultato.
Obbligatorio. La query da cercare. Deve essere impostato esattamente un tipo di query. Di seguito è riportato un elenco di campi che si escludono a vicenda. In una risposta verrà impostato al massimo uno dei campi:
textQuery

object (TextQuery)

Una query di testo.
Fine dei campi che si escludono a vicenda.

Corpo della risposta

Messaggio di risposta per DocumentSearchService.SearchDocuments.

In caso di esito positivo, il corpo della risposta contiene dati con la seguente struttura:

Rappresentazione JSON 
{
  "results": [
    {
      object (DocumentSearchResult)
    }
  ],
  "warnings": [
    {
      object (Status)
    }
  ]
}
Campi
results[]

object (DocumentSearchResult)

Solo output. I segmenti di documento corrispondenti ai criteri di ricerca, ordinati per pertinenza.
warnings[]

object (Status)

Solo output. Avvisi o errori non irreversibili che si sono verificati durante l'esecuzione.

Ambiti di autorizzazione

Richiede uno dei seguenti ambiti OAuth:

  • https://www.googleapis.com/auth/cloud-platform
  • https://www.googleapis.com/auth/vectorsearch
  • https://www.googleapis.com/auth/vectorsearch.readonly

Per saperne di più, consulta la Authentication Overview.

TextQuery

Una query di testo.

Rappresentazione JSON 
{
  "text": string
}
Campi
text

string

Obbligatorio. Il testo da cercare.

RankingSpec

Controlla il modo in cui vengono classificati i risultati.

Rappresentazione JSON 
{
  "rerankingSpec": {
    object (RerankingSpec)
  }
}
Campi
rerankingSpec

object (RerankingSpec)

Facoltativo. Controlla la fase di riassegnazione del ranking.

RerankingSpec

Configurazione per il reranking semantico applicato ai risultati candidati dopo il recupero ibrido e il Reciprocal Rank Fusion (RRF).

Rappresentazione JSON 
{
  "enabled": boolean,
  "rankOversamplingFactor": integer
}
Campi
enabled

boolean

Facoltativo. Indica se riordinare i risultati uniti. Il valore predefinito è false: i risultati vengono restituiti nell'ordine di fusione RRF, a meno che il chiamante non attivi l'opzione.

Se abilitato, il reranking utilizza semantic-ranker-fast@latest sul servizio Vertex Ranking e richiede l'abilitazione dell'API Discovery Engine nel progetto del chiamante.

Non supportato per un datastore VIDEO: una richiesta che lo abilita non va a buon fine con INVALID_ARGUMENT.
rankOversamplingFactor

integer

Facoltativo. Il fattore di sovracampionamento dei candidati prima del nuovo ranking. Il numero totale di candidati recuperati per il reranking è min(rankOversamplingFactor * topK, 200). Dopo il reranking, i risultati vengono ridotti a SearchDocumentsRequest.top_k.

Ignorato a meno che enabled non sia true. Se l'opzione è abilitata, il valore predefinito è 5 (recupero di min(5 * topK, 200) candidati, con un massimo di 200).

Per riordinare senza oversampling, imposta questo campo su 1.

OutputFields

Campi da restituire per ogni DocumentSearchResult, oltre a quelli presenti in ogni risultato.

Rappresentazione JSON 
{
  "metadata": [
    string
  ]
}
Campi
metadata[]

string

Facoltativo. Proprietà dei metadati da restituire in DocumentSearchResult.document.metadata, denominate come dichiarato in documentMetadataSchema del datastore. Una proprietà nidificata è denominata in base al percorso con punti, ad esempio address.city, senza il prefisso metadata. utilizzato da filter. "*" restituisce ogni proprietà dichiarata. Se non è impostato, non restituisce alcun valore. Una proprietà per la quale il documento non ha un valore viene omessa.

DocumentSearchResult

Un singolo segmento corrispondente di un documento.

Rappresentazione JSON 
{
  "document": {
    object (Document)
  },

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "videoDetails": {
    object (VideoSegmentDetails)
  },
  "unstructuredDetails": {
    object (UnstructuredSegmentDetails)
  }
  // End of mutually exclusive fields.
}
Campi
document

object (Document)

Solo output. Il documento da cui proviene questo segmento, incluso il nome della risorsa e la località di Cloud Storage da cui è stato importato.

Tieni presente che non tutti i campi del documento sono compilati. Per il documento completo, chiama documents.get sul nome del documento restituito.
Dettagli sulla posizione del segmento all'interno del documento. Il campo impostato segue il campo document_type del datastore principale. Di seguito è riportato un elenco di campi che si escludono a vicenda. In una risposta verrà impostato al massimo uno dei campi:
videoDetails

object (VideoSegmentDetails)

Impostato quando il valore documentType del datastore principale è VIDEO.
unstructuredDetails

object (UnstructuredSegmentDetails)

Impostato quando il valore documentType del datastore principale è UNSTRUCTURED.
Fine dei campi che si escludono a vicenda.

VideoSegmentDetails

Individua un segmento all'interno di un documento video.

Rappresentazione JSON 
{
  "startOffset": string,
  "endOffset": string
}
Campi
startOffset

string (Duration format)

Solo output. Dove inizia questo segmento, rispetto all'inizio del video di origine.

Una durata in secondi con un massimo di nove cifre frazionarie, che termina con "s". Esempio: "3.5s".
endOffset

string (Duration format)

Solo output. Dove termina questo segmento, rispetto all'inizio del video di origine.

Una durata in secondi con un massimo di nove cifre frazionarie, che termina con "s". Esempio: "3.5s".

UnstructuredSegmentDetails

Individua un segmento all'interno di un documento non strutturato e ne riporta il testo.

Rappresentazione JSON 
{
  "contentSnippet": string,
  "pageRange": {
    object (PageRange)
  }
}
Campi
contentSnippet

string

Solo output. Contenuto di testo del segmento.
pageRange

object (PageRange)

Solo output. La posizione del segmento nel documento di origine. Impostato per i file PDF, PowerPoint ed Excel, dove una pagina è una pagina PDF, una slide o un foglio. Per i file di testo normale e Word, imposta questo valore solo quando il file è suddiviso in pagine (pageSegmentationConfig con analisi digitale). Le pagine sono quindi sezioni consecutive del testo, numerate in ordine.

PageRange

Un intervallo di pagine all'interno del documento di origine. Le pagine sono basate su 1 e l'intervallo è inclusivo; una singola pagina è rappresentata come startPage == endPage.

Rappresentazione JSON 
{
  "startPage": string,
  "endPage": string
}
Campi
startPage

string (int64 format)

Solo output. Prima pagina dell'intervallo.
endPage

string (int64 format)

Solo output. Ultima pagina dell'intervallo.