Mulai menggunakan keamanan dokumen obrolan untuk Python

Saat Anda membangun aplikasi obrolan dengan menggunakan pola Retrieval Augmented Generation (RAG) dengan data Anda sendiri, pastikan bahwa setiap pengguna menerima jawaban berdasarkan izin mereka. Ikuti proses dalam artikel ini untuk menambahkan kontrol akses dokumen ke aplikasi obrolan Anda.

• Pengguna yang berwenang: Orang ini harus memiliki akses ke jawaban yang terkandung dalam dokumen aplikasi obrolan.

  

• Pengguna yang tidak sah: Orang ini seharusnya tidak memiliki akses ke jawaban dari dokumen aman yang tidak memiliki otorisasi untuk dilihat.

  

Nota

Artikel ini menggunakan satu atau beberapa templat aplikasi AI sebagai dasar untuk contoh dan panduan dalam artikel. Templat aplikasi AI memberi Anda implementasi referensi yang terawat dengan baik yang mudah disebarkan. Ini membantu memastikan titik awal berkualitas tinggi untuk aplikasi AI Anda.

Gambaran umum arsitektur

Tanpa fitur keamanan dokumen, aplikasi obrolan perusahaan memiliki arsitektur sederhana dengan menggunakan Azure AI Search dan Azure OpenAI Models di Microsoft Foundry. Jawaban ditentukan dari kueri ke Azure AI Search tempat dokumen disimpan, dalam kombinasi dengan respons dari model GPT Azure OpenAI. Tidak ada autentikasi pengguna yang digunakan dalam alur sederhana ini.

Untuk menambahkan keamanan untuk dokumen, Anda perlu memperbarui aplikasi obrolan perusahaan:

• Tambahkan autentikasi klien ke aplikasi obrolan dengan Microsoft Entra.
• Tambahkan logika sisi server untuk mengisi indeks pencarian dengan akses pengguna dan grup.

Pencarian Azure AI tidak menyediakan izin tingkat dokumen asli dan tidak dapat memvariasikan hasil pencarian dari dalam indeks berdasarkan izin pengguna. Sebagai gantinya, aplikasi Anda dapat menggunakan filter pencarian untuk memastikan bahwa dokumen dapat diakses oleh pengguna tertentu atau oleh grup tertentu. Dalam indeks pencarian Anda, setiap dokumen harus memiliki bidang yang dapat difilter yang menyimpan informasi identitas pengguna atau grup.

Karena otorisasi tidak terkandung secara asli di Azure AI Search, Anda perlu menambahkan bidang untuk menyimpan informasi pengguna atau grup, lalu memfilter dokumen apa pun yang tidak cocok. Untuk menerapkan teknik ini, Anda perlu:

• Buat bidang kontrol akses dokumen di indeks Anda yang didedikasikan untuk menyimpan detail pengguna atau grup dengan akses dokumen.
• Isi bidang kontrol akses dokumen dengan detail pengguna atau grup yang relevan.
• Perbarui bidang kontrol akses ini setiap kali ada perubahan izin akses pengguna atau grup.

Jika pembaruan indeks Anda dijadwalkan dengan pengindeks, perubahan akan diproses pada saat pengindeks berikutnya dijalankan. Jika Anda tidak menggunakan pengindeks, Anda perlu mengindeks ulang secara manual.

Dalam artikel ini, proses mengamankan dokumen di Azure AI Search dimungkinkan dengan contoh skrip, yang akan Anda jalankan sebagai administrator pencarian. Skrip mengaitkan satu dokumen dengan satu identitas pengguna. Anda dapat mengambil skrip ini dan menerapkan persyaratan keamanan dan produksi Anda sendiri untuk menyesuaikan dengan kebutuhan Anda.

Menentukan konfigurasi keamanan

Solusi ini menyediakan variabel lingkungan Boolean untuk mengaktifkan fitur yang diperlukan untuk keamanan dokumen dalam sampel ini.

