LangChainとAzure OpenAIの連携手順｜初期化の差分とキーレス認証

LangChainで動いているコードの接続先をAzure OpenAIへ向けると、書き換わるのは主にモデルクラスの初期化部分です。エンドポイント、デプロイ名、API版の三つを渡し、認証をAPIキーかMicrosoft Entra IDのどちらかに決める。ここを外すと、鍵が正しいのに404が返る、埋め込みだけ通らない、といった切り分けにくい状態になります。この記事では2026年8月17日時点のPyPIとLangChain公式ドキュメントの実測値をもとに、AzureChatOpenAIとAzureOpenAIEmbeddingsの引数差分、OpenAI版コードからの移行で詰まる箇所、キーレス認証の組み方、Azure AI 検索と組むRAG最小構成のパッケージ選択までを整理します。

まとめ：書き換わるのは初期化の三引数と認証方式に集約される

結論から示します。LangChainのAzure対応は別フレームワークではなく、同じlangchain-openaiパッケージ内のクラス差し替えです。ChatOpenAIをAzureChatOpenAIに、OpenAIEmbeddingsをAzureOpenAIEmbeddingsに置き換え、エンドポイント・デプロイ名・API版を渡せば、その先のチェーンやエージェントの記述は触らずに動きます。

移行時の事故は、ほぼ二種類に集約されます。ひとつはmodelにモデル名を書いてしまう取り違えで、Azure側では実体がデプロイ名のため404になります。もうひとつは認証方式の選択で、APIキーをコードや環境変数で配る構成を続けるか、Entra IDのキーレス認証へ寄せるかの判断です。小規模かつ単一チームならキー方式のままで支障はありません。複数チームが同じリソースを共有する段階に入ったら、権限をロールで切れるEntra ID方式へ移すべきです。

RAGまで組む場合は、パッケージの選択がもう一段あります。Azure AI 検索との接続はマイクロソフト提供のlangchain-azure-aiに集約が進んでおり、新規に組むならこちらを起点にするのが素直な選択です。

AzureChatOpenAIの初期化でOpenAI版と変わる引数と環境変数の扱い

まず、どの値をどこから渡すのかを固定します。Azure OpenAIそのものの提供範囲や料金体系はAzure OpenAI Serviceの概要と導入事例をまとめた解説で扱っているため、ここでは接続に必要な指定だけを扱います。

azure_endpointとdeployment・api_versionの役割の違い

LangChain公式のAzureChatOpenAI統合ページが示す導入手順はpip install -U langchain-openaiの一行だけで、Azure専用のパッケージは要りません。初期化で例示されている引数はazure_deployment、api_version、temperature、max_tokens、timeout、max_retriesの六つです。

このうちAzure固有の意味を持つのは前二つです。azure_endpointはリソース単位のホスト名を示す値で、azure_deploymentはそのリソース内に作ったモデルの配置名です。api_versionはリクエストのスキーマ版を固定する値で、公式ドキュメントの例では2025-04-01-previewのような日付形式が入ります。三つは階層が違う値で、どれかひとつが欠けると別のエラーとして表面化します。

langchain-openai 1.5系が要求するopenaiとPythonの下限

依存関係の噛み合わせは先に確認しておく価値があります。2026年8月17日時点のPyPIではlangchain-openaiの最新が1.5.1で、依存にopenaiが2.45.0以上4.0.0未満、langchain-coreが1.5.4以上2.0.0未満、tiktokenが0.7.0以上と宣言されています。対応するPythonは3.10以上です。

ここで問題になるのが、社内に残っている旧環境です。Python 3.9で動いている既存のバッチにそのまま入れようとすると解決に失敗します。openaiを1系に固定している既存プロジェクトも同様で、先にSDK側を上げる工程が必要になります。1.5系への追随を止めて版を固定する判断もありますが、その場合はAzure側の新しいAPI形式に追随できなくなる点を織り込んでください。

環境変数で既定値を持つ指定とデプロイ名だけ渡す必要がある理由

LangChainリファレンスによると、既定値を環境変数から拾う引数は決まっています。azure_endpointはAZURE_OPENAI_ENDPOINT、api_keyはAZURE_OPENAI_API_KEY、openai_api_versionはAZURE_OPENAI_API_VERSIONを参照します。

