Parâmetros de procura

Use parâmetros de pesquisa para pesquisar sua coleção, identificar um conjunto de resultados e analisar o conjunto de resultados.

O conjunto de resultados é o grupo de documentos identificados pelas pesquisas combinadas dos parâmetros de pesquisa. O conjunto de resultados pode ser significativamente maior do que os resultados retornados. Se uma consulta vazia for enviada, o conjunto de resultados será igual a todos os documentos da coleção.

Os documentos que você não tem permissões para acessar não são retornados em resultados de consulta.

Localização da resposta

IBM Cloud O parâmetro find_answers é suportado apenas em implementações gerenciadas.

Por padrão, o Discovery fornece respostas ao retornar a passagem inteira que contém a resposta para uma consulta de linguagem natural. Quando o recurso de localização da resposta estiver ativado, Discovery também fornece uma "resposta curta" dentro da passagem, e uma pontuação de confiança para mostrar se a "resposta curta" responde a pergunta que está explícita ou implícita na consulta do usuário. Os aplicativos que usam o recurso de busca de respostas podem exibir apenas a resposta curta ou podem exibir a resposta curta enfatizada no contexto da passagem completa. Para a maioria dos aplicativos, é preferível exibir a resposta curta enfatizada na passagem completa, pois as respostas geralmente fazem mais sentido no contexto.

O recurso de localização da resposta se comporta das seguintes formas:

Nos exemplos de passagem que se seguem, as respostas curtas são mostradas em fonte ousada.

• Encontra respostas. Isso não cria respostas. A resposta deve ser parte do texto; ela não pode ser inferida.

  "O que foi a receita da IBMem 2022?" pode obter uma resposta correta se você tiver um documento que afirma o que a receita da IBMfoi em 2022. No entanto, se você tiver um documento que liste qual foi a receita da IBM em cada trimestre de 2022, ele não os somará e fornecerá um total.

• Manipula sinônimos e variações lexicais se a resposta estiver disponível.

  • Pergunta de exemplo: "Quando a IBM comprou o Red Hat?"
  • Passagem: " IBM fechou sua aquisição de US$ 34 bilhões da Red Hat em julho de 2019."

• Combina informações através de várias sentenças se elas estiverem próximas juntas (dentro de aproximadamente 2.000 caracteres).

  • Pergunta de exemplo: "Quando a IBM comprou o Red Hat?"
  • Passagem: " A IBM adquiriu a Red Hat por US$ 34 bilhões. O acordo foi fechado em julho de 2019".

• Trata as perguntas implícitas da mesma forma que trataria a pergunta explícita equivalente.

  Perguntas de exemplo:

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

• Funciona bem com perguntas com frases mais longas ou respostas de cláusula.

  • Exemplo de pergunta: Como faço para virar uma panqueca?
  • Passagem: O segredo para obter uma panqueca de primeira qualidade é virá-la corretamente. A melhor maneira de virar uma panqueca é enfiar uma espátula embaixo dela, levantá-la pelo menos 5 cm no ar e girar rapidamente a espátula em 180 graus.

• Muitas perguntas sobre como ou o motivo são respondidas totalmente por textos muitos longos. O recurso de localização da resposta não retorna um documento inteiro como a resposta (e não se resume uma resposta de comprimento de documento).

• Lida com perguntas de sim ou não que são factuais e têm uma resposta concisa no texto

  • Pergunta de exemplo: Existe uma biblioteca em Timbuktu
  • Passagem: A biblioteca principal de Timbuktu , oficialmente chamada de Ahmed Baba Institute of Higher Islâmico Studies and Research, é uma casa de tesouros que contém mais de 20.000 manuscritos que cobrem séculos da história do Mali.

• Lida com perguntas com respostas muito curtas, como nomes e datas, especialmente quando o tipo de resposta exigida está explícito no texto.

• Lida com questões de opinião, mas apenas encontrando uma declaração dessa opinião; não avalia a validade da opinião.

  • Exemplo de pergunta: Devo experimentar uma sombra azul?
  • Passagem: Achamos que a sombra azul está na moda este ano.

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

Use uma consulta de língua natural para inserir consultas que são expressas em língua natural, como podem ser recebidas de um usuário em uma interface de conversação ou de texto livre, como IBM Watson Assistant O parâmetro usa a entrada inteira como o texto da consulta. Ele não reconhece os operadores.

O comprimento máximo da sequência de consultas para uma consulta de língua natural é 2048.

query

Uma consulta de procura retorna todos os documentos em seu conjunto de dados com enriquecimentos completos e texto completo em ordem de relevância. Uma consulta também exclui quaisquer documentos que não mencionem o conteúdo da consulta.

aggregation

As consultas de agregação retornam uma contagem de documentos que correspondem a um conjunto de valores de dados. Para a lista completa de opções de agregação, consulte agregações de consultas.

filter

Uma consulta armazenável em cache que exclui quaisquer documentos que não mencionem o conteúdo da consulta. Os resultados da procura de filtro não são retornados em ordem de relevância.

Quando você escreve uma consulta que inclui um parâmetro filter e um aggregation, query ou natural_language_query, o parâmetro filter é executado primeiro e, em seguida, todos os parâmetros aggregation, query ou natural_language_query são executados em paralelo.

Com uma consulta simples, especialmente em um conjunto de dados pequeno, os parâmetros filter e query geralmente retornam exatamente os mesmos resultados (ou resultados semelhantes). Se as chamadas filter e query retornam resultados semelhantes, e você não precisa das respostas a serem retornadas em ordem de relevância, use o parâmetro filter. As chamadas de filtro são mais rápidas e são cachos. O armazenamento em cache significa que, na próxima vez que você fizer a mesma chamada, obterá uma resposta muito mais rápida, principalmente em um conjunto de dados grandes.

