Membuat proyek untuk Microsoft Foundry

Gunakan artikel ini untuk membuat proyek di Microsoft Foundry dan konfirmasikan bahwa lingkungan Anda sudah siap. Proyek mengatur agen, evaluasi, dan file saat Anda membangun aplikasi stateful dan menjelajahi ide-ide baru.

Jika organisasi Anda memerlukan konfigurasi Azure yang disesuaikan seperti nama alternatif, kontrol keamanan, atau tag biaya, Anda mungkin perlu menggunakan portal Azure atau opsi template untuk mematuhi persyaratan Azure Policy organisasi Anda.

Saat Anda menyiapkan proyek, Microsoft Foundry Skill dapat membantu menyiapkan lingkungan Anda dan menyelesaikan agen, evaluasi, dan alur kerja file terkait.

Prasyarat

• Akun Azure dengan langganan aktif. Jika Anda tidak memilikinya, buat akun Azure free, yang menyertakan langganan uji coba gratis.

• Jika Anda membuat proyek untuk diri Anda sendiri:

  • Akses ke peran yang memungkinkan Anda membuat sumber daya Foundry, seperti Pemilik Akun Foundry atau Pemilik Foundry pada grup langganan atau sumber daya. Untuk informasi lebih lanjut tentang izin, lihat kontrol akses berbasis peran Microsoft 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.

• Jika Anda membuat proyek untuk tim:

  • Akses ke peran yang memungkinkan Anda menyelesaikan tugas peran, seperti Pemilik. Untuk informasi lebih lanjut tentang izin, lihat kontrol akses berbasis peran Microsoft Foundry.
  • Daftar alamat email pengguna atau ID grup keamanan Microsoft Entra untuk anggota tim yang memerlukan akses.

Gunakan tab berikut untuk memilih metode yang ingin Anda gunakan untuk membuat proyek Foundry:

Portal Foundry

• Tidak ada prasyarat lain yang diperlukan saat menggunakan portal.

Python SDK

• Siapkan lingkungan pengembangan Anda.

• Jalankan az login atau az login --use-device-code di lingkungan Anda sebelum menjalankan kode.

• Pasang paket: pip install azure-identity "azure-mgmt-cognitiveservices>=13.7.0". Jika Anda berada di sel buku catatan, gunakan %pip install sebagai gantinya.

• Gunakan pip show azure-mgmt-cognitiveservices untuk memeriksa apakah versi Anda adalah 13.7 atau lebih tinggi.

• Validasi cepat: Sebelum membuat proyek, verifikasi SDK dan autentikasi Anda dengan menguji klien:

  from azure.identity import DefaultAzureCredential
  from azure.mgmt.cognitiveservices import CognitiveServicesManagementClient
  
  # Test authentication by instantiating the client
  credential = DefaultAzureCredential()
  subscription_id = "<your-subscription-id>"  # Replace with your subscription ID
  client = CognitiveServicesManagementClient(credential, subscription_id)
  print("✓ Authentication successful! Ready to create a project.")
  

• Mulai skrip Anda dengan kode berikut untuk membuat client koneksi dan variabel yang digunakan di seluruh artikel ini. Contoh ini membuat proyek di Timur AS:

  from azure.identity import DefaultAzureCredential
  from azure.mgmt.cognitiveservices import CognitiveServicesManagementClient
  
  subscription_id = 'your-subscription-id'
  resource_group_name = 'your-resource-group-name'
  foundry_resource_name = 'your-foundry-resource-name'
  foundry_project_name = 'your-foundry-project-name'
  location = 'eastus'
  
  client = CognitiveServicesManagementClient(
      credential=DefaultAzureCredential(), 
      subscription_id=subscription_id,
      api_version="2025-04-01-preview"
  )
  

• (Opsional) Jika Anda memiliki beberapa akun, tambahkan ID penyewa dari Microsoft Entra ID yang ingin Anda gunakan ke DefaultAzureCredential:

  DefaultAzureCredential(interactive_browser_tenant_id="<TENANT_ID>")
  

Azure CLI

