Menggunakan LangChain dengan model di Microsoft Foundry

Gunakan langchain-azure-ai untuk membangun aplikasi LangChain yang memanggil model yang disebarkan di Microsoft Foundry. Model dengan API yang kompatibel dengan OpenAI dapat langsung digunakan. Dalam artikel ini, Anda membuat klien percakapan dan embeddings, menjalankan rangkaian perintah, dan menggabungkan pembuatan dengan alur kerja verifikasi.

Prasyarat

Langganan Azure. Buat satu secara gratis.
Proyek Foundry.
Peran Pengguna Foundry pada proyek Foundry.

Penting

Peran Foundry RBAC baru-baru ini diubah namanya. Pengguna Foundry, Pemilik Foundry, Pemilik Akun Foundry, dan Manajer Proyek Foundry sebelumnya bernama Pengguna Azure AI, Pemilik Azure AI, Pemilik Akun Azure AI, dan Manajer Proyek Azure AI. Anda mungkin masih melihat nama sebelumnya di beberapa tempat saat penggantian nama diluncurkan. ID peran dan izin inti tidak berubah oleh penggantian nama.
Model obrolan yang disebarkan yang mendukung API yang kompatibel dengan OpenAI, seperti gpt-4.1 atau Mistral-Large-3.
Model embedding yang disebarkan, seperti text-embedding-3-large.
Python 3.10 atau yang lebih baru.

Instal paket yang diperlukan:

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

Penting

langchain-azure-ai menggunakan Microsoft Foundry SDK (v2) baru. Jika Anda menggunakan Foundry klasik, gunakan langchain-azure-ai[v1], yang menggunakan Azure AI Inference SDK (dihentikan). Pelajari lebih lanjut.

Mengonfigurasi lingkungan

Atur salah satu pola koneksi berikut:

Proyek endpoint dengan Microsoft Entra ID (disarankan).
Titik akhir langsung dengan kunci API.

import os

# Option 1: Project endpoint (recommended)
os.environ["FOUNDRY_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>"

Apa yang dilakukan cuplikan ini: Menentukan variabel lingkungan yang digunakan oleh langchain-azure-ai kelas model untuk akses titik akhir berbasis proyek atau langsung.

Menggunakan model obrolan

Anda dapat dengan mudah membuat instans model dengan menggunakan init_chat_model:

from langchain.chat_models import init_chat_model

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

Penting

Menggunakan init_chat_model memerlukan langchain>=1.2.13. Jika Anda tidak dapat memperbarui versi, konfigurasikan klien secara langsung.

Semua model Foundry yang mendukung API yang kompatibel dengan OpenAI dapat digunakan dengan klien, tetapi Anda perlu menyebarkannya ke sumber daya Foundry Anda terlebih dahulu. Menggunakan project_endpoint (variabel lingkungan FOUNDRY_PROJECT_ENDPOINT) memerlukan Microsoft Entra ID untuk autentikasi dan peran Foundry User.

Apa yang dilakukan cuplikan kode ini: Membuat klien model obrolan dengan menggunakan init_chat_model metode yang praktis. Klien mengarahkan ke model yang telah ditentukan melalui titik akhir proyek Foundry atau titik akhir langsung yang telah dikonfigurasi dalam lingkungan.

Referensi:

AzureAIOpenAIApiChatModel

Verifikasi pengaturan Anda

Jalankan pemanggilan model sederhana:

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

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

Apa yang dilakukan cuplikan ini: Mengirim permintaan dasar untuk memverifikasi titik akhir, autentikasi, dan perutean model.

Referensi:

Antarmuka yang dapat dijalankan LangChain

Model yang dapat dikonfigurasi

Anda juga dapat membuat model yang dapat dikonfigurasi runtime dengan menentukan configurable_fields. Saat Anda menghilangkan model parameter, parameter tersebut menjadi bidang yang dapat dikonfigurasi secara default.

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?

Apa yang dilakukan cuplikan ini: Membuat instans model yang dapat dikonfigurasi yang memungkinkan Anda untuk beralih model dengan mudah pada waktu pemanggilan. Karena parameter model hilang di init_chat_model, bidang tersebut secara default bidang yang dapat dikonfigurasi dan dapat diteruskan dengan invoke(). Anda dapat menambahkan bidang lain agar dapat dikonfigurasi dengan mengonfigurasi configurable_fields.

Mengonfigurasi klien secara langsung

Anda juga dapat membuat klien model obrolan dengan menggunakan AzureAIOpenAIApiChatModel kelas .

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",
)

