以前のバージョンからセマンティック ランク付けコードを移行する
セマンティック ランク付けコードが初期のプレビュー API に対して書かれたものである場合、この記事では新しい API バージョンに移行するために必要なコード変更を特定します。 セマンティック ランカーの破壊的変更は、最近の API におけるクエリ ロジックに制限されていますが、お使いのコードが最初のプレビュー バージョンに対して書かれたものであれば、セマンティック構成も変更する必要がある場合があります。
重大な変更
REST API のバージョン間で、セマンティック ランカーには次のような 2 つの変更点があります。
searchFieldsは 2021-04-30-preview でsemanticConfigurationに置き換えられましたqueryLanguageは 2023-07-01-preview で無視されましたが、2024-11-01-preview でクエリ書き換えのために復元されました
その他のバージョン固有の更新情報は新しい機能に関するものですが、既存のコードを大きく変更するものではありません。
Azure SDK を使用している場合、複数の API は時間の経過とともに名前が変更されています。 SDK の変更ログに詳細が記載されています。
セマンティック ランク付けを提供する API バージョン
REST API バージョンまたは SDK パッケージ バージョンのコードを確認し、どちらがセマンティック ランク付けを提供しているかを確認します。 次の API バージョンでは、セマンティック ランク付けがある程度サポートされています。
| リリースの種類 | REST API バージョン | セマンティック ランカーの更新 |
|---|---|---|
| イニシャル | 2020-06-30-preview | queryType=semantic をドキュメントの検索に追加する |
| preview | 2021-04-30-preview | semanticConfiguration をインデックスの作成または更新に追加する |
| preview | 2023-07-01-preview | semanticConfiguration を更新します。 Microsoft がホストするセマンティック モデルに対して、2023 年 7 月 14 日以降、セマンティック ランカーは言語に依存しなくなり、queryLanguage プロパティはセマンティック ランク付けに対して実質的に使用停止になりました。 コードに破壊的変更はありませんが、プロパティは無視されます。 お客様にはこのプロパティをコードから削除することがお勧めされました。 |
| preview | 2023-10-01-preview | semanticQuery を追加し、再ランク付けにのみ使用するクエリを送信します。 |
| stable | 2023-11-01 | 一般提供されています。 安定バージョンに進行する semanticConfiguration への変更を導入します。 お使いのコードがこのバージョンかそれ以降をターゲットにしている場合、新しいプレビュー機能を導入しない限りは新しい API バージョンと互換性があります。 |
| preview | 2024-05-01-preview | 変更なし |
| stable | 2024-07-01 | 変更なし |
| preview | 2024-09-01-preview | 変更なし |
| preview | 2024-11-01-preview | クエリの書き換えを追加します。 クエリの書き換え (プレビュー) を使用する場合は、queryLanguage プロパティが必須になりました。 |
Azure SDK の変更ログ
Azure SDK は独立したリリース スケジュールになっています。 どのパッケージでセマンティック機能が提供され、どの API の名前が変更されたかを確認するために、変更ログを確認する必要があります。
- Azure SDK for .NET の変更ログ
- Azure SDK for Python の変更ログ
- Azure SDK for Java の変更ログ
- Azure SDK for JavaScript の変更ログ
2024-11-01-preview
2024-09-01-preview
2024-07-01 安定バージョンからセマンティック ランク付け構文への変更はありません。
2024-07-01
2024-05-01-preview バージョンからセマンティック ランク付け構文への変更はありません。
この API バージョンは使用しないでください。 これは、新しい API バージョンと互換性のないベクトル クエリ構文を実装しています。
2024-05-01-preview
2024-03-01-preview バージョンからセマンティック ランク付け構文への変更はありません。
2024-03-01-preview
2023-10-01-preview バージョンからセマンティック ランク付け構文への変更はありませんが、ベクトル クエリが導入されました。 セマンティック ランク付けは、ハイブリッド クエリやベクトル クエリからの応答にも適用されるようになりました。 フィールドが prioritizedFields に一覧表示されているとして、応答の中で人間が判読できるテキスト フィールドに再ランク付けを適用できます。
2023-11-01
SemanticDebugとsemanticQueryを除いて、それ以外は 2023-10-01-preview バージョンと同じです。
2023-10-01-preview
semanticQueryを追加
2023-07-01-preview
semanticErrorHandling、semanticMaxWaitInMillisecondsが追加されます。SemanticDebugやSemanticErrorModeなど、セマンティックに関連する多数のフィールドが応答に追加されます。queryLanguageは無視され、セマンティックランク付けでは使用されなくなります。
2023 年 7 月 14 日以降、セマンティック ランカーは言語に依存しなくなります。 プレビュー バージョンでは、セマンティック ランク付けによってフィールド アナライザーで指定された querylanguage とは異なる結果の優先度が下がります。 ただし、queryLanguage プロパティは、スペル修正とその機能でサポートされている短い言語の一覧には引き続き適用できます。
2021-04-30-preview
- セマンティック サポートは、[ドキュメントの検索] と [インデックスを作成または更新] プレビュー API 呼び出しを通して行われます。
- 検索インデックスに
semanticConfigurationを追加します。 セマンティック構成には、名前と優先順位が設定されたフィールド リストがあります。 - ``prioritizedFields` を追加します。
searchFields プロパティはフィールドの優先順位付けには使われなくなります。 今後すべてのバージョンで、semanticConfiguration.prioritizedFields は L2 ランク付けに使用するフィールドを指定するためのメカニズムとして searchFields を置き換えます。
2020-06-30-preview
- セマンティック サポートは、[ドキュメントの検索] プレビュー API 呼び出しを通して行われます。
queryType=semanticをクエリ要求の料金に追加します。- クエリの種類がセマンティックである場合、
searchFieldsプロパティがセマンティック ランカーへのフィールド入力の優先順位を決定するようにsearchFieldsに適応します。 - クエリ応答に
captions、answers、highlightsを追加します。
次のステップ
セマンティック クエリを実行して、セマンティック構成移行をテストします。