Microsoft Foundry에서 모델과 함께 LangChain 사용

langchain-azure-ai 사용하여 Microsoft Foundry에 배포된 모델을 호출하는 LangChain 앱을 빌드합니다. OpenAI 호환 API를 사용하는 모델을 직접 사용할 수 있습니다. 이 문서에서는 채팅 및 임베딩 클라이언트를 만들고, 프롬프트 체인을 실행하며, 생성을 검증 워크플로우와 결합하는 과정을 수행합니다.

필수 구성 요소

• Azure 구독입니다. 무료로 만듭니다.

• Foundry 프로젝트입니다.

• Foundry 프로젝트의 Foundry 사용자 역할입니다.

  중요

  Foundry RBAC 역할의 이름이 최근에 바뀌었습니다. Foundry User, Foundry OwnerFoundry 계정 소유자 및 Foundry Project Manager는 이전에 Azure AI 사용자, Azure AI 소유자, Azure AI 계정 소유자 및 Azure AI Project Manager로 이름이 지정되었습니다. 이름 바꾸기가 롤아웃되는 동안 일부 위치에서는 이전 이름이 계속 표시될 수 있습니다. 역할 ID 및 핵심 권한은 이름 바꾸기에 의해 변경되지 않습니다.

• OpenAI 호환 API(예: gpt-4.1 또는 Mistral-Large-3.)를 지원하는 배포된 채팅 모델입니다.

• 배포된 임베딩 모델(예: text-embedding-3-large)입니다.

• Python 3.9 이상.

필요한 패키지를 설치합니다.

pip install -U langchain langchain-azure-ai azure-identity

환경 구성

다음 연결 패턴 중 하나를 설정합니다.

• Microsoft Entra ID와 연결된 프로젝트 엔드포인트(권장).
• API 키를 사용하여 엔드포인트를 직접 지정합니다.

import os

# Option 1: Project endpoint (recommended)
os.environ["AZURE_AI_PROJECT_ENDPOINT"] = (
	"https://<resource>.services.ai.azure.com/api/projects/<project>"
)

# Option 2: Direct OpenAI-compatible endpoint + API key
os.environ["OPENAI_BASE_URL"] = (
	"https://<resource>.services.ai.azure.com/openai/v1"
)
os.environ["OPENAI_API_KEY"] = "<your-api-key>"

이 코드 조각이 수행하는 작업: 프로젝트 기반 또는 직접 엔드포인트 액세스를 위해 모델 클래스에서 사용하는 langchain-azure-ai 환경 변수를 정의합니다.

채팅 모델 사용

다음을 사용하여 init_chat_model모델을 쉽게 인스턴스화할 수 있습니다.

from langchain.chat_models import init_chat_model

model = init_chat_model("azure_ai:gpt-4.1")

OpenAI 호환 API를 지원하는 모든 Foundry 모델은 클라이언트와 함께 사용할 수 있지만 먼저 Foundry 리소스에 배포해야 합니다. project_endpoint(환경 변수 AZURE_AI_PROJECT_ENDPOINT)를 사용하려면 인증에 대한 Microsoft Entra ID 및 Foundry User 역할이 필요합니다.

이 코드 조각이 수행하는 작업: 편리한 방법을 사용하여 채팅 모델 클라이언트를 init_chat_model 만듭니다. 클라이언트는 환경에 구성된 Foundry 프로젝트 엔드포인트 또는 직접 엔드포인트를 통해 지정된 모델로 라우팅됩니다.

참조:

• AzureAIOpenAIApiChatModel

설치 확인

간단한 모델 호출을 실행합니다.

response = model.invoke("Say hello")
response.pretty_print()

================================== Ai Message ==================================
Hello! 👋 How can I help you today?

이 코드 조각이 수행하는 작업: 엔드포인트, 인증 및 모델 라우팅을 확인하는 기본 프롬프트를 보냅니다.

참조:

• LangChain 실행 가능 인터페이스

구성 가능한 모델