Secara bawaan, AzureAIOpenAIApiChatModel menggunakan OpenAI Responses API. Anda dapat mengubah perilaku ini dengan meneruskan use_responses_api=False:

import os

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

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

Menjalankan panggilan asinkron

Gunakan kredensial asinkron jika aplikasi Anda memanggil model dengan ainvoke. Saat menggunakan Microsoft Entra ID untuk autentikasi, gunakan implementasi asinkron yang sesuai untuk kredensial:

import os

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()


import asyncio
asyncio.run(main())

Tips

Jika Anda menjalankan kode ini di buku catatan Jupyter, Anda bisa menggunakan await main() secara langsung alih-alih asyncio.run(main()).

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

Apa yang dilakukan cuplikan ini: Membuat klien asinkron dan menjalankan permintaan non-pemblokiran dengan ainvoke.

Referensi:

Penalaran

Banyak model dapat melakukan penalaran multi-langkah untuk sampai pada kesimpulan. Ini melibatkan memecah masalah kompleks menjadi langkah-langkah yang lebih kecil dan lebih mudah dikelola.

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 ...

Referensi:

LangChain Streaming

Alat sisi server

Model OpenAI yang disebarkan di Foundry mendukung perulangan panggilan alat sisi server: model dapat berinteraksi dengan pencarian web, penerjemah kode, dan alat lainnya, lalu menganalisis hasilnya dalam satu giliran percakapan. Jika model memanggil alat pada sisi server, konten pesan respons akan menyertakan konten yang mewakili pemanggilan dan hasil dari alat tersebut.

Penting

Alat di namespace langchain_azure_ai.tools.builtin hanya didukung dalam model OpenAI.

Ini adalah alat yang disediakan oleh OpenAI yang memperluas kemampuan model. Untuk melihat daftar lengkap alat yang didukung, lihat alat bawaan.

Contoh berikut menunjukkan cara menggunakan pencarian web:

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))

Beberapa alat mungkin memerlukan konfigurasi sumber daya lain dalam proyek Anda. Gunakan azure-ai-projects untuk mengonfigurasi sumber daya tersebut lalu mereferensikannya dari LangChain/LangGraph.

Contoh berikut menunjukkan cara mengonfigurasi penyimpanan file sebelum menggunakannya dalam alat:

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

# Create clients to call Foundry API
project = AIProjectClient(
    endpoint=os.environ["FOUNDRY_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,
    )

Apa cuplikan ini melakukan: Menyiapkan penyimpanan vektor dengan file di Microsoft Foundry sehingga model nantinya dapat mencari konten file tersebut (digunakan dengan FileSearchTool di blok kode berikutnya).

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

Menggunakan model Foundry di agen

Gunakan create_agent dengan model yang terhubung ke Foundry untuk membuat loop agen bergaya 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.

Alat sisi server juga dapat digunakan, tetapi memerlukan panggilan 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.", 
)

Tips

Alat pembuatan gambar di Foundry memerlukan penyertaan nama penyebaran model sebagai bagian dari header untuk pembuatan gambar, x-ms-oai-image-generation-deployment. Saat menggunakan langchain-azure-ai, ini ditangani secara otomatis. Namun, jika Anda berencana menggunakan alat ini dengan langchain-openai, Anda harus meneruskan header secara manual.

Menggunakan model embedding

Anda dapat dengan mudah membuat instans model dengan menggunakan init_embeddings:

from langchain.embeddings import init_embeddings
from azure.identity import DefaultAzureCredential

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

Apa yang dilakukan cuplikan ini: Membuat klien model embedding dengan menggunakan init_embeddings metode praktis. Tidak seperti init_chat_model, init_embeddings tidak secara otomatis kembali ke DefaultAzureCredential, jadi berikan kredensial secara eksplisit.

Atau buat klien embedding dengan AzureAIOpenAIApiEmbeddingsModel.

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",
)

