Corpora

REST 資源：corpora

資源：Corpus

Corpus 是 Document 的集合。一個專案最多可以建立 5 個語料庫。

JSON 表示法 
{
  "name": string,
  "displayName": string,
  "createTime": string,
  "updateTime": string
}
欄位
name string

不可變動。ID。Corpus 資源名稱。ID (名稱不含「corpora/」前置字串) 最多可包含 40 個字元，可以使用小寫英數字元或破折號 (-)。ID 的開頭或結尾不得為破折號。如果建立時未指定名稱，系統會從 displayName 衍生專屬名稱，加上 12 個字元的隨機後置字串。範例：corpora/my-awesome-corpora-123a456b789c

displayName string

選用設定。使用者可理解的 Corpus 顯示名稱。顯示名稱長度不得超過 512 個字元 (包含空格)。例如：「語意擷取工具的文件」

createTime string (Timestamp format)

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

RFC3339 世界標準時間「Zulu」的時間戳記格式，解析度為奈秒，且最多 9 個小數位數。範例："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。

updateTime string (Timestamp format)

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

RFC3339 世界標準時間「Zulu」的時間戳記格式，解析度為奈秒，且最多 9 個小數位數。範例："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。

方法：corpora.create

可建立空白的 Corpus。

端點

則貼文 https://generativelanguage.googleapis.com/v1beta/corpora 。

要求主體

要求主體包含 Corpus 的例項。

回應主體

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

方法：corpora.list

列出使用者擁有的所有 Corpora。

端點

取得 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.query

對 Corpus 執行語意搜尋。

端點

則貼文 https://generativelanguage.googleapis.com/v1beta/{name=corpora/*}:query 。

路徑參數

name string

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

要求主體

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

欄位
query string

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

metadataFilters[] object (MetadataFilter)

選用設定。篩選 Chunk 和 Document 中繼資料。每個 MetadataFilter 物件都應對應至不重複的索引鍵。多個 MetadataFilter 物件會以邏輯「AND」連結。

文件層級查詢範例：(年 >= 2020 OR 年份 < 2010) AND (類型 = 戲劇 OR 類型 = 動作)

MetadataFilter 物件清單：metadataFilters = [ {key = "document.custom_metadata.year"條件 = [{int_value = 2020，Operation = GREATER_EQUAL}, {int_value = 2010, operations = LESS}]}, {key = "document.custom_metadata.year"條件 = [{int_value = 2020，Operation = GREATER_EQUAL}, {int_value = 2010, operations = LESS}]}, {key = "document.custom_metadata.category"條件 = [{stringValue = "drama",Operation = EQUAL}, {stringValue = "action", operations = EQUAL}]}

針對某個數值範圍的區塊層級查詢範例：(年 > 2015 AND 年 <= 2020)

MetadataFilter 物件清單：metadataFilters = [ {key = "chunk.custom_metadata.year"conditions = [{int_value = 2015, operation = GREATER}]}, {key = &quot;chunk.custom_metadata.year&quot;條件 = [{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.get

取得特定 Corpus 的資訊。

端點

取得 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 的例項。

回應主體

如果成功，回應主體會包含 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 錯誤。

要求主體

要求主體必須為空白。

回應主體

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

REST 資源：corpora.permissions

資源：權限

權限資源可將 PaLM API 資源 (例如經過調整的模型、語料庫) 存取權授予使用者、群組或全世界。

角色是一組許可的作業，可讓使用者對 PaLM API 資源執行特定動作。如要讓使用者、群組或服務帳戶使用這些服務，請指派角色。指派角色時，即代表您授予該角色具備的權限。

共有三種角色每個角色都是前一個角色允許作業的超集：

  • 讀取者可以使用資源 (例如調整過的模型、語料庫) 進行推論
  • 寫入者擁有讀取者的權限，還可以編輯和共用
  • 擁有者俱備寫入者權限，而且可以刪除
JSON 表示法 
{
  "name": string,
  "granteeType": enum (GranteeType),
  "emailAddress": string,
  "role": enum (Role)
}
欄位
name string

僅供輸出。ID。權限名稱。建立時會產生不重複的名稱。例如：TuneModels/{tunedModel}/permissions/{permission} 語料庫/{corpus}/permissions/{permission}，僅限輸出。

granteeType enum (GranteeType)

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

emailAddress string

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

role enum (Role)

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

GranteeType

定義這項權限的授予對象類型。

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

角色

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

列舉
ROLE_UNSPECIFIED 預設值。這個值未使用。
OWNER 擁有者可以使用、更新、共用及刪除資源，
WRITER 寫入者可以使用、更新和共用資源。
READER 讀取者可以使用資源。

MetadataFilter

使用者提供的篩選器，依據 Chunk 或 Document 層級的中繼資料值限制擷取作業。範例 (類型 = 戲劇 OR 類型 = 動作)：key = "document.custom_metadata.category"條件 = [{stringValue = "drama",Operation = EQUAL}, {stringValue = "action", operations = EQUAL}]

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

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

conditions[] object (Condition)

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

條件

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

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

  // Union field value can be only one of the following:
  "stringValue": string,
  "numericValue": number
  // End of list of possible types for union field value.
}
欄位
operation enum (Operator)

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

聯集欄位 value。值類型必須與對應鍵欄位中的值類型一致。如果值類型不一致，結果會是空白的集合。如果 CustomMetadata 的值類型為 StringList，篩選條件應使用 string_value 搭配 INCLUDES/EXCLUDES 運算，否則結果也會為空白組合。value 只能採用下列其中一種設定：
stringValue string

要篩選中繼資料的字串值。

numericValue number

要篩選中繼資料的數值。

運算子

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

列舉
OPERATOR_UNSPECIFIED 預設值。這個值未使用。
LESS 支援數值。
LESS_EQUAL 支援數值。
EQUAL 支援的數字和字串。
GREATER_EQUAL 支援數值。
GREATER 支援數值。
NOT_EQUAL 支援的數字和字串。
INCLUDES 只有在特定鍵的 CustomMetadata 值類型包含 stringListValue 時，才會受到字串支援。
EXCLUDES 只有在特定鍵的 CustomMetadata 值類型包含 stringListValue 時，才會受到字串支援。

RelevantChunk

查詢相關區塊的資訊。

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

Chunk 與查詢相關。

chunk object (Chunk)

與查詢相關聯的 Chunk。