Corpora

REST 资源：语料库

资源：语料库

Corpus 是 Document 的集合。一个项目最多可以创建 5 个语料库。

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

不可变。标识符。Corpus 资源名称。ID（不含“corpora/”前缀的名称）最多可包含 40 个字符，这些字符由小写字母、数字或短划线 (-) 组成。ID 不能以短划线开头或结尾。如果创建时名称为空，系统将从 displayName 派生一个唯一名称，并附带 12 个字符的随机后缀。示例：corpora/my-awesome-corpora-123a456b789c

displayName string

可选。直观易懂的 Corpus 显示名。显示名称的长度不得超过 512 个字符（包括空格）。示例：“语义检索器上的文档”

createTime string (Timestamp format)

仅限输出。Corpus 创建时的时间戳。

时间戳采用 RFC3339 世界协调时间（UTC，即“祖鲁时”）格式，精确到纳秒，最多九个小数位。示例："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。

updateTime string (Timestamp format)

仅限输出。上次更新 Corpus 时的时间戳。

时间戳采用 RFC3339 世界协调时间（UTC，即“祖鲁时”）格式，精确到纳秒，最多九个小数位。示例："2014-10-02T15:01:23Z" 和 "2014-10-02T15:01:23.045123456Z"。

方法：corpora.create

创建一个空的 Corpus。

端点

<ph type="x-smartling-placeholder"></ph> 帖子 https://generativelanguage.googleapis.com/v1beta/corpora

请求正文

请求正文包含一个 Corpus 实例。

响应正文

如果成功，响应正文将包含一个新创建的 Corpus 实例。

方法：corpora.list

列出用户拥有的所有 Corpora。

端点

<ph type="x-smartling-placeholder"></ph> 领取 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 执行语义搜索。

端点

<ph type="x-smartling-placeholder"></ph> 帖子 https://generativelanguage.googleapis.com/v1beta/{name=corpora/*}:query

路径参数

name string

必需。要查询的 Corpus 的名称。示例：corpora/my-corpus-123 其格式为 corpora/{corpora}。

请求正文

请求正文中包含结构如下的数据：

<ph type="x-smartling-placeholder">
</ph> 田野
query string

必需。用于执行语义搜索的查询字符串。

metadataFilters[] object (MetadataFilter)

可选。过滤出 Chunk 和 Document 元数据。每个 MetadataFilter 对象都应对应于一个唯一的键。多个 MetadataFilter 对象通过逻辑“AND”连接。

文档级别的查询示例：(year >= 2020 OR year < 2010) AND (genre = Drales OR genre = action)

MetadataFilter 对象列表：metadataFilters = [ {key = "document.custom_metadata.year"条件 = [{int_value = 2020, 操作 = GREATER_EQUAL}, {int_value = 2010, 操作 = LESS}]}, {key = "document.custom_metadata.year"条件 = [{int_value = 2020, 操作 = GREATER_EQUAL}, {int_value = 2010, 操作 = LESS}]}, {key = "document.custom_metadata.genre"条件 = [{stringValue = "drama", 操作 = EQUAL}, {stringValue = "action", 操作 = EQUAL}]}]

针对数值范围的分块级查询示例：(year > 2015 AND year <= 2020)

MetadataFilter 对象列表：metadataFilters = [ {key = "chunk.custom_metadata.year"conditions = [{int_value = 2015, operation = GREATER}]}, {key = &quot;chunk.custom_metadata.year&quot;条件 = [{int_value = 2020, 操作 = LESS_EQUAL}]}]

注意：只有数值支持对同一键使用“AND”。字符串值仅支持对同一键使用“OR”。

resultsCount integer

可选。要返回的最大 Chunk 数量。服务返回的 Chunk 数可能会减少。

如果未指定，则最多返回 10 个 Chunk。指定的最大结果数为 100。

响应正文

来自 corpora.query 的响应，其中包含相关分块的列表。

如果成功，响应正文将包含结构如下的数据：

田野
relevantChunks[] object (RelevantChunk)

相关分块。

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

方法：corpora.get

获取有关特定 Corpus 的信息。

端点

<ph type="x-smartling-placeholder"></ph> 领取 https://generativelanguage.googleapis.com/v1beta/{name=corpora/*}

路径参数

name string

必需。Corpus 的名称。示例：corpora/my-corpus-123 其格式为 corpora/{corpora}。

请求正文

请求正文必须为空。

响应正文

如果成功，则响应正文包含一个 Corpus 实例。

方法：corpora.patch

更新 Corpus。

端点

<ph type="x-smartling-placeholder"></ph> 补丁 https://generativelanguage.googleapis.com/v1beta/{corpus.name=corpora/*}

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

路径参数

corpus.name string

不可变。标识符。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。

端点

<ph type="x-smartling-placeholder"></ph> 删除 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

仅限输出。标识符。权限名称。创建时，系统会生成一个唯一名称。示例：tuneModels/{tunedModel}/permissions/{permission} corpora/{corpus}/permissions/{permission} 输出。

granteeType enum (GranteeType)

可选。不可变。受赠人的类型。

emailAddress string

可选。不可变。该权限所引用的群组用户的电子邮件地址。当权限的被授予方类型为 EVERYONE 时，未设置此字段。

role enum (Role)

必需。此权限授予的角色。

GranteeType

定义此权限的被授予者的类型。

枚举
GRANTEE_TYPE_UNSPECIFIED 默认值。此值未使用。
USER 表示用户。设置后，您必须为用户提供 emailAddress。
GROUP 表示群组。设置后，您必须为群组提供 emailAddress。
EVERYONE 代表对所有人的访问权限。无需提供额外信息。

角色

定义此权限所授予的角色。

枚举
ROLE_UNSPECIFIED 默认值。此值未使用。
OWNER 所有者可以使用、更新、共享和删除资源。
WRITER 写入者可以使用、更新和共享资源。
READER 读取者可以使用该资源。

MetadataFilter

用户提供的过滤条件，用于根据 Chunk 或 Document 级元数据值限制检索。示例（类型 = 戏剧 OR 类型 = 动作）：key = "document.custom_metadata.genre"条件 = [{stringValue = "drama", 操作 = EQUAL}, {stringValue = "action", 操作 = 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。