Azure SDK documentation update: [Search] Refresh azure-search-documents samples for 2026-04-01 GAは、Azure AI SearchをPython SDKで扱う開発者に向けた「サンプル刷新」の更新です。結論から言うと、既存の本番アプリがこの更新だけで自動的に壊れるわけではありません。ただし、azure-search-documents 12.0.0、Knowledge Source、Knowledge Base、agentic retrieval、ベクトル検索サンプルを使っている場合は、サンプルの参照先と実装パターンを見直すべきです。GitHubのPR #46677では、Knowledge Source / Knowledge BaseのCRUDサンプル追加、sample_agentic_retrievalの役割変更、hotels-sample-*命名への統一、ベクトル検索サンプルの初回クエリ安定化が行われています。(GitHub)
Azure SDK documentation updateでまず押さえる結論
今回のAzure SDK documentation updateは、Azure SDK for Pythonのazure-search-documentsサンプルを、2026-04-01 GAのAPI面に合わせて整理する更新です。PR上では12ファイルが変更され、Knowledge Source / Knowledge BaseのCRUD、agentic retrieval、インデックスエイリアス、インデクサーデータソース、ベクトル検索サンプルが対象になっています。(GitHub)
特に重要なのは、sample_agentic_retrieval.pyが「CRUDを全部学ぶサンプル」ではなく、「Knowledge SourceとKnowledge Baseをセットアップして取得し、最後に片付けるエンドツーエンドの流れを確認するサンプル」に寄せられた点です。CRUDの細かい操作は、新しく追加されたsample_knowledge_source_crud.pyとsample_knowledge_base_crud.pyを見る構成になりました。(GitHub)
今回の更新で変わった内容
| 変更点 | 影響する人 | 確認すべきこと |
|---|---|---|
sample_knowledge_source_crud.py / _async.pyを追加 | Knowledge Sourceをコードで作成・更新・削除したい人 | 既存インデックス名、セマンティック構成、認証情報を確認する |
sample_knowledge_base_crud.py / _async.pyを追加 | Knowledge Baseをコードで管理したい人 | 先にKnowledge Sourceが存在しているか確認する |
sample_agentic_retrieval.py / _async.pyを再整理 | agentic retrievalを試している人 | CRUD目的ではなく、取得フロー確認用として読む |
hotels-sample-*命名に統一 | サンプルをコピーして検証環境を作る人 | 自社環境の命名規則に置き換える |
sample_query_vector.py / _async.pyで初回クエリ前にドキュメント件数を確認 | ベクトル検索サンプルを動かす人 | アップロード直後の検索で0件になる問題を避ける |
この更新は「サンプルの見やすさを上げる」だけではありません。サンプルをそのまま社内のPoC、検証用スクリプト、教育資料に流用している場合、古いサンプルの関数名や呼び出し方を前提にした手順書がずれる可能性があります。
Knowledge SourceとKnowledge BaseのCRUDサンプルが独立した
Azure AI Searchのagentic retrievalでは、検索対象をKnowledge Sourceとして定義し、それをKnowledge Baseが束ねて取得処理を実行します。Microsoft Learnでは、Knowledge Baseはagentic retrievalを調整する上位オブジェクトであり、どのKnowledge Sourceに問い合わせるか、取得時の既定動作を定義するものと説明されています。(Microsoft Learn)
今回追加されたCRUDサンプルは、次のような用途で役立ちます。
| サンプル | 主な用途 | 実務での使いどころ |
|---|---|---|
sample_knowledge_source_crud.py | Knowledge Sourceの作成、取得、更新、一覧、削除 | 既存の検索インデックスをagentic retrievalの検索対象として登録する |
sample_knowledge_source_crud_async.py | 非同期版のKnowledge Source CRUD | FastAPIなど非同期アプリと同じ設計で検証する |
sample_knowledge_base_crud.py | Knowledge Baseの作成、取得、更新、一覧、削除 | 複数のKnowledge Sourceを束ねる構成を確認する |
sample_knowledge_base_crud_async.py | 非同期版のKnowledge Base CRUD | 非同期処理のテストやサンプル移植に使う |
実務では、CRUDサンプルを「管理系コードのひな型」として見るのが適切です。たとえば、検証環境を毎回作り直すスクリプト、CIで検索リソースを作成するテスト、PoC用の環境構築手順に向いています。
一方で、ユーザーの質問に対して検索結果を返すアプリ本体の処理は、CRUDサンプルではなくsample_agentic_retrieval.pyやKnowledge Base Retrieval Clientのドキュメントを確認する流れになります。
sample_agentic_retrievalは「取得フロー確認用」に再整理された
以前のsample_agentic_retrieval.pyは、Knowledge Source / Knowledge BaseのCRUDと取得処理が同じサンプル内に混在していました。今回の更新では、役割がより明確になっています。
新しい位置づけは、次の流れを確認するサンプルです。
| ステップ | 内容 | 見るべきポイント |
|---|---|---|
| セットアップ | 既存の検索インデックスを参照するKnowledge Sourceを作成する | インデックス名とセマンティック構成 |
| Knowledge Base作成 | Knowledge Sourceを参照するKnowledge Baseを作成する | Knowledge Source名の一致 |
| 取得 | KnowledgeBaseRetrievalClientで検索意図を投げる | クライアント生成とretrieve呼び出し |
| クリーンアップ | Knowledge BaseとKnowledge Sourceを削除する | 検証後に不要リソースを残さない |
KnowledgeBaseRetrievalClientは、Knowledge Baseをクエリするためのクライアントです。コンストラクターでは検索サービスのエンドポイント、Knowledge Base名、認証情報を指定します。(Microsoft Learn)
サンプルを自社コードへ取り込む場合は、次のような考え方で切り分けると安全です。
from azure.search.documents.knowledgebases import KnowledgeBaseRetrievalClient
client = KnowledgeBaseRetrievalClient(
endpoint=service_endpoint,
knowledge_base_name=knowledge_base_name,
credential=credential,
)
result = client.retrieve(request)この形に寄せると、Knowledge Base名をクライアント作成時に固定し、取得時はリクエスト内容に集中できます。PRの差分でも、古い呼び出し方からretrieve(request)へ整理されたことが確認できます。(GitHub)
hotels-sample-*命名統一は小さく見えて重要
今回の更新では、エイリアス、ベクトルプロファイル、HNSW設定、Knowledge Source、Knowledge Base、セマンティック構成、インデクサーデータソースなどのサンプルリソース名がhotels-sample-*系に統一されています。(GitHub)
これは単なる見た目の整理ではありません。サンプルを何度も実行する開発現場では、名前の不一致が原因で次のようなトラブルが起きやすくなります。
| よくあるトラブル | 原因 | 回避策 |
|---|---|---|
| 削除対象を間違える | 作成時と削除時のリソース名が違う | 名前を固定し、環境名や日付をsuffixで管理する |
| 別サンプルのリソースと衝突する | 似た名前のインデックスやKnowledge Sourceが残る | 検証用プレフィックスを決める |
| サンプルの一部だけコピーして動かない | index_nameやknowledge_source_nameの前提が違う | 変数定義を先に確認する |
| CIで再実行に失敗する | 前回作成したリソースが残っている | 作成前の存在確認、または後処理を入れる |
社内環境に取り込むなら、hotels-sample-*をそのまま使うより、dev-search-*、poc-agentic-*、teamname-kb-*のように、用途と所有者が分かる名前へ置き換えるのがおすすめです。
ベクトル検索サンプルは「アップロード直後の0件」を避ける修正が入った
sample_query_vector.pyと非同期版では、ドキュメントをアップロードした直後に最初の検索を投げると、インデックス側の反映が間に合わず結果が安定しない可能性があります。今回の更新では、初回クエリ前にget_document_countで件数を確認するポーリングが追加されています。(GitHub)
これは実務でもよくある落とし穴です。upload_documents()が成功したからといって、すぐに検索結果として期待件数が返るとは限りません。検証スクリプトやデモでは特に、アップロード直後に検索して「ベクトル検索が効いていない」と誤解しがちです。
本番コードでは、サンプルと同じ考え方をより堅牢にして、次のように設計すると安全です。
| 観点 | サンプルでの考え方 | 本番での推奨 |
|---|---|---|
| 反映待ち | ドキュメント件数を一定時間ポーリング | タイムアウト、リトライ、ログ出力を入れる |
| エラー検知 | 件数が期待値に達するか確認 | アップロード結果と検索結果を別々に監視する |
| 大量データ | サンプルは小規模データ向け | バッチ単位で進捗を記録する |
| デモ | 初回検索の空振りを減らす | デモ前にインデックス状態を確認する |
ベクトル検索やハイブリッド検索のPoCでは、検索アルゴリズムや埋め込みモデルだけでなく、「インデックス反映待ち」をテスト手順に含めることが重要です。
影響を受ける利用者と、急がなくてよい利用者
| 利用状況 | 対応優先度 | 理由 |
|---|---|---|
azure-search-documentsのサンプルをコピーしてPoCを作っている | 高 | サンプル構成と呼び出し方が変わっているため |
| Knowledge Source / Knowledge BaseをPythonで管理している | 高 | CRUDサンプルが独立し、参照先が変わったため |
| agentic retrievalを検証中 | 高 | sample_agentic_retrievalの役割が変わったため |
| ベクトル検索サンプルをデモや検証で使っている | 中 | 初回クエリ前の反映待ちを取り入れる価値があるため |
| 既存の通常検索だけを使っている | 低 | 今回の主な変更はagentic retrievalとサンプル整理のため |
| Azure AI Searchを使っていない | 低 | 直接影響はないため |
注意したいのは、ドキュメント更新とSDKバージョンアップを混同しないことです。サンプルの更新自体は、手元のアプリに自動反映されません。しかし、同時期のazure-search-documents 12.0.0ではKnowledge Base関連のクライアントやモデル追加、既定APIバージョンの更新、serialize() / deserialize()削除などの変更が案内されています。SDKを12.0.0へ上げる場合は、サンプル確認とは別にリリースノート確認と回帰テストが必要です。(GitHub)
移行・設定確認のチェックリスト
依存パッケージのバージョンを確認する
まず、手元の環境でどのバージョンのazure-search-documentsを使っているか確認します。
python -m pip show azure-search-documentsrequirements.txt、pyproject.toml、poetry.lock、uv.lockなどでバージョン固定している場合は、開発環境だけでなくCI/CD、検証環境、本番環境の固定値も確認します。
特に12.0.0へ更新する場合は、次の観点を見ます。
| 確認項目 | 理由 |
|---|---|
serialize() / deserialize()を使っていないか | 12.0.0で削除が案内されているため |
| 旧プレビュー版のKnowledge Agent系モデルを使っていないか | Knowledge Base系の名称・ルートへ整理されているため |
| Vector Search関連の古いプロパティを使っていないか | 削除・置き換え対象があるため |
| 自動生成コードや社内ラッパーが古い型名を参照していないか | ビルド時ではなく実行時に気づくことがあるため |
Knowledge Source作成前に検索インデックスを確認する
Knowledge SourceのCRUDサンプルでは、既存の検索インデックスを参照する前提です。サンプル説明でも、対象インデックス名を環境変数で指定し、そのインデックスにセマンティック構成があることが前提として示されています。(GitHub)
確認すべき項目は次の通りです。
| 項目 | 確認内容 |
|---|---|
| インデックス名 | サンプル変数とAzure AI Search上の実名が一致しているか |
| セマンティック構成 | title、content、keywordsに相当するフィールドが適切か |
| 検索対象フィールド | ユーザー質問に答えるのに必要なフィールドが検索可能か |
| ベクトルフィールド | agentic retrievalで使う場合、必要なベクトル化設定があるか |
| 権限 | APIキーまたはEntra ID認証で作成・更新できるか |
Knowledge Base作成前にKnowledge Sourceの存在を確認する
Knowledge BaseのCRUDサンプルは、hotels-sample-knowledge-sourceというKnowledge Sourceがすでに存在する前提で説明されています。(GitHub)
そのため、サンプルを分割して実行する場合は、次の順序を守る必要があります。
| 順序 | 作業 | 失敗しやすい点 |
| -: | ——————— | ———————– |
| 1 | 検索インデックスを用意する | セマンティック構成がない |
| 2 | Knowledge Sourceを作成する | インデックス名を間違える |
| 3 | Knowledge Baseを作成する | Knowledge Source名が一致しない |
| 4 | Retrieval Clientで取得する | Knowledge Base名や認証情報が違う |
| 5 | 検証後に削除する | 不要リソースが残る |
サンプルを社内手順にするなら、「Knowledge Source作成」と「Knowledge Base作成」を別々の章に分けると、初学者が混乱しにくくなります。
認証方式を見直す
サンプルではAPIキーを使う形が多く、短時間のローカル検証では分かりやすい方法です。一方、本番アプリやチーム共有の検証環境では、キーをコードや設定ファイルに残さない設計が重要です。Microsoft Learnの取得API説明では、Knowledge Baseをクエリする権限として、Search Index Data Readerロールを割り当てたキーなし認証が推奨され、APIキーも選択肢として説明されています。(Microsoft Learn)
特にMCPエンドポイントやエージェント連携まで広げる場合、admin keyは読み書き権限が強すぎます。検証では使えても、本番ではEntra ID、マネージドID、最小権限のロール割り当てを優先して検討してください。
agentic retrievalの提供状態を個別に確認する
PR名には「2026-04-01 GA」が含まれていますが、サンプル更新とサービス機能の提供状態は切り分けて確認する必要があります。Microsoft LearnのKnowledge Base取得ページでは、agentic retrieval関連機能についてpublic previewとして説明されている箇所があります。リージョン、SLA、料金、制限は時期によって変わる可能性があるため、本番導入前に公式ドキュメントで最新状態を確認してください。(Microsoft Learn)
また、Azure AI Searchのagentic retrievalは、複雑な質問をLLMでサブクエリに分解し、複数の検索を並列実行して結果を統合するマルチクエリパイプラインとして説明されています。通常の単一検索より設計要素が増えるため、精度だけでなく待機時間、トークン利用、セマンティックランカー、認証、ログの確認も必要です。(Microsoft Learn)
よくある失敗と回避策
| 失敗例 | なぜ起きるか | 回避策 |
|---|---|---|
sample_agentic_retrieval.pyだけでCRUDを学ぼうとする | CRUDの詳細が別サンプルに分かれたため | CRUDはsample_knowledge_source_crud.pyとsample_knowledge_base_crud.pyを見る |
| Knowledge Baseを先に作ろうとして失敗する | 参照するKnowledge Sourceがまだない | 先にKnowledge Sourceを作成する |
サンプルのhotels-sample-*を本番名に残す | コピー時に名前を置き換えていない | 環境名、用途、所有者を含む命名規則に変える |
| ベクトル検索でアップロード直後に0件になる | インデックス反映が完了していない | 件数確認、リトライ、待機処理を入れる |
| APIキーをそのまま共有する | サンプルの認証方式を本番に流用している | Entra IDやマネージドIDを検討する |
| SDK 12.0.0へ上げたら型やメソッドで詰まる | サンプル更新とSDK破壊的変更を混同している | リリースノートを確認し、回帰テストを行う |
| 非同期アプリに同期サンプルを混ぜる | _async.pyを見ていない | アプリ構成に合わせて同期版・非同期版を選ぶ |
実務でのおすすめ対応手順
最初にやるべきことは、現在のコードがどのサンプル由来なのかを確認することです。特にPoCや社内検証では、公式サンプルをコピーしてから少しだけ改修しているケースが多く、どの時点のサンプルを使ったか分からなくなりがちです。
おすすめの順序は次の通りです。
| 手順 | 作業 | ゴール |
| -: | —————————————— | —————– |
| 1 | azure-search-documentsのバージョンを確認する | 12.0.0対応が必要か判断する |
| 2 | 既存コード内のsample_agentic_retrieval由来の処理を探す | CRUDと取得処理の混在を見つける |
| 3 | Knowledge Source / Knowledge Baseの作成処理を分ける | 管理系処理を明確にする |
| 4 | Retrieval Clientの作成とretrieve呼び出しを確認する | 新しいサンプルの考え方に合わせる |
| 5 | ベクトル検索のアップロード後待機を入れる | 初回検索の不安定さを減らす |
| 6 | 認証方式と権限を見直す | 本番運用に近い構成へ寄せる |
| 7 | 検証後の削除処理を確認する | 不要リソースや名前衝突を避ける |
この更新は、単なるドキュメント差し替えではなく、Azure AI Searchのagentic retrievalをPython SDKで扱う際の「サンプルの読み方」を整理する変更です。CRUDは専用サンプルで確認し、取得フローはsample_agentic_retrievalで確認し、ベクトル検索ではインデックス反映待ちを入れる。この3点を押さえれば、2026-04-01 GA対応のサンプルを実務に取り込みやすくなります。
コメント