Corpora

方法：corpora.create

创建一个空的 Corpus。

端点

POST 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 执行语义搜索。

端点

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”连接。

文档级别的查询示例：(year >= 2020 OR year < 2010) AND (genre = Drales 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 object list: metadataFilters = [ {key = &quot;chunk.custom_metadata.year&quot;条件 = [{int_value = 2015, 操作 = GREATER}]}, {key = "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。

端点

获取 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 的信息。

端点

领取 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 错误。

请求正文

请求正文必须为空。

响应正文

如果成功，则响应正文为空。

REST 资源：corpora.permissions

资源：权限

权限资源可向用户、群组或其他用户授予对 PaLM API 资源（例如经过调整的模型、语料库）的访问权限。

角色是一组允许的操作，可让用户对 PaLM API 资源执行特定操作。如需将其提供给用户、群组或服务账号，您可以分配角色。分配角色即授予该角色包含的权限。

其中包含三个同心角色。每个角色都是前一个角色所允许操作的超集：

  • 读取器可以使用资源（例如调优后的模型、语料库）进行推理
  • 写入者拥有读者权限，还可以编辑和分享
  • 所有者拥有写入者的权限，还可以删除
字段
name string

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

granteeType enum (GranteeType)

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

emailAddress string

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

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 级元数据值限制检索。示例（类型 = 剧情片或类型 = 动作片）：键 = "document.custom_metadata.genre" 条件 = [{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 是 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 创建时的时间戳。

时间戳采用 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"。

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