Documents

方法:corpora.documents.create

创建一个空的 Document

端点

帖子 https://generativelanguage.googleapis.com/v1beta/{parent=corpora/*}/documents

网址采用 gRPC 转码语法。

路径参数

parent string

必需。将要创建此 DocumentCorpus 的名称。示例:corpora/my-corpus-123,格式为 corpora/{corpora}

请求正文

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

字段
name string

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

displayName string

可选。Document 的直观易懂的显示名称。显示名称不得超过 512 个字符(包括空格)。示例:“Semantic Retriever Documentation”(语义检索器文档)

customMetadata[] object (CustomMetadata)

可选。用户提供的自定义元数据,以键值对的形式存储,用于查询。一个 Document 最多可以有 20 个 CustomMetadata

响应正文

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

方法:corpora.documents.query

Document 执行语义搜索。

端点

帖子 https://generativelanguage.googleapis.com/v1beta/{name=corpora/*/documents/*}:query

网址采用 gRPC 转码语法。

路径参数

name string

必需。要查询的 Document 的名称。示例:corpora/my-corpus-123/documents/the-doc-abc,格式为 corpora/{corpora}/documents/{document}

请求正文

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

字段
query string

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

resultsCount integer

可选。要返回的 Chunk 的数量上限。服务返回的 Chunk 可能较少。

如果未指定,则最多返回 10 个 Chunk。指定的结果数量上限为 100。

metadataFilters[] object (MetadataFilter)

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

注意:由于已指定 Document 名称,因此此请求不支持 Document 级过滤。

查询示例:(year >= 2020 OR year < 2010) AND (genre = drama OR genre = action)

MetadataFilter 对象列表:metadataFilters = [ {key = "chunk.custom_metadata.year" conditions = [{int_value = 2020, operation = GREATER_EQUAL}, {int_value = 2010, operation = LESS}}, {key = "chunk.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”运算。字符串值仅支持针对同一键的“或”运算。

响应正文

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

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

字段
relevantChunks[] object (RelevantChunk)

返回的相关数据块。

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

方法:corpora.documents.list

列出 Corpus 中的所有 Document

端点

get https://generativelanguage.googleapis.com/v1beta/{parent=corpora/*}/documents

网址采用 gRPC 转码语法。

路径参数

parent string

必需。包含 DocumentCorpus 的名称。示例:corpora/my-corpus-123,格式为 corpora/{corpora}

查询参数

pageSize integer

可选。要返回的 Document 的数量上限(每页)。服务返回的 Document 可能较少。

如果未指定,则最多返回 10 个 Document。每个页面的大小上限为 20 个 Document

pageToken string

可选。从之前的 documents.list 调用接收的页面令牌。

将响应中返回的 nextPageToken 作为下一个请求的参数提供,以检索下一页。

进行分页时,提供给 documents.list 的所有其他参数必须与提供页面令牌的调用匹配。

请求正文

请求正文必须为空。

响应正文

来自 documents.list 的响应,其中包含分页的 Document 列表。Document 按升序 document.create_time 排序。

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

字段
documents[] object (Document)

返回的 Document

nextPageToken string

可作为 pageToken 发送并用于检索下一页的令牌。如果省略此字段,则不存在后续页面。

JSON 表示法
{
  "documents": [
    {
      object (Document)
    }
  ],
  "nextPageToken": string
}

方法:corpora.documents.get

获取有关特定 Document 的信息。

端点

get https://generativelanguage.googleapis.com/v1beta/{name=corpora/*/documents/*}

网址采用 gRPC 转码语法。

路径参数

name string

必需。要检索的 Document 的名称。示例:corpora/my-corpus-123/documents/the-doc-abc,格式为 corpora/{corpora}/documents/{document}

请求正文

请求正文必须为空。

响应正文

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

方法:corpora.documents.patch

更新 Document

端点

补丁 https://generativelanguage.googleapis.com/v1beta/{document.name=corpora/*/documents/*}

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

网址采用 gRPC 转码语法。

路径参数

document.name string

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

查询参数

updateMask string (FieldMask format)

必需。要更新的字段列表。目前,此方法仅支持更新 displayNamecustomMetadata

这是完全限定字段名称的逗号分隔列表。示例:"user.displayName,photo"

请求正文

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

字段
displayName string

可选。Document 的直观易懂的显示名称。显示名称不得超过 512 个字符(包括空格)。示例:“Semantic Retriever Documentation”(语义检索器文档)

customMetadata[] object (CustomMetadata)

可选。用户提供的自定义元数据,以键值对的形式存储,用于查询。一个 Document 最多可以有 20 个 CustomMetadata

响应正文

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

方法:corpora.documents.delete

删除 Document

端点

删除 https://generativelanguage.googleapis.com/v1beta/{name=corpora/*/documents/*}

网址采用 gRPC 转码语法。

路径参数

name string

必需。要删除的 Document 的资源名称。示例:corpora/my-corpus-123/documents/the-doc-abc,格式为 corpora/{corpora}/documents/{document}

查询参数

force boolean

可选。如果设置为 true,则与此 Document 相关的所有 Chunk 和对象也会被删除。

如果为 false(默认值),当 Document 包含任何 Chunk 时,系统会返回 FAILED_PRECONDITION 错误。

请求正文

请求正文必须为空。

响应正文

如果成功,响应正文将为空的 JSON 对象。

REST 资源:corpora.documents

资源:Document

DocumentChunk 的集合。一个 Corpus 最多可以有 10,000 个 Document

字段
name string

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

displayName string

可选。Document 的直观易懂的显示名称。显示名称不得超过 512 个字符(包括空格)。示例:“Semantic Retriever Documentation”(语义检索器文档)

customMetadata[] object (CustomMetadata)

可选。用户提供的自定义元数据,以键值对的形式存储,用于查询。一个 Document 最多可以有 20 个 CustomMetadata

updateTime string (Timestamp format)

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

使用 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"

createTime string (Timestamp format)

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

使用 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,
  "customMetadata": [
    {
      object (CustomMetadata)
    }
  ],
  "updateTime": string,
  "createTime": string
}

CustomMetadata

用户提供的元数据以键值对的形式存储。

字段
key string

必需。要存储的元数据的键。

value Union type
value 只能是下列其中一项:
stringValue string

要存储的元数据的字符串值。

stringListValue object (StringList)

要存储的元数据的 StringList 值。

numericValue number

要存储的元数据的数值。

JSON 表示法
{
  "key": string,

  // value
  "stringValue": string,
  "stringListValue": {
    object (StringList)
  },
  "numericValue": number
  // Union type
}

StringList

分配给单个元数据键的用户提供的字符串值。

字段
values[] string

要存储的元数据的字符串值。

JSON 表示法
{
  "values": [
    string
  ]
}