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。

端点

delete 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

资源：Permission

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

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

有三个同心角色。每个角色都是前一个角色允许的操作的超集：

  • 读者可以使用资源（例如调优后的模型、语料库）进行推理
  • 写入者拥有读者的权限，此外还可以修改和共享内容
  • 所有者拥有写入者权限，此外还可以删除
字段
name string

仅限输出。标识符。权限名称。系统会在创建时生成唯一名称。示例：tunedModels/{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 级元数据值限制检索。示例（类型为“剧情”或“动作”）：key = "document.custom_metadata.genre" conditions = [{stringValue = "剧情", operation = EQUAL}, {stringValue = "动作", 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。

document object (Document)

与块关联的 Document。

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

REST 资源：corpora

资源：Corpus

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
}