Tutorial: Bagian 1 - Menyiapkan lingkungan proyek dan pengembangan untuk membangun aplikasi pengambilan pengetahuan kustom (RAG) dengan Microsoft Foundry SDK (klasik)

Hanya berlaku untuk:Portal Foundry (klasik). Artikel ini tidak tersedia untuk portal Foundry baru. Pelajari selengkapnya tentang portal baru.

Catatan

Tautan dalam artikel ini mungkin membuka konten dalam dokumentasi Microsoft Foundry baru alih-alih dokumentasi Foundry (klasik) yang Anda lihat sekarang.

Dalam tutorial ini, Anda menyiapkan sumber daya yang diperlukan untuk membangun aplikasi obrolan pengambilan pengetahuan kustom (RAG) dengan Microsoft Foundry SDK. Ini adalah bagian salah satu dari seri tutorial tiga bagian. Anda membuat sumber daya di sini, membangun aplikasi di bagian dua, dan mengevaluasinya di bagian tiga. Di bagian ini, Anda:

  • Membuat proyek
  • Membuat indeks Pencarian Azure AI
  • Instal Azure CLI dan masuk
  • Menginstal Python dan paket
  • Menyebarkan model ke dalam proyek Anda
  • Mengonfigurasi variabel lingkungan Anda

Jika Anda telah menyelesaikan tutorial atau panduan memulai cepat lainnya, Anda mungkin sudah membuat beberapa sumber daya yang diperlukan untuk tutorial ini. Jika ya, jangan ragu untuk melewati langkah-langkah tersebut.

Prasyarat

Penting

Artikel ini menyediakan dukungan warisan untuk proyek berbasis hub. Ini tidak akan berfungsi untuk proyek Foundry. Lihat Bagaimana cara mengetahui jenis proyek mana yang saya miliki?

catatan kompatibilitas SDK: Contoh kode memerlukan versi SDK Foundry Microsoft tertentu. Jika Anda mengalami masalah kompatibilitas, pertimbangkan untuk bermigrasi dari proyek berbasis hub ke Foundry.

  • Akun Azure dengan langganan aktif dan peran sebagai Owner atau Contributor yang telah ditetapkan. Jika Anda tidak memilikinya, buat akun secara gratis.
  • Microsoft Foundry: Peran Pemilik atau Kontributor untuk membuat proyek.

Membuat proyek berbasis hub

Untuk membuat proyek berbasis hub di Microsoft Foundry, ikuti langkah-langkah berikut:

  1. Masuk ke Microsoft Foundry. Pastikan tombol New Foundry nonaktif. Langkah-langkah ini mengacu pada Foundry (klasik).

  2. Apa yang Anda lakukan selanjutnya tergantung pada di mana Anda berada:

    • Jika Anda belum berada dalam proyek, atau belum memiliki proyek apa pun: Pilih Buat baru di kanan atas untuk membuat proyek Foundry baru

      Cuplikan layar memperlihatkan cara membuat proyek baru di Foundry.

    • Jika Anda berada dalam proyek: Pilih breadcrumb proyek, lalu pilih Buat sumber daya baru.

      Cuplikan layar memperlihatkan pembuatan proyek baru dari remah roti.

  3. Pilih sumber daya hub AI, lalu pilih Berikutnya.

  4. Masukkan nama untuk proyek.

  5. Jika Anda memiliki hub, Anda akan melihat hub yang terakhir Anda gunakan dipilih.

    • Jika Anda memiliki akses ke lebih dari satu hub, Anda dapat memilih hub yang berbeda dari menu dropdown.

    • Jika Anda ingin membuat hub baru, pilih Buat hub baru dari menu dropdown.

      Cuplikan layar halaman detail proyek dalam dialog buat proyek.

  6. Jika Anda tidak memiliki hub, hub default dibuat untuk Anda.

  7. Pilih Buat.

Menyebarkan model

Anda memerlukan dua model untuk membangun aplikasi obrolan berbasis RAG: model obrolan OpenAI Azure (gpt-4o-mini) dan model penyematan OpenAI Azure (text-embedding-ada-002). Sebarkan model ini di proyek Foundry Anda dengan menggunakan serangkaian langkah ini untuk setiap model.

Langkah-langkah ini menyebarkan model ke titik akhir real-time dari katalog model portal Foundry:

Tips

