Documents

方法:corpora.documents.create

建立空白的 Document

端點

post https://generativelanguage.googleapis.com/v1beta/{parent=corpora/*}/documents

這個網址使用 gRPC 轉碼語法。

路徑參數

parent string

必要欄位。這個 Document 將會建立在哪個 Corpus 中。範例:corpora/my-corpus-123 的格式為 corpora/{corpora}

要求主體

要求主體包含 Document 的例項。

欄位
name string

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

displayName string

選用設定。Document 的使用者可讀顯示名稱。顯示名稱的長度 (包括空格) 不得超過 512 個半形字元。示例:「Semantic Retriever 說明文件」

customMetadata[] object (CustomMetadata)

選用設定。使用者提供的自訂中繼資料會以鍵/值組合形式儲存,用於查詢。一個 Document 最多可包含 20 個 CustomMetadata

回應主體

如果成功,回應主體會包含新建立的 Document 例項。

方法:corpora.documents.query

針對 Document 執行語意搜尋。

端點

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

這個網址使用 gRPC 轉碼語法。

路徑參數

name string

必要欄位。要查詢的 Document 名稱。範例:corpora/my-corpus-123/documents/the-doc-abc 的格式為 corpora/{corpora}/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 物件清單: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 物件清單: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)
    }
  ]
}

方法:corpora.documents.list

列出 Corpus 中的所有 Document

端點

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

這個網址使用 gRPC 轉碼語法。

路徑參數

parent string

必要欄位。包含 DocumentCorpus 名稱。範例:corpora/my-corpus-123 的格式為 corpora/{corpora}

查詢參數

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
}

方法:corpora.documents.get

取得特定 Document 的相關資訊。

端點

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

這個網址使用 gRPC 轉碼語法。

路徑參數

name string

必要欄位。要擷取的 Document 名稱。範例:corpora/my-corpus-123/documents/the-doc-abc 的格式為 corpora/{corpora}/documents/{document}

要求主體

要求主體必須為空白。

回應主體

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

方法:corpora.documents.patch

更新 Document

端點

修補 https://generativelanguage.googleapis.com/v1beta/{document.name=corpora/*/documents/*}

PATCH https://generativelanguage.googleapis.com/v1beta/{document.name=corpora/*/documents/*}

這個網址使用 gRPC 轉碼語法。

路徑參數

document.name string

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

查詢參數

updateMask string (FieldMask format)

必要欄位。要更新的欄位清單。目前僅支援更新 displayNamecustomMetadata

這是以半形逗號分隔的完整欄位名稱清單。範例:"user.displayName,photo"

要求主體

要求主體包含 Document 的例項。

欄位
displayName string

選用設定。Document 的使用者可讀顯示名稱。顯示名稱的長度 (包括空格) 不得超過 512 個半形字元。示例:「Semantic Retriever 說明文件」

customMetadata[] object (CustomMetadata)

選用設定。使用者提供的自訂中繼資料會以鍵/值組合形式儲存,用於查詢。一個 Document 最多可包含 20 個 CustomMetadata

回應主體

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

方法:corpora.documents.delete

刪除 Document

端點

刪除 https://generativelanguage.googleapis.com/v1beta/{name=corpora/*/documents/*}

這個網址使用 gRPC 轉碼語法。

路徑參數

name string

必要欄位。要刪除的 Document 資源名稱。範例:corpora/my-corpus-123/documents/the-doc-abc 的格式為 corpora/{corpora}/documents/{document}

查詢參數

force boolean

選用設定。如果設為 True,系統也會刪除與這個 Document 相關的所有 Chunk 和物件。

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

要求主體

要求主體必須為空白。

回應主體

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

REST 資源:corpora.documents

資源:Document

DocumentChunk 的集合。Corpus 最多可包含 10,000 個 Document

欄位
name string

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

displayName string

選用設定。Document 的使用者可讀顯示名稱。顯示名稱的長度 (包括空格) 不得超過 512 個半形字元。示例:「Semantic Retriever 說明文件」

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"

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

CustomMetadata

使用者提供的中繼資料以鍵/值組合形式儲存。

欄位
key string

必要欄位。要儲存的中繼資料鍵。

value Union type
value 只能是下列其中一項:
stringValue string

要儲存的中繼資料字串值。

stringListValue object (StringList)

要儲存的中繼資料的 StringList 值。

numericValue number

要儲存的中繼資料的數值。

JSON 表示法
{
  "key": string,

  // value
  "stringValue": string,
  "stringListValue": {
    object (StringList)
  },
  "numericValue": number
  // Union type
}

StringList

使用者提供的字串值,已指派給單一中繼資料鍵。

欄位
values[] string

要儲存的中繼資料字串值。

JSON 表示法
{
  "values": [
    string
  ]
}