.NET で Azure AI Foundry や Azure OpenAI の File Search／RAG を実装しているなら、ProjectVectorStoresClient は「Azure AI プロジェクト内の Vector Store を .NET から操作するためのクライアント」と考えるのが最短です。2026年7月2日に公開または更新された公式情報では、Azure.AI.Extensions.OpenAI 名前空間のクラスとして、OpenAI の Vector Store API を通じて Azure AI プロジェクトの Vector Store 操作を提供することが示されています。既存アプリに対して直ちに移行期限が示された更新ではありませんが、プレビュー版パッケージや API バージョンを使っている場合は、バージョン固定、権限、不要な Vector Store の削除方針を確認しておくべきです。(Microsoft Learn)
.NET の ProjectVectorStoresClient とは
ProjectVectorStoresClient は、Azure AI プロジェクトで使う Vector Store 操作を .NET SDK から扱うためのクラスです。公式 API リファレンスでは、Azure.AI.Extensions.OpenAI 名前空間に属し、Azure.AI.Extensions.OpenAI.dll に含まれ、Azure.AI.Extensions.OpenAI v2.0.0 および v2.1.0-beta.4 の対象として記載されています。また、クラス定義は OpenAI.VectorStores.VectorStoreClient を継承する形になっています。(Microsoft Learn)
| 確認項目 | 公式情報で分かる内容 | 実務上の見方 |
|---|---|---|
| クラス名 | ProjectVectorStoresClient | Azure AI プロジェクト向けの Vector Store 操作用クライアント |
| 名前空間 | Azure.AI.Extensions.OpenAI | using Azure.AI.Extensions.OpenAI; を使う領域 |
| パッケージ | Azure.AI.Extensions.OpenAI v2.0.0 / v2.1.0-beta.4 | 安定版とベータ版のどちらを採用しているか確認が必要 |
| 継承元 | OpenAI.VectorStores.VectorStoreClient | OpenAI の Vector Store API と近い操作モデルで扱える |
| コンストラクター | モック用の protected ProjectVectorStoresClient() | 通常は直接 new するより、上位クライアントから取得する設計と考える |
特に重要なのは、ProjectVectorStoresClient が単体の「汎用ベクトルデータベース SDK」ではない点です。Microsoft Learn の .NET 向け Vector Store 解説では、Vector Database は埋め込みを保存・管理し、RAG ではデータをベクトル化して検索し、検索結果をモデル応答に使う流れが説明されています。一方、ProjectVectorStoresClient はその中でも Azure AI プロジェクトと OpenAI Vector Store API の文脈で使うクライアントです。(Microsoft Learn)
更新ポイントは「Vector Store 操作のプロジェクト文脈」が明確になったこと
今回の公式情報で開発者が見るべきポイントは、新しい大規模な移行作業というより、Azure AI プロジェクト内で Vector Store を扱うためのクラスと取得方法を明確に把握することです。ProjectOpenAIClient.GetProjectVectorStoresClient() は、プロジェクトの Vector Store 操作用クライアントを返すメソッドとして定義されています。(Microsoft Learn)
Azure.AI.Extensions.OpenAI の概要では、Azure AI Agents 機能を使うには Azure サブスクリプションが必要で、SDK は既存エージェントへのリクエスト作成に使えること、またエージェントの作成・更新・削除のような管理操作は高い権限を持つユーザーに限定するのが望ましいことが説明されています。さらに、/responses、/files、/vector_stores のような OpenAI API ベースの操作は、ProjectOpenAIClient から関連クライアントを取得して扱う構成になっています。(Microsoft Learn)
管理者・開発者が見るべき変更点
| 観点 | 確認すべきこと | 対応の優先度 |
|---|---|---|
| SDK パッケージ | Azure.AI.Extensions.OpenAI の利用有無、v2.0.0 か v2.1.0-beta.4 か | 高 |
| API バージョン | 既定の stable v1 を使うのか、プレビュー API を明示するのか | 高 |
| クライアント取得方法 | ProjectOpenAIClient.GetProjectVectorStoresClient() を使っているか | 中 |
| 権限設計 | エージェント管理操作と実行時操作の権限を分けているか | 高 |
| データ管理 | アップロード済みファイル、Vector Store、参照 ID の棚卸しができるか | 高 |
| 監査・トレース | 内容記録を有効化する場合、機密情報を扱う前提で設計しているか | 高 |
API バージョンについては、ProjectOpenAIClientOptions の ApiVersion で明示できる例が示されており、公式ドキュメントでは現在の安定版は既定で v1 と説明されています。プレビュー機能を試す場合は、サンプルのように 2025-11-15-preview などを明示できますが、本番環境では「なぜプレビューを使うのか」を設計書やリリースノートに残しておくべきです。(Microsoft Learn)
ProjectOpenAIClientOptions options = new()
{
ApiVersion = "2025-11-15-preview"
};影響範囲：対象になる .NET アプリと対象外のケース
影響を受けやすいのは、Azure AI Foundry のプロジェクト、エージェント、Responses API、File Search、Vector Store を組み合わせている .NET アプリです。たとえば、社内 FAQ、製品マニュアル、問い合わせ履歴、規程文書などをファイルとしてアップロードし、エージェントがその内容を検索して回答する構成では、ProjectVectorStoresClient の理解が重要になります。公式サンプルでも、ファイルをアップロードし、Vector Store を作成し、その Vector Store ID を File Search Tool に渡してエージェントに追加する流れが示されています。(Microsoft Learn)
| 利用パターン | 影響 | 確認ポイント |
|---|---|---|
| Azure AI Foundry の Agent に File Search を持たせている | 影響あり | Vector Store 作成・削除・参照 ID 管理を確認 |
Azure.AI.Extensions.OpenAI を使って /vector_stores を操作している | 影響あり | ProjectOpenAIClient 経由の取得方法と API バージョンを確認 |
| Azure AI Search、SQL、Cosmos DB などを直接 Vector Database として使っている | 直接影響は限定的 | Microsoft.Extensions.VectorData など別レイヤーの管理対象として確認 |
| 単純な Chat Completions のみを使っている | 直接影響は小さい | File Search や Vector Store を追加する予定があるか確認 |
| Assistants／Threads／Vector Stores を永続リソースとして使っている | 影響あり | 不要リソース削除と ID 再利用方針を確認 |
.NET 全体の Vector Store 活用では、Microsoft.Extensions.VectorData のように複数のベクトルストアを抽象化する方法もあります。Microsoft Learn では、通常の DB ドライバーや SDK を使う方法に加え、Microsoft.Extensions.VectorData が Vector Store 操作用の統一抽象化レイヤーを提供する選択肢として説明されています。ProjectVectorStoresClient はこの汎用抽象化とは別に、Azure AI プロジェクト上の OpenAI Vector Store 操作に寄ったクラスとして整理すると混乱しません。(Microsoft Learn)
典型的な使い方：File Search 用の Vector Store を作る
実装イメージは、ファイルをアップロードし、そのファイル ID を使って Vector Store を作成し、エージェントの File Search Tool に関連付ける流れです。公式サンプルでは、OpenAIFileClient でファイルをアップロードし、VectorStoreCreationOptions に FileIds を指定して Vector Store を作成し、その Vector Store ID を ResponseTool.CreateFileSearchTool に渡しています。(Microsoft Learn)
using Azure.AI.Extensions.OpenAI;
using OpenAI.Files;
using OpenAI.VectorStores;
// 例: projectClient は AIProjectClient などから初期化済みとする
OpenAIFile uploadedFile = await projectClient.ProjectOpenAIClient
.GetProjectFilesClient()
.UploadFileAsync(
filePath: "support-faq.txt",
purpose: FileUploadPurpose.Assistants);
ProjectVectorStoresClient vectorStoresClient =
projectClient.ProjectOpenAIClient.GetProjectVectorStoresClient();
VectorStoreCreationOptions options = new()
{
Name = "support-faq-store",
FileIds = { uploadedFile.Id }
};
VectorStore vectorStore =
await vectorStoresClient.CreateVectorStoreAsync(options);このコードの目的は、単にファイルを保存することではありません。エージェントが検索対象として使える形にファイルを関連付けることです。実務では、support-faq-store のような名前だけでなく、環境名、用途、作成日、データ所有部門が分かる命名規則を用意しておくと、後から不要な Vector Store を削除しやすくなります。
設定変更と移行期限の考え方
今回の ProjectVectorStoresClient の API リファレンス自体は、廃止告知や強制移行期限を示すページではなく、クラス定義、対応パッケージ、継承関係、コンストラクターなどを説明する内容です。したがって、公式情報だけを見る限り、「何日までに必ず移行」といった期限対応よりも、利用中の SDK バージョンとプレビュー API の扱いを確認することが現実的な対応になります。(Microsoft Learn)
ただし、v2.1.0-beta.4 のようなベータ版を使っている場合は注意が必要です。公式 API リファレンスには、プレリリース製品に関する情報は正式リリースまでに大きく変更される可能性がある旨の注意書きがあります。CI/CD で自動的に最新版へ上げる設定にしている場合は、ビルドが通っても実行時の挙動や型定義が変わる可能性を考え、明示的なバージョン固定と検証環境での回帰テストを挟むべきです。(Microsoft Learn)
移行が必要になりやすいケース
| ケース | 対応方針 |
|---|---|
Azure.AI.Extensions.OpenAI のベータ版を本番で使っている | 安定版で代替できるか確認し、ベータ継続時はバージョン固定する |
| Vector Store 操作のクライアント取得方法がプロジェクト文脈と合っていない | ProjectOpenAIClient.GetProjectVectorStoresClient() を基準に整理する |
| API バージョンをプレビューに固定している | プレビューが必要な理由と影響範囲をドキュメント化する |
| ファイルや Vector Store の削除処理がない | 管理バッチ、運用手順、棚卸しレポートを用意する |
| エージェント管理者と実行ユーザーの権限が同じ | 作成・更新・削除と実行時アクセスの権限を分離する |
管理者が確認すべきポイント
NuGet パッケージの棚卸し
まず、対象リポジトリで Azure.AI.Extensions.OpenAI を使っているか確認します。Directory.Packages.props を使っている組織では、個別プロジェクトだけでなく中央管理されたバージョンも確認してください。
dotnet list package確認すべきなのは、単に「入っているか」ではなく、安定版とベータ版のどちらを採用しているかです。公式 API リファレンスでは v2.0.0 と v2.1.0-beta.4 が対象として表示されているため、ベータ版を採用している場合は、機能検証用なのか、本番利用なのかを明確に分ける必要があります。(Microsoft Learn)
認証と権限を分離する
Azure OpenAI の .NET クライアントでは、Microsoft Entra ID を使うキーレス認証が推奨され、API キー認証も可能ですが Entra ベースの認証より安全性は劣るものとして説明されています。Vector Store や File Search のように社内文書を扱う構成では、ローカル環境のキー直書きや共有キーの使い回しを避け、Managed Identity や DefaultAzureCredential を使う構成を優先して検討すべきです。(Microsoft Learn)
また、エージェントの作成・更新・削除と、エージェントに問い合わせる実行時処理は権限を分けるのが安全です。Azure.AI.Extensions.OpenAI の概要でも、エージェント管理操作には高い権限を持つユーザーを使うのがよいと説明されています。(Microsoft Learn)
Vector Store とファイルのライフサイクルを決める
Vector Store は作ったら終わりではありません。FAQ や規程文書は更新されるため、古いファイルが残ったままだと、エージェントが古い情報を参照する可能性があります。Microsoft の Azure OpenAI .NET ドキュメントでも、Assistants、Threads、Vector Stores のようなものは永続リソースであり、ID を保存して再利用するか、不要になったら削除できるものとして説明されています。(Microsoft Learn)
実務では、次のようなルールを決めておくと運用が安定します。
| ルール | 具体例 |
|---|---|
| 命名規則 | app-env-purpose-yyyyMMdd のように用途と作成日を入れる |
| 所有者 | Vector Store ごとに業務部門またはシステム責任者を決める |
| 更新方式 | 差し替え型、追記型、定期再作成型のどれかを決める |
| 削除基準 | 検証用は一定期間後に削除、本番用は次版作成後に旧版を削除 |
| 監査 | どのエージェントがどの Vector Store ID を参照しているか記録する |
トレース設定では機密情報の記録に注意する
トラブルシューティングでは OpenTelemetry を使ったトレースが役立ちます。公式ドキュメントでは、GenAI トレースを有効化するための AZURE_EXPERIMENTAL_ENABLE_GENAI_TRACING や AppContext.SetSwitch("Azure.Experimental.EnableGenAITracing", true) が示されています。一方で、メッセージ内容やツール呼び出しのパラメーター、戻り値を記録する content recording は機密情報を含む可能性があり、既定では無効と説明されています。(Microsoft Learn)
本番環境で Vector Store を使う場合、ログにユーザーの問い合わせ、社内文書の抜粋、検索結果、ファイル名、メタデータが残る可能性があります。トレースを有効にする前に、保存先、保存期間、閲覧権限、マスキング方針を決めてください。
よくある失敗と回避策
Vector Store と Azure AI Search を混同する
ProjectVectorStoresClient は、Azure AI プロジェクトで OpenAI Vector Store API を扱うためのクライアントです。企業検索、複雑なフィルター、既存インデックス連携、アクセス制御を細かく作り込みたい場合は、Azure AI Search やデータベース側のベクトル検索の方が適していることがあります。Microsoft Learn でも、RAG の一般的なワークフローとして、埋め込み作成、保存・インデックス化、クエリのベクトル化、検索、モデル応答への利用という流れが説明されています。(Microsoft Learn)
判断基準はシンプルです。エージェントの File Search に素早く文書を持たせたいなら Vector Store、検索体験そのものを細かく設計したいなら Azure AI Search や専用のベクトル DB を検討します。
プレビュー API を本番の前提にしてしまう
プレビュー API やベータ版パッケージは、検証速度を上げるには便利です。しかし、正式 API と同じ変更耐性を期待すると、SDK 更新時にビルドエラーや実行時エラーが出る可能性があります。公式ドキュメントにも、プレリリース情報は正式リリースまでに変更される可能性があると明記されています。(Microsoft Learn)
本番利用する場合は、次の3点を必ず残してください。
- 採用しているパッケージ名とバージョン
- 明示している API バージョン
- プレビュー機能を使う理由と代替案
ファイル更新時に古い Vector Store を残し続ける
社内文書を更新しても、古い Vector Store や古いファイル参照が残っていると、ユーザーに古い回答を返す原因になります。特に「規程」「価格表」「障害対応手順」「製品仕様」のように日付が重要な文書では、Vector Store の作成日と参照元ファイルの版数を管理する必要があります。
おすすめは、検証環境では短いライフサイクルで作り直し、本番環境では新しい Vector Store を作成して検証後に参照先を切り替え、旧 Store を一定期間後に削除する方式です。これならロールバックもしやすくなります。
導入前チェックリスト
| チェック項目 | 確認内容 |
|---|---|
| SDK | Azure.AI.Extensions.OpenAI のバージョンを固定しているか |
| API バージョン | stable v1 で足りるか、プレビュー指定が必要か |
| 認証 | API キー直書きではなく Entra ID ベースの認証を検討しているか |
| 権限 | 管理操作と実行時操作の権限を分離しているか |
| データ | Vector Store に入れる文書の機密区分を確認しているか |
| 更新 | ファイル差し替え時の再作成・削除手順があるか |
| 監査 | どのエージェントがどの Vector Store を参照しているか追跡できるか |
| ログ | トレースや content recording で機密情報が残らない設計か |
| テスト | ファイル更新後、期待する回答に変わるかを自動または手動で確認しているか |
まとめ：まずは SDK・API バージョン・Vector Store 管理を確認する
ProjectVectorStoresClient は、.NET から Azure AI プロジェクトの Vector Store 操作を扱うための重要なクライアントです。公式情報では、Azure.AI.Extensions.OpenAI に含まれ、OpenAI.VectorStores.VectorStoreClient を継承し、ProjectOpenAIClient.GetProjectVectorStoresClient() から取得できることが確認できます。(Microsoft Learn)
今回の更新で最初にやるべきことは、大きな設計変更ではなく現状確認です。Azure.AI.Extensions.OpenAI のバージョン、stable／preview の API バージョン、Vector Store とファイルの削除ルール、エージェント管理者の権限、トレース時の機密情報記録を確認してください。特に File Search や RAG を本番導入している環境では、Vector Store を「作る処理」だけでなく「更新する処理」「削除する処理」「監査する処理」まで含めて設計することが、安定運用のポイントです。
コメント