Documents

L'API File Search fa riferimento ai file di origine non elaborati o ai documenti come oggetti File temporanei.

Metodo: fileSearchStores.documents.delete

Elimina un Document.

Endpoint

delete https://generativelanguage.googleapis.com/v1beta/{name=fileSearchStores/*/documents/*}

Parametri del percorso

name string

Obbligatorio. Il nome della risorsa Document da eliminare. Esempio: fileSearchStores/my-file-search-store-123/documents/the-doc-abc Assume la forma fileSearchStores/{filesearchstore}/documents/{document}.

Parametri di query

force boolean

Facoltativo. Se è impostata su true, verranno eliminati anche tutti gli Chunk e gli oggetti correlati a questo Document.

Se è false (impostazione predefinita), verrà restituito un errore FAILED_PRECONDITION se Document contiene Chunk.

Corpo della richiesta

Il corpo della richiesta deve essere vuoto.

Corpo della risposta

In caso di esito positivo, il corpo della risposta è un oggetto JSON vuoto.

Metodo: fileSearchStores.documents.get

Recupera informazioni su un Document specifico.

Endpoint

get https://generativelanguage.googleapis.com/v1beta/{name=fileSearchStores/*/documents/*}

Parametri del percorso

name string

Obbligatorio. Il nome di Document da recuperare. Esempio: fileSearchStores/my-file-search-store-123/documents/the-doc-abc Assume la forma fileSearchStores/{filesearchstore}/documents/{document}.

Corpo della richiesta

Il corpo della richiesta deve essere vuoto.

Corpo della risposta

In caso di esito positivo, il corpo della risposta contiene un'istanza di Document.

Metodo: fileSearchStores.documents.list

Elenca tutti i Document in un Corpus.

Endpoint

get https://generativelanguage.googleapis.com/v1beta/{parent=fileSearchStores/*}/documents

Parametri del percorso

parent string

Obbligatorio. Il nome di FileSearchStore contenente Document. Esempio: fileSearchStores/my-file-search-store-123 Assume la forma fileSearchStores/{filesearchstore}.

Parametri di query

pageSize integer

Facoltativo. Il numero massimo di Document da restituire (per pagina). Il servizio potrebbe restituire meno Document.

Se non specificato, verranno restituiti al massimo 10 Document. Il limite massimo di dimensioni è di 20 Document per pagina.

pageToken string

Facoltativo. Un token di pagina ricevuto da una precedente chiamata documents.list.

Fornisci il valore nextPageToken restituito nella risposta come argomento della richiesta successiva per recuperare la pagina successiva.

Durante la paginazione, tutti gli altri parametri forniti a documents.list devono corrispondere alla chiamata che ha fornito il token di pagina.

Corpo della richiesta

Il corpo della richiesta deve essere vuoto.

Corpo della risposta

Risposta da documents.list contenente un elenco paginato di Document. I Document sono ordinati in base al document.create_time in ordine crescente.

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

Campi
documents[] object (Document)

Document restituito.

nextPageToken string

Un token, che può essere inviato come pageToken per recuperare la pagina successiva. Se questo campo viene omesso, non verranno visualizzate altre pagine.

Rappresentazione JSON 
{
  "documents": [
    {
      object (Document)
    }
  ],
  "nextPageToken": string
}

Metodo: fileSearchStores.documents.query

Esegue la ricerca semantica su un Document.

Endpoint

post https://generativelanguage.googleapis.com/v1beta/{name=fileSearchStores/*/documents/*}:query

Parametri del percorso

name string

Obbligatorio. Il nome di Document su cui eseguire la query. Esempio: fileSearchStores/my-file-search-store-123/documents/the-doc-abc Assume la forma fileSearchStores/{filesearchstore}/documents/{document}.

Corpo della richiesta

Il corpo della richiesta contiene dati con la seguente struttura:

Campi
query string

Obbligatorio. Stringa di query per eseguire la ricerca semantica.

resultsCount integer

Facoltativo. Il numero massimo di Chunk da restituire. Il servizio potrebbe restituire meno Chunk.

Se non specificato, verranno restituiti al massimo 10 Chunk. Il numero massimo di risultati specificato è 100.

metadataFilters[] object (MetadataFilter)

Facoltativo. Filtra in base ai metadati Chunk. Ogni oggetto MetadataFilter deve corrispondere a una chiave univoca. Più oggetti MetadataFilter sono uniti da "AND" logici.