Untuk titik akhir langsung dan autentikasi kunci 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",
)

Apa yang dilakukan cuplikan ini: Mengonfigurasi pembuatan penyematan untuk alur kerja pencarian, pengambilan, dan peringkat vektor.

Referensi:

AzureAIOpenAIApiEmbeddingsModel

Contoh: Menjalankan pencarian kesamaan dengan penyimpanan vektor

Gunakan penyimpanan vektor dalam memori untuk eksperimen lokal.

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'}]

Apa yang dilakukan cuplikan ini: Menambahkan dokumen sampel ke penyimpanan vektor dan mengembalikan dokumen yang paling mirip untuk kueri.

Referensi:

Penyimpanan vektor LangChain

Melakukan debugging permintaan dengan pencatatan log

Aktifkan langchain_azure_ai pengelogan debug untuk memeriksa alur permintaan.

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)

Apa yang dilakukan cuplikan ini: Mengonfigurasi penyimpanan log Python untuk mengeluarkan log SDK terperinci yang membantu menyelesaikan masalah pada titik akhir atau payload.

Referensi:

pengelogan Python

Referensi variabel lingkungan

Anda dapat mengonfigurasi variabel lingkungan berikut. Nilai-nilai ini juga dapat dikonfigurasi saat membuat objek:

Variabel	Peran	Contoh	Parameter dalam konstruktor
`FOUNDRY_PROJECT_ENDPOINT`	Titik akhir proyek Foundry. Penggunaan titik akhir proyek memerlukan autentikasi Microsoft Entra ID (disarankan).	`https://contoso.services.ai.azure.com/api/projects/my-project`	`project_endpoint`
`AZURE_OPENAI_ENDPOINT`	Dukung sumber daya OpenAI.	`https://contoso.openai.azure.com`	Tidak.
`OPENAI_BASE_URL`	Endpoint yang kompatibel dengan OpenAI yang langsung digunakan untuk pemanggilan model.	`https://contoso.services.ai.azure.com/openai/v1`	`endpoint`
`OPENAI_API_KEY` Atau `AZURE_OPENAI_API_KEY`	Kunci API yang digunakan dengan `OPENAI_BASE_URL` atau `AZURE_OPENAI_ENDPOINT` untuk autentikasi berbasis kunci.	`<your-api-key>`	`credential`
`AZURE_OPENAI_DEPLOYMENT_NAME`	Nama penyebaran model di sumber daya Foundry atau OpenAI. Periksa nama di portal Foundry karena nama penyebaran dapat berbeda dari model dasar yang digunakan. Model apa pun yang mendukung API yang kompatibel dengan OpenAI dapat digunakan, namun, tidak semua parameter mungkin didukung.	`Mistral-Large-3`	`model`
`AZURE_OPENAI_API_VERSION`	Versi API yang akan digunakan. Ketika `api_version` tersedia, kami membuat klien OpenAI dan menyuntikkan parameter kueri `api-version` melalui `default_query`.	`v1` Atau `preview`	`api_version`

Penting

Variabel lingkungan AZURE_AI_INFERENCE_ENDPOINT dan AZURE_AI_CREDENTIALS digunakan untuk AzureAIChatCompletionsModel atau AzureAIEmbeddingsModel (warisan) tidak lagi digunakan.

Langkah berikutnya

Menggunakan Foundry Content Safety dengan LangGraph

Saran dan Komentar

Apakah halaman ini membantu?

Terakhir diperbarui pada 2026-09-03

Menggunakan LangChain dengan model di Microsoft Foundry

Prasyarat

Mengonfigurasi lingkungan

Menggunakan model obrolan

Verifikasi pengaturan Anda

Model yang dapat dikonfigurasi

Mengonfigurasi klien secara langsung

Menjalankan panggilan asinkron

Penalaran

Alat sisi server

Menggunakan model Foundry di agen

Menggunakan model embedding

Contoh: Menjalankan pencarian kesamaan dengan penyimpanan vektor

Melakukan debugging permintaan dengan pencatatan log

Referensi variabel lingkungan

Langkah berikutnya

Konten terkait

Saran dan Komentar

Sumber Daya Tambahan: