Go to Qiita Advent Calendar 2024 Top
LoginSignup
5
4

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

More than 1 year has passed since last update.

@to_tomo

IBM Watson Discovery v1 と v2 の API のバージョン間で Request / Response を比較してみました(クエリ関連)

Last updated at Posted at 2022-09-07

はじめに

  • IBM Watson Discovery v1 の非推奨の発表 を受けて、v1 から v2 へのアプリ改修にどの程度のインパクトがありそうか、v1 と v2 の API のバージョン間で Request / Response を比較してみました。
  • 今回は、API バージョンの比較 を参考にクエリ関連にフォーカスしてまとめたいと思います。

前提

調査対象

操作 v1 API v2 API
1. コレクションの照会 関数 query() 関数 query()
2. 複数のコレクションを照会 関数 federated_query() 関数 query()
3. システム通知の照会 関数 query_notices() 関数 query_collection_notices()
4. 複数収集システム通知の照会 関数 federated_query_notices() 関数 query_notices()

サンプルコード: v1 API 、 v2 API

1. コレクションの照会

v1 API の Request / Response

関数 (Request)

query(self,
        environment_id: str,
        collection_id: str,
        *,
        filter: str = None,
        query: str = None,
        natural_language_query: str = None,
        passages: bool = None,
        aggregation: str = None,
        count: int = None,
        return_: str = None,
        offset: int = None,
        sort: str = None,
        highlight: bool = None,
        passages_fields: str = None,
        passages_count: int = None,
        passages_characters: int = None,
        deduplicate: bool = None,
        deduplicate_field: str = None,
        similar: bool = None,
        similar_document_ids: str = None,
        similar_fields: str = None,
        bias: str = None,
        spelling_suggestions: bool = None,
        x_watson_logging_opt_out: bool = None,
        **kwargs
    ) -> DetailedResponse

Response の具体例

以下の Request パラメータを指定した場合

  • "query": "スマートフォン"
  • "filter": "enriched_text.entities.text: パナソニック"
  • "aggregation": "max(enriched_text.entities.confidence)"}
{
  "matching_results": 14,
  "session_token": "1_xmoy1pzIN4aFXWU1YXc6FKmrN6",
  "aggregations": [
    {
      "type": "max",
      "field": "enriched_text.entities.confidence",
      "value": 1
    }
  ],
  "passages": [
    {
      "document_id": "29d2ee189106154050c9e1e801da9111",
      "passage_score": 21.79992871263062,
      "passage_text": "【話題】シニア世代のスマートフォン所有率は４.７％",
      "start_offset": 0,
      "end_offset": 25,
      "field": "title"
    },
    (繰り返しのため省略)
  ],
  "results": [
    {
      "id": "29d2ee189106154050c9e1e801da9111",
      "result_metadata": {
        "confidence": 0.34704432134462687,
        "score": 5.576931
      },
      "file_name": "kaden-channel-5804649.txt",
      "url": "http://news.livedoor.com/article/detail/5804649/",
      "text": "(省略)",
      "date": "2011-08-23T16:00:00+0900",
      "enriched_text": {
        "sentiment": {
          "document": {
            "score": 0.643816,
            "label": "positive"
          }
        },
        "entities": [
          {
            "count": 2,
            "sentiment": {
              "score": 0,
              "label": "neutral"
            },
            "text": "12.6",
            "confidence": 0.96,
            "relevance": 0.831319,
            "type": "Number"
          },
          (繰り返しのため省略)
        ],
        "concepts": [
          {
            "text": "東芝",
            "relevance": 0.956625,
            "dbpedia_resource": "http://ja.dbpedia.org/resource/東芝"
          },
          (繰り返しのため省略)
        ],
        "categories": [
          {
            "score": 0.996412,
            "label": "/technology and computing/consumer electronics/telephones/mobile phones/smart phones"
          },
          {
            "score": 0.778951,
            "label": "/technology and computing/tech news"
          }
        ]
      },
      "category": "kaden-channel",
      "extracted_metadata": {
        "sha1": "62e9929924d9e340b92bf0fe4261803565a19345",
        "filename": "126.json",
        "file_type": "json"
      },
      "title": "【話題】シニア世代のスマートフォン所有率は４.７％"
    }
  ],
  "retrieval_details": {
    "document_retrieval_strategy": "untrained"
  }
}

v2 API の Request / Response

関数 (Request)