를 지정하여 런타임 구성 가능 모델을 만들 수도 있습니다 configurable_fields. 매개 변수를 model 생략하면 기본적으로 구성 가능한 필드가 됩니다.

from langchain.chat_models import init_chat_model
from azure.identity import DefaultAzureCredential

configurable_model = init_chat_model(
    model_provider="azure_ai", 
    temperature=0,
	credential=DefaultAzureCredential()
)


configurable_model.invoke(
    "what's your name",
    config={"configurable": {"model": "gpt-5-nano"}},  # Run with GPT-5-nano
).pretty_print()

configurable_model.invoke(
    "what's your name",
    config={"configurable": {"model": "Mistral-Large-3"}}, # Run with Mistral Large
).pretty_print()

================================== Ai Message ==================================

Hi! I'm ChatGPT, an AI assistant built by OpenAI. You can call me ChatGPT or just Assistant. How can I help you today?
================================== Ai Message ==================================

I don't have a name, but you can call me **Assistant** or anything you like! 😊 What can I help you with today?

이 코드 조각이 수행하는 작업: 호출 시 모델을 쉽게 전환할 수 있는 구성 가능한 모델 인스턴스를 만듭니다. model 매개 변수가 init_chat_model에 없기 때문에 기본적으로 구성 가능한 필드이며, invoke()와 함께 전달될 수 있습니다. 다른 필드를 구성 가능하도록 configurable_fields를 설정할 수 있습니다.

클라이언트를 직접 구성

클래스를 사용하여 AzureAIOpenAIApiChatModel 채팅 모델 클라이언트를 만들 수도 있습니다.

import os

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

model = AzureAIOpenAIApiChatModel(
	project_endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
	credential=DefaultAzureCredential(),
	model="Mistral-Large-3",
)

기본적으로 AzureAIOpenAIApiChatModel OpenAI 응답 API를 사용합니다. 다음을 전달 use_responses_api=False하여 이 동작을 변경할 수 있습니다.

import os

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

model = AzureAIOpenAIApiChatModel(
    endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
    credential=DefaultAzureCredential(),
    model="Mistral-Large-3",
    use_responses_api=False
)

비동기 호출 실행

앱이 ainvoke을(를) 사용하여 모델을 호출하는 경우 비동기 자격 증명을 사용합니다. 인증에 Microsoft Entra ID 사용하는 경우 자격 증명에 해당하는 비동기 구현을 사용합니다.

import os

from azure.identity.aio import DefaultAzureCredential as DefaultAzureCredentialAsync
from langchain_azure_ai.chat_models import AzureAIOpenAIApiChatModel

model = AzureAIOpenAIApiChatModel(
	project_endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
	credential=DefaultAzureCredentialAsync(),
	model="gpt-4.1",
)


async def main():
	response = await model.ainvoke("Say hello asynchronously")
	response.pretty_print()


import asyncio
asyncio.run(main())

================================== Ai Message ==================================
Hello! 👋 How can I help you today?

이 코드 조각이 수행하는 작업: 비동기 클라이언트를 만들고 ainvoke과 함께 비차단 요청을 실행합니다.

참조:

• Azure ID의 동기화 자격 증명
• LangChain 실행 가능 인터페이스

추론

많은 모델이 다단계 추론을 수행하여 결론에 도달할 수 있습니다. 여기에는 복잡한 문제를 더 작고 관리하기 쉬운 단계로 나누는 작업이 포함됩니다.

from langchain.chat_models import init_chat_model

model = init_chat_model("azure_ai:DeepSeek-R1-0528")

for chunk in model.stream("Why do parrots have colorful feathers?"):
    reasoning_steps = [r for r in chunk.content_blocks if r["type"] == "reasoning"]
    print(reasoning_steps if reasoning_steps else chunk.text, end="")

print("\n")

Parrots have colorful feathers primarily due to a combination of evolutionary ...

참조:

• LangChain 스트리밍

서버 쪽 도구

