Bagikan melalui

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

Dalam tutorial ini, Anda menggunakan Microsoft Foundry SDK (dan pustaka lainnya) untuk membangun, mengonfigurasi, dan mengevaluasi aplikasi obrolan untuk perusahaan ritel Anda yang disebut Contoso Trek. Perusahaan ritel Anda memiliki spesialisasi perlengkapan berkemah luar ruangan dan pakaian. Aplikasi obrolan harus menjawab pertanyaan tentang produk dan layanan Anda. Misalnya, aplikasi obrolan dapat menjawab pertanyaan seperti "tenda mana yang paling tahan air?" atau "apa kantong tidur terbaik untuk cuaca dingin?".

Tutorial ini adalah bagian salah satu dari tutorial tiga bagian. Bagian satu ini membuat Anda siap untuk menulis kode di bagian dua dan mengevaluasi aplikasi obrolan Anda di bagian tiga. Di bagian ini, Anda:

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

Jika Anda telah menyelesaikan tutorial lain atau panduan cepat lainnya, kemungkinan Anda telah membuat beberapa sumber daya yang diperlukan untuk tutorial ini. Jika sudah, jangan ragu untuk melewati langkah-langkah tersebut di sini.

Tutorial ini adalah bagian salah satu dari tutorial tiga bagian.

Prasyarat

Nota

Tutorial ini menggunakan proyek berbasis hub. Langkah-langkah dan kode yang ditampilkan di sini tidak berfungsi untuk proyek Foundry. Untuk informasi selengkapnya, lihat Jenis 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 tidak memiliki proyek yang sudah ada: Ikuti langkah-langkah di Mulai Cepat: Mulai menggunakan Microsoft Foundry untuk membuat proyek pertama Anda.

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

      Cuplikan layar memperlihatkan pembuatan proyek baru dari remah roti.

    • Jika Anda tidak berada dalam proyek: Pilih Buat baru di kanan atas untuk membuat proyek Foundry baru

      Cuplikan layar memperlihatkan cara membuat proyek baru di Foundry.

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

  4. Masukkan nama untuk proyek tersebut.

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

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

    • Jika Anda ingin membuat yang baru, pilih Buat hub baru dan berikan nama.

      Cuplikan layar halaman detail proyek dalam dialog buat proyek.

  6. Jika Anda tidak memiliki hub, maka secara otomatis satu hub akan dibuat untuk Anda.

  7. Pilih Buat.

Terapkan model

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

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

Petunjuk / Saran

Karena Anda bisa mengkustomisasi 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. 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 menyebarkan gpt-4o-mini, ulangi langkah-langkah untuk menyebarkan model text-embedding-ada-002 .

Membuat layanan Pencarian Azure AI

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

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

Nota

Membuat layanan Pencarian Azure AI dan indeks pencarian berikutnya memiliki biaya terkait. Anda dapat melihat detail tentang harga dan tingkatan harga untuk layanan Azure AI Search di halaman pembuatan, untuk mengonfirmasi biaya sebelum membuat sumber daya. Untuk tutorial ini, sebaiknya gunakan tingkat harga Dasar atau di atasnya.

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

Jika tidak, Anda dapat membuat layanan Pencarian Azure AI menggunakan portal Azure.

Petunjuk / Saran

Langkah ini adalah satu-satunya waktu Anda menggunakan portal Azure dalam seri tutorial ini. Sisa pekerjaan Anda dilakukan 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. Anda dapat melihat detail tentang harga dan tingkat harga di halaman ini.
  3. Lanjutkan melalui proses dan pilih Tinjau + tetapkan untuk membuat sumber daya.
  4. Konfirmasikan detail layanan Pencarian Azure AI Anda, termasuk perkiraan biaya.
  5. Pilih Buat untuk membuat azure AI layanan Pencarian.

Menyambungkan Azure AI Search ke proyek Anda

Jika Anda sudah memiliki koneksi Azure AI Search di proyek, Anda dapat melompat ke Menginstal Azure CLI dan masuk.

Di portal Foundry, periksa sumber daya yang terhubung dengan Azure AI Search.

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

  2. Di bagian Sumber daya tersambung, lihat untuk melihat apakah Anda memiliki koneksi jenis Azure AI Search.

  3. Jika Anda memiliki koneksi Azure AI Search, Anda dapat melompat ke bagian berikutnya.

  4. Jika tidak, pilih Koneksi Baru lalu Azure AI Search.

  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 lingkungan produksi. Untuk memilih dan menggunakan opsi autentikasi Microsoft Entra ID yang direkomendasikan, Anda juga harus mengonfigurasi akses kontrol untuk layanan pencarian Azure AI. Tetapkan peran Kontributor Data Indeks Pencarian dan Kontributor Layanan Pencarian ke akun pengguna Anda. Untuk informasi selengkapnya, lihat Menyambungkan ke Azure AI Search menggunakan peran dan kontrol akses berbasis peran di portal Foundry.

  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, Anda perlu membuat lingkungan Python baru. JANGAN menginstal paket ke dalam penginstalan python global Anda. Anda harus selalu menggunakan lingkungan virtual atau conda saat menginstal paket python, jika tidak, Anda dapat memutuskan penginstalan global Python Anda.

Jika diperlukan, instal Python

Sebaiknya gunakan Python 3.10 atau yang lebih baru, tetapi memiliki setidaknya Python 3.9 diperlukan. Jika Anda tidak memiliki versi Python yang sesuai yang terinstal, ikuti instruksi dalam Tutorial Python Visual Studio Code untuk cara term mudah menginstal Python pada sistem operasi Anda.

Membuat lingkungan virtual

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

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

Mengaktifkan lingkungan Python berarti bahwa ketika Anda menjalankan python atau pip dari baris perintah, Anda menggunakan interpreter Python yang terkandung dalam .venv folder aplikasi Anda.

Nota

Anda dapat menggunakan deactivate perintah untuk keluar dari lingkungan virtual python, dan nantinya dapat mengaktifkannya kembali saat diperlukan.

Memasang paket

Pasang paket yang diperlukan.

  1. Pertama, 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

  2. Instal paket yang diperlukan:

    pip install -r requirements.txt

Membuat skrip pembantu

Buat folder untuk pekerjaan Anda. Buat file bernama config.py di folder ini. Skrip pembantu ini digunakan dalam dua bagian berikutnya dari seri tutorial. 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)

Nota

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

Mengonfigurasi variabel lingkungan

String koneksi proyek Anda diperlukan untuk 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 di proyek Foundry yang Anda buat di Foundry Playground Quickstart. Buka proyek, lalu temukan string koneksi di halaman Gambaran Umum. Salin string koneksi dan tempelkan ke .env dalam file.

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

Petunjuk / Saran

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

Peringatan

Pastikan bahwa .env Anda ada di dalam file .gitignore Anda sehingga Anda tidak secara tidak sengaja memasukkannya ke dalam repositori git Anda.

Menginstal Azure CLI dan masuk

Anda menginstal Azure CLI dan masuk dari lingkungan pengembangan lokal Anda, sehingga Anda dapat menggunakan kredensial pengguna Anda untuk memanggil Azure OpenAI di Model Microsoft 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.

Setelah Anda menginstal Azure CLI, masuk menggunakan az login perintah 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.

Membersihkan sumber daya

Untuk menghindari timbulnya biaya Azure yang tidak perlu, Anda harus menghapus 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 membangun 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.

Bagian 2: Membangun aplikasi obrolan kustom dengan Azure AI SDK

  • Last updated on