query(self,
        project_id: str,
        *,
        collection_ids: List[str] = None,
        filter: str = None,
        query: str = None,
        natural_language_query: str = None,
        aggregation: str = None,
        count: int = None,
        return_: List[str] = None,
        offset: int = None,
        sort: str = None,
        highlight: bool = None,
        spelling_suggestions: bool = None,
        table_results: 'QueryLargeTableResults' = None,
        suggested_refinements: 'QueryLargeSuggestedRefinements' = None,
        passages: 'QueryLargePassages' = None,
        similar: 'QueryLargeSimilar' = None,
        **kwargs
    ) -> DetailedResponse

Response の具体例

以下の Request パラメータを指定した場合

  • "query": "スマートフォン"
  • "filter": "enriched_text.entities.text: パナソニック"
  • "aggregation": "max(enriched_text.entities.confidence)"}
{
  "matching_results": 6,
  "retrieval_details": {
    "document_retrieval_strategy": "untrained"
  },
  "aggregations": [
    {
      "type": "max",
      "field": "enriched_text.entities.mentions.confidence",
      "value": 0.9988022
    }
  ],
  "passages": [
    {
      "passage_text": "【話題】シニア世代のスマートフォン所有率は４.７％",
      "passage_score": 7.928385987689591,
      "document_id": "29d2ee189106154050c9e1e801da9111",
      "collection_id": "4555e469-846e-1cf0-0000-0182b0e7a646",
      "start_offset": 0,
      "end_offset": 25,
      "field": "title"
    },
    (繰り返しのため省略)
  ],
  "results": [
    {
      "document_id": "29d2ee189106154050c9e1e801da9111",
      "result_metadata": {
        "collection_id": "4555e469-846e-1cf0-0000-0182b0e7a646"
      },
      "date": "2011-08-23T16:00:00+0900",
      "enriched_text": [
        {
          "entities": [
            {
              "model_name": "natural_language_understanding",
              "mentions": [
                {
                  "confidence": 0.8,
                  "location": {
                    "end": 31,
                    "begin": 29
                  },
                  "text": "二つ"
                }
              ],
              "text": "二つ",
              "type": "Number"
            },
            (繰り返しのため省略)
          ]
        }
      ],
      "metadata": {
        "parent_document_id": "29d2ee189106154050c9e1e801da9111",
        "customer_id": "IBMid-661003P94Q"
      },
      "extracted_metadata": {
        "sha1": "62E9929924D9E340B92BF0FE4261803565A19345",
        "filename": "126.json",
        "file_type": "json"
      },
      "file_name": "kaden-channel-5804649.txt",
      "text": [
        "(省略)"
      ],
      "title": "【話題】シニア世代のスマートフォン所有率は４.７％",
      "category": "kaden-channel",
      "url": "http://news.livedoor.com/article/detail/5804649/"
    }
  ]
}

比較結果

  • v2 API では、environment の概念はなく、collection は project で編成するように変更されており、関数の引数が異なります。
  • v2 API で単一のコレクションを指定したい場合、collection_ids=["<collection_id>"] のように要素が一つの配列を渡すことで対処することができます。なお、関数 query() の引数に collection_id を含めるだけでは　TypeError: Session.request() got an unexpected keyword argument 'collection_id' というエラーが発生してしまいます。
  • Request パラメータに関して、v1 API と v1 API の差異で大きな変更は以下の表の通りになります。
    v1 API v2 API
    - → 新規追加! table_results: 'QueryLargeTableResults'
    - → 新規追加! suggested_refinements: 'QueryLargeSuggestedRefinements'
    passages: bool , passages_fields: str , passages_count: int , passages_characters: int → passages: 'QueryLargePassages'
    similar: bool , similar_document_ids: str , similar_fields: str → similar: 'QueryLargeSimilar'
    • 上記の表の QueryLargePassages の v1 API と v2 API の対応付けは以下の表の通りになります。
      v1 API v2 API
      passages → passages.enable
      passages_fields → passages.fields
      passages_count → passages.count
      passages_characters → passages.characters
      - → 新規追加! passages.per_document
      - → 新規追加! passages.max_per_document
      - → 新規追加! passages.find_answers
      - → 新規追加! passages.max_answers_per_passage
      • v1 API と同様の挙動にしたい場合は、passages.per_document に False を設定します。
    • 上記の表の QueryLargeSimilar の v1 API と v2 API の対応付けは以下の表の通りになります。
      v1 API v2 API
      similar → similar.enable
      similar_document_ids → similar.document_ids
      similar_fields → similar.fields
  • 他は、Request パラーメータが v2 API にて整理されており、以下のパラメータが廃止されています。
    • deduplicate、deduplicate_field、bias、x_watson_logging_opt_out
  • 「query + filter + aggregation」 と 「natural_language_query + filter + aggregation」 の基本的なパターンで動作確認をしましたが、v1 API と v2 API で同じものを使用できることを確認しました。