Karena Anda dapat kustomisasi panel kiri di portal Microsoft Foundry, Anda mungkin melihat item yang berbeda dari yang diperlihatkan dalam langkah-langkah ini. Jika Anda tidak melihat apa yang Anda cari, pilih ... Lainnya di bagian bawah panel kiri.

  1. Di panel kiri, pilih Katalog model.

  2. Pilih model gpt-4o-mini dari daftar model. Anda dapat menggunakan bilah pencarian untuk menemukannya.

    Cuplikan layar halaman pemilihan model.

  3. Pada halaman detail model, pilih Gunakan model ini.

  4. Biarkan nama Penyebaran default dan pilih Sebarkan. Atau, jika model tidak tersedia di wilayah Anda, wilayah lain dipilih untuk Anda dan tersambung ke proyek Anda. Dalam hal ini, pilih Sambungkan dan sebarkan.

Setelah Anda menerapkan gpt-4o-mini, lakukan lagi langkah-langkah untuk menerapkan model text-embedding-ada-002.

Membuat layanan Pencarian Azure AI

Tujuan dari aplikasi ini adalah untuk membumikan respons model dalam data kustom Anda. Indeks pencarian mengambil dokumen yang relevan berdasarkan pertanyaan pengguna.

Anda memerlukan layanan dan koneksi Pencarian Azure AI untuk membuat indeks pencarian.

Catatan

Membuat layanan Pencarian Azure AI dan indeks pencarian berikutnya dikenakan biaya. Untuk mengonfirmasi biaya sebelum membuat sumber daya, periksa kategori harga dan biaya untuk layanan Pencarian Azure AI pada halaman pembuatan. Untuk tutorial ini, gunakan tingkat harga Dasar atau yang lebih tinggi.

Jika Anda sudah memiliki layanan Pencarian Azure AI, lanjutkan ke bagian berikutnya.

Jika tidak, buat layanan Pencarian Azure AI dengan menggunakan portal Azure.

Tips

Langkah ini adalah satu-satunya waktu Anda menggunakan portal Azure dalam seri tutorial ini. Anda melakukan sisa pekerjaan Anda di portal Foundry atau di lingkungan pengembangan lokal Anda.

  1. Buat layanan Pencarian Azure AI di portal Azure.
  2. Pilih grup sumber daya dan detail instans Anda. Periksa harga dan tingkatan harga di halaman ini. Untuk tutorial ini, gunakan tingkat harga Dasar atau yang lebih tinggi.
  3. Lanjutkan penggunaan wizard dan pilih Tinjau + tetapkan guna membuat sumber daya.
  4. Konfirmasikan detail layanan Pencarian Azure AI Anda, termasuk perkiraan biaya.
  5. Pilih Buat untuk membuat layanan Pencarian Azure AI.

Menyambungkan Pencarian Azure AI ke proyek Anda

Jika proyek Anda sudah memiliki koneksi Pencarian Azure AI, buka Instal Azure CLI dan masuk.

Di dalam portal Foundry, periksa apakah ada sumber daya yang terhubung dengan Pencarian Azure AI.

  1. Di Foundry, buka proyek Anda dan pilih Pusat manajemen dari panel kiri.

  2. Di bagian Koneksi, lihat apakah Anda memiliki koneksi jenis Pencarian Azure AI.

  3. Jika Anda memiliki koneksi Pencarian Azure AI, Anda dapat melewati langkah-langkah berikutnya.

  4. Jika tidak, pilih Koneksi baru lalu Pencarian Azure AI.

  5. Temukan layanan Pencarian Azure AI Anda di opsi dan pilih Tambahkan koneksi.

  6. Gunakan kunci API untuk Autentikasi.

    Penting

    Opsi kunci API tidak disarankan untuk produksi. Pendekatan yang disarankan adalah autentikasi Microsoft Entra ID, yang memerlukan peran Kontributor Data Indeks Pencarian dan Kontributor Layanan Pencarian (dikonfigurasi dalam Prasyarat). Untuk informasi selengkapnya, lihat Hubungkan ke Pencarian Azure AI menggunakan peran. Untuk tutorial ini, kunci API dapat diterima jika Anda ingin melanjutkan dengan cepat. Beralih ke Entra ID sebelum diterapkan ke lingkungan produksi.

  7. Pilih Tambahkan koneksi.

Membuat lingkungan Python baru

Di IDE pilihan Anda, buat folder baru untuk proyek Anda. Buka jendela terminal di folder tersebut.

Pertama, buat lingkungan Python baru. Jangan menginstal paket ke dalam penginstalan Python global Anda. Selalu gunakan lingkungan virtual atau conda saat menginstal paket Python. Jika tidak, Anda dapat memutuskan penginstalan global Python Anda.

