搜索参数

使用搜索参数来搜索集合，识别结果集以及分析结果集。

结果集是指通过组合搜索参数搜索到的文件组。 结果集可能比返回的结果集大得多。 如果提交了空查询，则结果集等于集合中的所有文档。

您无权访问的文档不会在查询结果中返回。

答案结果

IBM Cloud find_answers 参数仅在受管部署中受支持。

缺省情况下，Discovery 提供答案时，会返回包含对自然语言查询的答案的整个段落。 当启用了答案查找功能时，Discovery 还会在段落中提供“简短答案”，并提供置信度分数以显示“简短答案”是否回答了用户查询中显式或隐式的问题。 使用答案查找功能的应用程序可以单独显示简短答案，也可以在全文上下文中显示强调的简短答案。 对于大多数应用，显示全文中强调的简短答案更为可取，因为答案通常在上下文中更有意义。

答案发现功能的行为方式如下:

在下面的段落示例中，简短的答案以粗体显示。

• 查找答案。 它不会产生答案。 答案必须是文本的一部分，不能是推断出来的。

  “2022 年 IBM的收入是多少?”如果您有一个文档说明 2022 年 IBM的收入是什么，那么可以得到正确的答案。 但是，如果您有一份文件，上面列出了 IBM 在2022年每个季度的收入，那么它不会将这些收入相加，得出总数。

• 处理同义词和词法变体 (如果答案可用)。

  • 示例问题：“When did IBM purchase Red Hat?”
  • 段落 ：“2019年7月，IBM 完成了对 Red Hat 的340亿美元收购。”

• 如果多个句子紧密地结合在一起 (大约在 2,000 个字符内)，那么将这些句子中的信息组合在一起。

  • 示例问题：“When did IBM purchase Red Hat?”
  • 段落：“IBM 以340亿美元收购了 Red Hat。 The deal closed in July of 2019.”

• 处理隐性问题的思路与处理同等显性问题类似。

  示例问题:

  • company that developed the AS/400
  • What company developed the AS/400?

• 适用于具有较长短语或子句答案的问题。

  • 示例问题：如何煎饼？
  • 诀窍：制作世界一流的煎饼的关键在于正确的翻面。 煎饼的最佳翻转方法是 ：在煎饼下面放一把铲子，将煎饼举到至少4英寸的高度，然后迅速将铲子旋转180度

• 许多有关如何或为什么的问题只能通过非常长的文本段来完整回答。 答案查找功能不会将整个文档作为答案返回 (并且不会汇总文档长度答案)。

• 处理文本中事实性、答案简洁的“是”或“否”问题

  • 示例问题: 廷巴克图中是否有库
  • 段落: 廷巴克图的 主图书馆，正式被称为 Ahmed Baba 高等伊斯兰研究所，是一座藏有超过 20,000 件手稿的宝库，涵盖了几个世纪的马里历史。

• 用简短的答案回答问题，例如姓名和日期，特别是当文本中明确要求提供某种类型的答案时。

• 处理意见问题，但仅限于找到该意见的陈述；它不评估意见的有效性。

  • 示例问题：我应该尝试蓝色眼影吗？
  • 段落：我们认为今年蓝色眼影是流行趋势。

POST /v2/projects/{project_id}/query{
  "natural_language_query": "Why did Nixon resign?",
  "passages": {
    "enabled": true, "find_answers":true
  }
}