一方でデプロイ名に対応する環境変数はありません。理由は単純で、同じリソースに複数のデプロイを置くのが通常の構成だからです。チャット用と埋め込み用で別のデプロイを指すため、プロセス単位の環境変数では表現できません。結果として、環境変数を整えてもazure_deploymentだけはコード側に残ります。ここを「環境変数で全部済むはず」と考えて省略すると、接続先が定まらないまま失敗します。

OpenAI版コードから移行するときに404と認証で詰まる箇所の切り分け

ここからは、実際に書き換えたときに出るエラーの読み方を扱います。呼び出しそのものの手順やREST版の確認方法はAzure OpenAI APIの使い方をリソース作成から追った記事に譲り、本節ではLangChain層に固有の症状に絞ります。

model引数にデプロイ名を渡す設計が生む404の切り分け手順

移行直後にもっとも多いのが、鍵もエンドポイントも正しいのに404が返る状態です。原因はgpt-4oのようなモデル名をそのまま渡した点です。Azureではモデルの実体がデプロイであり、ポータル上で付けた配置名がURLに埋まります。切り分けは次の順で進めると短く済みます。

1. ポータルのデプロイ一覧で、配置名の綴りと大小文字を目視で照合する
2. その名前をリテラルでazure_deploymentに直書きして単発実行する
3. 通ったら環境変数や設定ファイル側の受け渡しを疑う
4. 通らなければエンドポイントのホスト名を確認する

三段目で切り分けが終わるケースが大半です。設定ファイルの階層を深くしている案件ほど、値が届いていないだけという結末になります。

AzureOpenAIEmbeddingsでモデル名とデプロイ名を取り違えた場合の症状

埋め込み側は症状の出方が違います。AzureOpenAIEmbeddingsが受け取る引数はmodel、dimensions、chunk_size、azure_endpoint、api_key、openai_api_versionで、チャット側と語彙が揃っていません。チャットは通るのに埋め込みだけ落ちる、という非対称な壊れ方をします。

厄介なのは、次元数の不一致が例外ではなく検索結果の劣化として出る場合です。text-embedding-3-large系はdimensionsで出力次元を縮められますが、インデックス作成時の次元数と食い違うと、書き込みは通っても検索が意味を成しません。埋め込みモデルを差し替えるときは、インデックスを作り直す前提で計画してください。

api_versionをコードで固定するか環境変数へ逃がすかの線引き

版指定をどこに置くかは、更新の頻度で決まります。検証環境で新しい機能を試す段階ならコードに直書きして差分を見えるようにし、本番の複数サービスで同じ版を揃えたい段階なら環境変数へ寄せます。

判断の前提として、Azure側の版体系そのものが移行期にあります。日付形式の版指定とv1形式の扱いはapi-versionの意味とv1 APIへの移行を整理した記事で扱っており、LangChain側はその値を透過的に渡しているだけです。つまりLangChainを挟んでいても、版の互換性はAzure側の仕様に従います。フレームワークが吸収してくれる範囲ではありません。

Entra IDのキーレス認証をLangChain側で成立させる実装と適用の範囲

認証は、コードの分量としては数行です。判断すべきは「いつ切り替えるか」のほうです。

get_bearer_token_providerで作る供給関数の受け渡しと必要な準備

公式ドキュメントが示すキーレス構成は、追加パッケージがazure-identityひとつ、関数呼び出しが三つという小ささです。DefaultAzureCredentialで資格情報を作り、get_bearer_token_providerにその資格情報とスコープcognitiveservices.azure.com/.defaultを渡してトークン供給関数を得ます。得られた関数をAzureChatOpenAIのazure_ad_token_providerに渡すと、以後のトークン更新は自動で回ります。

api_keyの指定は不要になり、コードから鍵という文字列が消えます。注意点は、ローカル開発と本番で資格情報の取得元が変わることです。開発者のサインイン情報で通っていたものが、本番のマネージドIDでは権限不足で落ちる。この差はコードではなくロール割り当て側の話で、権限設計の全体像はAzure OpenAIのセキュリティ設計をまとめた記事で扱っています。

APIキー方式のまま据え置いてよい運用規模と認証切り替えを急ぐ条件

ここは言い切ります。単一チームが単一のデプロイを使い、鍵をシークレット管理サービスに置いて回している段階なら、キー方式のままで構いません。切り替えの手間に見合う効果が出ません。

切り替えを急ぐべき条件は三つです。複数チームが同一リソースを共有していて誰がどのデプロイを叩いたか追えないとき。退職や異動のたびに鍵の再発行が発生しているとき。そして監査で「認証情報の共有をやめること」を指摘されたときです。この三つのいずれかに当たったら、鍵の管理を厳しくする方向ではなく、鍵そのものをなくす方向へ倒すのが結果的に安く済みます。

Azure AI 検索と組むRAG最小構成の部品構成とパッケージ選択の判断軸

RAGまで組むと、登場する部品が三つに増えます。チャットモデル、埋め込みモデル、そしてベクトルの置き場です。LangChainそのものの構成概念はLangChainの仕組みと採用判断を解説した記事で扱っているため、ここではAzure側の部品の組み合わせ方に絞ります。

langchain-azure-ai 1.2.8が束ねる依存関係と版の噛み合わせ

2026年8月17日時点のPyPIではlangchain-azure-aiの最新が1.2.8で、公開日は2026年6月30日です。マイクロソフト側が提供するこのパッケージは、Microsoft Foundry（旧Azure AI）系の機能をLangChainとLangGraphから扱えるようにするもので、Azure AI 検索向けのベクトルストアもここに含まれます。ソースを確認すると、langchain_azure_ai.vectorstoresが公開しているクラスは4種で、Azure AI 検索向けのものとCosmos DB系の3種という内訳でした。

依存の宣言はazure-search-documentsが11.4以上13.0未満、langchainが1.2.12以上、langchain-openaiが1.0.0以上、langgraphが1.1.1以上です。既存プロジェクトがlangchainの0系や1.1系で止まっていると、このパッケージを足した時点でまとめて上がります。RAGの追加を「ライブラリを一本足すだけ」と見積もると、そこで工数が膨らみます。

チャットモデル側で二系統のクラスが並ぶ構成と要件別の選び分けの基準

チャットモデルには経路が二つあります。langchain-openaiのAzureChatOpenAIと、langchain-azure-ai側のAzureAIChatCompletionsModel・AzureAIOpenAIApiChatModel・AzureAIAnthropicChatModelです。

選び分けの基準は単純です。呼ぶモデルがOpenAI系だけで完結するならAzureChatOpenAIで足ります。Foundry上のカタログから他社モデルも含めて差し替えたい要件があるなら、後者の系統を選びます。両方を同じアプリに混在させると、認証の渡し方と例外の型が二系統になって保守が重くなるため、どちらかに寄せてください。

取得処理を自前で組む構成とAzureマネージド機能に寄せる構成の分岐

取得部分をAzure側のマネージド機能に任せる選択肢も存在したものの、こちらは提供終了が決まった構成です。移行の期限と構成の詳細はOn Your Dataの構成と移行判断を整理した記事にまとめています。新規案件では選べないため、実質的にはLangChainで取得部分を自前で組む構成が既定になります。

自前で組む場合、検索方式・チャンク分割・引用の返し方をすべて自分たちで決めることになります。ここは制御が利く反面、精度が出るまでの検証工数が読みにくい領域です。社内文書を対象にした構成の設計や、既存の索引を再利用した移行を外部と組んで進める場合は、RAG構築支援で扱っている検証の進め方が参考になります。非Azure環境も含めた汎用的な組み立て方はLangChainを使ったRAGの実践方法を解説した記事で扱っています。

LangChainを挟むべき案件と直接SDKで足りる案件を分ける条件

最後に採用判断を示します。フレームワークを入れること自体が目的化すると、依存が増えるだけで終わります。

LangChainを外したほうが記述量も依存も減る三つの条件

次の条件に当てはまるなら、LangChainを挟まずopenaiパッケージを直接呼ぶほうが軽く済みます。

• 単発のチャット呼び出しだけで、履歴も取得処理も持たない
• 取得先が自社の既存API一本で、抽象化する対象が存在しない
• 依存パッケージの版を長期固定したい制約が先にある

三つ目は見落とされがちです。langchain-openaiはlangchain-coreの版に強く紐づくため、周辺パッケージを足すたびに解決範囲が変動する関係です。版を止めたい要件が先にあるなら、SDKを直接呼ぶほうが管理は楽になります。逆に、取得先が複数ある、モデルを差し替えて比較する、エージェント的な分岐を持つ、といった要件があるならLangChainの抽象化が効きます。

