LangChain と Azure AI Foundry を使用してアプリケーションを開発する

2025-06-26

LangChain は、論理的に思考するアプリケーションを開発者が可能な限り簡単にビルドできるようにする開発エコシステムです。このエコシステムは複数のコンポーネントによって構成されています。ほとんどのコンポーネントは単体で使用できるため、好きなものを選んで組み合わせることができます。

Azure AI Foundry にデプロイされたモデルは、次の 2 つの方法で LangChain と共に使用できます。

Azure AI モデル推論 API の使用: Azure AI Foundry にデプロイされるすべてのモデルでは、モデル推論 API がサポートされています。モデル推論 API は、カタログ内のほとんどのモデルで使用できる共通の機能セットを提供します。この API の利点は、すべてのモデルに対して同じであるために、あるモデルから別のモデルへの変更は、使用中のモデルデプロイを変更するのと同じく簡単であるということです。コードにそれ以上変更を加える必要はありません。 LangChain を使用するときは、拡張機能 langchain-azure-ai をインストールします。
モデルのプロバイダー固有の API を使用する: OpenAI、Cohere、Mistral などの一部のモデルは、LangChain 用の独自の API と拡張機能のセットを備えています。これらの拡張機能には、モデルがサポートする特定の機能が含まれる可能性があるため、それらを利用する場合に適しています。 LangChain を使用するときは、langchain-openai や langchain-cohere など、使用するモデルに固有の拡張機能をインストールします。

このチュートリアルでは、パッケージ langchain-azure-ai を使用して LangChain でアプリケーションをビルドする方法について説明します。

[前提条件]

このチュートリアルを実行するには、次のものが必要です。

Azure サブスクリプション。
モデル推論APIをサポートするモデルのデプロイが完了した。この例では、Mistral-Large-2411でデプロイを使用します。
Python 3.9 以降 (PIP を含む) がインストールされている。
LangChain がインストールされていること。これは、次を使用して行います。
```
pip install langchain
```
この例では、モデル推論 API を使用しているため、次のパッケージをインストールします。
```
pip install -U langchain-azure-ai
```

環境の構成

Azure AI Foundry ポータルにデプロイされた LLM を使用するには、エンドポイントと資格情報を使用してこれに接続する必要があります。使用するモデルから必要な情報を取得するには、次の手順に従います。

ヒント

Azure AI Foundry ポータルで左側のウィンドウをカスタマイズできるため、これらの手順に示されている項目とは異なる項目が表示される場合があります。探しているものが表示されない場合は、左側のペインの下部にある… もっと見るを選択してください。

Azure AI Foundry に移動します。
モデルがデプロイされているプロジェクトをまだ開いていない場合は開きます。
[モデル + エンドポイント] に移動し、前提条件に示されているように、デプロイしたモデルを選択します。
エンドポイントの URL とキーをコピーします。

ヒント

モデルが Microsoft Entra ID サポートを使用してデプロイされた場合は、キーは必要ありません。

このシナリオでは、エンドポイントの URL とキーを環境変数として設定します。 (コピーしたエンドポイントに /models後に追加のテキストが含まれている場合は、次に示すように URL が /models で終わるように削除します)。

export AZURE_INFERENCE_ENDPOINT="https://<resource>.services.ai.azure.com/models"
export AZURE_INFERENCE_CREDENTIAL="<your-key-goes-here>"

構成したら、 init_chat_modelを使用してチャットモデルに接続するクライアントを作成します。 Azure OpenAI モデルの場合、「Azure OpenAI モデルを使用する」で示されているようにクライアントを構成します。

from langchain.chat_models import init_chat_model

llm = init_chat_model(model="Mistral-Large-2411", model_provider="azure_ai")

クラス AzureAIChatCompletionsModel を直接使用することもできます。

import os
from langchain_azure_ai.chat_models import AzureAIChatCompletionsModel

model = AzureAIChatCompletionsModel(
    endpoint=os.environ["AZURE_INFERENCE_ENDPOINT"],
    credential=os.environ["AZURE_INFERENCE_CREDENTIAL"],
    model="Mistral-Large-2411",
)