2. 複数のコレクションを照会

v1 API の Request / Response

関数 (Request)

federated_query(self,
        environment_id: str,
        collection_ids: str,
        *,
        filter: str = None,
        query: str = None,
        natural_language_query: str = None,
        passages: bool = None,
        aggregation: str = None,
        count: int = None,
        return_: str = None,
        offset: int = None,
        sort: str = None,
        highlight: bool = None,
        passages_fields: str = None,
        passages_count: int = None,
        passages_characters: int = None,
        deduplicate: bool = None,
        deduplicate_field: str = None,
        similar: bool = None,
        similar_document_ids: str = None,
        similar_fields: str = None,
        bias: str = None,
        x_watson_logging_opt_out: bool = None,
        **kwargs
    ) -> DetailedResponse

Response の具体例

以下の Request パラメータを指定した場合

  • "query": "スマートフォン"
  • "filter": "enriched_text.entities.text: パナソニック"
  • "aggregation": "max(enriched_text.entities.confidence)"}
{
  "matching_results": 14,
  "session_token": "1_xmoy1pzIN4aFHvV1YXc6FKmrN6",
  "aggregations": [
    {
      "type": "max",
      "field": "enriched_text.entities.confidence",
      "value": 1
    }
  ],
  "passages": [
    {
      "document_id": "29d2ee189106154050c9e1e801da9111",
      "passage_score": 21.79992871263062,
      "passage_text": "【話題】シニア世代のスマートフォン所有率は４.７％",
      "start_offset": 0,
      "end_offset": 25,
      "field": "title"
    },
    (繰り返しのため省略)
  ],
  "results": [
    {
      "id": "29d2ee189106154050c9e1e801da9111",
      "result_metadata": {
        "confidence": 0.34704432134462687,
        "score": 5.576931
      },
      "file_name": "kaden-channel-5804649.txt",
      "url": "http://news.livedoor.com/article/detail/5804649/",
      "text": "(省略)",
      "date": "2011-08-23T16:00:00+0900",
      "enriched_text": {
        "sentiment": {
          "document": {
            "score": 0.643816,
            "label": "positive"
          }
        },
        "entities": [
          {
            "count": 2,
            "sentiment": {
              "score": 0,
              "label": "neutral"
            },
            "text": "12.6",
            "confidence": 0.96,
            "relevance": 0.831319,
            "type": "Number"
          },
          (繰り返しのため省略)
        ],
        "concepts": [
          {
            "text": "東芝",
            "relevance": 0.956625,
            "dbpedia_resource": "http://ja.dbpedia.org/resource/東芝"
          },
          (繰り返しのため省略)
        ],
        "categories": [
          {
            "score": 0.996412,
            "label": "/technology and computing/consumer electronics/telephones/mobile phones/smart phones"
          },
          (繰り返しのため省略)
        ]
      },
      "category": "kaden-channel",
      "extracted_metadata": {
        "sha1": "62e9929924d9e340b92bf0fe4261803565a19345",
        "filename": "126.json",
        "file_type": "json"
      },
      "title": "【話題】シニア世代のスマートフォン所有率は４.７％"
    }
  ],
  "retrieval_details": {
    "document_retrieval_strategy": "untrained"
  }
}

v2 API の Request / Response

関数 (Request)

query(self,
        project_id: str,
        *,
        collection_ids: List[str] = None,
        filter: str = None,
        query: str = None,
        natural_language_query: str = None,
        aggregation: str = None,
        count: int = None,
        return_: List[str] = None,
        offset: int = None,
        sort: str = None,
        highlight: bool = None,
        spelling_suggestions: bool = None,
        table_results: 'QueryLargeTableResults' = None,
        suggested_refinements: 'QueryLargeSuggestedRefinements' = None,
        passages: 'QueryLargePassages' = None,
        similar: 'QueryLargeSimilar' = None,
        **kwargs
    ) -> DetailedResponse

Response の具体例

「1. コレクションの照会」と同様

比較結果

  • v2 API では、environment の概念はなく、collection は project で編成するように変更されています。
  • v2では1つのプロジェクトに複数のコレクションを作ることができますが、そのような構成をした場合は、関数 query() の collection_ids に複数のコレクションIDを配列で入れることで検索が可能です。従って、v2 API には 関数 federated_query() がありません。
    • 言い換えると、v1 API で 関数 federated_query() を使用している場合、v2 API では 関数 query() の collection_ids に複数のコレクションIDを指定するように変更が必要です。
  • 他は 1. コレクションの照会 の比較結果と同様です。