失敗パターン：抽象化に寄せてAzure固有の設定へ届かなくなる構成

実装で見かける失敗は、共通ラッパーを自作してOpenAI版とAzure版を一枚のインターフェースに押し込む設計です。動き出しは速いのですが、Azure側だけに必要な指定が増えたときに破綻します。デプロイ名の切り替え、版の固定、キーレス認証のトークン供給関数、これらはOpenAI版に対応物がありません。

共通化するなら、モデルを生成する工場関数までに留めて、それより下のチェーンだけを共有する構成にしてください。生成部分をクラウドごとに分けておけば、Azure固有の引数が増えても影響範囲が閉じます。設定を一枚に統合したくなる誘惑はありますが、ここは分けたままにしておくほうが後の変更に耐えます。

よくある質問

LangChainとAzure OpenAIの接続について、実装時に確認されることの多い点をまとめます。

AzureChatOpenAIとChatOpenAIでコードはどこまで共有できますか？

初期化より下、つまりプロンプトの組み立て、チェーンの接続、出力パーサ、エージェントの定義はそのまま共有できます。どちらも同じインターフェースを実装しているため、モデルオブジェクトを差し替えるだけで動きます。共有できないのは初期化そのもので、エンドポイント、デプロイ名、版の指定、認証方式の四点はAzure側に固有です。ここだけを生成関数に切り出して分岐させる構成にすると、移行の影響範囲が最小になります。

api_versionはどの値を指定すればよいですか？

使いたい機能が要求する版を確認して固定するのが基本です。LangChain公式ドキュメントの例では2025-04-01-previewのような日付形式が示されていますが、これはあくまで例示であり、推奨値ではありません。プレビュー版はスキーマが変わる可能性があるため、本番では安定版を選び、版を上げるときは検証環境で先に通してください。版体系の全体像はAzure側の仕様に属します。

デプロイ名とモデル名が違う場合、どちらを書けばよいですか？

azure_deploymentにはポータルで付けた配置名を書きます。モデル名ではありません。両者を同じ文字列にしておく運用も可能ですが、同一モデルを用途別に複数デプロイする場合は名前が分かれるため、揃える前提で設計しないほうが安全です。埋め込み側のAzureOpenAIEmbeddingsは引数名がmodelのまま残っている箇所があるため、チャット側と同じ感覚で書くと取り違えます。

LangChainからキーレス認証を使うには何を追加すればよいですか？

azure-identityパッケージの追加と、トークン供給関数の生成、そしてazure_ad_token_providerへの受け渡しの三つです。コード量は数行ですが、実際に通すにはAzure側でロールの割り当てが必要になります。ローカル開発では開発者のサインイン情報、本番ではマネージドIDと、資格情報の取得元が変わる点に注意してください。コードは同じでも権限が別なので、環境ごとにロール付与を確認します。

langchain-openaiとlangchain-azure-aiのどちらを使うべきですか？

チャットと埋め込みだけならlangchain-openaiで完結します。Azure AI 検索をベクトルの置き場として使う、あるいはFoundry上の他社モデルも呼ぶ、という要件が出た段階でlangchain-azure-aiを足します。ただし後者は依存が広く、langchain本体やLangGraphの版まで引き上げるため、既存プロジェクトに入れるときは版の噛み合わせを先に検証してください。

関連記事

• Azure OpenAI Serviceとは？できること・料金・導入事例まで実務目線で解説：本記事の接続先そのものの提供範囲と料金体系を扱っています。
• Azure OpenAI APIの使い方｜リソース作成からPython・REST呼び出しまでの実装手順：フレームワークを挟まない素の呼び出し手順と疎通確認の進め方をまとめています。
• Azure OpenAIのapi-versionとは？v1 APIへの移行とバージョン固定の判断：本記事で扱った版指定の体系と移行の判断軸を詳しく扱っています。
• Azure OpenAI On Your Dataとは？廃止予定までの構成と移行の判断：取得処理をマネージド機能に任せる構成と、その提供終了までの扱いを整理しています。
• LangChainとは？LLMアプリ開発フレームワークの仕組み・できること・採用判断を解説：フレームワーク自体の構成概念と採用可否の判断を扱う判断ハブです。