Pengaturan	Tujuan
AZURE_USE_AUTHENTICATION	Saat diatur ke true, memungkinkan pengguna masuk ke aplikasi obrolan dan autentikasi Azure App Service. Mengaktifkan Use oid security filter di pengaturan pengembang aplikasi obrolan.
AZURE_ENFORCE_ACCESS_CONTROL	Saat diatur ke true, memerlukan autentikasi untuk akses dokumen apa pun. Pengaturan Pengembang untuk ID objek (OID) dan keamanan grup diaktifkan dan dinonaktifkan sehingga tidak dapat dinonaktifkan dari UI.
AZURE_ENABLE_GLOBAL_DOCUMENTS_ACCESS	Ketika diatur ke true, pengaturan ini memungkinkan pengguna terautentikasi untuk mencari pada dokumen yang tidak memiliki kontrol akses yang ditetapkan, bahkan ketika kontrol akses diperlukan. Parameter ini harus digunakan hanya ketika AZURE_ENFORCE_ACCESS_CONTROL diaktifkan.
AZURE_ENABLE_UNAUTHENTICATED_ACCESS	Ketika diatur ke true, pengaturan ini memungkinkan pengguna yang tidak diautentikasi untuk menggunakan aplikasi, bahkan ketika kontrol akses diberlakukan. Parameter ini harus digunakan hanya ketika AZURE_ENFORCE_ACCESS_CONTROL diaktifkan.

Gunakan bagian berikut untuk memahami profil keamanan yang didukung dalam sampel ini. Artikel ini mengonfigurasi profil Enterprise.

Perusahaan: Akun yang diwajibkan + filter dokumen

Setiap pengguna situs harus masuk. Situs ini berisi isi publik untuk semua pengguna. Filter keamanan tingkat dokumen diterapkan ke semua permintaan.

Variabel lingkungan:

• AZURE_USE_AUTHENTICATION=true
• AZURE_ENABLE_GLOBAL_DOCUMENTS_ACCESS=true
• AZURE_ENFORCE_ACCESS_CONTROL=true

Penggunaan campuran: Akun opsional + filter dokumen

Setiap pengguna situs mungkin masuk. Situs ini berisi isi publik untuk semua pengguna. Filter keamanan tingkat dokumen diterapkan ke semua permintaan.

Variabel lingkungan:

• AZURE_USE_AUTHENTICATION=true
• AZURE_ENABLE_GLOBAL_DOCUMENTS_ACCESS=true
• AZURE_ENFORCE_ACCESS_CONTROL=true
• AZURE_ENABLE_UNAUTHENTICATED_ACCESS=true

Prasyarat

Lingkungan kontainer pengembangan tersedia dengan semua dependensi yang diperlukan untuk menyelesaikan artikel ini. Anda dapat menjalankan kontainer pengembangan di GitHub Codespaces (di browser) atau secara lokal dengan menggunakan Visual Studio Code.

Untuk menggunakan artikel ini, Anda memerlukan prasyarat berikut:

• Sebuah langganan Azure. Buat akun gratis.
• Izin akun Azure: Akun Azure Anda harus memiliki:
  • Izin untuk mengelola aplikasi di ID Microsoft Entra.
  • Microsoft.Authorization/roleAssignments/write izin, seperti Administrator Akses Pengguna atau Pemilik.

Anda memerlukan lebih banyak prasyarat tergantung pada lingkungan pengembangan pilihan Anda.

• Akun GitHub

Visual Studio Code

• Azure Developer CLI.
• Docker Desktop. Mulai Docker Desktop jika belum berjalan.
• Kode Visual Studio.
• Dev Containers ekstensi.

Membuka lingkungan pengembangan

Gunakan instruksi berikut untuk menyebarkan lingkungan pengembangan yang telah dikonfigurasi sebelumnya yang berisi semua dependensi yang diperlukan untuk menyelesaikan artikel ini.

GitHub Codespaces menjalankan kontainer pengembangan yang dikelola oleh GitHub dengan Visual Studio Code untuk Web sebagai antarmuka pengguna. Untuk lingkungan pengembangan yang paling mudah, gunakan GitHub Codespaces sehingga Anda memiliki alat dan dependensi pengembang yang benar yang telah diinstal sebelumnya untuk menyelesaikan artikel ini.

