Note
Azure AI 検索は、Azure ポータル、REST API、およびAzure SDKから使用できます。 また、Foundry IQ は、エンタープライズ コンテンツを、Microsoft Foundry ポータルのエージェントの再利用可能なアクセス許可に対応したナレッジ ベースに変換するマネージド ナレッジ レイヤーです。
セマンティック ランク付けコードが初期のプレビュー 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 バージョン | セマンティック ランカーの更新 |
|---|---|---|
| Initial | 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 を追加し、再ランク付けにのみ使用するクエリを送信します。 |
| 安定 | 2023-11-01 | 一般提供されています。 安定バージョンに進行する semanticConfiguration への変更を導入します。 お使いのコードがこのバージョンかそれ以降をターゲットにしている場合、新しいプレビュー機能を導入しない限りは新しい API バージョンと互換性があります。 |
| Preview | 2024-05-01-preview | 変更なし。 |
| 安定 | 2024-07-01 | 変更なし。 |
| Preview | 2024-09-01-preview | 変更なし。 |
| Preview | 2024-11-01-preview | クエリの書き換えを追加します。
queryLanguage プロパティは、クエリの書き換え（プレビュー） を使用する場合に必須となりました。 |
| Preview | 2025-03-01-preview | セマンティック モデルのプレリリース バージョンにオプトインを追加します。 |
| Preview | 2025-05-01-プレビュー | このプレビューでは API は更新されませんが、セマンティック ランク付 けによってスコアリング プロファイルとの統合が向上しました。 |
| Preview | 2025-08-01-preview | 変更なし。 |
| 安定 | 2025-09-01 | 変更なし。 |
| Preview | 2025-11-01-プレビュー | 無料ティアで使えます。 |
| 安定 | 2026-04-01 | セマンティック ランカーとエージェント型検索に関する課金同意を分離します。
semanticSearch は現在、セマンティック ランカーの課金のみを制御します。 アップグレードする前に、 semanticSearch=standardがある場合は、 knowledgeRetrieval=standardも設定する必要があります。 詳細については、「 セマンティック ランカーの課金を有効または無効にする」を参照してください。 |
| Preview | 2026-05-01-プレビュー | 変更なし。 |
Azure SDK の変更ログ
特定の Azure SDK パッケージで使用できるセマンティック機能と、API の名前が変更されたかどうかを確認するには、SDK の変更ログを参照してください。
- 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年7月1日
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-プレビュー
-
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を追加します。
次のステップ
セマンティック クエリを実行して、セマンティック構成移行をテストします。