• Instal Azure CLI.
• Atur nilai default untuk subscription.

# Set your default subscription
az account set --subscription "{subscription-name}"

Membuat proyek Foundry

Gunakan salah satu metode berikut.

Portal Foundry

Langkah-langkah ini menyediakan cara untuk membuat sumber daya Azure baru dengan pengaturan default dasar.

Untuk membuat proyek Foundry, ikuti langkah-langkah berikut:

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

   

2. Proyek yang sedang Anda kerjakan muncul di sudut kiri atas.

3. Untuk membuat proyek baru, pilih nama proyek, lalu pilih Buat proyek baru.

4. Beri nama proyek Anda dan pilih Buat proyek. Atau lihat bagian berikutnya untuk opsi tingkat lanjut.

Opsi tingkat lanjut

1. Anda membuat proyek Foundry pada Foundry sumber daya. Portal secara otomatis membuat sumber daya ini saat Anda membuat proyek. Pilih grup Sumber Daya yang sudah ada untuk digunakan, atau biarkan default untuk membuat grup sumber daya baru.

   Tips

   Terutama untuk memulai, buat grup sumber daya baru untuk proyek Anda. Grup sumber daya memudahkan untuk mengelola proyek dan semua sumber dayanya bersama-sama.

2. Pilih Lokasi atau gunakan default. Lokasi adalah wilayah tempat sumber daya proyek dihosting.

3. Pilih Buat. Anda melihat kemajuan pembuatan sumber daya. Proyek dibuat ketika proses selesai.

Python SDK

Untuk membuat proyek Foundry:

• Tambahkan kode berikut untuk membuat proyek Foundry dengan menggunakan variabel dan client koneksi dari bagian prasyarat.

  # Create resource
  resource = client.accounts.begin_create(
      resource_group_name=resource_group_name,
      account_name=foundry_resource_name,
      account={
          "location": location,
          "kind": "AIServices",
          "sku": {"name": "S0",},
          "identity": {"type": "SystemAssigned"},
          "properties": {
              "allowProjectManagement": True,
              "customSubDomainName": foundry_resource_name
          }
      }
  )
  
  # Wait for the resource creation to complete
  resource_result = resource.result()
  
  # Create default project
  project = client.projects.begin_create(
      resource_group_name=resource_group_name,
      account_name=foundry_resource_name,
      project_name=foundry_project_name,
      project={
          "location": location,
          "identity": {
              "type": "SystemAssigned"
          },
          "properties": {}
      }
  )
  

  Referensi: CognitiveServicesManagementClient.

Azure CLI

Note

Langkah-langkah ini memerlukan Azure CLI versi 2.80.0 atau yang lebih baru dan peran Kontributor atau Pemilik pada grup sumber daya. Jalankan az version untuk memeriksa versi Anda dan az upgrade jika Anda memerlukan versi yang lebih baru. Buka az login untuk masuk sebelum memulai. Untuk wilayah yang didukung, lihat Dukungan wilayah.

1. Buat grup sumber daya atau gunakan yang sudah ada. Misalnya, buat my-foundry-rg di eastus:

   az group create --name my-foundry-rg --location eastus
   

   Verifikasi bahwa grup sumber daya ada:

   az group show --name my-foundry-rg --query properties.provisioningState --output tsv
   

   Keluaran menunjukkan Succeeded.

2. Buat sumber daya Foundry dengan manajemen proyek diaktifkan. Misalnya, buat my-foundry-resource di my-foundry-rg grup sumber daya:

   az cognitiveservices account create \
       --name my-foundry-resource \
       --resource-group my-foundry-rg \
       --kind AIServices \
       --sku S0 \
       --location eastus \
       --custom-domain my-foundry-resource \
       --assign-identity \
       --allow-project-management true
   

   Gunakan nilai-nilai ini:

   Parameter	Kegunaan
   --assign-identity	Membuat identitas terkelola yang diperlukan manajemen proyek. Tanpa itu, pembuatan proyek gagal dengan kesalahan bahwa identitas terkelola harus diaktifkan pada sumber daya.
   --allow-project-management	Mengaktifkan manajemen proyek. Anda tidak dapat mengubah pengaturan ini setelah membuat sumber daya.
   --custom-domain	Harus unik secara global. Jika my-foundry-resource diambil, perintah gagal dengan CustomDomainInUse. Pilih nama yang berbeda dan jalankan perintah lagi.