Penting

Semua akun GitHub dapat menggunakan GitHub Codespaces hingga 60 jam gratis setiap bulan dengan dua instans inti. Untuk informasi selengkapnya, lihat penyimpanan dan jam inti yang disertakan setiap bulan di GitHub Codespaces.

1. Mulai proses untuk membuat ruang kode GitHub baru di cabang mainAzure-Samples/azure-search-openai-demo repositori GitHub.

2. Klik kanan tombol berikut, dan pilih tautan buka di jendela baru agar lingkungan pengembangan dan dokumentasi tersedia secara bersamaan.

   

3. Pada halaman Buat codespace , tinjau pengaturan konfigurasi codespace, lalu pilih Buat codespace baru.

   

4. Tunggu hingga codespace menyala. Proses startup ini dapat memakan waktu beberapa menit.

5. Di terminal di bagian bawah layar, masuk ke Azure dengan Azure Developer CLI.

   azd auth login
   

6. Selesaikan proses autentikasi.

7. Tugas yang tersisa dalam artikel ini berlangsung dalam konteks kontainer pengembangan ini.

Visual Studio Code

Ekstensi Dev Containers untuk Visual Studio Code mengharuskan Docker diinstal pada komputer lokal Anda. Ekstensi menghosting kontainer pengembangan secara lokal dengan menggunakan host Docker dengan alat pengembang dan dependensi yang benar yang telah diinstal sebelumnya untuk menyelesaikan artikel ini.

1. Buat direktori lokal baru di komputer Anda untuk proyek tersebut.

   mkdir my-intelligent-app && cd my-intelligent-app
   

2. Buka Visual Studio Code di direktori tersebut.

   code .
   

3. Buka terminal baru di Visual Studio Code.

4. Jalankan perintah berikut AZD untuk membawa repositori GitHub ke komputer lokal Anda.

   azd init -t azure-search-openai-demo
   

5. Buka palet Command, dan cari dan pilih Dev Containers: Open Folder in Container untuk membuka proyek dalam kontainer dev. Tunggu hingga kontainer dev terbuka sebelum Anda melanjutkan.

6. Masuk ke Azure dengan Azure Developer CLI.

   azd auth login
   

   Salin kode dari terminal lalu tempelkan ke browser. Ikuti instruksi untuk mengautentikasi dengan akun Azure Anda.

7. Latihan yang tersisa dalam proyek ini berlangsung dalam konteks kontainer pengembangan ini.

Mendapatkan informasi yang diperlukan dengan Azure CLI

Dapatkan ID langganan dan ID penyewa Anda dengan perintah Azure CLI berikut. Salin nilai yang akan digunakan sebagai nilai Anda AZURE_TENANT_ID .

az account list --query "[].{subscription_id:id, name:name, tenantId:tenantId}" -o table

Jika Anda mendapatkan kesalahan tentang kebijakan akses bersyarat penyewa, Anda memerlukan penyewa kedua tanpa kebijakan akses bersyarat.

• Penyewa pertama Anda, yang terkait dengan akun pengguna Anda, digunakan sebagai variabel lingkungan AZURE_TENANT_ID.
• Penyewa kedua Anda, tanpa akses bersyarat, digunakan sebagai variabel lingkungan AZURE_AUTH_TENANT_ID untuk mengakses Microsoft Graph. Untuk penyewa dengan kebijakan akses bersyarat, temukan ID penyewa kedua tanpa kebijakan akses bersyarat atau buat penyewa baru.

Atur variabel lingkungan

1. Jalankan perintah berikut untuk mengonfigurasi aplikasi untuk profil Enterprise .

   azd env set AZURE_USE_AUTHENTICATION true
   azd env set AZURE_ENABLE_GLOBAL_DOCUMENTS_ACCESS true
   azd env set AZURE_ENFORCE_ACCESS_CONTROL true
   

2. Jalankan perintah berikut untuk mengatur tenant, yang mengotorisasi masuk pengguna ke lingkungan aplikasi yang dihosting. Ganti <YOUR_TENANT_ID> dengan ID penyewa.

   azd env set AZURE_TENANT_ID <YOUR_TENANT_ID>
   