Foundry에 배포된 OpenAI 모델은 서버 쪽 도구 호출 루프를 지원합니다. 모델은 웹 검색, 코드 인터프리터 및 기타 도구와 상호 작용한 다음 단일 대화형 턴에서 결과를 분석할 수 있습니다. 모델이 도구 서버 쪽을 호출하는 경우 응답 메시지의 콘텐츠에는 도구의 호출 및 결과를 나타내는 콘텐츠가 포함됩니다.

이러한 도구는 모델의 기능을 확장하는 OpenAI에서 제공하는 도구입니다. 지원되는 도구의 전체 목록을 보려면 기본 제공 도구를 참조하세요.

다음 예제에서는 웹 검색을 사용하는 방법을 보여줍니다.

from langchain.chat_models import init_chat_model
from langchain_azure_ai.tools.builtin import WebSearchTool
from azure.identity import DefaultAzureCredential

model = init_chat_model("azure_ai:gpt-4.1", credential=DefaultAzureCredential())
model_with_web_search = model.bind_tools([WebSearchTool()])

result = model_with_web_search.invoke("What is the current price of gold? Give me the answer in one sentence.")
result.content[-1]["text"]

As of today, March 24, 2026, the spot price of gold is approximately $4,397.80 per ounce. ([tradingeconomics.com](https://tradingeconomics.com/commodity/gold))

일부 도구에는 프로젝트의 다른 리소스 구성이 필요할 수 있습니다. azure-ai-projects를 사용하여 이러한 리소스를 구성한 다음 LangChain/LangGraph에서 참조합니다.

다음 예제에서는 도구에서 사용하기 전에 파일 저장소를 구성하는 방법을 보여줍니다.

import os
from azure.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential

# Create clients to call Foundry API
project = AIProjectClient(
    endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
    credential=DefaultAzureCredential(),
)
openai = project.get_openai_client()

# Create vector store and upload file
vector_store = openai.vector_stores.create(name="ProductInfoStore")
vector_store_id = vector_store.id

with open("product_info.md", "rb") as file_handle:
    vector_store_file = openai.vector_stores.files.upload_and_poll(
        vector_store_id=vector_store.id,
        file=file_handle,
    )

이 코드 조각이 수행하는 작업: 모델이 나중에 해당 파일의 콘텐츠를 검색할 수 있도록 Microsoft Foundry의 파일로 벡터 저장소를 설정합니다(다음 코드 블록의 FileSearchTool 사용).

from langchain_azure_ai.tools.builtin import FileSearchTool

model_with_tools = model.bind_tools([FileSearchTool(vector_store_ids=[vector_store.id])])

results = model_with_tools.invoke("Tell me about Contoso products")
print("Answer:", results.content[-1]["text"])
print("Annotations:", results.content[-1]["annotations"])

Answer: Contoso offers the following products:

1. **The widget**
   - Description: A high-quality widget that is perfect for all your widget needs.
   - Price: $19.99

2. **The gadget**
   - Description: An advanced gadget that offers exceptional performance and reliability.
   - Price: $49.99

These products are part of Contoso's main offerings as detailed in their product information documentation.
Annotations: [{'file_id': 'assistant-MvU5SEqUcUBumoLUV5BXxn', 'filename': 'product_info.md', 'type': 'file_citation', 'file_index': 395}]

에이전트에서 Foundry 모델 사용

다음과 같이 Foundry에 연결된 모델과 함께 create_agent를 사용하여 ReAct 스타일 에이전트 루프를 만듭니다.

from langchain.agents import create_agent

agent = create_agent(
    model="azure_ai:gpt-5.2", 
    system_prompt="You're an informational agent. Answer questions cheerfully.", 
)

response = agent.invoke({"messages": "what's your name?"})
response["messages"][-1].pretty_print()

================================== Ai Message ==================================

I’m ChatGPT, your AI assistant.

서버 쪽 도구도 사용할 수 있지만 호출 bind_tools이 필요합니다.

from langchain.chat_models import init_chat_model
from langchain.agents import create_agent
from langchain_azure_ai.tools.builtin import ImageGenerationTool

model = init_chat_model("azure_ai:gpt-5.2")
tools = [ImageGenerationTool(model="gpt-image-1.5", size="1024x1024")]
model_with_tools = model.bind_tools(tools)

agent = create_agent(
    model=model_with_tools,
    tools=tools,
    system_prompt="You're an informational agent. Answer questions with graphics.", 
)

임베딩 모델 사용

다음을 사용하여 init_embeddings모델을 쉽게 인스턴스화할 수 있습니다.

from langchain.embeddings import init_embeddings

embed_model = init_embeddings("azure_ai:text-embedding-3-small")

이 코드 조각이 수행하는 작업: 편의 메서드를 사용하여 embeddings 모델 클라이언트를 init_embeddings 만듭니다.

OpenAI 호환 API를 지원하는 모든 Foundry 모델은 클라이언트와 함께 사용할 수 있지만 먼저 Foundry 리소스에 배포해야 합니다. project_endpoint(환경 변수 AZURE_AI_PROJECT_ENDPOINT)를 사용하려면 인증에 대한 Microsoft Entra ID 및 Foundry User 역할이 필요합니다.

또는 AzureAIOpenAIApiEmbeddingsModel을 사용하여 embeddings 클라이언트를 만듭니다.

import os

from azure.identity import DefaultAzureCredential
from langchain_azure_ai.embeddings import AzureAIOpenAIApiEmbeddingsModel

embed_model = AzureAIOpenAIApiEmbeddingsModel(
	project_endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
	credential=DefaultAzureCredential(),
	model="text-embedding-3-large",
)

직접 엔드포인트 및 API 키 인증의 경우:

import os

from langchain_azure_ai.embeddings import AzureAIOpenAIApiEmbeddingsModel

embed_model = AzureAIOpenAIApiEmbeddingsModel(
	endpoint=os.environ["OPENAI_BASE_URL"],
	credential=os.environ["OPENAI_API_KEY"],
	model="text-embedding-3-large",
)

이 코드 조각이 수행하는 작업: 벡터 검색, 검색 및 순위 워크플로에 대한 포함 생성을 구성합니다.

참조:

• AzureAIOpenAIApiEmbeddingsModel

예: 벡터 저장소를 사용하여 유사성 검색 실행

로컬 실험을 위해 메모리 내 벡터 저장소를 사용합니다.

from langchain_core.documents import Document
from langchain_core.vectorstores import InMemoryVectorStore

vector_store = InMemoryVectorStore(embed_model)

documents = [
	Document(id="1", page_content="foo", metadata={"baz": "bar"}),
	Document(id="2", page_content="thud", metadata={"bar": "baz"}),
]

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}]")