3. Buat proyek. Misalnya, buat my-foundry-project di my-foundry-resource:

   az cognitiveservices account project create \
       --name my-foundry-resource \
       --resource-group my-foundry-rg \
       --project-name my-foundry-project \
       --location eastus
   

4. Verifikasi bahwa sumber daya disediakan:

   az cognitiveservices account show \
       --name my-foundry-resource \
       --resource-group my-foundry-rg \
       --query properties.provisioningState --output tsv
   

   Output harus menunjukkan Succeeded. Jika output menunjukkan status yang berbeda, periksa izin, ketersediaan wilayah, dan kuota sumber daya Anda. Untuk bantuan selengkapnya, lihat Membuat sumber daya multi-layanan.

5. Verifikasi bahwa proyek telah dibuat:

   az cognitiveservices account project show \
       --name my-foundry-resource \
       --resource-group my-foundry-rg \
       --project-name my-foundry-project \
       --query properties.provisioningState --output tsv
   

   Output harus menunjukkan Succeeded. Jika perintah gagal dengan pesan bahwa identitas terkelola harus diaktifkan, konfirmasikan bahwa Anda membuat sumber daya dengan --assign-identity.

Referensi: az cognitiveservices account project

Mengonfigurasi penyimpanan agen

Jika proyek Anda menjalankan agen, Anda dapat mendeklarasikan sumber daya Azure yang menyimpan status agen, data vektor, dan file. Atur sumber daya ini pada akun Foundry untuk menetapkan default untuk setiap proyek yang dikandungnya, lalu biarkan setiap proyek mewarisi default atau mengambil alih penyimpanan individual.

Dua poin memengaruhi cara Anda merencanakan penyebaran:

• Pewarisan: Proyek mewarisi tiap setelan yang tidak ditetapkannya sendiri. Permintaan GET pada proyek mengembalikan konfigurasi efektif, yang menggabungkan nilai akun yang diwarisi dengan nilai penimpaan tingkat proyek apa pun. Mengubah default akun nanti tidak memperbarui proyek yang ada.
• Otorisasi: Untuk permintaan pengaturan kemampuan, pemanggil memerlukan Kontributor Data Blob Penyimpanan pada akun Azure Storage yang dirujuk dan Operator Cosmos DB pada akun Azure Cosmos DB yang dirujuk. Pencarian Azure AI tidak memerlukan peran penelepon. Konfigurasikan akses runtime untuk identitas terkelola proyek secara terpisah.

Untuk pengaturan, izin, dan contoh Bicep, lihat Mengonfigurasi pengaturan kemampuan agen.

Membuat beberapa proyek pada sumber daya yang sama

Buat beberapa proyek Foundry pada sumber daya yang ada Foundry untuk memungkinkan kolaborasi tim dan akses sumber daya bersama termasuk keamanan, penyebaran, dan alat yang terhubung. Pengaturan ini sangat ideal untuk langganan Azure terbatas di mana pengembang membutuhkan kemampuan eksplorasi secara mandiri dalam pengaturan lingkungan yang telah dikonfigurasi sebelumnya.

Proyek foundry sebagai sumber daya anak Azure dapat diberi kontrol akses mereka sendiri, tetapi berbagi pengaturan umum seperti keamanan jaringan, penyebaran, dan integrasi alat Azure dari sumber daya induk mereka.

Meskipun belum semua kemampuan Foundry mendukung pengorganisasian pekerjaan dalam proyek, proyek "default" pertama sumber daya Anda lebih unggul. Anda dapat mengidentifikasinya dengan tag "default" dalam pengalaman UX dan properti sumber daya "is_default" saat menggunakan opsi kode.

