Mulai menggunakan LangChain dan LangGraph dengan Foundry

Gunakan paket langchain-azure-ai sebagai titik masuk untuk membangun aplikasi LangChain dan LangGraph dengan kemampuan Microsoft Foundry. Artikel ini memberi Anda peta paket tingkat tinggi sehingga Anda dapat memulai dengan cepat, lalu berpindah ke dokumentasi mendalam yang tepat untuk setiap kemampuan.

Prasyarat

  • Langganan Azure. Buat satu secara gratis.

  • Proyek Foundry.

  • Peran Pengguna Foundry di proyek Foundry (peran dengan hak akses minimum untuk

    Important

    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.

    pengembangan). Jika Anda juga membuat atau mengelola sumber daya, gunakan Kontributor atau Pemilik sesuai kebutuhan. Untuk detailnya, lihat kontrol akses berbasis Role untuk Microsoft Foundry.

  • Python 3.10 atau yang lebih baru.

  • Azure CLI masuk (az login) sehingga DefaultAzureCredential dapat mengautentikasi.

Tips

Artikel ini menyebutkan dukungan untuk Microsoft Foundry (baru), yang menggunakan versi azure-ai-projects>=2.0. Jika Anda menggunakan Foundry klasik, gunakan langchain-azure-ai[v1] sebagai gantinya.

Menginstal paket

Instal paket dasar:

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

Instal ekstra opsional berdasarkan skenario Anda:

pip install -U "langchain-azure-ai[tools]"
pip install -U "langchain-azure-ai[opentelemetry]"
  • Gunakan [tools] jika aplikasi Anda menggunakan alat dari namespace langchain_azure_ai.tools.*, seperti Kecerdasan Dokumen.
  • Gunakan [opentelemetry] jika Anda ingin melacak integrasi melalui OpenTelemetry.

Pilih blok penyusun integrasi

Gunakan peta ini untuk memilih namespace yang tepat untuk solusi Anda:

Kemampuan Namespace Penggunaan umum
Layanan Agen Foundry langchain_azure_ai.agents Buat simpul agen terkelola untuk membangun grafik dan alur kompleks untuk LangGraph dan LangChain. Lihat contoh terperinci.
Hosting LangGraph langchain_azure_ai.agents.hosting Host agen LangGraph terkompilasi di Foundry Agent Service dengan protokol Responses atau Invocations. Lihat contoh terperinci.
Keamanan Konten Foundry langchain_azure_ai.agents.middleware Gunakan Foundry Content Safety and Moderation untuk memastikan Anda dapat menyebarkan solusi dengan pagar pembatas yang tepat. Lihat contoh terperinci.
Model percakapan langchain_azure_ai.chat_models Panggil Azure OpenAI dan model obrolan katalog model. Lihat contoh terperinci.
Penyisipan langchain_azure_ai.embeddings Panggil model penyematan dari katalog dan hasilkan vektor untuk alur kerja pencarian, pengambilan, dan peringkat. Lihat contoh terperinci.
Penyimpanan vektor langchain_azure_ai.vectorstores Gunakan integrasi vektor Pencarian Azure AI dan Cosmos DB.
Retriever langchain_azure_ai.retrievers Jalankan pengambilan melalui indeks dan penyimpanan yang didukung Azure.
Penyimpanan riwayat obrolan langchain_azure_ai.chat_history Pertahankan dan putar ulang riwayat obrolan di seluruh sesi. Gunakan riwayat yang didukung oleh memori untuk mengambil riwayat obrolan masa lalu yang terkonsolidasi. Lihat contoh terperinci.
Perangkat langchain_azure_ai.tools Tambahkan alat seperti Kecerdasan Dokumen, Visi, analitik teks kesehatan, dan Logic Apps; atau seluruh kotak alat proyek. Lihat contoh terperinci
Kotak Alat Foundry langchain_azure_ai.tools Muat alat dan keterampilan terkelola dari Foundry Toolbox melalui satu endpoint MCP. Lihat contoh terperinci.
Panggilan balik dan pelacakan langchain_azure_ai.callbacks Tangkap peristiwa run dan keluarkan jejak OpenTelemetry. Lihat contoh terperinci.
Konstruktor kueri langchain_azure_ai.query_constructors Buat filter kueri khusus backend untuk skenario pengambilan.
Pemuat dokumen langchain_azure_ai.document_loaders Muat dokumen dan media dengan contoh Pemahaman Konten.