3. システム通知の照会

v1 API の Request / Response

関数 (Request)

query_notices(self,
        environment_id: str,
        collection_id: str,
        *,
        filter: str = None,
        query: str = None,
        natural_language_query: str = None,
        passages: bool = None,
        aggregation: str = None,
        count: int = None,
        return_: List[str] = None,
        offset: int = None,
        sort: List[str] = None,
        highlight: bool = None,
        passages_fields: List[str] = None,
        passages_count: int = None,
        passages_characters: int = None,
        deduplicate_field: str = None,
        similar: bool = None,
        similar_document_ids: List[str] = None,
        similar_fields: List[str] = None,
        **kwargs
    ) -> DetailedResponse

Response の具体例 (IBM Cloud 資料 | Query > Query system notices より抜粋)

{
  "matching_results": 24,
  "results": [
    {
      "id": "030ba125-29db-43f2-8552-f941ae30a7a8",
      "collection_id": "f1360220-ea2d-4271-9d62-89a910b13c37",
      "code": 200,
      "score": 1,
      "filename": "instructions.html",
      "file_type": "html",
      "sha1": "de9f2c7fd25e1b3afad3e85a0bd17d9b100db4b3",
      "notices": [
        {
          "notice_id": "xpath_not_found",
          "created": "2016-09-20T17:26:17.000Z",
          "document_id": "030ba125-29db-43f2-8552-f941ae30a7a8",
          "severity": "warning",
          "step": "html-to-html",
          "description": "The xpath expression \"boom\" was not found."
        }
      ]
    }
  ],
  "aggregations": {
    "term": {
      "results": [
        {
          "key": "warning",
          "matching_results": 34
        }
      ]
    }
  }
}

v2 API の Request / Response

関数 (Request)

query_collection_notices(self,
        project_id: str,
        collection_id: str,
        *,
        filter: str = None,
        query: str = None,
        natural_language_query: str = None,
        count: int = None,
        offset: int = None,
        **kwargs
    ) -> DetailedResponse

Response の具体例 (IBM Cloud 資料 | Query > Query collection notices より抜粋)

)

{
  "matching_results": 48,
  "notices": [
    {
      "severity": "warning",
      "created": "2021-09-15T20:11:22Z",
      "description": "We couldn't download the requested content from https://www.cdc.gov/coronavirus/2019-ncov/global-covid-19/essential-health-services.html because the request timed out.",
      "step": "conversion",
      "document_id": "9yJk9qKOQ",
      "notice_id": "failed_crawl"
    },
    (繰り返しのため省略)
  ]
}

比較結果

  • v2 API では、environment の概念はなく、collection は project で編成するように変更されており、関数の引数が異なります。
  • Request パラーメータが v2 API にて整理されており、以下の v1 API のパラメータが廃止されています。
    • passages、aggregation、return_、sort、highlight、passages_fields、passages_count、passages_characters、deduplicate_field、similar、similar_document_ids、similar_fields
  • Response のデータ構造に関しても、v2 APIにて整理されており、results を廃止して notices を最上位階層に配置するように変更されています。
  • Request パラーメータとResponse のデータ構造ともに大きな差異があるため改修が必要そうです。

4. 複数収集システム通知の照会

v1 API の Request / Response

関数 (Request)

federated_query_notices(self,
        environment_id: str,
        collection_ids: List[str],
        *,
        filter: str = None,
        query: str = None,
        natural_language_query: str = None,
        aggregation: str = None,
        count: int = None,
        return_: List[str] = None,
        offset: int = None,
        sort: List[str] = None,
        highlight: bool = None,
        deduplicate_field: str = None,
        similar: bool = None,
        similar_document_ids: List[str] = None,
        similar_fields: List[str] = None,
        **kwargs
    ) -> DetailedResponse

Response の具体例 (IBM Cloud 資料 | Query > Query multiple collection system notices より抜粋)

