Mulai menggunakan keamanan dokumen obrolan untuk Python

Saat Anda membuat aplikasi obrolan menggunakan pola RAG dengan data Anda sendiri, pastikan setiap pengguna menerima jawaban berdasarkan izin mereka. Ikuti proses dalam artikel ini untuk menambahkan kontrol akses dokumen ke aplikasi obrolan Anda.

Pengguna yang berwenang harus memiliki akses ke jawaban yang terkandung dalam dokumen aplikasi obrolan.

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

Catatan

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 dan mudah disebarkan dengan baik yang membantu memastikan titik awal berkualitas tinggi untuk aplikasi AI Anda.

Ikhtisar arsitektur

Tanpa fitur keamanan dokumen, aplikasi obrolan perusahaan memiliki arsitektur sederhana menggunakan Azure AI Search dan Azure OpenAI. 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 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 diambil pada pengindeks berikutnya yang 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 menskalakan kebutuhan Anda.

Menentukan konfigurasi keamanan

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

Parameter	Tujuan
AZURE_USE_AUTHENTICATION	Saat diatur ke true, memungkinkan pengguna masuk ke aplikasi obrolan dan autentikasi App Service. Use oid security filter Mengaktifkan di pengaturan Pengembang aplikasi obrolan.
AZURE_ENFORCE_ACCESS_CONTROL	Saat diatur ke true, memerlukan autentikasi untuk akses dokumen apa pun. Pengaturan Pengembang untuk oid dan keamanan grup akan 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 hanya boleh digunakan saat 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 hanya boleh digunakan saat AZURE_ENFORCE_ACCESS_CONTROL diaktifkan.

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

Perusahaan: Akun + filter dokumen yang diperlukan

Setiap pengguna situs harus masuk, dan situs memang berisi konten yang bersifat 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 dapat masuk, dan situs memang berisi konten yang bersifat 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 menggunakan Visual Studio Code.

Untuk menggunakan artikel ini, Anda memerlukan prasyarat berikut:

• Langganan Azure. Buat satu secara gratis
• Izin akun Azure - Akun Azure Anda harus memiliki
  • Izin untuk mengelola aplikasi di ID Microsoft Entra.
  • Izin Microsoft.Authorization/roleAssignments/write, seperti Administrator Akses Pengguna atau Pemilik.
• Akses yang diberikan ke Azure OpenAI dalam langganan Azure yang diinginkan. Saat ini, akses ke layanan ini hanya diberikan oleh aplikasi. Anda dapat mengajukan permohonan akses ke Azure OpenAI dengan melengkapi formulir di https://aka.ms/oai/access.

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

Codespace (disarankan)

• Akun GitHub

Visual Studio Code

• Azure Developer CLI
• Docker Desktop - mulai Docker Desktop jika belum berjalan
• Visual Studio Code
• Ekstensi Kontainer Dev

Membuka lingkungan pengembangan

Mulai sekarang dengan lingkungan pengembangan yang memiliki semua dependensi yang diinstal untuk menyelesaikan artikel ini.

GitHub Codespaces (disarankan)

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 Codespace hingga 60 jam gratis setiap bulan dengan 2 instans inti. Untuk informasi selengkapnya, lihat GitHub Codespaces bulanan yang disertakan penyimpanan dan jam inti.

1. Mulai proses untuk membuat GitHub Codespace baru di main cabang Azure-Samples/azure-search-openai-demo repositori GitHub.

2. Klik kanan pada tombol berikut, dan pilih Buka tautan 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 dimulai. 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 Kontainer Dev untuk Visual Studio Code mengharuskan Docker diinstal pada komputer lokal Anda. Ekstensi menghosting kontainer pengembangan secara lokal 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 AZD berikut untuk membawa repositori GitHub ke komputer lokal Anda.

   azd init -t azure-search-openai-demo
   

5. Buka Palet Perintah, cari dan pilih Kontainer Dev: Buka Folder di Kontainer untuk membuka proyek dalam kontainer pengembangan. Tunggu hingga kontainer dev terbuka sebelum 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 AZURE_TENANT_ID.

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

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

• Penyewa pertama Anda, yang terkait dengan akun pengguna Anda, digunakan untuk AZURE_TENANT_ID variabel lingkungan.
• Penyewa kedua Anda, tanpa akses bersyarah, digunakan untuk AZURE_AUTH_TENANT_ID variabel lingkungan untuk mengakses Microsoft Graph. Untuk penyewa dengan kebijakan akses bersyarah, temukan ID penyewa kedua tanpa kebijakan akses bersyarah 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 penyewa, yang mengotorisasi pengguna masuk ke lingkungan aplikasi yang dihosting. Ganti <YOUR_TENANT_ID> dengan ID penyewa.

   azd env set AZURE_TENANT_ID <YOUR_TENANT_ID>
   

Catatan

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

Menyebarkan aplikasi obrolan ke Azure

Penyebaran termasuk membuat sumber daya Azure, mengunggah dokumen, membuat aplikasi identitas Microsoft Entra (klien &server), dan mengaktifkan identitas untuk sumber daya hosting.

1. Jalankan perintah Azure Developer CLI berikut untuk menyediakan sumber daya Azure dan menyebarkan kode sumber:

   azd up
   

