Microsoft 통합 가이드

Microsoft 통합 가이드 (Microsoft integrations)

LangChain이 Microsoft Azure와 Microsoft 제품과 제공하는 모든 통합을 다루는 페이지예요. 핵심 권장 사항은, 새로 LangChain·LangGraph 앱을 만들 때는 Microsoft Foundry를 중심으로 두라는 거예요. Foundry 중심 앱은 langchain-azure-ai 패키지로 시작해서 Foundry 프로젝트 엔드포인트·Azure 자격 증명·Agent Service·호스팅·툴·Content Safety·검색·관찰성까지 한 번에 잡을 수 있어요. 반대로 Azure OpenAI v1 API를 직접 쓰거나 OpenAI와 Azure를 오가는 코드가 필요하면 langchain-openai 패키지를 쓰면 돼요.

출처: 공식문서

패키지 선택하기

langchain-azure-ai와 langchain-openai는 대안이라기보다 서로 보완적인 관계예요. langchain-azure-ai는 langchain-openai에 의존하고, 채팅·임베딩 클래스가 ChatOpenAI와 OpenAIEmbeddings를 상속해요. 시나리오별 시작점:

시나리오	패키지
Foundry 프로젝트 중심의 새 앱	`langchain-azure-ai`
Foundry Agent Service, 호스팅된 LangGraph, Toolbox, Content Safety, Azure 툴, Application Insights	`langchain-azure-ai`
Foundry 프로젝트 엔드포인트에서 구성한 임베딩	`langchain-azure-ai`
Azure OpenAI v1 채팅 직접 호출	`langchain-openai`
같은 코드로 OpenAI와 Azure 전환	`langchain-openai`
기존 `AzureChatOpenAI` 앱	`langchain-openai`
전통적 날짜 버전의 Azure OpenAI API	`langchain-openai`
Completion LLM 인터페이스	`langchain-openai`
최소 의존성·운영 표면	`langchain-openai`

기존 langchain-openai 앱을 langchain-azure-ai로 옮기는 건 import만 바꾸는 간단한 일이 아니에요. 설정이 달라서 azure_endpoint, azure_deployment, api_version, 토큰 제공자 인자가 project_endpoint 또는 endpoint, model, credential로 바뀌어요. 또 AzureAIOpenAIApiChatModel은 프로젝트 엔드포인트를 해석하면 기본값으로 Responses API를 쓰는데, Chat Completions 동작을 유지하려면 use_responses_api=False를 설정해야 해요. AzureOpenAI에 해당하는 completion-LLM은 langchain-azure-ai에 없고요, 두 패키지 모두 공식 OpenAI 스키마를 따르므로 DeepSeek·Mistral 같은 호환 provider의 비표준 필드는 보존되지 않을 수 있어요.

채팅 모델

Azure로 채팅 모델에 접근하는 세 가지 주요 옵션:

Microsoft Foundry(프로젝트 중심 앱에 권장): langchain-azure-ai의 AzureAIOpenAIApiChatModel을 Foundry 프로젝트 엔드포인트 + Azure 자격 증명으로 사용. Foundry 에이전트·호스팅·툴·Content Safety·검색·관찰성도 통합.
Azure OpenAI: langchain-openai의 ChatOpenAI로 v1 API 직접 호출 또는 OpenAI/Azure 전환 코드. AzureChatOpenAI는 전통적 Azure OpenAI API 버전과 기존 앱용.
Azure ML: Azure Machine Learning으로 커스텀·파인튜닝 오픈소스 모델을 배포·관리.

Microsoft Foundry — 프로젝트 엔드포인트 설정 후 채팅 모델 생성:

export AZURE_AI_PROJECT_ENDPOINT="https://<resource>.services.ai.azure.com/api/projects/<project>"

from azure.identity import DefaultAzureCredential
from langchain_azure_ai.chat_models import AzureAIOpenAIApiChatModel

llm = AzureAIOpenAIApiChatModel(
    model="gpt-5.2",  # your Foundry model deployment name
    credential=DefaultAzureCredential(),
)

