Documents

La API de File Search hace referencia a tus archivos fuente sin procesar, o documentos, como objetos File temporales.

Método: fileSearchStores.documents.delete

Borra un Document.

Extremo

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

Parámetros de ruta

name string

Obligatorio. Es el nombre del recurso del Document que se borrará. Ejemplo: fileSearchStores/my-file-search-store-123/documents/the-doc-abc Toma la forma fileSearchStores/{filesearchstore}/documents/{document}.

Parámetros de consulta

force boolean

Opcional. Si se establece como verdadero, también se borrarán los Chunk y los objetos relacionados con este Document.

Si es falso (valor predeterminado), se mostrará un error FAILED_PRECONDITION si Document contiene algún Chunk.

Cuerpo de la solicitud

El cuerpo de la solicitud debe estar vacío.

Cuerpo de la respuesta

Si se ejecuta correctamente, el cuerpo de la respuesta es un objeto JSON vacío.

Método: fileSearchStores.documents.get

Obtiene información sobre un Document específico.

Extremo

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

Parámetros de ruta

name string

Obligatorio. Nombre del Document que se recuperará. Ejemplo: fileSearchStores/my-file-search-store-123/documents/the-doc-abc Toma la forma fileSearchStores/{filesearchstore}/documents/{document}.

Cuerpo de la solicitud

El cuerpo de la solicitud debe estar vacío.

Cuerpo de la respuesta

Si se ejecuta de forma correcta, el cuerpo de la respuesta incluye una instancia de Document.

Método: fileSearchStores.documents.list

Enumera todos los Document en un Corpus.

Extremo

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

Parámetros de ruta

parent string

Obligatorio. Nombre del FileSearchStore que contiene los Document. Ejemplo: fileSearchStores/my-file-search-store-123 Toma la forma fileSearchStores/{filesearchstore}.

Parámetros de consulta

pageSize integer

Opcional. Es la cantidad máxima de Documents que se devolverán (por página). El servicio puede devolver menos objetos Document.

Si no se especifica, se devolverán, como máximo, 10 Documents. El límite de tamaño máximo es de 20 Documents por página.

pageToken string

Opcional. Un token de página, recibido desde una llamada documents.list anterior.

Proporciona el nextPageToken que se devolvió en la respuesta como argumento para la siguiente solicitud y, así, recuperar la página siguiente.

Cuando se pagina, todos los demás parámetros proporcionados a documents.list deben coincidir con la llamada que proporcionó el token de la página.

Cuerpo de la solicitud

El cuerpo de la solicitud debe estar vacío.

Cuerpo de la respuesta

Respuesta de documents.list que contiene una lista paginada de Documents. Los objetos Document se ordenan de forma ascendente según document.create_time.

Si se ejecuta correctamente, el cuerpo de la respuesta contendrá datos con la siguiente estructura:

Campos
documents[] object (Document)

Son los objetos Document que se devolvieron.

nextPageToken string

Un token, que se puede enviar como pageToken para recuperar la página siguiente. Si se omite este campo, no habrá más páginas.

Representación JSON 
{
  "documents": [
    {
      object (Document)
    }
  ],
  "nextPageToken": string
}

Método: fileSearchStores.documents.query

Realiza una búsqueda semántica en un Document.

Extremo

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

Parámetros de ruta

name string

Obligatorio. Es el nombre del Document que se consultará. Ejemplo: fileSearchStores/my-file-search-store-123/documents/the-doc-abc Toma la forma fileSearchStores/{filesearchstore}/documents/{document}.

Cuerpo de la solicitud

El cuerpo de la solicitud contiene datos con la siguiente estructura:

Campos
query string

Obligatorio. Es la cadena de búsqueda para realizar la búsqueda semántica.

resultsCount integer

Opcional. Es la cantidad máxima de Chunk que se devolverán. El servicio puede devolver menos objetos Chunk.

Si no se especifica, se devolverán, como máximo, 10 Chunks. La cantidad máxima de resultados especificada es 100.

metadataFilters[] object (MetadataFilter)

Opcional. Filtra por metadatos de Chunk. Cada objeto MetadataFilter debe corresponder a una clave única. Varios objetos MetadataFilter se unen con operadores "Y" lógicos.

Nota: No se admite el filtrado a nivel de Document para esta solicitud porque ya se especificó un nombre de Document.

Ejemplo de búsqueda: (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}}]

Ejemplo de consulta para un rango numérico de valores: (año > 2015 AND año <= 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: Los "AND" para la misma clave solo se admiten para valores numéricos. Los valores de cadena solo admiten "OR" para la misma clave.

Cuerpo de la respuesta

Respuesta de documents.query que contiene una lista de fragmentos relevantes.

Si se ejecuta correctamente, el cuerpo de la respuesta contendrá datos con la siguiente estructura:

Campos
relevantChunks[] object (RelevantChunk)

Son los fragmentos relevantes que se muestran.

Representación JSON 
{
  "relevantChunks": [
    {
      object (RelevantChunk)
    }
  ]
}

Recurso de REST: fileSearchStores.documents

Recurso: Document

Una Document es una colección de elementos Chunk.

Campos
name string

Inmutable. Es el identificador. Nombre del recurso de Document. El ID (nombre sin el prefijo "fileSearchStores/*/documents/") puede contener hasta 40 caracteres alfanuméricos en minúscula o guiones (-). El ID no puede comenzar ni terminar con un guion. Si el nombre está vacío en la creación, se derivará un nombre único de displayName junto con un sufijo aleatorio de 12 caracteres. Ejemplo: fileSearchStores/{file_search_store_id}/documents/my-awesome-doc-123a456b789c

displayName string

Opcional. Es el nombre visible legible por humanos para Document. El nombre visible no debe tener más de 512 caracteres, incluidos los espacios. Ejemplo: "Documentación de Semantic Retriever"

customMetadata[] object (CustomMetadata)

Opcional. Son los metadatos personalizados proporcionados por el usuario que se almacenan como pares clave-valor y se usan para realizar consultas. Un Document puede tener un máximo de 20 CustomMetadata.

updateTime string (Timestamp format)

Solo salida. Es la marca de tiempo de la última actualización del Document.

Usa el formato RFC 3339, en el que el resultado generado siempre estará normalizada a Z y usa 0, 3, 6 o 9 dígitos fraccionarios. También se aceptan otras compensaciones que no sean “Z”. Ejemplos: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" o "2014-10-02T15:01:23+05:30".

createTime string (Timestamp format)

Solo salida. Es la marca de tiempo de cuándo se creó el Document.

Usa el formato RFC 3339, en el que el resultado generado siempre estará normalizada a Z y usa 0, 3, 6 o 9 dígitos fraccionarios. También se aceptan otras compensaciones que no sean “Z”. Ejemplos: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" o "2014-10-02T15:01:23+05:30".

state enum (State)

Solo salida. Es el estado actual del Document.

sizeBytes string (int64 format)

Solo salida. Es el tamaño de los bytes sin procesar transferidos al documento.

mimeType string

Solo salida. Es el tipo MIME del documento.

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

Estado

Estados del ciclo de vida de un Document.

Enums
STATE_UNSPECIFIED Es el valor predeterminado. Este valor se usa si se omite el estado.
STATE_PENDING Algunos Chunks de los Document se están procesando (almacenamiento de vectores y embeddings).
STATE_ACTIVE Todos los Chunks de Document se procesan y están disponibles para realizar consultas.
STATE_FAILED No se pudo procesar parte de Chunks de Document.