Azure SDK documentation update: [Search] Regenerate search-documents for GA 13.0は、Azure AI Search向けJavaScript/TypeScript SDKである@azure/search-documents 13.0.0の生成コードとドキュメントをGA 13.0に合わせる更新です。まず確認すべき結論は、ナレッジベース、ナレッジソース、KnowledgeRetrievalClient、活動ログ、ベクトル検索まわりを使っているプロジェクトは移行確認が必要という点です。通常のSearchClientで検索・追加・削除だけを行っているアプリは影響が小さい可能性がありますが、型定義や戻り値の変更でビルドが止まることはあります。
今回のPRは2026年5月1日にAzure SDK for JavaScriptリポジトリへマージされ、@azure/search-documents 13.0.0のリリース履歴にも、KnowledgeRetrievalClient、ナレッジソース、debug、oversampling、ContentUnderstandingSkillなどの追加と、ベータ版から安定版へのAPI調整が記載されています。この記事では、2026年5月2日に公開・更新された情報として、開発者が確認すべき変更点、影響範囲、移行時のチェックポイントを実務目線で整理します。(GitHub)
Azure SDK documentation updateで最初に押さえるべき変更点
今回の更新は、単にドキュメントの文言を整えたものではありません。search-documentsパッケージを最新のTypeSpec仕様から再生成し、GA 13.0のAPI形状に合わせるための変更です。PRの概要では、KnowledgeSourceIngestionPermissionOptionの削除、KnowledgeBaseModelWebSummarizationActivityRecordの追加、操作ごとのAcceptヘッダー処理の更新、KnowledgeRetrievalClientやヘルパー関数の型修正が挙げられています。(GitHub)
特に注意したいのは、ナレッジベース関連のAPIをプレビュー版やベータ版から使っていたコードです。GA化に伴って、プレビュー時代のプロパティや型が整理されているため、「npmパッケージを上げるだけ」で済むとは限りません。
| 確認項目 | 変更内容 | 対応が必要になりやすいケース |
|---|---|---|
| ナレッジソースの権限取り込み | KnowledgeSourceIngestionPermissionOption enumと関連プロパティが削除対象 | ingestionPermissionOptionsを設定していたコード |
| ナレッジベース活動ログ | KnowledgeBaseModelWebSummarizationActivityRecordが追加 | 活動ログ、課金影響、トークン数、遅延を集計しているコード |
KnowledgeRetrievalClient | コンストラクターや取得メソッドのシグネチャがGA形状に調整 | 旧ベータの呼び出し方を残しているコード |
| Acceptヘッダー | 生成されたoperations内のAcceptヘッダー処理が更新 | HTTPモック、録画テスト、スナップショットテスト |
| 検索・ページング系ヘルパー | 戻り値や型互換性の修正 | TypeScriptの厳格な型チェックを有効にしているプロジェクト |
| サンプル | v13サンプル公開、古いv11/v12サンプル整理 | サンプルコードを社内テンプレートに流用している場合 |
影響を受けやすい開発者と影響が小さい開発者
今回のAzure SDK documentation updateで最も影響を受けるのは、Azure AI Searchの新しいナレッジベース機能やエージェント検索を使っている開発者です。Microsoft LearnのJavaScript APIリファレンスでは、KnowledgeRetrievalClientは知識ベースに対する操作を行うクラスとして定義され、現在のコンストラクターはendpoint、knowledgeBaseName、credential、optionsを受け取る形です。取得処理はretrieve(retrievalRequest, options)として定義されています。(Microsoft Learn)
対応優先度が高いケース
以下に当てはまる場合は、パッケージ更新前に検証環境でビルドと実行テストを行うべきです。
@azure/search-documentsのベータ版またはプレビュー相当の機能を使っているKnowledgeRetrievalClientでナレッジベース取得を実装しているKnowledgeSourceIngestionParametersやナレッジソース作成処理を使っている- Webナレッジソース、Azure Blobナレッジソース、OneLakeナレッジソースを組み合わせている
- 活動ログの
type、トークン数、処理時間を監視・可視化している SearchClientの戻り値型を独自ラッパーやテストで厳密に固定している
影響が比較的小さいケース
一方で、既存インデックスに対して通常のキーワード検索、ベクトル検索、ドキュメント追加・削除だけを行っている場合は、破壊的な影響は限定的な可能性があります。ただし、BaseVectorQueryのoversamplingやBaseSearchRequestOptionsのdebugなど、検索オプション側にも追加があるため、検索品質の検証や型補完の変化は確認しておく価値があります。13.0.0の変更履歴では、非セマンティック検索向けのdebug、ベクトル検索向けのoversampling、VectorizableImageBinaryQueryのbinaryImageからbase64Imageへのマッピング修正も明記されています。(GitHub)
削除されたKnowledgeSourceIngestionPermissionOptionはどう見るべきか
今回の変更で注意したいのが、KnowledgeSourceIngestionPermissionOption enumと関連プロパティの削除です。これは、ナレッジソース取り込み時に権限情報をどう扱うかをコード側で指定していた場合に影響します。PRでは、公開モデルのKnowledgeSourceIngestionParametersからingestionPermissionOptionsを削除する変更も示されています。(GitHub)
実務では、次のような検索をまず行ってください。
grep -R "KnowledgeSourceIngestionPermissionOption" ./src
grep -R "ingestionPermissionOptions" ./src該当箇所が見つかった場合は、単純に削除して終わりにしないことが重要です。権限情報の取り込みを前提に、検索結果のフィルタリング、ユーザー別アクセス制御、監査ログを設計しているケースがあるためです。
確認すべき観点は次の3つです。
| 観点 | 確認内容 |
|---|---|
| セキュリティ | 権限情報を検索インデックス側に持たせる前提の実装が残っていないか |
| 検索結果 | ユーザーごとの表示制御がSDK側の設定に依存していないか |
| 運用 | 権限取り込みの成否をログやメトリクスで監視していないか |
特に社内文書検索、RAG、チャットボットで「ユーザーが見られる文書だけを回答に使う」設計をしている場合は、SDKの型修正だけでなく、実際の検索結果に権限漏れがないかをテストデータで確認してください。
KnowledgeBaseModelWebSummarizationActivityRecordの追加で見るべきログ
新しく追加されたKnowledgeBaseModelWebSummarizationActivityRecordは、LLMによるWeb要約活動を表す活動レコードです。APIリファレンスでは、inputTokensCount、outputTokensCount、type: "modelWebSummarization"を持ち、継承プロパティとしてelapsedInMs、error、idを持つことが示されています。(Microsoft Learn)
これは、ナレッジベース取得を「動いたかどうか」だけで見るのではなく、どの活動でどれだけ時間とトークンを使ったかを把握するための重要な情報です。KnowledgeBaseRetrievalResponseには、進行状況や課金影響を追跡するためのactivityが含まれるため、運用監視ではこの配列を見落とさないようにしましょう。(Microsoft Learn)
実装では、次のようにtypeで分岐してログを取る形が扱いやすくなります。
for (const activity of response.activity ?? []) {
if (activity.type === "modelWebSummarization") {
console.log({
id: activity.id,
inputTokensCount: activity.inputTokensCount,
outputTokensCount: activity.outputTokensCount,
elapsedInMs: activity.elapsedInMs,
error: activity.error,
});
}
}ここで間違えやすいのが、プロパティ名です。今回の更新では、elapsedMsではなくelapsedInMsを維持する方針が明記されています。プレビュー仕様や別言語SDKの記述を見ながら実装していると、プロパティ名を取り違える可能性があります。ログ基盤やダッシュボードのフィールド名もあわせて確認してください。
KnowledgeRetrievalClientの移行確認ポイント
KnowledgeRetrievalClientは、現在のAPIリファレンスでは次の形で作成します。知識ベース名はクライアント作成時に渡し、取得時はリクエスト本体を渡す構成です。(Microsoft Learn)
import { KnowledgeRetrievalClient, AzureKeyCredential } from "@azure/search-documents";
const knowledgeRetrievalClient = new KnowledgeRetrievalClient(
"<endpoint>",
"<knowledgeBaseName>",
new AzureKeyCredential("<apiKey>")
);
const response = await knowledgeRetrievalClient.retrieve(retrievalRequest);移行時は、次のような古い設計が残っていないか確認してください。
| 確認対象 | 見直しポイント |
|---|---|
| クライアント生成 | ナレッジベース名をコンストラクターで渡しているか |
| 取得メソッド | retrieve呼び出し時に不要なナレッジベース名を渡していないか |
| 認証 | APIキーとMicrosoft Entra ID認証のどちらを使うか明確になっているか |
| テスト | モックのURL展開、パスパラメーター、Acceptヘッダーが新しい生成コードと一致するか |
APIキーを使う場合は、クライアントアプリから管理キーを直接使わないことも重要です。Microsoft Learnの概要ページでは、クエリ元のクライアントアプリでは管理キーではなくクエリキーを使うべきだと説明されています。管理操作やナレッジソース作成を行うサーバー側処理と、検索だけを行うフロントエンド処理は分離して設計しましょう。(Microsoft Learn)
Webナレッジソースを使う場合の注意点
今回の更新では、WebナレッジソースやWeb要約活動ログとの関係も意識する必要があります。Microsoft Learnでは、Webナレッジソースはエージェント検索パイプライン内でBingからリアルタイムWebデータを取得し、ナレッジベースで参照される仕組みとして説明されています。ただし、該当機能はパブリックプレビューであり、SLAなしで提供され、運用環境のワークロードには推奨されない旨も明記されています。(Microsoft Learn)
つまり、SDK側でGA 13.0として型や生成コードが整っていても、個別機能がすべて本番利用に適しているとは限りません。Webナレッジソースを使う場合は、少なくとも次を確認してください。
| 確認項目 | 実務での判断基準 |
|---|---|
| 利用環境 | 本番回答に使うか、検証・社内PoCに限定するか |
| ドメイン制御 | 許可ドメイン・ブロックドメインを設定するか |
| 回答品質 | 自社データとWeb情報が混ざった回答をどう評価するか |
| コスト | Web要約活動のトークン数と処理時間を監視するか |
| コンプライアンス | 外部Web情報を回答根拠に使ってよい業務か |
特に、ドメインを指定しない場合は公開インターネット全体が検索対象になり得るため、企業内チャットボットでは許可ドメインを明示する運用が現実的です。Microsoft Learnでも、Webナレッジソースでは許可またはブロックするドメインを設定できることが説明されています。(Microsoft Learn)
移行前に実行したいチェックリスト
SDK更新で失敗しやすいのは、「npm install後にアプリが起動したから問題ない」と判断してしまうケースです。今回のように型、生成コード、サンプル、ヘルパーが変わる更新では、ビルド・単体テスト・統合テストを分けて確認しましょう。
npm ls @azure/search-documents
npm outdated @azure/search-documents
npm install @azure/search-documents@13
npx tsc --noEmit
npm test実務では、次の順番で見ると抜け漏れを減らせます。
| 手順 | 確認内容 | 失敗しやすいポイント |
|---|---|---|
| 依存関係確認 | package.jsonとlockファイルのSDKバージョン | 一部環境だけ旧版が残る |
| 型チェック | tsc --noEmitでコンパイル | 削除されたenumやプロパティで停止 |
| コード検索 | KnowledgeSourceIngestionPermissionOption、ingestionPermissionOptions、elapsedMsを検索 | 古いプレビュー実装が残る |
| API呼び出し確認 | KnowledgeRetrievalClientの生成とretrieve実行 | ナレッジベース名の渡し方が旧式 |
| ログ確認 | activity、inputTokensCount、outputTokensCount、elapsedInMs | ダッシュボードの項目名が不一致 |
| 検索品質確認 | debug、oversampling、ベクトル検索結果 | 型は通るが検索順位が想定と違う |
| セキュリティ確認 | APIキー、権限、ナレッジソースの範囲 | 管理キーの露出、検索範囲の過大化 |
すぐに対応すべき判断基準
今回のAzure SDK documentation updateは、すべてのAzure SDK利用者が緊急対応すべき更新ではありません。しかし、Azure AI SearchでRAG、エージェント検索、ナレッジベース、Webナレッジソースを使っている場合は、早めに検証すべきです。
判断基準はシンプルです。
- ナレッジベース関連APIを使っているなら、移行確認は必須
ingestionPermissionOptionsを使っているなら、設計レベルで見直し- 活動ログやコスト監視をしているなら、新しい活動レコードとプロパティ名を反映
- 通常の検索だけを使っているなら、型チェックと回帰テストを中心に確認
- Webナレッジソースを本番利用したいなら、プレビュー条件とSLAの扱いを事前確認
まずは@azure/search-documentsの現在バージョンを確認し、該当するコード文字列を検索してください。そのうえで、ナレッジベース取得、ナレッジソース作成、検索結果、活動ログの4点を検証環境で実行すれば、GA 13.0への移行リスクをかなり下げられます。
コメント