注意事項

破壊的変更:パラメーター model_nameは、バージョン modelで0.1.3名前が変更されました。

エンドポイントが Microsoft Entra ID をサポートしている場合は、次のコードを使用してクライアントを作成できます。

import os
from azure.identity import DefaultAzureCredential
from langchain_azure_ai.chat_models import AzureAIChatCompletionsModel

model = AzureAIChatCompletionsModel(
    endpoint=os.environ["AZURE_INFERENCE_ENDPOINT"],
    credential=DefaultAzureCredential(),
    model="Mistral-Large-2411",
)

注

Microsoft Entra ID を使用する場合は、その認証方法でエンドポイントがデプロイされており、エンドポイントを呼び出すために必要なアクセス許可があることを確認してください。

非同期呼び出しを使用する予定の場合は、資格情報に非同期バージョンを使用することをお勧めします。

from azure.identity.aio import (
    DefaultAzureCredential as DefaultAzureCredentialAsync,
)
from langchain_azure_ai.chat_models import AzureAIChatCompletionsModel

model = AzureAIChatCompletionsModel(
    endpoint=os.environ["AZURE_INFERENCE_ENDPOINT"],
    credential=DefaultAzureCredentialAsync(),
    model="Mistral-Large-2411",
)

エンドポイントがサーバーレス API デプロイのように 1 つのモデルにサービスを提供している場合は、 model パラメーターを指定する必要はありません。

import os
from langchain_azure_ai.chat_models import AzureAIChatCompletionsModel

model = AzureAIChatCompletionsModel(
    endpoint=os.environ["AZURE_INFERENCE_ENDPOINT"],
    credential=os.environ["AZURE_INFERENCE_CREDENTIAL"],
)

チャット入力候補モデルを使用する

最初にモデルを直接使用しましょう。 ChatModels は LangChain Runnable のインスタンスです。つまり、インスタンスと対話するための標準インターフェイスが公開されます。モデルを呼び出すために、メッセージの一覧を invoke メソッドに渡すことができます。

from langchain_core.messages import HumanMessage, SystemMessage

messages = [
    SystemMessage(content="Translate the following from English into Italian"),
    HumanMessage(content="hi!"),
]

model.invoke(messages)

チェーンで必要に応じて操作を作成することもできます。それでは、プロンプトテンプレートを使用して文を翻訳してみましょう。

from langchain_core.output_parsers import StrOutputParser
from langchain_core.prompts import ChatPromptTemplate

system_template = "Translate the following into {language}:"
prompt_template = ChatPromptTemplate.from_messages(
    [("system", system_template), ("user", "{text}")]
)

プロンプトテンプレートからわかるように、このチェーンには language と text が入力されています。次に、出力パーサーを作成しましょう。

from langchain_core.output_parsers import StrOutputParser

parser = StrOutputParser()

これで、パイプ (|) 演算子を使用し、上記のテンプレート、モデル、出力パーサーを組み合わせることができます。

chain = prompt_template | model | parser

チェーンを呼び出すには、必要な入力を特定し、invoke メソッドを使用して値を指定します。

chain.invoke({"language": "italian", "text": "hi"})

複数の LLM を連結する

Azure AI Foundry にデプロイされたモデルでは、モデル推論 API がサポートされています。これは、すべてのモデルで標準です。各モデルの機能に基づいて複数の LLM 操作を連結し、機能に基づいて最適なモデルが活用されるようにします。

次の例では、2 つのモデルクライアントを作成します。 1人はプロデューサーで、もう1人は検証者です。区別を明確にするために、Foundry Models API のようなマルチモデルエンドポイントを使用しているため、modelとMistral-Large モデルを使用するためにパラメーター Mistral-Smallを渡しています。これは、コンテンツの生成が検証よりも複雑であるという事実を引用しています。

from langchain_azure_ai.chat_models import AzureAIChatCompletionsModel

producer = AzureAIChatCompletionsModel(
    endpoint=os.environ["AZURE_INFERENCE_ENDPOINT"],
    credential=os.environ["AZURE_INFERENCE_CREDENTIAL"],
    model="Mistral-Large-2411",
)

