Azure AI Foundry で LangChain 連携を使っている場合、今回まず確認すべき答えは「新規開発は langchain-azure-ai と OpenAI互換APIを前提にし、Project endpoint と Microsoft Entra ID 認証を標準にする」という点です。2026年7月2日に更新された Microsoft Learn の「Use LangChain with models in Microsoft Foundry」は、Foundry にデプロイしたチャットモデルや埋め込みモデルを LangChain から利用するための実装パターンを整理しています。特に、旧 langchain-azure-ai[v1] や Azure AI Inference SDK 前提のコードを残している環境では、依存パッケージ、環境変数、認証方式、モデルデプロイ名の見直しが必要です。(Microsoft Learn)
この記事では、Azure AI Foundry の LangChain 連携に関する更新ポイントを、開発者・管理者・グローバル運用担当者の視点で整理します。単にサンプルコードを動かすだけでなく、既存アプリへの影響、設定変更、移行期限、確認すべきチェック項目まで実務向けに解説します。
Azure AI Foundry の LangChain 連携で確認すべき更新ポイント
今回の公式情報は、Azure AI Foundry、公式ページ表記では Microsoft Foundry、にデプロイしたモデルを LangChain アプリから呼び出すための開発者向けガイドです。対象は、OpenAI互換APIをサポートするチャットモデルと埋め込みモデルです。公式ドキュメントでは、langchain-azure-ai を使ってチャットクライアント、Embedding クライアント、非同期呼び出し、ベクトル検索、サーバーサイドツール連携を扱う流れが示されています。(Microsoft Learn)
実務上の重要ポイントは、次の5つです。
| 確認項目 | 内容 | 実務での対応 |
|---|---|---|
| 推奨パッケージ | langchain-azure-ai を利用する | requirements.txt や lock file の依存関係を確認する |
| SDK の前提 | 新しい Microsoft Foundry SDK v2 を利用する | 旧 langchain-azure-ai[v1] 依存を棚卸しする |
| 推奨認証 | Project endpoint と Microsoft Entra ID | 本番環境では API キー直書きより RBAC とマネージド ID を優先する |
| 対象モデル | OpenAI互換APIをサポートするデプロイ済みモデル | モデル名ではなく「デプロイ名」を設定値として管理する |
| 旧設定 | AZURE_AI_INFERENCE_ENDPOINT などの旧環境変数は新クラスでは使わない | CI/CD、Key Vault、コンテナ環境変数を更新する |
この更新は、Azure AI Foundry の管理画面に新しいボタンが追加されるような変更ではありません。影響が大きいのは、LangChain を使った生成AIアプリ、RAG、エージェント、埋め込み検索、検証ワークフローを実装している開発チームです。
公式ドキュメントが対象にしている利用シーン
公式ガイドが扱っている主な利用シーンは、次のとおりです。
- Foundry にデプロイしたチャットモデルを LangChain から呼び出す
init_chat_modelでモデルクライアントを作成するAzureAIOpenAIApiChatModelでクライアントを直接構成するainvokeによる非同期呼び出しを行う- 埋め込みモデルを使ってベクトル検索を行う
- OpenAI モデルでサーバーサイドツールを利用する
- LangChain agent から Foundry のモデルを使う
- デバッグログでリクエストの流れを確認する
前提条件として、Azure サブスクリプション、Foundry プロジェクト、Foundry User ロール、OpenAI互換APIをサポートするデプロイ済みチャットモデル、デプロイ済み埋め込みモデル、Python 3.9 以降が必要です。公式ページでは、チャットモデルの例として gpt-4.1 や Mistral-Large-3、埋め込みモデルの例として text-embedding-3-large が挙げられています。(Microsoft Learn)
ここで注意したいのは、モデルカタログ上のモデル名と、アプリから指定するデプロイ名が一致するとは限らない点です。環境変数や設定ファイルには、Foundry ポータルで確認したデプロイ名を使う必要があります。公式の環境変数リファレンスでも、AZURE_OPENAI_DEPLOYMENT_NAME はモデルのデプロイ名を指し、実際の基盤モデル名と異なる場合があると説明されています。(Microsoft Learn)
設定変更の要点：Project endpoint と OpenAI互換エンドポイントを使い分ける
今回のガイドで最も重要なのは、接続パターンの整理です。公式ドキュメントでは、Project endpoint と Microsoft Entra ID の組み合わせが推奨されています。一方で、直接 OpenAI互換エンドポイントに API キーで接続する方法も示されています。(Microsoft Learn)
import os
# 推奨: Project endpoint + Microsoft Entra ID
os.environ["FOUNDRY_PROJECT_ENDPOINT"] = (
"https://<resource>.services.ai.azure.com/api/projects/<project>"
)
# 代替: 直接 OpenAI互換エンドポイント + API キー
os.environ["OPENAI_BASE_URL"] = (
"https://<resource>.services.ai.azure.com/openai/v1"
)
os.environ["OPENAI_API_KEY"] = "<your-api-key>"実務では、次のように使い分けると判断しやすくなります。
| 接続方式 | 向いているケース | 注意点 |
|---|---|---|
| Project endpoint + Microsoft Entra ID | 本番環境、社内アプリ、権限管理が必要な環境 | Foundry User ロールやマネージド ID の設定が必要 |
| OpenAI互換エンドポイント + API キー | 既存 OpenAI 互換コードの流用、検証環境、短期PoC | API キーの保管、ローテーション、漏えい対策が必要 |
Azure OpenAI /openai/v1 エンドポイント | 最大限の OpenAI 互換性や低レイテンシを重視する場合 | Foundry 固有の機能、エージェント、評価、専用ツールを使う場合は Project endpoint 側も検討する |
Microsoft Foundry SDK の概要では、Foundry SDK はエージェント、評価、トレーシングなど Foundry 固有の操作に向き、OpenAI SDK は互換性や低レイテンシ、Embedding 生成などを重視する場合に向くと整理されています。つまり、すべてを1つのSDKに寄せるのではなく、アプリの目的に応じて Project client と OpenAI互換クライアントを使い分ける設計が現実的です。(Microsoft Learn)
パッケージと依存関係で確認すべきこと
公式ガイドでは、必要なパッケージとして次のインストールコマンドが示されています。(Microsoft Learn)
pip install -U langchain langchain-azure-ai azure-identity新規開発では、この組み合わせを基準にします。既存環境では、次のような状態になっていないか確認してください。
| 確認ポイント | 問題になりやすい状態 | 対応 |
|---|---|---|
langchain-azure-ai | langchain-azure-ai[v1] を使っている | 新しい langchain-azure-ai 前提に移行する |
| LangChain 本体 | init_chat_model が使えない古いバージョン | 公式要件に合うバージョンへ更新する |
| Azure Identity | 認証コードが API キー前提だけになっている | DefaultAzureCredential やマネージド ID を検討する |
| requirements 管理 | 開発環境だけ新しく、本番イメージが古い | Dockerfile、CI、lock file を同時に更新する |
init_chat_model を使うには langchain>=1.2.13 が必要です。バージョンを上げられない場合は、AzureAIOpenAIApiChatModel などのクライアントクラスを直接構成する必要があります。(Microsoft Learn)
チャットモデルを呼び出す基本パターン
最小構成では、init_chat_model を使ってチャットモデルを呼び出せます。
from langchain.chat_models import init_chat_model
model = init_chat_model("azure_ai:gpt-4.1")
response = model.invoke("Say hello")
response.pretty_print()このコードは、環境変数に設定された Project endpoint または直接エンドポイントを使って、指定したモデルデプロイにリクエストを送ります。ここで指定する gpt-4.1 の部分は、実際の環境では自社の Foundry プロジェクトにデプロイ済みのモデル名またはデプロイ名に合わせる必要があります。(Microsoft Learn)
バージョンや構成を細かく制御したい場合は、クライアントを直接作成します。
import os
from azure.identity import DefaultAzureCredential
from langchain_azure_ai.chat_models import AzureAIOpenAIApiChatModel
model = AzureAIOpenAIApiChatModel(
project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
credential=DefaultAzureCredential(),
model="Mistral-Large-3",
)AzureAIOpenAIApiChatModel は、既定で OpenAI Responses API を使います。既存コードとの互換性などの理由で挙動を変えたい場合は、use_responses_api=False を指定できます。移行時は、レスポンス形式やストリーミング処理、ツール呼び出しの扱いが既存コードと一致するかをテストしてください。(Microsoft Learn)
Prompt chain と検証ワークフローでの使い方
LangChain の強みは、単発のモデル呼び出しだけではなく、Prompt template、Parser、複数モデル、検証処理を組み合わせられる点です。今回のガイドでも、Foundry にデプロイされたモデルを使って、プロンプトチェーンや生成結果の検証ワークフローを構成することが想定されています。(Microsoft Learn)
実務で分かりやすい例は、次のような構成です。
| 処理 | 使うモデルの例 | 目的 |
|---|---|---|
| 生成 | 高性能なチャットモデル | 回答文、要約、提案文を作成する |
| 検証 | 小型または低コストのモデル | 禁止表現、形式違反、根拠不足をチェックする |
| 整形 | Parser または軽量モデル | JSON、箇条書き、社内フォーマットに変換する |
| 検索 | Embedding + ベクトルストア | 社内文書やFAQから関連情報を取得する |
例えば、社内FAQボットでは、最初に Embedding で関連文書を検索し、その検索結果をもとにチャットモデルで回答を生成し、最後に別モデルまたはルールで「根拠がない断定をしていないか」をチェックする構成が考えられます。Azure AI Foundry 側で重要なのは、チェーンの各ステップにどのモデルデプロイを使うか、どの認証方式で呼び出すか、ログにどこまで残すかを明確にすることです。
非同期呼び出しでは async 用の認証実装を使う
Web API、バッチ処理、チャットUIなどで並列リクエストを扱う場合は、LangChain の ainvoke を使った非同期呼び出しが重要になります。公式ガイドでは、Microsoft Entra ID 認証で非同期呼び出しを行う場合、azure.identity.aio の非同期版 DefaultAzureCredential を使う例が示されています。(Microsoft Learn)
import os
import asyncio
from azure.identity.aio import DefaultAzureCredential as DefaultAzureCredentialAsync
from langchain_azure_ai.chat_models import AzureAIOpenAIApiChatModel
model = AzureAIOpenAIApiChatModel(
project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
credential=DefaultAzureCredentialAsync(),
model="gpt-4.1",
)
async def main():
response = await model.ainvoke("Say hello asynchronously")
response.pretty_print()
asyncio.run(main())よくある失敗は、同期版の DefaultAzureCredential をそのまま非同期処理に使ってしまうことです。開発環境では動いているように見えても、高負荷時に接続数やイベントループ周りの問題が出ることがあります。FastAPI、Azure Functions、コンテナ上の非同期ワーカーで利用する場合は、認証クラス、セッション管理、終了時のクローズ処理まで含めて確認してください。
Embedding とベクトル検索：RAG 実装への影響
RAG や類似検索を使っている環境では、チャットモデルだけでなく Embedding モデルの呼び出しも確認が必要です。公式ガイドでは、init_embeddings または AzureAIOpenAIApiEmbeddingsModel を使って埋め込みモデルを作成し、InMemoryVectorStore で類似検索を試す例が示されています。(Microsoft Learn)
from langchain.embeddings import init_embeddings
embed_model = init_embeddings("azure_ai:text-embedding-3-small")クライアントを直接構成する場合は、次のようになります。
import os
from azure.identity import DefaultAzureCredential
from langchain_azure_ai.embeddings import AzureAIOpenAIApiEmbeddingsModel
embed_model = AzureAIOpenAIApiEmbeddingsModel(
project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
credential=DefaultAzureCredential(),
model="text-embedding-3-large",
)検証用にはインメモリのベクトルストアで十分ですが、本番環境ではそれだけでは足りません。文書量、更新頻度、アクセス制御、監査ログ、再インデックスの手順を考える必要があります。特にグローバル運用では、地域ごとのデータ保管要件や社内ポリシーに合わせて、ベクトルストアの配置先とデータ投入フローを設計してください。
Server-side tools と agent 利用時の注意点
公式ガイドでは、Foundry にデプロイされた OpenAI モデルが、Web search、Code interpreter、File search などのサーバーサイドツール呼び出しループをサポートすることも説明されています。ただし、langchain_azure_ai.tools.builtin 名前空間のツールは OpenAI モデルでのみサポートされる点に注意が必要です。(Microsoft Learn)
この点は、管理者にとって重要です。なぜなら、ツール連携はモデル呼び出しの範囲を広げるからです。たとえば Web search を許可すれば外部情報を参照でき、File search を許可すればアップロード済みファイルの内容を検索できます。便利な一方で、データ持ち出し、検索対象ファイル、ログ、アクセス権限の整理が必要になります。
agent 実装では、create_agent と Foundry に接続されたモデルを組み合わせる例も示されています。画像生成ツールを LangChain から使う場合、langchain-azure-ai では画像生成デプロイ名を渡すためのヘッダー処理が自動で扱われますが、langchain-openai を使う場合は手動設定が必要とされています。(Microsoft Learn)
移行期限：旧 langchain-azure-ai[v1] は優先的に確認する
今回の新しい公式ガイドそのものには、新たな一斉強制移行日が書かれているわけではありません。ただし、旧 Foundry classic 向けの公式ページでは、langchain-azure-ai[v1] による Model Inference API 連携は非推奨であり、2026年5月30日に廃止予定と明記されています。2026年7月時点ではこの期限を過ぎているため、旧実装が残っている環境では、通常の改善タスクではなくリスク対応として扱うべきです。(Microsoft Learn)
移行対象になりやすいコードの特徴は、次のとおりです。
| 旧実装の兆候 | リスク | 推奨対応 |
|---|---|---|
langchain-azure-ai[v1] をインストールしている | 旧 SDK・旧 API 前提で将来の互換性が低い | langchain-azure-ai に移行する |
AzureAIChatCompletionsModel を中心に使っている | 新ガイドの AzureAIOpenAIApiChatModel と構成が異なる | クライアント作成部分を差し替える |
AZURE_AI_INFERENCE_ENDPOINT を使っている | 新しい OpenAI互換クラスでは使われない | FOUNDRY_PROJECT_ENDPOINT または OPENAI_BASE_URL に整理する |
API キーをコードや .env に固定している | 漏えい・ローテーション漏れのリスク | Key Vault、マネージド ID、Entra ID 認証を検討する |
| モデル名をコードに直書きしている | 環境差分や再デプロイ時に壊れやすい | 環境別設定として管理する |
移行で最初にやるべきことは、コード修正ではなく棚卸しです。GitHub、Azure Repos、コンテナイメージ、CI/CD 変数、Key Vault、アプリ設定を横断して、旧パッケージ名、旧環境変数、旧クライアントクラス、モデル名の直書きがないか確認してください。
管理者が確認すべきチェックリスト
Azure AI Foundry の LangChain 連携は開発者だけの話に見えますが、本番運用では管理者の確認が欠かせません。特にグローバル環境では、テナント、サブスクリプション、リージョン、プロジェクトごとに設定差分が出やすくなります。
| 確認項目 | 管理者が見るポイント | 失敗しやすい例 |
|---|---|---|
| RBAC | 対象プロジェクトに Foundry User 以上の適切なロールがあるか | 開発者には権限があるが、本番のマネージド ID には権限がない |
| ロール名 | 旧 Azure AI User などの表示が残っていても同一権限として扱えるか | 画面上のロール名差分を別権限と誤解する |
| エンドポイント | Project endpoint と OpenAI互換エンドポイントを混在させていないか | FOUNDRY_PROJECT_ENDPOINT に /openai/v1 を入れてしまう |
| シークレット | API キーを使う場合、保管場所とローテーション手順があるか | .env や CI ログにキーが残る |
| モデルデプロイ | デプロイ名、モデル種類、対応APIを一覧化しているか | カタログ名を指定して呼び出しに失敗する |
| 依存関係 | 開発、本番、バッチで同じSDK世代を使っているか | ローカルだけ成功し、コンテナ本番で失敗する |
| ログ | デバッグログにプロンプトや個人情報が出ないよう制御しているか | 障害調査で DEBUG を有効化したまま運用する |
| ツール利用 | Web search、File search、Code interpreter の利用可否を決めているか | PoC のツール設定が本番に残る |
Foundry の RBAC ロールは名称変更が行われており、Foundry User、Foundry Owner、Foundry Account Owner、Foundry Project Manager は、以前の Azure AI User、Azure AI Owner、Azure AI Account Owner、Azure AI Project Manager に相当します。公式ドキュメントでは、ロール ID と中核的な権限は変更されていないと説明されています。(Microsoft Learn)
グローバル運用で特に注意したい設計ポイント
グローバル向けに Azure AI Foundry と LangChain を運用する場合、単一リージョンのサンプルコードをそのまま全社展開するのは避けた方が安全です。プロジェクト名、エンドポイント、モデルデプロイ名、認証方式、利用できるモデルは環境によって変わる可能性があります。
実務では、次のように設定を分離します。
| 設定 | コードに直書きしない理由 | 推奨管理方法 |
|---|---|---|
| Project endpoint | プロジェクトやリージョンで変わる | 環境変数、App Configuration、Key Vault 参照 |
| モデルデプロイ名 | 環境ごとに別名になりやすい | MODEL_CHAT_PRIMARY など論理名で管理 |
| API キー | 漏えいリスクが高い | Key Vault、シークレットストア、短期ローテーション |
| ツール許可 | 国・部門・用途でポリシーが異なる | 機能フラグや環境別設定 |
| ログレベル | 個人情報や業務データを含む可能性がある | 本番は最小限、障害時のみ一時的に詳細化 |
特に RAG では、どの文書をベクトル化するか、どの国のユーザーが検索できるか、削除要求があった文書をどう再インデックスするかが運用上の論点になります。LangChain と Foundry の接続が動くことと、企業として安全に運用できることは別問題です。
よくある失敗と対処法
エンドポイント形式を混同して 404 になる
FOUNDRY_PROJECT_ENDPOINT には、Project endpoint を設定します。一方、直接 OpenAI互換APIを使う場合は OPENAI_BASE_URL に /openai/v1 形式のエンドポイントを設定します。この2つを混同すると、認証は通っているのに 404 や接続エラーになることがあります。Microsoft Foundry SDK のトラブルシューティングでも、接続エラーや 404 の場合はリソース名、プロジェクト名、エンドポイント形式を確認するよう案内されています。(Microsoft Learn)
Foundry User ロールがなく認証エラーになる
Project endpoint と Microsoft Entra ID を使う場合、対象プロジェクトに Foundry User ロールが必要です。ローカル開発者の Azure CLI では動いても、本番のマネージド ID にロールが付いていなければ失敗します。開発者個人ではなく、アプリの実行主体に権限があるかを確認してください。(Microsoft Learn)
init_chat_model が動かない
init_chat_model は便利ですが、LangChain のバージョン要件があります。古い LangChain を使っている環境では、エラーになったり、期待した provider が解決されなかったりします。すぐに LangChain を更新できない場合は、AzureAIOpenAIApiChatModel を直接構成する方法に切り替えるのが現実的です。(Microsoft Learn)
モデル名とデプロイ名を取り違える
Foundry ポータルで見える基盤モデル名と、アプリから指定するデプロイ名は異なる場合があります。開発環境で gpt-4.1 として動いていても、本番では prod-chat-primary のような別名でデプロイしていることがあります。モデル名はコードに固定せず、環境別設定として管理してください。
非同期処理で同期版 Credential を使ってしまう
ainvoke を使う場合、Microsoft Entra ID 認証では azure.identity.aio の非同期 Credential を使う必要があります。同期版 Credential を流用すると、負荷試験や本番運用で問題が出る可能性があります。非同期 API を使うアプリでは、Credential、HTTP セッション、終了処理をセットで確認してください。(Microsoft Learn)
インメモリのベクトルストアを本番に使ってしまう
公式サンプルの InMemoryVectorStore は、ローカル検証や最小構成の理解には便利です。しかし、本番の RAG では永続化、スケール、アクセス制御、削除対応、再インデックスが必要です。サンプルで動いた構成をそのまま本番に持ち込まず、運用要件に合うベクトル検索基盤を選定してください。
既存環境で今すぐやるべき確認手順
既存の Azure AI Foundry + LangChain アプリがある場合は、次の順番で確認すると効率的です。
| 手順 | 作業内容 | 完了条件 |
|---|---|---|
| 1 | パッケージを確認する | langchain-azure-ai[v1] が残っているか把握できている |
| 2 | 環境変数を確認する | FOUNDRY_PROJECT_ENDPOINT、OPENAI_BASE_URL、旧変数の利用状況を整理できている |
| 3 | 認証方式を決める | 本番は Entra ID、PoC は API キーなど方針が決まっている |
| 4 | モデルデプロイ名を一覧化する | チャット、Embedding、画像、ツール用のデプロイ名が分かる |
| 5 | クライアント作成コードを更新する | AzureAIOpenAIApiChatModel や init_chat_model で疎通できる |
| 6 | 非同期・RAG・ツールを個別にテストする | invoke だけでなく ainvoke、Embedding、File search まで確認できている |
| 7 | ログとシークレットを点検する | プロンプト、API キー、個人情報が不要に出力されない |
| 8 | CI/CD に反映する | ローカルだけでなく本番デプロイでも同じ設定で動く |
最初のテストは、複雑なチェーンではなく model.invoke("Say hello") のような最小呼び出しにするのが安全です。認証、エンドポイント、モデルデプロイ名の問題を先に切り分けてから、Prompt chain、Embedding、agent、server-side tools を順番に戻していくと、障害箇所を特定しやすくなります。
まとめ：Azure AI Foundry の LangChain 連携は「動くコード」より「運用できる設定」が重要
2026年7月2日に更新された公式ガイドは、Azure AI Foundry のモデルを LangChain から使うための実装方法を、OpenAI互換APIと langchain-azure-ai を軸に整理したものです。新規開発では、Project endpoint、Microsoft Entra ID、Foundry User ロール、デプロイ済みモデル、langchain-azure-ai の新しい構成を前提にするのが基本です。(Microsoft Learn)
既存環境では、旧 langchain-azure-ai[v1]、旧環境変数、API キー固定、モデル名直書き、同期 Credential の流用が残っていないかを確認してください。特に旧 Model Inference API 連携は、公式の旧ガイドで 2026年5月30日の廃止予定が示されていたため、残存している場合は早めに OpenAI/v1 系の実装へ移行する判断が必要です。(Microsoft Learn)
次に取るべき行動は明確です。まず、現在のアプリがどのパッケージ、どの環境変数、どの認証方式、どのモデルデプロイ名を使っているかを棚卸ししてください。そのうえで、新しい langchain-azure-ai、Project endpoint、Entra ID 認証を基準に、最小呼び出し、非同期処理、Embedding、RAG、server-side tools の順にテストを進めると、移行リスクを抑えながら実運用に耐える構成へ近づけられます。
コメント