Azure OpenAI v1 — v1 API에서는 ChatOpenAI를 Azure 엔드포인트에 직접 사용하고 api_version은 필요 없어요:

pip install azure-identity

from azure.identity import DefaultAzureCredential, get_bearer_token_provider
from langchain_openai import ChatOpenAI

token_provider = get_bearer_token_provider(
    DefaultAzureCredential(),
    "https://cognitiveservices.azure.com/.default",
)

llm = ChatOpenAI(
    model="gpt-5.4-mini",  # your Azure deployment name
    base_url="https://YOUR-RESOURCE-NAME.openai.azure.com/openai/v1/",
    api_key=token_provider,  # callable that handles token refresh
)

전통적 Azure OpenAI API 버전에는 AzureChatOpenAI를 사용해요:

from langchain_openai import AzureChatOpenAI

Responses API — Azure OpenAI는 상태ful 대화, 내장 툴(웹 검색·파일 검색·코드 인터프리터), 구조화된 추론 요약을 제공하는 Responses API를 지원해요. ChatOpenAI는 reasoning 파라미터를 설정하면 Responses API로 자동 라우팅되고, use_responses_api=True로 명시적으로 선택할 수도 있어요.

LLM

Azure로 LLM에 접근하는 두 가지 주요 옵션: Azure OpenAI(권장, langchain-openai의 AzureOpenAI로 텍스트 완성 배포 사용)와 Azure ML(커스텀·오픈소스 모델 호스팅).

from azure.identity import DefaultAzureCredential, get_bearer_token_provider
from langchain_openai import AzureOpenAI

token_provider = get_bearer_token_provider(
    DefaultAzureCredential(),
    "https://cognitiveservices.azure.com/.default",
)

llm = AzureOpenAI(
    azure_deployment="gpt-5.4-mini",  # your Azure deployment name
    api_version="2025-04-01-preview",
    azure_ad_token_provider=token_provider,
)

print(llm.invoke("Write a haiku about the ocean."))

임베딩

임베딩 통합은 1) Microsoft Foundry(권장, langchain-azure-ai의 AzureAIOpenAIApiEmbeddingsModel), 2) Azure OpenAI(langchain-openai의 AzureOpenAIEmbeddings)로 나뉘어요. Foundry 프로젝트 구성은 임베딩이 아직 프로젝트 엔드포인트 자체로는 서빙되지 않아 /openai/v1 엔드포인트를 직접 유도해요.

미들웨어

langchain-azure-ai 패키지는 AzureContentModerationMiddleware 등 Azure AI Content Safety 미들웨어를 export해요. 텍스트·이미지 조정, 프롬프트 인젝션 탐지, 보호 콘텐츠 탐지, 근거성(groundedness) 평가를 에이전트에 적용할 수 있어요.

문서 로더와 백엔드

AzureBlobStorageLoader로 Azure Blob Storage 문서를 로드할 수 있어요. 또 langchain-azure-storage의 AzureBlobBackend는 Deep Agents BackendProtocol을 구현해서 딥 에이전트가 전체 워크스페이스(파일·기억·아티팩트)를 blob 컨테이너에 영속화할 수 있게 해줘요 (현재 Public Preview, Python 3.11+ 필요).

Foundry 호스팅 에이전트

langchain_azure_ai.agents.hosting 패키지로 컴파일된 LangGraph 그래프를 Foundry가 관리하는 런타임에 노출할 수 있어요. 호스팅 지원에는 langchain-azure-ai[hosting]>=1.2.8이 필요해요. 프로토콜은 Responses(ResponsesHostServer, /responses)와 Invocations(InvocationsHostServer, /invocations) 중에서 선택해요. 구성 기반 러너는 python -m langchain_azure_ai.agents.hosting.run --protocol responses로 시작하고, 배포는 azd ai agent init → azd ai agent run → azd deploy 순으로 진행해요.

더 알아보기 (Learn more)

Microsoft Foundry 채팅 모델 통합 문서
Azure ChatOpenAI 통합 문서
Microsoft Foundry 미들웨어 가이드