2. Gunakan tabel berikut untuk menjawab perintah penyebaran AZD:

   Prompt	Jawaban
   Nama lingkungan	Gunakan nama pendek dengan informasi identifikasi seperti alias dan aplikasi Anda: 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, Anda akan melihat URL yang ditampilkan di terminal.

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

   

5. Setujui pop-up autentikasi aplikasi.

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

7. Buka Pengaturan pengembang dan perhatikan opsi ini dipilih dan berwarna abu-abu (dinonaktifkan untuk perubahan).

   • Menggunakan filter keamanan oid
   • Menggunakan filter keamanan grup

8. Pilih kartu dengan What does a product manager do?.

9. Anda mendapatkan jawaban seperti: The provided sources do not contain specific information about the role of a Product Manager at Contoso Electronics.

   

Membuka akses ke dokumen untuk pengguna

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

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

Setelah informasi ini diketahui, perbarui bidang indeks oids Pencarian Azure AI untuk dokumen tersebut 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 blob role_library.pdf dalam kontainer konten .

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

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

4. Salin URL blob untuk digunakan nanti.

Mendapatkan ID pengguna Anda

1. Di aplikasi chap, pilih Pengaturan pengembang.
2. Di bagian klaim Token ID, salin objectidentifier. 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 for role_library.pdf sehingga Anda memiliki akses ke bidang tersebut.

   ./scripts/manageacl.sh \
       -v \
       --acl-type oids \
       --acl-action add \
       --acl <REPLACE_WITH_YOUR_USER_OBJECT_ID> \
       --url <REPLACE_WITH_YOUR_DOCUMENT_URL>
   

   Parameter	Tujuan
   -v	Output verbose.
   --acl-type	ID objek grup atau pengguna (OID): oids
   --acl-action	Tambahkan ke bidang Indeks pencarian. Opsi lain termasuk remove, remove_all, list.
   --Acl	Grup atau pengguna USER_OBJECT_ID
   --url	Lokasi file di penyimpanan Azure, 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.

   ./scripts/manageacl.sh \
       -v \
       --acl-type oids \
       --acl-action list \
       --acl <REPLACE_WITH_YOUR_USER_OBJECT_ID> \
       --url <REPLACE_WITH_YOUR_DOCUMENT_URL>
   

   Parameter	Tujuan
   -v	Output verbose.
   --acl-type	Grup atau pengguna (oid): oids
   --acl-action	Mencantumkan bidang oidsIndeks pencarian . Opsi lain termasuk remove, remove_all, list.
   --Acl	Grup atau pengguna USER_OBJECT_ID
   --url	Lokasi file di penyimpanan Azure, 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 di akhir output mencakup USER_OBJECT_ID Anda dan digunakan untuk menentukan apakah dokumen digunakan dalam jawaban dengan Azure OpenAI.

Verifikasi Azure AI Search berisi USER_OBJECT_ID Anda

1. Buka portal Azure dan cari AI Search.

2. Pilih sumber daya pencarian Anda dari daftar.

3. Pilih Manajemen pencarian -> Indeks.

4. Pilih gptkbindex.

5. Pilih Tampilan -> tampilan JSON.

6. Ganti JSON dengan JSON berikut.

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

   Ini mencari semua dokumen di mana oids bidang memiliki nilai apa pun dan mengembalikan sourcefilebidang , 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 USER_OBJECT_ID Anda diatur dengan benar di Azure AI Search untuk itu 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

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

GitHub Codespaces

Menghapus lingkungan GitHub Codespaces memastikan bahwa Anda dapat memaksimalkan jumlah pemberian izin per jam inti gratis yang Anda dapatkan untuk akun Anda.

Penting

Untuk informasi selengkapnya tentang penetapan akun GitHub Anda, lihat GitHub Codespaces bulanan yang disertakan penyimpanan dan jam inti.

1. Masuk ke dasbor GitHub Codespaces (https://github.com/codespaces).

2. Temukan Codespace Yang sedang berjalan yang bersumber dari Azure-Samples/azure-search-openai-demo repositori GitHub.

   

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, cari perintah Kontainer Dev, lalu pilih Kontainer Dev: Buka Kembali Folder Secara Lokal.

   

Tip

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

Dapatkan bantuan

Repositori sampel ini menawarkan informasi pemecahan masalah.

Pemecahan Masalah

Bagian ini menawarkan pemecahan masalah untuk masalah khusus untuk artikel ini.

Menyediakan penyewa autentikasi

Saat autentikasi Anda berada di penyewa terpisah dari aplikasi hosting Anda, Anda perlu mengatur penyewa autentikasi tersebut dengan proses berikut.

1. Jalankan perintah berikut untuk mengonfigurasi sampel untuk menggunakan penyewa kedua untuk penyewa autentikasi.

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

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

2. Sebarkan ulang solusi dengan perintah berikut.

   azd up
   

Langkah berikutnya

• Membangun aplikasi obrolan dengan arsitektur solusi praktik terbaik Azure OpenAI
• Kontrol akses di Generative AI Apps dengan Azure AI Search
• Membangun solusi OpenAI siap Enterprise dengan Azure API Management
• Pencarian vektor yang mengungguli dengan kemampuan pengambilan dan peringkat hibrid