Lihat bagian Pelajari setiap kemampuan secara terperinci untuk panduan tertentu.

Menghubungkan dengan titik akhir dan kredensial proyek

Banyak kelas langchain-azure-ai mendukung koneksi melalui endpoint proyek Foundry. Atur AZURE_AI_PROJECT_ENDPOINT sekali, lalu gunakan kembali di seluruh kelas yang didukung.

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

Saat Anda menggunakan project_endpoint, autentikasi menggunakan Microsoft Entra ID dan Azure RBAC pada proyek.

Kunci API adalah untuk titik akhir layanan langsung, seperti /openai/v1.

export OPENAI_BASE_URL="https://<resource>.services.ai.azure.com/openai/v1"
export OPENAI_API_KEY="<your-key>"

Contoh: Menggunakan Model Foundry

Setelah variabel lingkungan dikonfigurasi, Anda dapat menggunakan model dengan:

from langchain.chat_models import init_chat_model

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

Anda juga dapat mengonfigurasi klien secara khusus. Sebagai contoh, mari kita lihat AzureAIOpenAIApiChatModel sebagai pola representatif:

import os

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

# Option A: Use a Foundry project endpoint (Microsoft Entra ID required).
model_from_project = AzureAIOpenAIApiChatModel(
  project_endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
  credential=DefaultAzureCredential(),
  model="gpt-5.2",
)

# Option B: Use a service endpoint directly with an API key.
model_from_endpoint = AzureAIOpenAIApiChatModel(
  endpoint=os.environ["OPENAI_BASE_URL"],
  credential=os.environ["OPENAI_API_KEY"],
  model="gpt-5.2",
)

# Option C: Use a different credential strategy.
model_with_cli_credential = AzureAIOpenAIApiChatModel(
  endpoint=os.environ["OPENAI_BASE_URL"],
  credential=AzureCliCredential(),
  model="gpt-5.2",
)

Apa yang dilakukan cuplikan ini: Memperlihatkan model yang sama yang diinisialisasi dari titik akhir proyek Foundry atau dari titik akhir layanan langsung, dan memperlihatkan cara menukar kredensial.

Anda dapat menerapkan pola yang sama ke alat. Misalnya, AzureAIDocumentIntelligenceTool dapat menggunakan titik akhir proyek dan DefaultAzureCredential tanpa konfigurasi tambahan saat AZURE_AI_PROJECT_ENDPOINT diatur:

from langchain_azure_ai.tools import AzureAIDocumentIntelligenceTool

document_tool = AzureAIDocumentIntelligenceTool()

Cara kerja DefaultAzureCredential

DefaultAzureCredential mencoba beberapa sumber kredensial Microsoft Entra ID secara berurutan dan menggunakan sumber pertama yang berfungsi. Sumber umum adalah variabel lingkungan, identitas terkelola, alat pengembang, dan Azure CLI.

Gunakan DefaultAzureCredential sebagai default untuk pengembangan lokal dan beban kerja yang disebarkan. Jika Anda memerlukan kontrol yang lebih ketat, ganti dengan kredensial tertentu seperti AzureCliCredential untuk pengembangan khusus lokal atau ManagedIdentityCredential untuk beban kerja produksi di Azure.

Pola titik akhir proyek yang sama juga digunakan oleh kelas lain.

Pelajari setiap kemampuan secara rinci

Mulailah dengan panduan ini dalam kumpulan dokumentasi ini:

Gunakan sumber daya paket ini untuk detail dan pembaruan tingkat modul:

Temukan sampel

Gunakan repositori ini untuk menemukan contoh skenario Anda:

Langkah berikutnya

Menggunakan Model Foundry dengan LangChain

  • Terakhir diperbarui pada