검색 매개변수

검색 매개변수를 사용하여 컬렉션을 검색하고, 결과 집합을 식별하고, 결과 집합을 분석할 수 있습니다.

결과 집합 은 검색 매개변수의 결합된 검색으로 식별된 문서 그룹입니다. 결과 세트는 리턴된 결과보다 훨씬 더 클 수 있습니다. 빈 쿼리가 제출되면 결과 집합은 컬렉션의 모든 문서와 동일합니다.

액세스 권한이 없는 문서는 쿼리 결과에서 반환되지 않습니다.

답변 찾기

IBM Cloud find_answers 매개 변수는 관리형 배포에서만 지원됩니다.

기본적으로 Discovery는 자연어 조회에 대한 응답이 포함된 전체 단락을 리턴하여 응답을 제공합니다. 답변 찾기 기능이 활성화된 경우 Discovery에서는 구절 내의 '짧은 답변'과 '짧은 답변'이 사용자 쿼리에 명시적으로 또는 암시적으로 질문에 대한 답변인지를 보여주는 신뢰도 점수도 제공합니다. 답 찾기 기능을 사용하는 애플리케이션은 짧은 답을 단독으로 표시하거나 전체 문맥에서 강조된 짧은 답을 표시할 수 있습니다. 대부분의 응용 프로그램의 경우, 전체 문장 내에서 강조된 짧은 답을 표시하는 것이 더 바람직합니다. 왜냐하면 답이 문맥상 더 이해하기 쉽기 때문입니다.

답 찾기 기능은 다음과 같은 방식으로 작동합니다:

다음 지문의 예에서 짧은 답은 굵은 글꼴로 표시되어 있습니다.

• 답을 찾습니다. 답을 만들어내지는 않습니다. 응답은 텍스트의 일부여야 하며 유추할 수는 없습니다.

  " IBM 의 2022년 매출은 얼마였습니까?"라는 질문에 대한 정확한 답을 얻으려면 2022년 IBM 의 매출이 얼마였는지를 명시한 문서가 있어야 합니다. 그러나 2022년 각 분기의 IBM 의 수익을 나열한 문서가 있다면, 그것을 합산하여 총액을 알려주지는 않습니다.

• 답을 사용할 수 있는 경우 동의어 및 어휘 변형을 처리합니다.

  • 질문 예: “언제 IBM이 Red Hat을 인수했습니까?”
  • Passage: "IBM은 Red Hat에서 340억 달러 규모의 2019년 7월 인수를 완료했습니다."

• 여러 문장이 서로 가까운 경우(약 2,000자 이내) 여러 문장에 걸쳐 있는 정보를 결합합니다.

  • 질문 예: “언제 IBM이 Red Hat을 인수했습니까?”
  • 구절: " IBM 이 340억 달러에 Red Hat 를 인수했습니다. 계약은 2019년 7월에 체결되었습니다."

• 암묵적 질문에 대해 명시적 질문에 대해 처리하는 방식과 유사한 방식으로 처리합니다.

  질문 예시:

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

• 긴 문구 또는 절의 답변이 있는 질문에 적합합니다.

  • 예시 질문: 팬케이크를 뒤집는 방법은 무엇입니까?
  • 구절: 세계 최고 수준의 팬케이크를 만드는 비결은 팬케이크를 제대로 뒤집는 것입니다. 팬케이크를 뒤집는 가장 좋은 방법은 팬케이크 밑에 주걱을 꽂고, 팬케이크를 공중으로 최소 10cm 정도 들어 올린 다음, 주걱을 빠르게 180도 회전시키는 것입니다

• 더욱 긴 텍스트를 사용하여 방법 또는 이유에 대한 여러 가지 질문을 해야 완벽한 응답이 제공됩니다. 답변 찾기 기능은 전체 문서를 답변으로 반환하지 않으며, 문서 길이의 답변을 요약하지도 않습니다.

• 사실에 근거하고 텍스트에 간결한 답변이 있는 예 또는 아니요 질문을 처리합니다

  • 질문 예시: 팀북투에 도서관이 있나요?
  • Passage: 팀북투의 주요 도서관인 아메드 바바 고등 이슬람학 연구소는 말리의 수세기 역사를 아우르는 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입니다. 하나의 조회에 count 및 offset을 함께 사용할 경우 최대값은 10000입니다.

offset

반환할 결과 집합이 시작되는 검색 결과의 위치의 인덱스 값입니다. 예를 들어, 리턴된 총 결과 수가 10이고 오프셋이 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": []
        }
      ]
    }
  ]
}