はじめに

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

前提

Watson Developer Cloud Python SDK を使用した確認になります。
Python のバージョンは 3.10.4 です。

調査対象

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

以下は、Cloud Pak 版のみ有効であるため調査対象外にしています。

操作 v1 API v2 API

5. オートコンプリート候補の取得関数 get_autocompletion() 関数 get_autocompletion()

操作	v1 API	v2 API
5. オートコンプリート候補の取得	関数 get_autocompletion()	関数 get_autocompletion()

サンプルコード: 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 で同じものを使用できることを確認しました。

v1 API		v2 API
`similar`	→	`similar.enable`
`similar_document_ids`	→	`similar.document_ids`
`similar_fields`	→	`similar.fields`

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から移行する場合は、プロジェクト対コレクションの関係を１:１にすると移行がシンプルになると思います。

参考

お断り

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

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

はじめに

前提

調査対象

1. コレクションの照会

v1 API の Request / Response

関数 (Request)

Response の具体例

v2 API の Request / Response

関数 (Request)

Response の具体例

比較結果

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

v1 API の Request / Response

関数 (Request)

Response の具体例

v2 API の Request / Response

関数 (Request)

Response の具体例

比較結果

3. システム通知の照会

v1 API の Request / Response

関数 (Request)

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

v2 API の Request / Response

関数 (Request)

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

比較結果

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

v1 API の Request / Response

関数 (Request)

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

v2 API の Request / Response

関数 (Request)

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

比較結果

終わりに

参考

お断り