* thud [{'bar': 'baz'}]

이 코드 조각이 수행하는 작업: 샘플 문서를 벡터 저장소에 추가하고 쿼리에 가장 유사한 문서를 반환합니다.

참조:

• LangChain 벡터 저장소

로깅을 사용하여 요청 디버그

langchain_azure_ai 디버그 로깅을 사용하도록 설정하여 요청 흐름을 확인합니다.

import logging
import sys

logger = logging.getLogger("langchain_azure_ai")
logger.setLevel(logging.DEBUG)

handler = logging.StreamHandler(stream=sys.stdout)
formatter = logging.Formatter(
	"%(asctime)s:%(levelname)s:%(name)s:%(message)s"
)
handler.setFormatter(formatter)
logger.addHandler(handler)

이 코드 조각이 수행하는 작업: 엔드포인트 또는 페이로드 문제를 해결하는 데 도움이 되는 자세한 SDK 로그를 내보내도록 Python 로깅을 구성합니다.

참조:

• Python 로깅

환경 변수 참조

다음 환경 변수를 구성할 수 있습니다. 개체를 생성할 때 이러한 값을 구성할 수도 있습니다.

다음 단계

관련 콘텐츠

• Foundry 모델 개요
• Microsoft Foundry SDK 개요
• Foundry에서 메모리와 함께 LangChain 사용
• Foundry 에이전트 서비스에서 LangChain 사용