Nota

Jika Anda memiliki kebijakan akses bersyarat pada penyewa pengguna, Anda perlu menentukan penyewa autentikasi.

Menyebarkan aplikasi obrolan ke Azure

Penyebaran terdiri dari langkah-langkah berikut:

• Buat sumber daya Azure.
• Unggah dokumen.
• Buat aplikasi identitas Microsoft Entra (klien dan server).
• Aktifkan identitas untuk sumber daya hosting.

1. Provisikan sumber daya Azure dan sebarkan kode sumber.

   azd up
   

2. Gunakan tabel berikut untuk menjawab AZD perintah penyebaran.

   Cepat	Jawaban
   Nama lingkungan	Gunakan nama pendek dengan informasi identifikasi seperti alias dan aplikasi Anda. Dan contohnya adalah tjones-secure-chat.
   Langganan	Pilih langganan untuk membuat sumber daya.
   Lokasi untuk sumber daya Azure	Pilih lokasi di dekat Anda.
   Lokasi untuk documentIntelligentResourceGroupLocation	Pilih lokasi di dekat Anda.
   Lokasi untuk openAIResourceGroupLocation	Pilih lokasi di dekat Anda.

   Tunggu 5 atau 10 menit setelah aplikasi disebarkan untuk memungkinkan aplikasi memulai.

3. Setelah aplikasi berhasil disebarkan, URL muncul di terminal.

4. Pilih URL berlabel (✓) Done: Deploying service webapp untuk membuka aplikasi obrolan di browser.

   

5. Setujui pop-up autentikasi aplikasi.

6. Saat aplikasi obrolan muncul, perhatikan di sudut kanan atas bahwa pengguna Anda masuk.

7. Buka Pengaturan pengembang dan perhatikan bahwa kedua opsi berikut dipilih dan dinonaktifkan untuk perubahan:

   • Menggunakan filter keamanan oid
   • Menggunakan filter keamanan grup

8. Pilih kartu dengan Apa yang dilakukan manajer produk?.

9. Anda mendapatkan jawaban seperti: Sumber yang disediakan tidak berisi informasi spesifik tentang peran Manajer Produk di Contoso Electronics.

   

Membuka akses ke dokumen untuk pengguna

Aktifkan izin Anda untuk dokumen yang tepat sehingga Anda bisa mendapatkan jawabannya. Anda memerlukan beberapa informasi:

• Azure Storage
  • Nama akun
  • Nama kontainer
  • URL dokumen/blob untuk role_library.pdf
• ID pengguna di ID Microsoft Entra

Saat informasi ini diketahui, perbarui bidang indeks oids Pencarian Azure AI untuk dokumen.role_library.pdf

Mendapatkan URL untuk dokumen di penyimpanan

1. .azure Di folder di akar proyek, temukan direktori lingkungan, dan buka file dengan direktori tersebut.env.

2. Cari AZURE_STORAGE_ACCOUNT entri dan salin nilainya.

3. Gunakan perintah Azure CLI berikut untuk mendapatkan URL role_library.pdf blob dalam content kontainer.

   az storage blob url \
       --account-name <REPLACE_WITH_AZURE_STORAGE_ACCOUNT \
       --container-name 'content' \
       --name 'role_library.pdf' 
   

   Pengaturan	Tujuan
   --account-name	Nama akun Azure Storage.
   --container-name	Nama kontainer dalam sampel ini adalah content.
   --Nama	Nama blob dalam langkah ini adalah role_library.pdf.

4. Salin URL blob untuk digunakan nanti.

Mendapatkan ID pengguna Anda

1. Di aplikasi obrolan, pilih Pengaturan pengembang.
2. Di bagian klaim Token ID , salin parameter Anda objectidentifier . Parameter ini dikenal di bagian berikutnya sebagai USER_OBJECT_ID.

Menyediakan akses pengguna ke dokumen di Azure Search