Fitur	Proyek bawaan	Proyek lain
Inferensi model	✅	✅
Taman Bermain	✅	✅
Agen	✅	✅
Evaluasi	✅	✅
Menelusuri	✅	✅
Datasets	✅	✅
Indeks	✅	✅
SDK dan API Foundry	✅	✅
Pemahaman terhadap isi konten	✅	✅
OpenAI SDK dan API	✅	Tanggapan, Berkas, Percakapan
OpenAI Batch, Penyelarasan, Hasil Penyelesaian Tersimpan	✅	-
Penyempurnaan bahasa	✅	✅
Penyempurnaan ucapan	✅	-
Koneksi	✅	✅

• Untuk menambahkan proyek ke sumber daya Foundry:

  Portal Foundry

  1. Pilih Kelola di navigasi kanan atas.
  2. Pilih Detail sumber daya di panel kiri.
  3. Pilih Tambahkan proyek.

  Python SDK

  Tambahkan kode ini ke skrip Anda untuk membuat proyek baru di sumber daya yang sudah ada:

  # Create additional project
  new_project_name = 'your-new-project-name'
  
  project = client.projects.begin_create(
      resource_group_name=resource_group_name,
      account_name=foundry_resource_name,
      project_name=new_project_name,
      project={
          "location": location,
          "identity": {
              "type": "SystemAssigned"
          },
          "properties": {}
      }
  )
  

  Azure CLI

  Untuk menambahkan proyek baru ke my-foundry-resource:

   az cognitiveservices account project create \
   --name my-foundry-resource \
   --resource-group my-foundry-rg \
   --project-name {new_project_name} \
   --location eastus
  

• Jika Anda menghapus proyek default sumber daya Foundry, proyek berikutnya yang dibuat akan menjadi proyek default.

Menampilkan pengaturan proyek

Portal Foundry

Pada halaman Proyek beranda , Anda akan melihat titik akhir proyek dan kunci API untuk proyek tersebut. Anda tidak memerlukan kunci API jika Anda menggunakan autentikasi Microsoft Entra ID.

Python SDK

# Get project
project = client.projects.get(
    resource_group_name=resource_group_name,
    account_name=foundry_resource_name,
    project_name=foundry_project_name
)
print(project)

Referensi: CognitiveServicesManagementClient.

Azure CLI

Untuk melihat pengaturan proyek, gunakan az cognitiveservices account project show perintah . Misalnya:

az cognitiveservices account project show \
--name my-foundry-resource \
--resource-group my-foundry-rg \
--project-name my-foundry-project

Memberikan akses ke anggota tim

Jika Anda membuat proyek untuk tim, tetapkan peran Pengguna Foundry kepada anggota tim sehingga mereka dapat menggunakan proyek dan sumber dayanya. Peran ini menyediakan izin minimum yang diperlukan untuk membangun dan menguji aplikasi AI. Untuk peran lain yang mungkin perlu Anda tetapkan, lihat kontrol akses berbasis peran untuk Microsoft 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.

Penting

Untuk menyelesaikan penugasan peran, Anda memerlukan peran seperti Pemilik dalam proyek. Untuk informasi selengkapnya, lihat kontrol akses berbasis peran untuk Microsoft Foundry.

Portal Foundry

1. Di portal Foundry, pilih Kelola di navigasi kanan atas.
2. Pilih detail Project di panel kiri.
3. Pilih tab Pengguna.
4. Pilih Tambahkan pengguna di kanan atas.
5. Masukkan alamat email anggota tim.
6. Pilih Tambahkan.

Ulangi langkah-langkah ini untuk setiap anggota tim atau grup keamanan.

Tips

Untuk menambahkan beberapa pengguna sekaligus, gunakan grup keamanan Microsoft Entra alih-alih alamat email individual.

Python SDK

Gunakan portal Azure CLI atau Foundry untuk mengelola penetapan peran. SDK Python tidak mendukung operasi penetapan peran.

Azure CLI

1. Dapatkan ID sumber daya proyek:

   PROJECT_ID=$(az cognitiveservices account project show \
       --name my-foundry-resource \
       --resource-group my-foundry-rg \
       --project-name my-foundry-project \
       --query id -o tsv)
   

