Corpora

方法：corpora.create

可建立空白的 Corpus。

端點

則貼文 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 個半形字元。例如：「語意擷取工具的文件」

回應主體

如果成功，回應主體會包含新建立的 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)

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

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

MetadataFilter object list: metadataFilters = [ {key = &quot;document.custom_metadata.year&quot;條件 = [{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"conditions = [{stringValue = &quot;drama&quot;, operation = EQUAL}, {stringValue = &quot;action&quot;, operation = EQUAL}]}]

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

MetadataFilter object list: metadataFilters = [ {key = &quot;chunk.custom_metadata.year&quot;Conditions = [{int_value = 2015, Operation = GREATER}]}, {鍵 = "chunk.custom_metadata.year"條件 = [{int_value = 2020，作業 = 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 個字元 (包含空格)。示例：「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 錯誤。

要求主體

要求主體必須為空白。

回應主體

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

REST 資源：corpora.permissions

資源：權限

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

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

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

  • 讀取器可使用資源 (例如經過調整的模型、語料庫) 進行推論
  • 作者具備讀者的權限，且可編輯及分享
  • 擁有者俱備寫入者權限，而且可以刪除
，瞭解如何調查及移除這項存取權。
欄位
name string

僅供輸出。ID。權限名稱。系統會在建立時產生專屬名稱。例如：TuneModels/{tunedModel}/permissions/{permission} 語料庫/{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

使用者提供的篩選器，可根據 Chunk 或 Document 層級中繼資料值限制擷取作業。範例 (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。值類型必須與對應鍵欄位中的值類型一致。如果值類型不一致，結果會是空集合。如果 CustomMetadata 的值類型為 StringList，篩選條件應使用 string_value 搭配 INCLUDES/EXCLUDES 運算，否則結果也會為空白組合。value 只能是下列其中一項：
stringValue string

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

numericValue number

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

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.
}

運算子

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

列舉
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

Corpus 是 Document 的集合。一個專案最多可以建立 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 建立時間的時間戳記。

採用 RFC3339 世界標準時間「Zulu」格式的時間戳記，精確度達奈秒單位，最多九個小數位數。範例："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。

updateTime string (Timestamp format)

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

採用 RFC3339 世界標準時間「Zulu」格式的時間戳記，精確度達奈秒單位，最多九個小數位數。範例："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。

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