verifier = AzureAIChatCompletionsModel(
    endpoint=os.environ["AZURE_INFERENCE_ENDPOINT"],
    credential=os.environ["AZURE_INFERENCE_CREDENTIAL"],
    model="mistral-small",
)

ヒント

各モデルのモデルカードを調べ、各モデルに最適なユースケースを理解します。

次の例では、都会の詩人によって書かれた詩が生成されます。

from langchain_core.prompts import PromptTemplate

producer_template = PromptTemplate(
    template="You are an urban poet, your job is to come up \
             verses based on a given topic.\n\
             Here is the topic you have been asked to generate a verse on:\n\
             {topic}",
    input_variables=["topic"],
)

verifier_template = PromptTemplate(
    template="You are a verifier of poems, you are tasked\
              to inspect the verses of poem. If they consist of violence and abusive language\
              report it. Your response should be only one word either True or False.\n \
              Here is the lyrics submitted to you:\n\
              {input}",
    input_variables=["input"],
)

次に、ピースを連結してみましょう。

chain = producer_template | producer | parser | verifier_template | verifier | parser

前のチェーンは、ステップ verifier の出力のみを返します。 producer によって生成される中間結果にアクセスする必要があるため、LangChain では、RunnablePassthrough オブジェクトを使用してその中間ステップも出力する必要があります。

from langchain_core.runnables import RunnablePassthrough, RunnableParallel

generate_poem = producer_template | producer | parser
verify_poem = verifier_template | verifier | parser

chain = generate_poem | RunnableParallel(poem=RunnablePassthrough(), verification=RunnablePassthrough() | verify_poem)

チェーンを呼び出すには、必要な入力を特定し、invoke メソッドを使用して値を指定します。

chain.invoke({"topic": "living in a foreign country"})

埋め込みモデルを使用する

LLM クライアントを作成するのと同じ方法で、埋め込みモデルに接続できます。次の例では、環境変数を埋め込みモデルを指すように設定しています。

export AZURE_INFERENCE_ENDPOINT="<your-model-endpoint-goes-here>"
export AZURE_INFERENCE_CREDENTIAL="<your-key-goes-here>"

次に、以下のようにクライアントを作成します。

import os
from langchain_azure_ai.embeddings import AzureAIEmbeddingsModel

embed_model = AzureAIEmbeddingsModel(
    endpoint=os.environ["AZURE_INFERENCE_ENDPOINT"],
    credential=os.environ["AZURE_INFERENCE_CREDENTIAL"],
    model="text-embedding-3-large",
)

次の例は、メモリ内のベクトルストアを使用する簡単な例を示しています。

from langchain_core.vectorstores import InMemoryVectorStore

vector_store = InMemoryVectorStore(embed_model)

ドキュメントをいくつか追加してみましょう。

from langchain_core.documents import Document

document_1 = Document(id="1", page_content="foo", metadata={"baz": "bar"})
document_2 = Document(id="2", page_content="thud", metadata={"bar": "baz"})

documents = [document_1, document_2]
vector_store.add_documents(documents=documents)

類似性で検索してみましょう。

results = vector_store.similarity_search(query="thud", k=1)
for doc in results:
    print(f"* {doc.page_content} [{doc.metadata}]")

Azure OpenAI モデルを使用する

langchain-azure-ai パッケージで Azure OpenAI モデルを使用している場合は、次の URL を使用します。

from langchain_azure_ai.chat_models import AzureAIChatCompletionsModel

llm = AzureAIChatCompletionsModel(
    endpoint="https://<resource>.openai.azure.com/openai/v1",
    credential=os.environ["AZURE_INFERENCE_CREDENTIAL"],
    model="gpt-4o"
)

デバッグとトラブルシューティング

アプリケーションをデバッグし、Azure AI Foundry のモデルに送信される要求を理解する必要がある場合は、統合のデバッグ機能を次のように使用できます。

まず、ログ記録を関心のあるレベルに構成します。

import sys
import logging

# Acquire the logger for this client library. Use 'azure' to affect both
# 'azure.core` and `azure.ai.inference' libraries.
logger = logging.getLogger("azure")