1. Gunakan skrip berikut untuk mengubah oids bidang di Azure AI Search untuk role_library.pdf agar Anda dapat mengaksesnya.

   python ./scripts/manageacl.py --acl-type oids --acl-action add --acl <REPLACE_WITH_YOUR_USER_OBJECT_ID> --url <REPLACE_WITH_YOUR_DOCUMENT_URL>
   

   Pengaturan	Tujuan
   -v	Output verbose.
   --acl-type	OID grup atau pengguna: oids.
   --acl-action	Tambahkan ke bidang Indeks pencarian. Opsi lain termasuk enable_acls, remove, remove_all, dan view.
   --Acl	Grup atau pengguna USER_OBJECT_ID.
   --url	Lokasi file di Azure Storage, seperti https://MYSTORAGENAME.blob.core.windows.net/content/role_library.pdf. Jangan kelilingi URL dengan tanda kutip dalam perintah CLI.

2. Output konsol untuk perintah ini terlihat seperti:

   Loading azd .env file from current environment...
   Creating Python virtual environment "app/backend/.venv"...
   Installing dependencies from "requirements.txt" into virtual environment (in quiet mode)...
   Running manageacl.py. Arguments to script: -v --acl-type oids --acl-action add --acl 00000000-0000-0000-0000-000000000000 --url https://mystorage.blob.core.windows.net/content/role_library.pdf
   Found 58 search documents with storageUrl https://mystorage.blob.core.windows.net/content/role_library.pdf
   Adding acl 00000000-0000-0000-0000-000000000000 to 58 search documents
   

3. Secara opsional, gunakan perintah berikut untuk memverifikasi bahwa izin Anda tercantum untuk file di Azure AI Search.

   python ./scripts/manageacl.py -v --acl-type groups --acl-action view --url <REPLACE_WITH_YOUR_DOCUMENT_URL>
   

   Pengaturan	Tujuan
   -v	Output verbose.
   --acl-type	OID grup atau pengguna: oids.
   --acl-action	Lihat bidang indeks pencarian oids. Opsi lain termasuk enable_acls, remove, remove_all, dan add.
   --url	Lokasi file yang ditunjukkan, seperti https://MYSTORAGENAME.blob.core.windows.net/content/role_library.pdf. Jangan kelilingi URL dengan tanda kutip dalam perintah CLI.

4. Output konsol untuk perintah ini terlihat seperti:

   Loading azd .env file from current environment...
   Creating Python virtual environment "app/backend/.venv"...
   Installing dependencies from "requirements.txt" into virtual environment (in quiet mode)...
   Running manageacl.py. Arguments to script: -v --acl-type oids --acl-action view --acl 00000000-0000-0000-0000-000000000000 --url https://mystorage.blob.core.windows.net/content/role_library.pdf
   Found 58 search documents with storageUrl https://mystorage.blob.core.windows.net/content/role_library.pdf
   [00000000-0000-0000-0000-000000000000]
   

   Array pada akhir output menyertakan parameter USER_OBJECT_ID Anda dan digunakan untuk menentukan apakah dokumen tersebut digunakan sebagai jawaban dengan Azure OpenAI.

Verifikasi bahwa Azure AI Search berisi USER_OBJECT_ID Anda

1. Buka portal Microsoft Azure dan cari AI Search.

2. Pilih sumber daya pencarian Anda dari daftar.

3. Pilih manajemen pencarian>Indeks.

4. Pilih gptkbindex.

5. Pilih Tampilkan>tampilan JSON.

6. Ganti JSON dengan JSON berikut:

   {
     "search": "*",
     "select": "sourcefile, oids",
     "filter": "oids/any()"
   }
   

   JSON ini mencari semua dokumen di mana oids bidang memiliki nilai apa pun dan mengembalikan sourcefile bidang dan oids .

7. role_library.pdf Jika tidak memiliki OID Anda, kembali ke bagian Berikan akses pengguna ke dokumen di Azure Search dan selesaikan langkah-langkahnya.

Memverifikasi akses pengguna ke dokumen

Jika Anda menyelesaikan langkah-langkah tetapi tidak melihat jawaban yang benar, verifikasi bahwa parameter Anda USER_OBJECT_ID diatur dengan benar di Pencarian Azure AI untuk role_library.pdf.