Jika diperlukan, instal Python

Gunakan Python 3.10 atau yang lebih baru, tetapi setidaknya diperlukan Python 3.9. Jika Anda tidak memiliki versi Python yang sesuai yang terinstal, ikuti instruksi dalam Tutorial Python Kode VS untuk cara paling mudah menginstal Python pada sistem operasi Anda.

Membuat lingkungan virtual

Jika Anda sudah menginstal Python 3.10 atau lebih tinggi, buat lingkungan virtual dengan menggunakan perintah berikut:

py -3 -m venv .venv
.venv\scripts\activate

Saat Anda mengaktifkan lingkungan Python, menjalankan python atau pip dari baris perintah menggunakan penerjemah Python di folder .venv aplikasi Anda.

Catatan

Gunakan perintah deactivate untuk keluar dari lingkungan virtual Python. Anda dapat mengaktifkannya kembali nanti saat diperlukan.

Menginstal paket

Instal paket yang diperlukan.

  1. Buat file bernama requirements.txt di folder proyek Anda. Tambahkan paket berikut ke file:

    azure-ai-projects==1.0.0b10
azure-ai-inference[prompts]
azure-identity
azure-search-documents
pandas
python-dotenv
opentelemetry-api

    Referensi: pustaka klien Azure AI Projects, azure-ai-inference, python-dotenv.

  2. Instal paket yang diperlukan:

    pip install -r requirements.txt

Mengonfigurasi variabel lingkungan

String koneksi proyek Anda diperlukan untuk digunakan memanggil Azure OpenAI di Microsoft Foundry Models dari kode Anda. Dalam mulai cepat ini, Anda menyimpan nilai ini dalam .env file, yang merupakan file yang berisi variabel lingkungan yang dapat dibaca aplikasi Anda.

Buat .env file, dan tempelkan kode berikut:

AIPROJECT_CONNECTION_STRING=<your-connection-string>
AISEARCH_INDEX_NAME="example-index"
EMBEDDINGS_MODEL="text-embedding-ada-002"
INTENT_MAPPING_MODEL="gpt-4o-mini"
CHAT_MODEL="gpt-4o-mini"
EVALUATION_MODEL="gpt-4o-mini"

  • Temukan string koneksi Anda dalam proyek Foundry yang Anda buat di panduan cepat Foundry playground. Buka proyek, lalu temukan string koneksi di halaman Overview. Salin string koneksi dan tempelkan ke file .env.

    Screenshot memperlihatkan halaman gambaran umum proyek dan lokasi string koneksi.

  • Jika Anda belum memiliki indeks pencarian, pertahankan nilai "example-index" untuk AISEARCH_INDEX_NAME. Di Bagian 2 tutorial ini, Anda akan membuat indeks menggunakan nama ini. Jika sebelumnya Anda telah membuat indeks pencarian yang ingin Anda gunakan, perbarui nilai agar sesuai dengan nama indeks pencarian tersebut.

  • Jika Anda mengubah nama model saat menyebarkannya, perbarui nilai dalam .env file agar sesuai dengan nama yang Anda gunakan.

Tips

Jika Anda bekerja di Visual Studio Code, tutup dan buka kembali jendela terminal setelah Anda menyimpan perubahan dalam .env file.

Peringatan

Pastikan .env Anda terletak di file .gitignore Anda sehingga Anda tidak secara tidak sengaja mengunggahnya ke repositori git Anda.

Instal Azure CLI dan masuk

Anda menginstal Azure CLI dan masuk dari lingkungan pengembangan lokal Anda sehingga kode Anda dapat menggunakan kredensial pengguna Anda untuk memanggil layanan Azure melalui Foundry.

Dalam kebanyakan kasus, Anda dapat menginstal Azure CLI dari terminal Anda menggunakan perintah berikut:

winget install -e --id Microsoft.AzureCLI

Anda dapat mengikuti instruksi Cara menginstal Azure CLI jika perintah ini tidak berfungsi untuk sistem operasi atau penyiapan tertentu Anda.

Setelah Anda menginstal Azure CLI, masuk menggunakan perintah az login dan masuk menggunakan browser:

az login

Atau, Anda dapat masuk secara manual melalui browser dengan kode perangkat.

az login --use-device-code

Biarkan jendela terminal ini terbuka untuk menjalankan skrip python Anda dari sini juga, sekarang setelah Anda masuk.

