多词项向量
_mtermvectors API 在一个请求中检索多个文档的词项向量信息。词项向量提供了文档中词项（单词）的详细信息，包括词项频率、位置、偏移量和负载。这对于相关性评分、高亮显示或相似性计算等应用非常有用。有关更多信息，请参阅词项向量参数。
端点
GET /_mtermvectors
POST /_mtermvectors
GET /{index}/_mtermvectors
POST /{index}/_mtermvectors
路径参数
下表列出了可用的路径参数。所有路径参数均为可选。
| 参数 | 数据类型 | 描述 |
|---|---|---|
index | 字符串 | 包含文档的索引名称。 |
查询参数
下表列出了可用的查询参数。所有查询参数都是可选的。
| 参数 | 数据类型 | 描述 |
|---|---|---|
field_statistics | 布尔型 | 如果为 true，响应将包含文档计数、文档频率总和以及总词项频率总和。（默认值：true） |
fields | 列表或字符串 | 逗号分隔的列表或通配符表达式，指定要包含在统计信息中的字段。用作默认列表，除非在 completion_fields 或 fielddata_fields 参数中提供了特定的字段列表。 |
ids | 列表 | 逗号分隔的文档 ID 列表。您必须在请求正文中提供 docs 字段，或者将 ids 指定为查询参数或在请求正文中提供。 |
offsets | 布尔型 | 如果为 true，响应将包含词项偏移量。（默认值：true） |
payloads | 布尔型 | 如果为 true，响应将包含词项负载。（默认值：true） |
positions | 布尔型 | 如果为 true，响应将包含词项位置。（默认值：true） |
preference | 字符串 | 指定应执行操作的节点或分片。有关可用选项列表，请参阅preference 查询参数。默认情况下，请求会随机路由到可用的分片副本（主副本或副本），不保证重复查询之间的一致性。 |
realtime | 布尔型 | 如果为 true，请求是实时的，而不是近实时的。（默认值：true） |
路由 | 列表或字符串 | 用于将操作路由到特定分片的自定义值。 |
term_statistics | 布尔型 | 如果为 true，响应将包含词项频率和文档频率。（默认值：false） |
version | 整数 | 如果为 true，返回文档版本作为命中结果的一部分。 |
version_type | 字符串 | 特定版本类型。 有效值为 - external：版本号必须大于当前版本。- external_gte：版本号必须大于或等于当前版本。- force：版本号被强制设置为给定值。- internal：版本号由 OpenSearch 内部管理。 |
请求正文字段
下表列出了可在请求正文中指定的字段。
| 字段 | 数据类型 | 描述 |
docs | 数组 | 文档规范数组。 |
ids | 字符串数组 | 要检索的文档 ID 列表。仅当所有文档共享请求路径或查询中指定的相同索引时使用。 |
fields | 字符串数组 | 要返回词项向量的字段名称列表。 |
offsets | 布尔型 | 如果为 true，响应将包含每个词项的字符偏移量。（默认值：true） |
payloads | 布尔型 | 如果为 true，响应将包含每个词项的负载。（默认值：true） |
positions | 布尔型 | 如果为 true，响应将包含词元位置。（默认值：true） |
field_statistics | 布尔型 | 如果为 true，响应将包含统计信息，例如文档计数、文档频率总和以及总词项频率总和。（默认值：true） |
term_statistics | 布尔型 | 如果为 true，响应将包含词项频率和文档频率。（默认值：false） |
路由 | 字符串 | 用于标识分片的自定义路由值。如果在索引期间使用了自定义路由，则为必填项。 |
version | 整数 | 要检索的文档的特定版本。 |
version_type | 字符串 | 要使用的版本控制类型。有效值：internal、external、external_gte。 |
filter | 对象 | 过滤响应中返回的词元（例如，按频率或位置）。有关支持的字段，请参阅过滤词项。 |
per_field_analyzer | 对象 | 指定每个字段使用的自定义分析器。格式：{ "field_name": "analyzer_name" }。 |
过滤词项
请求正文中的 filter 对象允许您过滤要包含在词项向量响应中的词元。filter 对象支持以下字段。
| 字段 | 数据类型 | 描述 |
max_num_terms | 整数 | 要返回的最大词项数。 |
min_term_freq | 整数 | 词项包含在文档中所需的最小词项频率。 |
max_term_freq | 整数 | 词项包含在文档中所需的最大词项频率。 |
min_doc_freq | 整数 | 词项包含在索引中所需的最小文档频率。 |
max_doc_freq | 整数 | 词项包含在索引中所需的文档最大频率。 |
min_word_length | 整数 | 要包含的词项的最小长度。 |
max_word_length | 整数 | 要包含的词项的最大长度。 |
示例
创建启用词项向量的索引
PUT /my-index
{
"mappings": {
"properties": {
"text": {
"type": "text",
"term_vector": "with_positions_offsets_payloads"
}
}
}
}
索引第一个文档
POST /my-index/_doc/1
{
"text": "OpenSearch is a search engine."
}
索引第二个文档
POST /my-index/_doc/2
{
"text": "OpenSearch provides powerful features."
}
请求示例
获取多个文档的词项向量
POST /_mtermvectors
{
"docs": [
{
"_index": "my-index",
"_id": "1",
"fields": ["text"]
},
{
"_index": "my-index",
"_id": "2",
"fields": ["text"]
}
]
}
或者，您可以将 ids 和 fields 指定为查询参数
GET /my-index/_mtermvectors?ids=1,2&fields=text
您也可以在 ids 数组中提供文档 ID，而不是指定 docs
GET /my-index/_mtermvectors?fields=text
{
"ids": [
"1", "2"
]
}
示例响应
响应包含两个文档的词项向量信息
{
"docs": [
{
"_index": "my-index",
"_id": "1",
"_version": 1,
"found": true,
"took": 10,
"term_vectors": {
"text": {
"field_statistics": {
"sum_doc_freq": 9,
"doc_count": 2,
"sum_ttf": 9
},
"terms": {
"a": {
"term_freq": 1,
"tokens": [
{
"position": 2,
"start_offset": 14,
"end_offset": 15
}
]
},
"engine": {
"term_freq": 1,
"tokens": [
{
"position": 4,
"start_offset": 23,
"end_offset": 29
}
]
},
"is": {
"term_freq": 1,
"tokens": [
{
"position": 1,
"start_offset": 11,
"end_offset": 13
}
]
},
"opensearch": {
"term_freq": 1,
"tokens": [
{
"position": 0,
"start_offset": 0,
"end_offset": 10
}
]
},
"search": {
"term_freq": 1,
"tokens": [
{
"position": 3,
"start_offset": 16,
"end_offset": 22
}
]
}
}
}
}
},
{
"_index": "my-index",
"_id": "2",
"_version": 1,
"found": true,
"took": 0,
"term_vectors": {
"text": {
"field_statistics": {
"sum_doc_freq": 9,
"doc_count": 2,
"sum_ttf": 9
},
"terms": {
"features": {
"term_freq": 1,
"tokens": [
{
"position": 3,
"start_offset": 29,
"end_offset": 37
}
]
},
"opensearch": {
"term_freq": 1,
"tokens": [
{
"position": 0,
"start_offset": 0,
"end_offset": 10
}
]
},
"powerful": {
"term_freq": 1,
"tokens": [
{
"position": 2,
"start_offset": 20,
"end_offset": 28
}
]
},
"provides": {
"term_freq": 1,
"tokens": [
{
"position": 1,
"start_offset": 11,
"end_offset": 19
}
]
}
}
}
}
}
]
}
响应正文字段
下表列出了所有响应正文字段。
| 字段 | 数据类型 | 描述 |
|---|---|---|
docs | 数组 | 包含词项向量的请求文档列表。 |
docs 数组的每个元素包含以下字段。
| 字段 | 数据类型 | 描述 |
|---|---|---|
term_vectors | 对象 | 包含每个字段的词项向量数据。 |
term_vectors.<field>.field_statistics | 对象 | 包含有关该字段的统计信息。 |
term_vectors.<field>.field_statistics.doc_count | 整数 | 指定字段中包含至少一个词项的文档数量。 |
term_vectors.<field>.field_statistics.sum_doc_freq | 整数 | 字段中所有词项的文档频率总和。 |
term_vectors.<field>.field_statistics.sum_ttf | 整数 | 字段中所有词项的总词项频率总和。 |
term_vectors.<field>.terms | 对象 | 字段中的词项映射，其中每个词项都包含其频率（term_freq）和关联的词元信息。 |
term_vectors.<field>.terms.<term>.tokens | 数组 | 每个词项的词元对象数组，包括词元在文本中的 position 及其字符偏移量（start_offset 和 end_offset）。 |