Documents

File Search API 會將原始來源檔案或文件參照為暫時的 File 物件。

方法：fileSearchStores.documents.delete

刪除 Document。

端點

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

路徑參數

name string

必要欄位。要刪除的 Document 資源名稱。範例：fileSearchStores/my-file-search-store-123/documents/the-doc-abc 採用 fileSearchStores/{filesearchstore}/documents/{document} 形式。

查詢參數

force boolean

(選用步驟) 如果設為 true，系統也會刪除與這個 Document 相關的任何 Chunk 和物件。

如果為 false (預設值)，且 Document 包含任何 Chunk，系統就會傳回 FAILED_PRECONDITION 錯誤。

要求主體

要求主體必須為空白。

回應主體

如果成功，回應主體會是空白的 JSON 物件。

方法：fileSearchStores.documents.get

取得特定 Document 的相關資訊。

端點

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

路徑參數

name string

必要欄位。要擷取的 Document 名稱。範例：fileSearchStores/my-file-search-store-123/documents/the-doc-abc 採用 fileSearchStores/{filesearchstore}/documents/{document} 形式。

要求主體

要求主體必須為空白。

回應主體

如果成功，回應主體會包含 Document 的執行例項。

方法：fileSearchStores.documents.list

列出 Corpus 中的所有 Document。

端點

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

路徑參數

parent string

必要欄位。包含 Document 的 FileSearchStore 名稱。範例：fileSearchStores/my-file-search-store-123 採用 fileSearchStores/{filesearchstore} 形式。

查詢參數

pageSize integer

(選用步驟) 要傳回的 Document 數量上限 (每頁)。服務傳回的 Document 數量可能會較少。

如未指定，最多將傳回 10 個 Document。每頁最多可顯示 20 個 Document。

pageToken string

(選用步驟) 屬於接收自前一個 documents.list 呼叫的網頁權杖。

將回應中傳回的 nextPageToken 做為下一個要求的引數，即可擷取下一頁。

進行分頁時，提供至 documents.list 的所有其他參數須與提供網頁權杖的呼叫相符。

要求主體

要求主體必須為空白。

回應主體

來自 documents.list 的回應，內含分頁的 Document 清單。Document 會依遞增的 document.create_time 排序。

如果成功，回應主體會含有以下結構的資料：

欄位
documents[] object (Document)

傳回的 Document。

nextPageToken string

可做為 pageToken 傳送的權杖，用於擷取後續網頁。如果省略這個欄位，就不會有後續頁面。

JSON 表示法 
{
  "documents": [
    {
      object (Document)
    }
  ],
  "nextPageToken": string
}

方法：fileSearchStores.documents.query

對 Document 執行語意搜尋。

端點

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

路徑參數

name string

必要欄位。要查詢的 Document 名稱，範例：fileSearchStores/my-file-search-store-123/documents/the-doc-abc 採用 fileSearchStores/{filesearchstore}/documents/{document} 形式。

要求主體

要求主體會包含結構如下的資料：

欄位
query string

必要欄位。執行語意搜尋的查詢字串。

resultsCount integer

(選用步驟) 要傳回的 Chunk 數量上限。服務傳回的 Chunk 數量可能會較少。

如未指定，最多將傳回 10 個 Chunk。指定結果數上限為 100。

metadataFilters[] object (MetadataFilter)

(選用步驟) 篩選 Chunk 中繼資料。每個 MetadataFilter 物件都應對應至不重複的金鑰。多個 MetadataFilter 物件會以邏輯「AND」合併。

注意：由於已指定 Document 名稱，因此這項要求不支援 Document 層級的篩選。

查詢範例：(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}}]

數值範圍的查詢範例：(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}]}]

注意：相同鍵的「AND」僅支援數值。字串值僅支援相同鍵的「OR」。

回應主體

documents.query 的回應，其中包含相關區塊的清單。

如果成功，回應主體會含有以下結構的資料：

欄位
relevantChunks[] object (RelevantChunk)

傳回的相關區塊。

JSON 表示法 
{
  "relevantChunks": [
    {
      object (RelevantChunk)
    }
  ]
}

REST 資源：fileSearchStores.documents

資源：Document

Document 是 Chunk 的集合。

欄位
name string

不可變更。ID。Document 資源名稱。ID (名稱，不含「fileSearchStores/*/documents/」前置字元) 最多可包含 40 個字元，且只能是小寫英數字元或破折號 (-)。ID 開頭或結尾不得為破折號。如果建立時名稱為空白，系統會從 displayName 衍生出專屬名稱，並加上 12 個字元的隨機後置字串。範例：fileSearchStores/{file_search_store_id}/documents/my-awesome-doc-123a456b789c

displayName string

(選用步驟) Document 的使用者可讀顯示名稱。顯示名稱長度不得超過 512 個半形字元 (包括空格)。例如：「Semantic Retriever Documentation」(語意擷取器文件)

customMetadata[] object (CustomMetadata)

(選用步驟) 使用者提供的自訂中繼資料會以鍵/值組合的形式儲存，用於查詢。每個Document最多可有 20 個CustomMetadata。

updateTime string (Timestamp format)

僅供輸出。上次更新 Document 的時間戳記。

使用 RFC 3339，產生的輸出內容一律會經過 Z 標準化，並使用 0、3、6 或 9 個小數點後位數。系統也接受「Z」以外的偏移量。例如："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。

createTime string (Timestamp format)

僅供輸出。Document 的建立時間戳記。

使用 RFC 3339，產生的輸出內容一律會經過 Z 標準化，並使用 0、3、6 或 9 個小數點後位數。系統也接受「Z」以外的偏移量。例如："2014-10-02T15:01:23Z"、"2014-10-02T15:01:23.045123456Z" 或 "2014-10-02T15:01:23+05:30"。

state enum (State)

僅供輸出。Document 的目前狀態。

sizeBytes string (int64 format)

僅供輸出。擷取至文件的原始位元組大小。

mimeType string

僅供輸出。文件的 MIME 類型。

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

州

Document 生命週期的狀態。

列舉
STATE_UNSPECIFIED 預設值。如果省略狀態，系統會使用這個值。
STATE_PENDING 系統正在處理部分 Chunks (嵌入和向量儲存)。Document
STATE_ACTIVE 所有 Chunks 的 Document 都已處理完畢，可供查詢。
STATE_FAILED 部分 Chunks 的 Document 無法處理。