{
  "matching_results": 74, "retrieval_details": { "document_retrieval_strategy": "untrained"},
  "results": [
    {
      "document_id": "63919442-7d5b-4cae-ab7e-56f58b1390fe",
      "result_metadata":{"collection_id": "collection_id1234","document_retrieval_source":"search","confidence": 0.78214},
      "metadata": {"parent_document_id": "63919442-7d5b-4cae-ab7e-56f58b1390fg"},
      "title": "Watergate scandal",
      "document_passages": [
        {
          "passage_text": "With his complicity in the cover-up made public and his political support completely eroded, Nixon resigned from office on August 9, 1974. It is believed that, had he not done so, he would have been impeached by the House and removed from office by a trial in the Senate.",
          "field": "text",
          "start_offset": 281,
          "end_offset": 553,
          "answers": [
            {
              "answer_text": "his complicity in the cover-up made public and his political support completely eroded",
              "start_offset": 286, "end_offset": 373, "confidence": 0.78214
            }
          ]
        }
      ]
}

natural_language_query

使用自然语言查询来输入以自然语言表示的查询，如在会话式或自由文本界面 (例如 IBM Watson Assistant) 中从用户接收到的查询。 此参数将整个输入用作查询文本。 它不识别操作员。

自然语言查询的最大查询字符串长度为 2048。

query

查询搜索将按相关性顺序返回数据集内的所有文档，包括完整扩充项和完整文本。 查询还会排除未提及查询内容的所有文档。

aggregation

聚合查询返回与一组数据值匹配的文档数量。 有关聚集选项的完整列表，请参阅 查询聚集。

filter

可高速缓存的查询，用于排除未提及查询内容的所有文档。 过滤器搜索结果不会按相关性顺序返回。

当您编写一个查询，其中同时包含 filter 和 aggregation、query 或 natural_language_query 参数时，filter 参数会先运行，然后任何 aggregation、query 或 natural_language_query 参数会并行运行。

通过简单的查询，尤其是对较小的数据集进行查询时，filter 和 query 参数通常会返回完全相同（或相似）的结果。 如果 filter 和 query 调用返回类似的结果，并且您不需要按相关性顺序返回响应，请使用 filter 参数。 过滤器调用更快且已高速缓存。 缓存意味着下次您拨打相同的电话时，响应速度会更快，尤其是在大数据集的情况下。

结构参数

结构参数用于在返回的 JSON 中定义文档的内容和组织。 结构参数不会影响哪些文档属于整个结果集的一部分。

return

要返回的文档层次结构部分的逗号分隔列表。 任何文档层次结构都是有效的值。 如果此参数是空列表，那么将返回所有字段。

count

您希望在回复中退还的文件数量。 缺省值为 10。 在任一查询中，count 和 offset 值加起来的最大值都为 10000。

offset

要返回的结果集开始的搜索结果位置的索引值。 例如，如果返回的结果总数为 10，而 offset 为 8，那么将返回最后两个结果。 缺省值为 0。 在任何一次查询中，count 和 offset 的最大允许值为 10000。

spell correction

在自然语言查询中，检查针对拼写错误的词汇提交的查询。 将按目前的方式处理该查询。 但是，可能会在响应的 suggested_query 字段中返回对原始查询的更正 (如果存在)。 这些建议不会自动使用，但您的应用程序可以使用这些建议。

sort

按逗号分隔的文档字段列表，用于排序。 您可以选择通过为字段添加 -（表示降序）或 +（表示升序）前缀来指定排序方向。 升序是缺省排序方向。

highlight

一个布尔值，用于指定是否在返回的输出中包含 highlight 对象。 包含时，突出显示将返回作为字段名称的键和作为数组的值。 数组包含使用 HTML 强调 (<em>) 标记突出显示的查询匹配文本的段。

如果 passages.enabled 和 passages.per_document 为 true，那么将忽略此参数，在这种情况下，将针对每个文档返回段落而不是突出显示。

当前，如果查询搜索扩充项提及项的 exact match，那么仅突出显示小写匹配项。 使用 includes 运算符时，将突出显示大写和小写匹配项。

输出将在 highlight 对象后面列出 enriched_text 对象，如以下示例中所示。

curl -H "Authorization: Bearer {token}" \
'https://{hostname}/{instance_name}/v2/projects/{project_id}/collections/{collection_id}/query?version=2019-11-29&natural_language_query=Hybrid%20cloud%20companies&highlight=true'

返回的JSON格式如下：

{
  "highlight": {
    "extracted_metadata.title": [
      "IBM to Acquire Sanovi Technologies to Expand Disaster Recovery Services for <em>Hybrid</em> <em>Cloud</em>"
    ],
    "enriched_text.concepts.text": [
      "Privately held <em>company</em>",
      "<em>Cloud</em> computing"
    ],
    "text": [
      " Sanovi Technologies, a privately held <em>company</em> that provides <em>hybrid</em> <em>cloud</em> recovery, <em>cloud</em> migration",
      "IBM to Acquire Sanovi Technologies to Expand Disaster Recovery Services for <em>Hybrid</em> <em>Cloud</em>\n\nPublished",
      " undergoing digital and <em>hybrid</em> <em>cloud</em> transformation.\n\nURL: http://www.ibm.com/press/us/en/pressrelease/50837.wss",
      " and business continuity software for enterprise data centers and <em>cloud</em> infrastructure. Adding"
    ],
    "enriched_text.categories.label": [
      "/business and industrial/<em>company</em>/bankruptcy"
    ],
    "enriched_text.entities.type": [
      "<em>Company</em>"
    ],
    "html": [
      " Technologies, a privately held <em>company</em> that provides <em>hybrid</em> <em>cloud</em>\n recovery, <em>cloud</em> migration and business",
      " Disaster Recovery Services for <em>Hybrid</em> <em>Cloud</em></title></head>\n<body>\n\n\n<p>Published: Thu, 27 Oct 2016 07:01",
      " digital and <em>hybrid</em> <em>cloud</em> transformation.</p>\n<p>URL: http://www.ibm.com/press/us/en/pressrelease/50837.wss</p>\n\n\n\n</body></html>",
      " continuity software for \nenterprise data centers and <em>cloud</em> infrastructure. Adding these \ncapabilities"
    ]
  }
}

passages

一个布尔值，用于指定服务是否从使用 natural_language_query 参数的查询返回的文件中返回一组最相关的段落。 这些段落是由复杂的 Watson 算法生成的，该算法从查询返回的所有文档中确定最佳文本段落。 参数的缺省值根据您的项目类型而有所不同。 有关缺省值的更多信息，请参阅 缺省查询设置。

Discovery 尝试通过句子边界检测，将句子开头到结尾的段落返回。 为此，它首先搜索大约在 passages.characters 参数 中指定的长度的段落 (对于大多数项目类型，缺省值为 200)。 然后，它将每个段落扩展到指定长度的两倍，以返回完整的句子。 如果您的 passages.characters 参数太短，或者文档中的句子太长，可能没有足够接近的句子边界来返回完整句子，而不会超过所请求长度的两倍。 在这种情况下，Discovery 保持在 passages.characters 参数的两倍以内，因此返回的段落可能不包含整个句子，并且可能省略开头、结尾或两者。

由于句子边界调整扩大了通道大小，平均通道长度可以增加。 如果您的应用程序屏幕空间有限，您可能需要为 passages.characters 设置较小的值，或者截断 Discovery 返回的段落。 语句边界检测适用于所有支持的语言，并使用特定于语言的逻辑。

段落与每个文档结果分组在一起，并按段落相关性进行排序。 在查询中包含段落检索会增加响应时间，因为对段落进行评分需要更多时间。

您可以调整文档中用于段落检索的字段，以使用 passages.fields 参数进行搜索。

passages 参数返回匹配的段落（ passage_text ），score、document_id、提取段落的字段名称（ field ）以及字段中段落的起始和结束字符（ start_offset 和 end_offset ），如下例所示。

 curl -H "Authorization: Bearer {token}" 'https://{hostname}/{instance_name}/v2/projects/{project_id}/collections/{collection_id}/query?version=2019-11-29&natural_language_query=Hybrid%20cloud%20companies&passages=true&passages.per_document=false'

查询返回的JSON格式如下：

  {
    "matching_results":2,
    "passages":[
      {
        "document_id":"ab7be56bcc9476493516b511169739f0",
        "passage_score":15.230205287402338,
        "passage_text":"a privately held company that provides hybrid cloud recovery, cloud migration and business continuity software for enterprise data centers and cloud infrastructure.",
        "start_offset":120,
        "end_offset":300,
        "field":"text"
      },
      {
        "passage_text":"Disaster Recovery Services for Hybrid Cloud</title></head>\n<body>\n\n\n<p>Published: Thu, 27 Oct 2016 07:01:21 GMT</p>\n",
        "passage_score":10.153470191601558,
        "document_id":"fbb5dcb4d8a6a29f572ebdeb6fbed20e",
        "start_offset":70,
        "end_offset":120,
        "field":"html"
      }
    ]
  }

similar

查找与您认为感兴趣的文档类似的文档。 要查找类似文档，Discovery 将识别原始文档中最相关的 25 个术语，然后搜索具有类似相关术语的文档。

如果 similar.enabled 为 true，那么必须指定 similar.document_ids 字段以包含相关文档的逗号分隔列表。

在已安装的部署中，添加了对 4.6.0 发行版的此参数的支持。

table retrieval

如果在集合中启用了 表理解，那么 natural_language_query 将查找内容或上下文与搜索查询匹配的表。

示例查询：

 curl -H "Authorization: Bearer {token}" \
 'https://{hostname}/{instance_name}/v2/projects/{project_id}/collections/{collection_id}/query?version=2019-11-29&natural_language_query=interest%20appraised&table_results=true'

查询返回的JSON格式如下：

{
  "matching_results": 1,
  "session_token": "1_FDjAVkn9SW6oH9y5_9Ek3KsNFG",
  "results": [
    {}
  ]
  {
    "table_results": [
      {
        "table_id": "e883d3df1d45251121cd3d5aef86e4edc9658b21",
        "source_document_id": "c774c3df0c90255191cc0d4bb8b5e8edc6638d96",
        "collection_id": "collection_id",
        "table_html": "html snippet of the table info",
        "table_html_offset": 42500,
        "table": [
          {
            "location": {
              "begin": 42878,
              "end": 44757
          },
          "text": "Appraisal Premise Interest Appraised Date of Value Value Conclusion\nMarket Value \"As Is\" Fee Simple Estate January 12, 2016 $1,100,000\n",
          "section_title": {
            "location": {
              "begin": 42300,
              "end": 42323
            },
            "text": "MARKET VALUE CONCLUSION"
          },
          "title": {},
          "table_headers": [],
          "row_headers": [
            {
              "cell_id": "rowHeader-42878-42896",
              "location": {
                "begin": 42878,
                "end": 42896
              },
              "text": "Appraisal Premise",
              "text_normalized": "Appraisal Premise",
              "row_index_begin": 0,
              "row_index_end": 0,
              "column_index_begin": 0,
              "column_index_end": 0
            }
          ],
          "column_headers": [],
          "body_cells": [
            {
              "cell_id": "bodyCell-43410-43424",
              "location": {
                "begin": 43410,
                "end": 43424
              },
              "text": "Date of Value",
              "row_index_begin": 0,
              "row_index_end": 0,
              "column_index_begin": 2,
              "column_index_end": 2,
              "row_header_ids": [
                "rowHeader-42878-42896",
                "rowHeader-43145-43164"
              ],
              "row_header_texts": [
                "Appraisal Premise",
                "Interest Appraised"
              ],
              "row_header_texts_normalized": [
                "Appraisal Premise",
                "Interest Appraised"
              ],
              "column_header_ids": [],
              "column_header_texts": [],
              "column_header_texts_normalized": [],
              "attributes": []
            }
          ],
          "contexts": [
            {
              "location": {
                "begin": 44980,
                "end": 44996
              },
              "text": "Compiled by CBRE"
            }
          ],
          "key_value_pairs": []
        }
      ]
    }
  ]
}