検索パラメーター

検索パラメーターを使用して、コレクションを検索し、結果セットを識別し、結果セットを分析します。

検索結果セットとは、検索パラメータの組み合わせによる検索で特定された文書のグループです。 結果セットは、返された結果より大幅に大きい可能性があります。 空のクエリが送信された場合、結果セットはコレクション内のすべてのドキュメントに等しくなります。

アクセスする権限がない文書は、照会結果で返されません。

回答の検出

IBM Cloud find_answers パラメーターは、管理対象デプロイメントでのみサポートされます。

Discovery はデフォルトで、自然言語照会に対する答えが含まれているパッセージ全体を返すことによって答えを提供します。 回答検出機能が有効になっている場合、 Discovery は、パッセージ内の「短い回答」と、「短い回答」がユーザー照会内の明示的な質問に回答するか暗黙的な質問に回答するかを示す信頼性スコアも提供します。 回答検索機能を使用するアプリケーションでは、短い回答のみを表示することも、全文脈の中で強調された短い回答を表示することもできます。 ほとんどの用途では、短い回答を全文の中で強調して表示することが望ましい。なぜなら、回答は一般的に文脈の中でより意味をなすからである。

回答の検索機能は、以下のように動作します。

以下の一節の例では、短い回答が太字フォントで示されています。

• 回答を検索します。 回答は作成されません。 答えはテキストの一部である必要があり、答えの推測はできません。

  「2022年の IBM の収益はいくらだったか？」という質問には、2022年の IBM の収益が記載された文書があれば、正しい答えを得ることができます。 しかし、 IBM の2022年の各四半期の収益が記載された文書があったとしても、それらを合計して合計額を出すことはできません。

• 回答が使用可能な場合は、同義語および字句のバリエーションを処理します。

  • 質問の例: “When did IBM purchase Red Hat?”
  • 引用：「 IBM は 2019年7月、 Red Hat の340億ドルでの買収を完了した。」

• 複数のセンテンスが近い (約 2,000 文字以内) 場合に、それらのセンテンス間で情報を結合します。

  • 質問の例: “When did IBM purchase Red Hat?”
  • 引用：「 IBM は Red Hat を340億ドルで買収した。 The deal closed in July of 2019."

• 暗黙的な質問を、同等の明示的な質問を処理する方法と同様に処理します。

  質問の例:

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

• Works well with questions with longer phrase or clause answers.

  • 例題：パンケーキをひっくり返すにはどうすればいいですか？
  • 本文：世界トップクラスのパンケーキを作るには、上手にひっくり返すことが重要です。 パンケーキを上手にひっくり返すには、まずフライ返しをパンケーキの下に差し込み、少なくとも4インチ（約10cm）持ち上げてから、フライ返しを素早く180度回転させるのが一番です

• 方法や理由を尋ねる質問に対する完全な答えは、ほとんどの場合、長いテキストになります。 回答検出機能は、回答として文書全体を返しません (また、文書の長さの回答は要約しません)。

• テキスト内に簡潔な回答がある事実に基づく「はい」または「いいえ」の質問を処理します

  • 質問例: Timbuktu にライブラリーがあるかどうか
  • パッセージ: Timbuktu の メイン・ライブラリー (公式には Ahmed Baba Institute of 高等イスラム研究所と呼ばれる) は、マリの歴史をカバーする 2 万以上の原稿を含む宝庫です。

• 名前や日付など、非常に短い回答で済む質問を処理します。特に、求められている回答の種類がテキストで明確に示されている場合。

• 意見に関する質問には対応しますが、その意見の妥当性を評価するものではありません。意見の表明を見つけることによってのみ対応します。

  • 例題：青いアイシャドウを試してみるべきでしょうか？
  • 抜粋：今年は青いアイシャドウがトレンドになると思います。

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 です。 1 つの任意の照会で count 値と offset 値を合わせた場合の最大値は 10000 です。

offset

返される結果のセットが開始される検索結果の位置の索引値。 例えば、返される結果の総数が 10 で、オフセットが 8 の場合は、最後の 2 つの結果が返されます。 デフォルトは 0 です。 1つのクエリで 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 です)。 次に、各通路を指定された長さの2倍まで拡張し、完全な文章を返します。 passages.characters パラメータが短い場合、または文書内の文が長い場合、リクエストされた長さの2倍を超えずに完全な文を返すのに十分近い文の区切りがない可能性があります。 その場合、 Discovery は passages.characters パラメータの2倍の制限内に収まるため、返される文章は文全体を含んでいない可能性があり、冒頭や末尾、あるいはその両方が省略される場合があります。

センテンス境界調整によってパッセージ・サイズが拡張されるため、平均パッセージ長が増加する可能性があります アプリケーションの画面スペースが限られている場合は、 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

コレクションで 「表の理解(Table understanding)」 が有効になっている場合、 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": []
        }
      ]
    }
  ]
}