2. Tetapkan peran Pengguna Foundry ke anggota tim:

   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.

   az role assignment create \
       --role "53ca6127-db72-4b80-b1b0-d745d6d5456d" \
       --assignee "user@contoso.com" \
       --assignee-principal-type User \
       --scope $PROJECT_ID
   

Note

Karena peran RBAC Foundry baru-baru ini diganti namanya, gunakan ID definisi peran (GUID) alih-alih nama peran dalam kode Anda untuk menghindari masalah selama peluncuran nama ulang:

• Pengguna Foundry: 53ca6127-db72-4b80-b1b0-d745d6d5456d
• Pemilik Foundry: c883944f-8b7b-4483-af10-35834be79c4a
• Pemilik Akun Foundry: e47c6f54-e4a2-4754-9501-8e0985b135e1
• Manajer Proyek Foundry: eadc314b-1a2d-4efa-be10-5d325db5065e

Untuk menambahkan grup keamanan, bukan pengguna individual:

az role assignment create \
    --role "53ca6127-db72-4b80-b1b0-d745d6d5456d" \
    --assignee-object-id "<security-group-object-id>" \
    --assignee-principal-type Group \
    --scope $PROJECT_ID

1. Verifikasi penetapan peran:

   az role assignment list \
       --scope $PROJECT_ID \
       --role "53ca6127-db72-4b80-b1b0-d745d6d5456d" \
       --output table
   

Referensi: penugasan peran az

Memverifikasi akses anggota tim

Minta anggota tim untuk memverifikasi akses mereka dengan masuk ke Microsoft Foundry dan memilih proyek dari daftar proyek.

Jika anggota tim tidak dapat mengakses proyek, verifikasi bahwa penetapan peran berhasil diselesaikan. Periksa apakah Anda menggunakan alamat email atau ID grup keamanan yang benar. Pastikan akun Azure anggota tim berada di penyewa Microsoft Entra yang sama.

Menghapus proyek

Penting

Gunakan dengan hati-hati. Anda tidak dapat memulihkan proyek setelah dihapus.

Portal Foundry

1. Masuk ke Microsoft Foundry. Pastikan tombol New Foundry aktif. Langkah-langkah ini mengacu pada Foundry (baru).
2. Di navigasi kanan atas, pilih Kelola.
3. Di panel kiri, pilih detail Project.
4. Di kanan atas, pilih ikon tempat sampah untuk menghapus proyek.

Python SDK

Kode ini menggunakan variabel serta koneksi client dari prasyarat. Untuk menghapus satu proyek:

client.projects.begin_delete(
    resource_group_name, foundry_resource_name, foundry_project_name
)

Referensi: CognitiveServicesManagementClient.

Hapus sumber daya Foundry dan semua proyeknya:

# Delete projects
projects = client.projects.list(resource_group_name, foundry_resource_name)

for project in projects: 
    print("Deleting project:", project.name)
    client.projects.begin_delete(resource_group_name, foundry_resource_name,
        project_name=project.name.split('/')[-1]
    ).wait()

# Delete resource
print("Deleting resource:", foundry_resource_name)
client.accounts.begin_delete(resource_group_name, foundry_resource_name).wait()

Referensi: CognitiveServicesManagementClient.

Azure CLI

Jalankan perintah berikut:

az cognitiveservices account project delete \
--name my-foundry-resource \
--resource-group my-foundry-rg \
--project-name my-foundry-project

Untuk memverifikasi penghapusan, jalankan az cognitiveservices account project show dengan nama sumber daya dan proyek yang sama. Perintah mengembalikan kesalahan sumber daya yang tidak ditemukan.

Referensi ke: az cognitiveservices account project delete.

Membuat koneksi pertama Anda

Konten terkait

• Tugas peran yang ditinggikan di Microsoft Foundry — persyaratan peran untuk membuat sumber daya dan proyek.
• Panduan Mulai Cepat Microsoft Foundry
• Apa itu Foundry?
• Buat sumber daya menggunakan templat Bicep