Verifikasi pengaturan Anda

Verifikasi bahwa lingkungan Anda disiapkan dengan benar dengan menjalankan pengujian cepat:

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

# Check the SDK version
print(f"Azure AI Projects SDK version: {azure.ai.projects.__version__}")

# Test that you can connect to your project
project = AIProjectClient.from_connection_string(
    conn_str=os.environ["AIPROJECT_CONNECTION_STRING"], credential=DefaultAzureCredential()
)
print("✓ Setup verified! Ready to build your RAG app.")

Jika Anda melihat "Setup successful!", kredensial dan SDK Azure Anda dikonfigurasi dengan benar.

Tips

Tutorial ini memerlukan Azure AI Projects SDK versi 1.0.0b10. Versi SDK yang ditampilkan di atas membantu Anda memverifikasi kompatibilitas. Jika Anda memiliki versi yang berbeda, from_connection_string() metode mungkin tidak tersedia. Untuk menginstal versi yang diperlukan, jalankan pip install azure-ai-projects==1.0.0b10.

Referensi: pustaka klien Azure AI Projects, DefaultAzureCredential.

Membuat skrip pembantu

Buat folder untuk pekerjaan Anda. Buat file bernama config.py di folder ini. Anda akan menggunakan skrip pembantu ini di dua bagian berikutnya dari seri tutorial. Skrip memuat variabel lingkungan Anda dan menginisialisasi klien Proyek AI Azure. Tambahkan kode berikut:

# ruff: noqa: ANN201, ANN001

import os
import sys
import pathlib
import logging
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.inference.tracing import AIInferenceInstrumentor

# load environment variables from the .env file
from dotenv import load_dotenv

load_dotenv()

# Set "./assets" as the path where assets are stored, resolving the absolute path:
ASSET_PATH = pathlib.Path(__file__).parent.resolve() / "assets"

# Configure an root app logger that prints info level logs to stdout
logger = logging.getLogger("app")
logger.setLevel(logging.INFO)
logger.addHandler(logging.StreamHandler(stream=sys.stdout))


# Returns a module-specific logger, inheriting from the root app logger
def get_logger(module_name):
    return logging.getLogger(f"app.{module_name}")


# Enable instrumentation and logging of telemetry to the project
def enable_telemetry(log_to_project: bool = False):
    AIInferenceInstrumentor().instrument()

    # enable logging message contents
    os.environ["AZURE_TRACING_GEN_AI_CONTENT_RECORDING_ENABLED"] = "true"

    if log_to_project:
        from azure.monitor.opentelemetry import configure_azure_monitor

        project = AIProjectClient.from_connection_string(
            conn_str=os.environ["AIPROJECT_CONNECTION_STRING"], credential=DefaultAzureCredential()
        )
        tracing_link = f"https://ai.azure.com/tracing?wsid=/subscriptions/{project.scope['subscription_id']}/resourceGroups/{project.scope['resource_group_name']}/providers/Microsoft.MachineLearningServices/workspaces/{project.scope['project_name']}"
        application_insights_connection_string = project.telemetry.get_connection_string()
        if not application_insights_connection_string:
            logger.warning(
                "No application insights configured, telemetry will not be logged to project. Add application insights at:"
            )
            logger.warning(tracing_link)

            return

        configure_azure_monitor(connection_string=application_insights_connection_string)
        logger.info("Enabled telemetry logging to project, view traces at:")
        logger.info(tracing_link)

Referensi: AIProjectClient, DefaultAzureCredential, load_dotenv.

Catatan

Skrip ini juga menggunakan paket yang belum Anda instal, azure.monitor.opentelemetry. Anda akan menginstal paket ini di bagian berikutnya dari seri tutorial.

Membersihkan sumber daya

Untuk menghindari timbulnya biaya Azure yang tidak perlu, hapus sumber daya yang Anda buat dalam tutorial ini jika tidak lagi diperlukan. Untuk mengelola sumber daya, Anda dapat menggunakan portal Azure.

Tetapi jangan menghapusnya jika Anda ingin membuat aplikasi obrolan di bagian berikutnya dari seri tutorial ini.

Langkah berikutnya

Dalam tutorial ini, Anda menyiapkan semua yang Anda butuhkan untuk membangun aplikasi obrolan kustom dengan Azure AI SDK. Di bagian berikutnya dari seri tutorial ini, Anda membuat aplikasi kustom.

Part 2: Membangun aplikasi obrolan kustom dengan Azure AI SDK

  • Last updated on