Nota: il filtro a livello di Document non è supportato per questa richiesta perché è già specificato un nome Document.

Query di esempio: (year >= 2020 OR year < 2010) AND (genre = drama OR genre = action)

MetadataFilter object list: metadataFilters = [ {key = "chunk.custom_metadata.year" conditions = [{int_value = 2020, operation = GREATER_EQUAL}, {int_value = 2010, operation = LESS}}, {key = "chunk.custom_metadata.genre" conditions = [{stringValue = "drama", operation = EQUAL}, {stringValue = "action", operation = EQUAL}}]

Query di esempio per un intervallo numerico di valori: (year > 2015 AND year <= 2020)

MetadataFilter object list: metadataFilters = [ {key = "chunk.custom_metadata.year" conditions = [{int_value = 2015, operation = GREATER}]}, {key = "chunk.custom_metadata.year" conditions = [{int_value = 2020, operation = LESS_EQUAL}]}]

Nota: gli "AND" per la stessa chiave sono supportati solo per i valori numerici. I valori stringa supportano solo "OR" per la stessa chiave.

Corpo della risposta

Risposta di documents.query contenente un elenco di chunk pertinenti.

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

Campi
relevantChunks[] object (RelevantChunk)

I chunk pertinenti restituiti.

Rappresentazione JSON 
{
  "relevantChunks": [
    {
      object (RelevantChunk)
    }
  ]
}

Risorsa REST: fileSearchStores.documents

Risorsa: documento

Un Document è una raccolta di Chunk.

Campi
name string

Immutabile. Identificatore. Il nome della risorsa Document. L'ID (nome escluso il prefisso "fileSearchStores/*/documents/") può contenere fino a 40 caratteri alfanumerici minuscoli o trattini (-). L'ID non può iniziare o terminare con un trattino. Se il nome è vuoto al momento della creazione, verrà derivato un nome univoco da displayName insieme a un suffisso casuale di 12 caratteri. Esempio: fileSearchStores/{file_search_store_id}/documents/my-awesome-doc-123a456b789c

displayName string

Facoltativo. Il nome visualizzato leggibile per Document. Il nome visualizzato non deve contenere più di 512 caratteri, spazi inclusi. Esempio: "Documentazione di Semantic Retriever"

customMetadata[] object (CustomMetadata)

Facoltativo. Metadati personalizzati forniti dall'utente archiviati come coppie chiave-valore utilizzate per le query. Un Document può avere un massimo di 20 CustomMetadata.

updateTime string (Timestamp format)

Solo output. Il timestamp dell'ultimo aggiornamento di Document.

Utilizza RFC 3339, in cui l'output generato è sempre normalizzato in base al fuso orario UTC e utilizza 0, 3, 6 o 9 cifre frazionarie. Sono accettati anche offset diversi da "Z". Esempi: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" o "2014-10-02T15:01:23+05:30".

createTime string (Timestamp format)

Solo output. Il timestamp della creazione di Document.

Utilizza RFC 3339, in cui l'output generato è sempre normalizzato in base al fuso orario UTC e utilizza 0, 3, 6 o 9 cifre frazionarie. Sono accettati anche offset diversi da "Z". Esempi: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" o "2014-10-02T15:01:23+05:30".

state enum (State)

Solo output. Stato attuale di Document.

sizeBytes string (int64 format)

Solo output. Le dimensioni dei byte non elaborati inseriti nel documento.

mimeType string

Solo output. Il tipo MIME del documento.

Rappresentazione JSON 
{
  "name": string,
  "displayName": string,
  "customMetadata": [
    {
      object (CustomMetadata)
    }
  ],
  "updateTime": string,
  "createTime": string,
  "state": enum (State),
  "sizeBytes": string,
  "mimeType": string
}

Stato

Stati del ciclo di vita di un Document.

Enum
STATE_UNSPECIFIED Il valore predefinito. Questo valore viene utilizzato se lo stato viene omesso.
STATE_PENDING Alcuni Chunks di Document sono in fase di elaborazione (incorporamento e archiviazione dei vettori).
STATE_ACTIVE Tutti i Chunks di Document vengono elaborati e sono disponibili per le query.
STATE_FAILED L'elaborazione di alcuni Chunks di Document non è riuscita.