# Set the desired logging level. logging.INFO or logging.DEBUG are good options.
logger.setLevel(logging.DEBUG)

# Direct logging output to stdout:
handler = logging.StreamHandler(stream=sys.stdout)
# Or direct logging output to a file:
# handler = logging.FileHandler(filename="sample.log")
logger.addHandler(handler)

# Optional: change the default logging format. Here we add a timestamp.
formatter = logging.Formatter("%(asctime)s:%(levelname)s:%(name)s:%(message)s")
handler.setFormatter(formatter)

要求のペイロードを確認するには、クライアントをインスタンス化するときに、引数 logging_enable=True を client_kwargs に渡します。

import os
from langchain_azure_ai.chat_models import AzureAIChatCompletionsModel

model = AzureAIChatCompletionsModel(
    endpoint=os.environ["AZURE_INFERENCE_ENDPOINT"],
    credential=os.environ["AZURE_INFERENCE_CREDENTIAL"],
    model="Mistral-Large-2411",
    client_kwargs={"logging_enable": True},
)

コードでクライアントを通常のとおりに使用します。

トレース

トレーサーを作成することで、Azure AI Foundry のトレース機能を使用できます。ログは Azure Application Insights に格納され、Azure Monitor または Azure AI Foundry ポータルを使用していつでもクエリすることができます。各 AI ハブには、関連付けられている Azure Application Insights があります。

インストルメンテーション接続文字列を取得する

ヒント

Azure Application Insights にテレメトリを送信するようにアプリケーションを構成するには、次のいずれかのようにします。

Azure Application Insights への接続文字列を直接使用する。
1. Azure AI Foundry ポータルに移動し、[トレース] を選択します。
2. [データソースの管理] を選択します。この画面で、プロジェクトに関連付けられているインスタンスを確認できます。
3. [接続文字列] にある値をコピーし、次の変数に設定します。
```
import os

application_insights_connection_string = "instrumentation...."
```
Azure AI Foundry SDK とプロジェクト接続文字列の使用 (ハブベースのプロジェクトのみ)。
1. 使用している環境に azure-ai-projects パッケージがインストールされていることを確認します。
2. Azure AI Foundry ポータルに移動します。
3. プロジェクトの接続文字列をコピーし、次のコードを設定します。
```
from azure.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential

project_client = AIProjectClient.from_connection_string(
    credential=DefaultAzureCredential(),
    conn_str="<your-project-connection-string>",
)

application_insights_connection_string = project_client.telemetry.get_connection_string()
```

Azure AI Foundry のトレースを構成する

次のコードでは、Azure AI Foundry のプロジェクトの背後にある Azure Application Insights に接続されたトレーサーを作成します。パラメーター enable_content_recording が True に設定されていることに注意してください。これにより、アプリケーション全体の入力と出力、および中間ステップのキャプチャが可能になります。このようにすると、アプリケーションのデバッグとビルド時には便利ですが、運用環境では無効にすることも考えられます。環境変数 AZURE_TRACING_GEN_AI_CONTENT_RECORDING_ENABLED の既定の値になります。

from langchain_azure_ai.callbacks.tracers import AzureAIInferenceTracer

tracer = AzureAIInferenceTracer(
    connection_string=application_insights_connection_string,
    enable_content_recording=True,
)

チェーンでトレースを構成するには、invoke 操作の値の構成をコールバックとして指定します。

chain.invoke({"topic": "living in a foreign country"}, config={"callbacks": [tracer]})

トレース用にチェーン自体を構成するには、.with_config() メソッドを使用します。

chain = chain.with_config({"callbacks": [tracer]})

続いて、通常どおり invoke() メソッドを使用します。

chain.invoke({"topic": "living in a foreign country"})

トレースを表示する

トレースを確認するには次のようにします。

Azure AI Foundry ポータルに移動します。
[トレース] セクションに移動します。
作成したトレースを特定します。トレースが表示されるまでに数秒かかる場合があります。

詳細については、「トレースを視覚化して管理するプロジェクトを作成および管理する方法」を参照してください。