Corpora

方法:corpora.create

建立空白的 Corpus

端點

post https://generativelanguage.googleapis.com/v1beta/corpora

要求主體

要求主體包含 Corpus 的例項。

欄位
name string

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

displayName string

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

回應主體

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

方法:corpora.query

針對 Corpus 執行語意搜尋。

端點

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

路徑參數

name string

必要欄位。要查詢的 Corpus 名稱。範例:corpora/my-corpus-123 的格式為 corpora/{corpora}

要求主體

要求主體的資料會採用以下結構:

欄位
query string

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

metadataFilters[] object (MetadataFilter)

選用設定。篩選 ChunkDocument 中繼資料。每個 MetadataFilter 物件都應對應至專屬鍵。多個 MetadataFilter 物件會透過邏輯「AND」合併。

文件層級查詢範例:(year >= 2020 OR year < 2010) AND (genre = drama OR genre = action)

MetadataFilter 物件清單:metadataFilters = [ {key = "document.custom_metadata.year" conditions = [{int_value = 2020, operation = GREATER_EQUAL}, {int_value = 2010, operation = LESS}]}, {key = "document.custom_metadata.year" conditions = [{int_value = 2020, operation = GREATER_EQUAL}, {int_value = 2010, operation = LESS}]}, {key = "document.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」。

resultsCount integer

選用設定。要傳回的 Chunk 數量上限。服務傳回的 Chunk 可能會較少。

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

回應主體

來自 corpora.query 的回應,其中包含相關區塊的清單。

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

欄位
relevantChunks[] object (RelevantChunk)

相關區塊。

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

方法:corpora.list

列出使用者擁有的所有 Corpora

端點

get https://generativelanguage.googleapis.com/v1beta/corpora

查詢參數

pageSize integer

選用設定。每頁傳回的 Corpora 數量上限。服務傳回的 Corpora 可能會較少。

如未指定,最多將傳回 10 個 Corpora。每頁的大小上限為 20 Corpora

pageToken string

選用設定。從先前 corpora.list 呼叫收到的網頁權杖。

將回應中傳回的 nextPageToken 提供為下一個要求的引數,以便擷取下一頁。

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

要求主體

要求主體必須為空白。

回應主體

corpora.list 的回應,其中包含 Corpora 的分頁清單。結果會依 corpus.create_time 遞增排序。

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

欄位
corpora[] object (Corpus)

傳回的語料庫。

nextPageToken string

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

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

方法:corpora.get

取得特定 Corpus 的相關資訊。

端點

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

路徑參數

name string

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

要求主體

要求主體必須為空白。

回應主體

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

方法:corpora.patch

更新 Corpus

端點

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

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

路徑參數

corpus.name string

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

查詢參數

updateMask string (FieldMask format)

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

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

要求主體

要求主體包含 Corpus 的例項。

欄位
displayName string

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

回應主體

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

方法:corpora.delete

刪除 Corpus

端點

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

路徑參數

name string

必要欄位。Corpus 的資源名稱。範例:corpora/my-corpus-123 的格式為 corpora/{corpora}

查詢參數

force boolean

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

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

要求主體

要求主體必須為空白。

回應主體

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

REST 資源:corpora.permissions

資源:權限

權限資源可授予使用者、群組或其他使用者存取 PaLM API 資源 (例如經過調整的模型、字庫)。

角色是一系列允許使用者對 PaLM API 資源執行特定動作的許可作業。如要讓使用者、群組或服務帳戶使用這些資源,您必須指派角色。指派角色時,您會授予該角色包含的權限。

有三個同心圓角色。每個角色都包含前一個角色允許的操作的超集:

  • 讀取器可使用資源 (例如經過調整的模型、語料庫) 進行推論
  • 作者具備讀者的權限,且可編輯及分享
  • 擁有者具備編輯者權限,且可刪除
欄位
name string

僅供輸出。ID。權限名稱。系統會在建立時產生專屬名稱。範例:tunedModels/{tunedModel}/permissions/{permission} corpora/{corpus}/permissions/{permission} 僅供輸出。

granteeType enum (GranteeType)

選用設定。不可變動。授權對象的類型。

emailAddress string

選用設定。不可變動。這個權限參照的使用者或群組電子郵件地址。權限的授權對象類型為「所有人」時,系統不會設定欄位。

role enum (Role)

必要欄位。這個權限授予的角色。

JSON 表示法
{
  "name": string,
  "granteeType": enum (GranteeType),
  "emailAddress": string,
  "role": enum (Role)
}

GranteeType

定義此權限的授權對象類型。

列舉
GRANTEE_TYPE_UNSPECIFIED 預設值。此值未使用。
USER 代表使用者。設定後,您必須為使用者提供電子郵件地址。
GROUP 代表群組。設定後,您必須提供群組的電子郵件地址。
EVERYONE 代表所有人都能存取。不需要提供額外資訊。

角色

定義這個權限授予的角色。

列舉
ROLE_UNSPECIFIED 預設值。此值未使用。
OWNER 擁有者可以使用、更新、分享及刪除資源。
WRITER 編寫者可以使用、更新及分享資源。
READER 讀取器可以使用該資源。

MetadataFilter

使用者提供的篩選器,可根據 ChunkDocument 層級中繼資料值限制擷取作業。範例 (genre = drama OR genre = action):key = "document.custom_metadata.genre" conditions = [{stringValue = "drama", operation = EQUAL}, {stringValue = "action", operation = EQUAL}]

欄位
key string

必要欄位。要篩選的中繼資料鍵。

conditions[] object (Condition)

必要欄位。指定觸發此篩選器的鍵的 Condition。多個 Condition 會以邏輯 OR 連接。

JSON 表示法
{
  "key": string,
  "conditions": [
    {
      object (Condition)
    }
  ]
}

條件

適用於單一鍵的篩選條件。

欄位
operation enum (Operator)

必要欄位。套用至指定鍵/值組合的運算子,用於觸發條件。

value Union type
值類型必須與對應鍵欄位中定義的值類型一致。如果值類型不一致,結果會是空集合。如果 CustomMetadata 具有 StringList 值類型,篩選條件應使用 string_value 搭配 INCLUDES/EXCLUDES 作業,否則結果也會是空集。value 只能是下列其中一項:
stringValue string

用來篩選中繼資料的字串值。

numericValue number

用來篩選中繼資料的數值。

JSON 表示法
{
  "operation": enum (Operator),

  // value
  "stringValue": string,
  "numericValue": number
  // Union type
}

運算子

定義可套用至鍵/值組合的有效運算子。

列舉
OPERATOR_UNSPECIFIED 預設值。此值未使用。
LESS 數字支援。
LESS_EQUAL 數字支援。
EQUAL 數字和字串皆支援。
GREATER_EQUAL 數字支援。
GREATER 數字支援。
NOT_EQUAL 可使用數字和字串。
INCLUDES 只有在指定鍵的 CustomMetadata 值類型含有 stringListValue 時,才支援字串。
EXCLUDES 只有在特定鍵的 CustomMetadata 值類型含有 stringListValue 時,才支援字串。

RelevantChunk

與查詢相關的片段資訊。

欄位
chunkRelevanceScore number

Chunk 與查詢的關聯性。

chunk object (Chunk)

與查詢相關聯的 Chunk

JSON 表示法
{
  "chunkRelevanceScore": number,
  "chunk": {
    object (Chunk)
  }
}

REST 資源:corpora

資源:Corpus

CorpusDocument 的集合。每個專案最多可建立 5 個語料庫。

欄位
name string

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

displayName string

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

createTime string (Timestamp format)

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

使用 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"

updateTime string (Timestamp format)

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

使用 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,
  "createTime": string,
  "updateTime": string
}