Corpora

方法：corpora.create

创建一个空的 Corpus。

端点

帖子 https://generativelanguage.googleapis.com/v1beta/corpora

请求正文

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

字段
name string

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

displayName string

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

响应正文

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

方法：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”联接。

文档级查询示例：(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”运算。字符串值仅支持针对同一键的“或”运算。

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

不可变。标识符。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 个字符（包括空格）。示例：“关于语义检索器的文档”

响应正文

如果成功，则响应正文包含一个 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

仅限输出。标识符。权限名称。系统会在创建时生成一个唯一的名称。示例：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 表示用户。设置后，您必须为用户提供 emailAddress。
GROUP 表示组。设置后，您必须为群组提供 emailAddress。
EVERYONE 表示所有人都可以访问。无需提供额外的信息。

角色

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

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

MetadataFilter

用户提供的过滤条件，用于根据 Chunk 或 Document 级元数据值限制检索。示例（类型 = 剧情片或类型 = 动作片）：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 是 Document 的集合。一个项目最多可以创建 5 个语料库。

字段
name string

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

displayName string

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

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
}