{
{
  "matching_results": 24,
  "results": [
    {
      "id": "030ba125-29db-43f2-8552-f941ae30a7a8",
      "collection_id": "f1360220-ea2d-4271-9d62-89a910b13c37",
      "code": 200,
      "score": 1,
      "filename": "instructions.html",
      "file_type": "html",
      "sha1": "de9f2c7fd25e1b3afad3e85a0bd17d9b100db4b3",
      "notices": [
        {
          "notice_id": "xpath_not_found",
          "created": "2016-09-20T17:26:17.000Z",
          "document_id": "030ba125-29db-43f2-8552-f941ae30a7a8",
          "severity": "warning",
          "step": "html-to-html",
          "description": "The xpath expression \"boom\" was not found."
        }
      ]
    }
  ],
  "aggregations": {
    "term": {
      "results": [
        {
          "key": "warning",
          "matching_results": 34
        }
      ]
    }
  }
}
}

v2 API の Request / Response

関数 (Request)

query_notices(self,
        project_id: str,
        *,
        filter: str = None,
        query: str = None,
        natural_language_query: str = None,
        count: int = None,
        offset: int = None,
        **kwargs
    ) -> DetailedResponse

Response の具体例 (IBM Cloud 資料 | Query > Query collection notices を参考にイメージを手書きで記載)

{
  "matching_results": 48,
  "notices": [
    {
      "severity": "warning",
      "created": "2021-09-15T20:11:22Z",
      "description": "We couldn't download the requested content from https://www.cdc.gov/coronavirus/2019-ncov/global-covid-19/essential-health-services.html because the request timed out.",
      "step": "conversion",
      "document_id": "9yJk9qKOQ",
      "collection_id": "4555e469-846e-1cf0-0000-0182b0e7a646",
      "query_id": "c944292f19e0b285ac17c74b6c377280a4d8ba60",
      "notice_id": "failed_crawl"
    },
    (繰り返しのため省略)
  ]
}

比較結果

  • v2 API では、environment の概念はなく、collection は project で編成するように変更されており、異なるプロジェクトに追加された複数のコレクションを照会することは出来ないところが注意点です。
  • Request パラーメータが v2 API にて整理されており、以下の v1 API のパラメータが廃止されています。
    • aggregation、return_、sort、highlight、deduplicate_field、similar、similar_document_ids、similar_fields
  • Response のデータ構造に関しても、v2 APIにて整理されており、results を廃止して notices を最上位階層に配置するように変更されています。
  • Request パラーメータとResponse のデータ構造ともに大きな差異があるため改修が必要そうです。

終わりに

v1 から v2 へのアプリ改修へのインパクトという点では、以下が主な違いでした。

  • environment から project への構成変更に伴い、引数が変わった
    • 具体的には、 environment_id から project_id に変更
  • 2. 複数のコレクションを照会 〜 4. 複数収集システム通知の照会 は関数名が変わった
  • 1. コレクションの照会 〜 2. 複数のコレクションを照会は passages を　QueryLargePassages クラスや similar を QueryLargeSimilar クラスに纏める形に引数が変わった
  • さらに 3. システム通知の照会 と 4. 複数収集システム通知の照会 は Request パラーメータが多数廃止され、Response のデータ構造も変わった
  • 補足事項
    • 1. コレクションの照会 、2. 複数のコレクションを照会 の passages に関しては、v1 と同様の挙動にしたい場合は、passages.per_document に False を設定することで対処が出来ます。v2 で廃止されている Request パラメータに関しても、先ずは使用有無を確認しておくと良いでしょう。
    • v1 API では複数のコレクションに対して照会を実行する場合は、関数 federeated_query() を使用しますが、v2 API では1つのプロジェクトに複数のコレクションを作ることができるので、v2 API では照会対象のコレクションを全て同じプロジェクトに作れば、関数 query() 一本で済みます。ただし、v1 API で関連性トレーニングを実施しているコレクションを複数照会している場合は注意点です。v1 API ではコレクション単位で関連性トレーニングのモデルができます。v2 API ではプロジェクト単位で関連性トレーニングのモデルができます。したがって、v1 API で複数のコレクションがあり、かつ、それぞれ関連性トレーニングを実施していて、かつ、関数 federated_query() でまとめて照会している場合、v2 API ではプロジェクト対コレクションを１対１にして、プロジェクト毎に 関数 query() を実行する必要がありそうです。
    • その他 v1 と v2 の機能比較については こちら を参照してください。

なお、v2ではプロジェクトの中にコレクションを作る構成になりましたが、v1から移行する場合は、プロジェクト対コレクションの関係を １:１ にすると移行がシンプルになると思います。

参考

お断り

このサイトの掲載内容は私自身の見解であり、必ずしも所属会社の立場、戦略、意見を代表するものではありません。 記事は執筆時点の情報を元に書いているため、必ずしも最新情報であるとはかぎりません。 記事の内容の正確性には責任を負いません。自己責任で実行してください。

5
4
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
5
4

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?