方法:corpora.documents.create
创建一个空的 Document
。
端点
帖子https: / /generativelanguage.googleapis.com /v1beta /{parent=corpora /*} /documents
网址采用 gRPC 转码语法。
路径参数
parent
string
必需。将要创建此 Document
的 Corpus
的名称。示例: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 ( |
方法:corpora.documents.list
列出 Corpus
中的所有 Document
。
端点
gethttps: / /generativelanguage.googleapis.com /v1beta /{parent=corpora /*} /documents
网址采用 gRPC 转码语法。
路径参数
parent
string
必需。包含 Document
的 Corpus
的名称。示例:corpora/my-corpus-123
,格式为 corpora/{corpora}
。
查询参数
pageSize
integer
可选。要返回的 Document
的数量上限(每页)。服务返回的 Document
可能较少。
如果未指定,则最多返回 10 个 Document
。每个页面的大小上限为 20 个 Document
。
pageToken
string
可选。从之前的 documents.list
调用接收的页面令牌。
将响应中返回的 nextPageToken
作为下一个请求的参数提供,以检索下一页。
进行分页时,提供给 documents.list
的所有其他参数必须与提供页面令牌的调用匹配。
请求正文
请求正文必须为空。
方法:corpora.documents.get
获取有关特定 Document
的信息。
端点
gethttps: / /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)
必需。要更新的字段列表。目前,此方法仅支持更新 displayName
和 customMetadata
。
这是完全限定字段名称的逗号分隔列表。示例:"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
Document
是 Chunk
的集合。一个 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
用户提供的元数据以键值对的形式存储。
key
string
必需。要存储的元数据的键。
value
Union type
value
只能是下列其中一项:stringValue
string
要存储的元数据的字符串值。
stringListValue
object (StringList
)
要存储的元数据的 StringList 值。
numericValue
number
要存储的元数据的数值。
JSON 表示法 |
---|
{
"key": string,
// value
"stringValue": string,
"stringListValue": {
object ( |
StringList
分配给单个元数据键的用户提供的字符串值。
values[]
string
要存储的元数据的字符串值。
JSON 表示法 |
---|
{ "values": [ string ] } |