Parâmetros de estrutura

Os parâmetros de estrutura definem o conteúdo e a organização dos documentos no JSON retornado. Os parâmetros de estrutura não afetam quais documentos fazem parte do conjunto de resultados inteiro.

return

Uma lista separada por vírgula das parte da hierarquia de documentos a serem retornados. Qualquer uma das hierarquias de documentos é um valor válido. Se este parâmetro for uma lista vazia, então todos os campos são retornados.

count

O número de documentos que você deseja retornar na resposta. O padrão é 10. O máximo para os valores count e offset juntos em qualquer consulta é 10000.

offset

Valor do índice da posição do resultado da pesquisa onde começa o conjunto de resultados a retornar. Por exemplo, se o número total de resultados que são retornados for 10 e o deslocamento for 8, ele retornará os dois últimos resultados. O padrão é 0. O valor máximo permitido para count e offset juntos em qualquer consulta é 10000.

spell correction

Em consultas de linguagem natural, verifica a consulta que é enviada para termos digitados. A consulta é processada como-é. No entanto, prováveis correções na consulta original, se existir alguma, são retornadas no campo suggested_query da resposta. As sugestões não são usadas automaticamente, mas o seu aplicativo pode fazer uso delas.

sort

Uma lista separada por vírgulas de campos no documento para classificação. É possível, opcionalmente, especificar uma direção de classificação prefixando o campo com - para ordem decrescente ou + para ordem crescente. A ordem crescente é a direção de classificação padrão.

highlight

Um valor booleano que especifica se deve incluir um objeto highlight na saída devolvida. Quando incluído, o destaque retorna chaves que são nomes de campo e valores que são matrizes. As matrizes contêm segmentos de texto de correspondência de consulta que é destacado usando a tag ênfase HTML (<em>).

Esse parâmetro é ignorado se passages.enabled e passages.per_document são true, em quais passagens de caso são retornadas para cada documento em vez de destaques.

Atualmente, se a consulta procura um exact match de uma menção de enriquecimento, apenas as minúsculas correspondências são destacadas. Quando o operador includes é usado, as correspondências superior e minúsculas são destacadas.

A saída lista o objeto highlight após o objeto enriched_text, conforme mostrado no exemplo a seguir.

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'

O JSON que é retornado tem o seguinte formato:

{
  "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

Um booleano que especifica se o serviço retorna um conjunto das passagens mais relevantes dos documentos que são retornados por uma consulta que usa o parâmetro natural_language_query. Os trechos são gerados por algoritmos Watson sofisticados que determinam os melhores trechos de texto de todos os documentos retornados pela consulta. O valor padrão para o parâmetro difere baseado em seu tipo de projeto. Para obter mais informações sobre os valores padrão, consulte Configurações de consulta padrão.

Discovery tenta retornar passagens que começam no início de uma frase e param no final, usando a detecção de limite de frase. Para isso, ele primeiro busca passagens aproximadamente o comprimento especificado no parâmetro passages.characters (para a maioria dos tipos de projeto, o padrão é 200). Em seguida, ele expande cada passagem até o limite de duas vezes o comprimento especificado, de modo a retornar frases completas. Se o parâmetro passages.characters for curto ou se as frases dos documentos forem longas, talvez não haja limites de frases próximos o suficiente para retornar a frase completa sem ultrapassar o dobro do tamanho solicitado. Nesse caso, Discovery permanece dentro do limite de duas vezes o parâmetro passages.characters, de modo que as passagens retornadas podem não incluir a frase inteira e podem omitir o início, o fim ou ambos.

Como os ajustes limites de sentença expandem o tamanho da passagem, o comprimento médio de passagem pode aumentar. Se o seu aplicativo tiver espaço limitado na tela, talvez você queira definir um valor menor para passages.characters ou truncar os trechos retornados por Discovery. A detecção de limite de sentença funciona para todos os idiomas suportados e usa a lógica específica do idioma.

As passagens são agrupadas com cada resultado do documento e são ordenadas por relevância de passagem. Incluir a recuperação de passagem em consultas aumenta o tempo de resposta porque é preciso mais tempo para pontuar as passagens.

Você pode ajustar os campos nos documentos para recuperação de passagem para pesquisar com o parâmetro passages.fields.

O parâmetro passages retorna as passagens correspondentes ( passage_text ), e os parâmetros score, document_id, o nome do campo do qual a passagem foi extraída ( field ) e os caracteres iniciais e finais do texto da passagem dentro do campo ( start_offset e end_offset ), conforme mostrado no exemplo a seguir.

 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'

O JSON que é retornado da consulta tem o seguinte formato:

  {
    "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

Encontra documentos que são semelhantes a documentos que você identifica como sendo de seu interesse. Para encontrar documentos semelhantes, Discovery identifica os 25 termos mais relevantes do documento original e, em seguida, procura documentos com termos relevantes semelhantes.

Se similar.enabled for true, você deve especificar o campo similar.document_ids para incluir uma lista separada por vírgula dos documentos de interesse.

Em implementações instaladas, o suporte para esse parâmetro foi incluído com a liberação 4.6.0

table retrieval

Se a compreensão da tabela estiver ativada em sua coleção, um natural_language_query encontra tabelas com conteúdo ou contexto que correspondem a uma consulta de pesquisa.

Consulta de exemplo:

 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'

O JSON que é retornado da consulta tem o seguinte formato:

{
  "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": []
        }
      ]
    }
  ]
}