1. Kembali ke aplikasi obrolan. Anda mungkin perlu masuk lagi.

2. Masukkan kueri yang sama sehingga role_library konten digunakan dalam jawaban Azure OpenAI: What does a product manager do?.

3. Lihat hasilnya, yang sekarang menyertakan jawaban yang sesuai dari dokumen pustaka peran.

   

Membersihkan sumber daya

Langkah-langkah berikut memandu Anda melalui proses membersihkan sumber daya yang telah Anda gunakan.

Membersihkan sumber daya Azure

Sumber daya Azure yang dibuat dalam artikel ini ditagihkan ke langganan Azure Anda. Jika Anda tidak mengharapkan untuk membutuhkan sumber daya ini di masa mendatang, hapus sumber daya tersebut untuk menghindari dikenakan lebih banyak biaya.

Jalankan perintah Azure Developer CLI berikut untuk menghapus sumber daya Azure dan menghapus kode sumber.

azd down --purge

Membersihkan GitHub Codespaces dan Visual Studio Code

Langkah-langkah berikut memandu Anda melalui proses membersihkan sumber daya yang telah Anda gunakan.

GitHub Codespaces

Menghapus lingkungan GitHub Codespaces memastikan bahwa Anda dapat memaksimalkan kuota jam penggunaan inti gratis yang Anda dapatkan untuk akun Anda.

Penting

Untuk informasi lebih lanjut tentang hak akun GitHub Anda, lihat penyimpanan dan jam inti bulanan yang sudah termasuk dalam GitHub Codespaces.

1. Masuk ke dasbor GitHub Codespaces.

2. Temukan ruang kode Anda yang saat ini berjalan dan berasal dari repositori GitHub Azure-Samples/azure-search-openai-demo.

   

3. Buka menu konteks untuk codespace, lalu pilih Hapus.

   

Visual Studio Code

Anda tidak perlu membersihkan lingkungan lokal, tetapi Anda dapat menghentikan kontainer pengembangan yang sedang berjalan dan kembali menjalankan Visual Studio Code dalam konteks ruang kerja lokal.

1. Buka palet Perintah dan cari perintah Kontainer Dev.

2. Pilih Dev Containers: Buka Kembali Folder Secara Lokal.

   

Petunjuk / Saran

Setelah Visual Studio Code menghentikan kontainer pengembangan yang sedang berjalan, kontainer masih ada di Docker dalam status berhenti. Anda dapat menghapus instans kontainer, gambar kontainer, dan volume dari Docker untuk mengosongkan lebih banyak ruang di komputer lokal Anda.

Dapatkan bantuan

Repositori sampel menawarkan informasi pemecahan masalah.

Penyelesaian Masalah

Bagian ini membantu Anda memecahkan masalah khusus untuk artikel ini.

Menyediakan tenant autentikasi

Saat autentikasi Anda terletak di penyewa yang terpisah dari aplikasi hosting Anda, Anda perlu mengonfigurasi penyewa autentikasi tersebut menggunakan proses berikut.

1. Jalankan perintah berikut untuk mengonfigurasi sampel agar menggunakan tenant kedua dalam tenant autentikasi.

   azd env set AZURE_AUTH_TENANT_ID <REPLACE-WITH-YOUR-TENANT-ID>
   

   Pengaturan	Tujuan
   AZURE_AUTH_TENANT_ID	Jika AZURE_AUTH_TENANT_ID diatur, penyewalah yang menghosting aplikasi.

2. Sebarkan ulang solusi dengan perintah berikut:

   azd up
   

Konten terkait

• Buat aplikasi obrolan dengan arsitektur solusi praktik terbaik Azure OpenAI.
• Pelajari tentang kontrol akses di aplikasi AI generatif dengan Azure AI Search.
• Bangun solusi Azure OpenAI yang siap untuk perusahaan dengan Azure API Management.
• Lihat Azure AI Search: Mengungguli pencarian vektor dengan kemampuan pengambilan dan peringkat hibrid.