Aracılığıyla paylaş


Python için sohbet belgesi güvenliğini kullanmaya başlama

KENDI verilerinizle RAG desenini kullanarak bir sohbet uygulaması oluşturduğunuzda, her kullanıcının izinlerine göre bir yanıt aldığından emin olun. Sohbet uygulamanıza belge erişim denetimi eklemek için bu makaledeki işlemi izleyin.

Yetkili bir kullanıcının sohbet uygulamasının belgelerinde yer alan yanıtlara erişimi olmalıdır.

Gerekli kimlik doğrulaması erişimine sahip yanıt içeren sohbet uygulamasının ekran görüntüsü.

Yetkisiz bir kullanıcının , görme yetkisi olmayan güvenli belgelerden gelen yanıtlara erişmemesi gerekir.

Kullanıcının verilere erişimi olmadığını belirten yanıt içeren sohbet uygulamasının ekran görüntüsü.

Not

Bu makalede, makaledeki örnekler ve kılavuzlar için temel olarak bir veya daha fazla yapay zeka uygulaması şablonu kullanılır. Yapay zeka uygulama şablonları, yapay zeka uygulamalarınız için yüksek kaliteli bir başlangıç noktası sağlamaya yardımcı olan, bakımlı, kolay dağıtılan başvuru uygulamaları sağlar.

Mimariye genel bakış

Belge güvenliği özelliği olmadan, kurumsal sohbet uygulamasının Azure AI Search ve Azure OpenAI kullanan basit bir mimarisi vardır. Belgelerin depolandığı Azure AI Search sorgularından bir yanıt, Azure OpenAI GPT modelinden alınan yanıtla birlikte belirlenir. Bu basit akışta kullanıcı kimlik doğrulaması kullanılmaz.

Belgelerin depolandığı Azure AI Search sorgularından, Azure OpenAI'den gelen bir istem yanıtıyla birlikte belirlenen yanıtı gösteren mimari diyagram.

Belgelere güvenlik eklemek için kurumsal sohbet uygulamasını güncelleştirmeniz gerekir:

  • Microsoft Entra ile sohbet uygulamasına istemci kimlik doğrulaması ekleyin.
  • Arama dizinini kullanıcı ve grup erişimiyle doldurmak için sunucu tarafı mantığı ekleyin.

Microsoft Entra Id ile kimlik doğrulamayı ve ardından bu kimlik doğrulamasını Azure AI Search'e geçirmeyi gösteren mimari diyagram.

Azure AI Search yerel belge düzeyi izinleri sağlamaz ve kullanıcı izinlerine göre bir dizinin içinden arama sonuçlarını değiştiremez. Bunun yerine, uygulamanız bir belgenin belirli bir kullanıcı veya belirli bir grup tarafından erişilebilir olmasını sağlamak için arama filtrelerini kullanabilir. Arama dizininizde, her belgenin kullanıcı veya grup kimliği bilgilerini depolayan filtrelenebilir bir alanı olmalıdır.

Azure AI Search'teki belgelerin güvenliğini sağlamak için her belgenin sonuç kümesinde döndürülen kullanıcı kimlik doğrulamasını içerdiğini gösteren mimari diyagram.

Yetkilendirme Azure AI Search'te yerel olarak bulunmadığından, kullanıcı veya grup bilgilerini barındıracak bir alan eklemeniz ve ardından eşleşmeyen belgeleri filtrelemeniz gerekir. Bu tekniği uygulamak için şunları yapmanız gerekir:

  • Dizininizde, belge erişimi olan kullanıcıların veya grupların ayrıntılarını depolamak için ayrılmış bir belge erişim denetimi alanı oluşturun.
  • Belgenin erişim denetimi alanını ilgili kullanıcı veya grup ayrıntılarıyla doldurun.
  • Kullanıcı veya grup erişim izinlerinde değişiklik olduğunda bu erişim denetimi alanını güncelleştirin.
  • Dizin güncelleştirmeleriniz bir dizin oluşturucuyla zamanlanmışsa, değişiklikler sonraki dizin oluşturucu çalıştırması üzerinde alınır. Dizin oluşturucu kullanmıyorsanız el ile yeniden dizin oluşturmanız gerekir.

Bu makalede, Azure AI Search'teki belgelerin güvenliğini sağlama işlemi, arama yöneticisi olarak çalıştıracağınız örnek betiklerle mümkün hale getiriliyor. Betikler tek bir belgeyi tek bir kullanıcı kimliğiyle ilişkilendirir. Bu betikleri alabilir ve gereksinimlerinize göre ölçeklendirmek için kendi güvenlik ve üretim gereksinimlerinizi uygulayabilirsiniz.

Güvenlik yapılandırmasını belirleme

Çözüm, bu örnekte belge güvenliği için gerekli özellikleri açmak için boole ortam değişkenleri sağlar.

Parametre Purpose
AZURE_USE_AUTHENTICATION olarak trueayarlandığında, sohbet uygulamasında kullanıcı oturum açma ve App Service kimlik doğrulamasını etkinleştirir. Sohbet uygulaması Geliştirici ayarlarında etkinleştirirUse oid security filter.
AZURE_ENFORCE_ACCESS_CONTROL olarak trueayarlandığında, herhangi bir belge erişimi için kimlik doğrulaması gerektirir. Kullanıcı arabiriminden devre dışı bırakılmaması için oid ve grup güvenliği için Geliştirici ayarları açılır ve devre dışı bırakılır.
AZURE_ENABLE_GLOBAL_DOCUMENTS_ACCESS olarak ayarlandığında true, bu ayar kimliği doğrulanmış kullanıcıların erişim denetimi gerektiğinde bile erişim denetimi atanmamış belgelerde arama yapmasına olanak tanır. Bu parametre yalnızca etkinleştirildiğinde AZURE_ENFORCE_ACCESS_CONTROL kullanılmalıdır.
AZURE_ENABLE_UNAUTHENTICATED_ACCESS olarak ayarlandığında true, bu ayar kimliği doğrulanmamış kullanıcıların erişim denetimi uygulandığında bile uygulamayı kullanmasına izin verir. Bu parametre yalnızca etkinleştirildiğinde AZURE_ENFORCE_ACCESS_CONTROL kullanılmalıdır.

Bu örnekte desteklenen güvenlik profillerini anlamak için aşağıdaki bölümleri kullanın. Bu makalede Kurumsal profil yapılandırılır.

Kurumsal: Gerekli hesap + belge filtresi

Sitenin her kullanıcısı oturum açmalıdır ve site tüm kullanıcılar için ortak olan içerik içerir. Belge düzeyi güvenlik filtresi tüm isteklere uygulanır.

Ortam değişkenleri:

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

Karma kullanım: İsteğe bağlı hesap + belge filtresi

Sitenin her kullanıcısı oturum açabilir ve site tüm kullanıcılar için ortak olan içeriği içerir. Belge düzeyi güvenlik filtresi tüm isteklere uygulanır.

Ortam değişkenleri:

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

Önkoşullar

Bu makaleyi tamamlamak için gereken tüm bağımlılıklarla birlikte bir geliştirme kapsayıcısı ortamı sağlanır. Geliştirme kapsayıcısını GitHub Codespaces'ta (tarayıcıda) veya Visual Studio Code'u kullanarak yerel olarak çalıştırabilirsiniz.

Bu makaleyi kullanmak için aşağıdaki önkoşullara ihtiyacınız vardır:

  • Azure aboneliği. Ücretsiz bir tane oluşturun
  • Azure hesabı izinleri - Azure Hesabınızın sahip olması gerekir
  • İstenen Azure aboneliğinde Azure OpenAI'ya erişim verilir. Şu anda bu hizmete erişim yalnızca uygulama tarafından sağlanmaktadır. adresinden formu https://aka.ms/oai/accesstamamlayarak Azure OpenAI'ye erişim için başvurabilirsiniz.

Tercih ettiğiniz geliştirme ortamına bağlı olarak daha fazla önkoşula ihtiyacınız vardır.

Açık geliştirme ortamı

Bu makaleyi tamamlamak için tüm bağımlılıkların yüklü olduğu bir geliştirme ortamıyla hemen başlayın.

GitHub Codespaces, Kullanıcı arabirimi olarak Web için Visual Studio Code ile GitHub tarafından yönetilen bir geliştirme kapsayıcısı çalıştırır. En basit geliştirme ortamı için GitHub Codespaces'ı kullanarak bu makaleyi tamamlamak için doğru geliştirici araçlarını ve bağımlılıklarını önceden yüklemiş olursunuz.

Önemli

Tüm GitHub hesapları Codespaces'ı her ay 2 çekirdek örneğiyle 60 saate kadar ücretsiz olarak kullanabilir. Daha fazla bilgi için bkz . GitHub Codespaces aylık dahil depolama ve çekirdek saatler.

  1. GitHub deposunun dalında Azure-Samples/azure-search-openai-demo yeni bir GitHub Codespace main oluşturmak için işlemi başlatın.

  2. Hem geliştirme ortamının hem de belgelerin aynı anda kullanılabilir olması için aşağıdaki düğmeye sağ tıklayın ve Bağlantıyı yeni pencerelerde aç'ı seçin.

    GitHub Codespaces'ta aç

  3. Codespace oluştur sayfasında codespace yapılandırma ayarlarını gözden geçirin ve ardından Yeni kod alanı oluştur'u seçin

    Yeni bir kod alanı oluşturmadan önce onay ekranının ekran görüntüsü.

  4. Kod alanının başlamasını bekleyin. Bu başlatma işlemi birkaç dakika sürebilir.

  5. Ekranın alt kısmındaki terminalde Azure Geliştirici CLI'sı ile Azure'da oturum açın.

    azd auth login
    
  6. Kimlik doğrulama işlemini tamamlayın.

  7. Bu makaledeki kalan görevler bu geliştirme kapsayıcısı bağlamında gerçekleşir.

Azure CLI ile gerekli bilgileri alma

Aşağıdaki Azure CLI komutuyla abonelik kimliğinizi ve kiracı kimliğinizi alın. değerini, olarak AZURE_TENANT_IDkullanmak üzere kopyalayın.

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

Kiracınızın koşullu erişim ilkesiyle ilgili bir hata alırsanız, koşullu erişim ilkesi olmayan ikinci bir kiracıya ihtiyacınız vardır.

  • Kullanıcı hesabınızla ilişkili ilk kiracınız ortam değişkeni için AZURE_TENANT_ID kullanılır.
  • koşullu erişim olmadan ikinci kiracınız, ortam değişkeninin Microsoft Graph'a erişmesi AZURE_AUTH_TENANT_ID için kullanılır. Koşullu erişim ilkesi olan kiracılar için, koşullu erişim ilkesi olmayan ikinci bir kiracının kimliğini bulun veya yeni bir kiracı oluşturun.

Ortam değişkenlerini belirleme

  1. Uygulamayı Kurumsal profil için yapılandırmak için aşağıdaki komutları çalıştırın.

    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. Kullanıcının barındırılan uygulama ortamında oturum açmasına izin veren kiracıyı ayarlamak için aşağıdaki komutu çalıştırın. değerini kiracı kimliğiyle değiştirin <YOUR_TENANT_ID> .

    azd env set AZURE_TENANT_ID <YOUR_TENANT_ID>
    

Not

Kullanıcı kiracınızda koşullu erişim ilkeniz varsa, bir kimlik doğrulama kiracısı belirtmeniz gerekir.

Sohbet uygulamasını Azure'a dağıtma

Dağıtım, Azure kaynaklarını oluşturmayı, belgeleri karşıya yüklemeyi, Microsoft Entra kimlik uygulamalarını (istemci ve sunucu) oluşturmayı ve barındırma kaynağı için kimliği açmayı içerir.

  1. Azure kaynaklarını sağlamak ve kaynak kodu dağıtmak için aşağıdaki Azure Geliştirici CLI komutunu çalıştırın:

    azd up
    
  2. AZD dağıtım istemlerini yanıtlamak için aşağıdaki tabloyu kullanın:

    İstem Yanıt
    Ortam adı Diğer adınız ve uygulamanız gibi bilgileri tanımlamak için kısa bir ad kullanın: tjones-secure-chat.
    Abonelik Kaynakları oluşturmak için bir abonelik seçin.
    Azure kaynaklarının konumu Size yakın bir konum seçin.
    Konum: documentIntelligentResourceGroupLocation Size yakın bir konum seçin.
    Konum: openAIResourceGroupLocation Size yakın bir konum seçin.

    Uygulamanın başlatılmasına izin vermek için uygulama dağıtıldıktan sonra 5 veya 10 dakika bekleyin.

  3. Uygulama başarıyla dağıtıldıktan sonra terminalde bir URL görüntülenir.

  4. Sohbet uygulamasını tarayıcıda açmak için etiketli (✓) Done: Deploying service webapp URL'yi seçin.

    Tarayıcıdaki sohbet uygulamasının, sohbet girişi için birkaç öneriyi ve soru girmek için sohbet metin kutusunu gösteren ekran görüntüsü.

  5. Uygulama kimlik doğrulaması açılır penceresini kabul edin.

  6. Sohbet uygulaması görüntülendiğinde, sağ üst köşedeki kullanıcınızın oturum açtığına dikkat edin.

  7. Geliştirici ayarlarını açın ve bu seçeneklerin her ikisinin de seçili ve gri (değişiklik için devre dışı) olduğunu göreceksiniz.

    • Oid güvenlik filtresi kullanma
    • Grup güvenlik filtrelerini kullanma
  8. kartı ile What does a product manager do?seçin.

  9. Şuna benzer bir yanıt alırsınız: The provided sources do not contain specific information about the role of a Product Manager at Contoso Electronics.

    Yanıtın döndürülemadığını gösteren tarayıcıda sohbet uygulamasının ekran görüntüsü

Kullanıcı için belgeye erişimi açma

Yanıtı alabilmek için tam belge için izinlerinizi açın. Bunlar birkaç bilgi gerektirir:

  • Azure Depolama
    • Hesap adı
    • Kapsayıcı adı
    • Blob/belge URL'si role_library.pdf
  • Microsoft Entra Id'de kullanıcı kimliği

Bu bilgiler bilindikten sonra, belgenin Azure AI Search dizin oids alanını güncelleştirin role_library.pdf .

Depolamadaki bir belgenin URL'sini alma

  1. .azure Projenin kökündeki klasörde ortam dizinini bulun ve dosyayı bu dizinle açın.env.

  2. Girdiyi AZURE_STORAGE_ACCOUNT arayın ve değerini kopyalayın.

  3. İçerik kapsayıcısında role_library.pdf blobunun URL'sini almak için aşağıdaki Azure CLI komutlarını kullanın.

    az storage blob url \
        --account-name <REPLACE_WITH_AZURE_STORAGE_ACCOUNT \
        --container-name 'content' \
        --name 'role_library.pdf' 
    
    Parametre Purpose
    --account-name Azure Depolama hesabı adı
    --container-name Bu örnekteki kapsayıcı adı şudur: content
    --ad Bu adımdaki blob adı şudur: role_library.pdf
  4. Blob URL'sini daha sonra kullanmak üzere kopyalayın.

Kullanıcı kimliğinizi alma

  1. Chap uygulamasında Geliştirici ayarları'nı seçin.
  2. Kimlik Belirteci talepleri bölümünde, öğesini kopyalayın objectidentifier. Bu, sonraki bölümde olarak USER_OBJECT_IDbilinir.
  1. Role_library.pdf için Azure AI Search'te alanı değiştirmek oids için aşağıdaki betiği kullanın; böylece bu alana erişebilirsiniz.

    ./scripts/manageacl.sh \
        -v \
        --acl-type oids \
        --acl-action add \
        --acl <REPLACE_WITH_YOUR_USER_OBJECT_ID> \
        --url <REPLACE_WITH_YOUR_DOCUMENT_URL>
    
    Parametre Purpose
    -v Ayrıntılı çıkış.
    --acl-type Grup veya kullanıcı nesnesi kimlikleri (OID): oids
    --acl-action Arama dizini alanına ekleyin . Diğer seçenekler arasında remove, , listremove_all.
    --Acl Grup veya kullanıcının USER_OBJECT_ID
    --URL Dosyanın Azure depolamadaki konumu, örneğin https://MYSTORAGENAME.blob.core.windows.net/content/role_library.pdf. CLI komutunda URL'yi tırnak işaretleri ile çevrelemeyin.
  2. Bu komutun konsol çıkışı şöyle görünür:

    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. İsteğe bağlı olarak, Azure AI Search'te dosya için izninizin listelendiğini doğrulamak için aşağıdaki komutu kullanın.

    ./scripts/manageacl.sh \
        -v \
        --acl-type oids \
        --acl-action list \
        --acl <REPLACE_WITH_YOUR_USER_OBJECT_ID> \
        --url <REPLACE_WITH_YOUR_DOCUMENT_URL>
    
    Parametre Purpose
    -v Ayrıntılı çıkış.
    --acl-type Grup veya kullanıcı (oid): oids
    --acl-action Arama dizini alanını listeleyinoids. Diğer seçenekler arasında remove, , listremove_all.
    --Acl Grup veya kullanıcının USER_OBJECT_ID
    --URL Dosyanın Azure depolamadaki konumu, örneğin https://MYSTORAGENAME.blob.core.windows.net/content/role_library.pdf. CLI komutunda URL'yi tırnak işaretleri ile çevrelemeyin.
  4. Bu komutun konsol çıkışı şöyle görünür:

    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]
    

    Çıktının sonundaki dizi, USER_OBJECT_ID içerir ve belgenin Azure OpenAI ile yanıtta kullanılıp kullanılmadığını belirlemek için kullanılır.

Azure AI Search'in USER_OBJECT_ID içerdiğini doğrulayın

  1. Azure portalını açın ve öğesini arayınAI Search.

  2. Listeden arama kaynağınızı seçin.

  3. Arama yönetimi -> Dizinler'i seçin.

  4. gptkbindex'i seçin.

  5. Görünüm -> JSON görünümü'nü seçin.

  6. JSON değerini aşağıdaki JSON ile değiştirin.

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

    Bu, alanın herhangi bir değere oids sahip olduğu tüm belgeleri arar ve ve oids alanlarını döndürürsourcefile.

  7. role_library.pdf Oid'iniz yoksa Azure Search'te bir belgeye kullanıcı erişimi sağlama bölümüne dönün ve adımları tamamlayın.

Belgeye kullanıcı erişimini doğrulama

Adımları tamamladıysanız ancak doğru yanıtı görmediyseniz, USER_OBJECT_ID için Azure AI Search'te role_library.pdfdoğru ayarlandığını doğrulayın.

  1. Sohbet uygulamasına dönün. Yeniden oturum açmanız gerekebilir.

  2. İçeriğin Azure OpenAI yanıtında kullanılması için role_library aynı sorguyu girin: What does a product manager do?.

  3. Şimdi rol kitaplığı belgesinden uygun yanıtı içeren sonucu görüntüleyin.

    Yanıtın döndürülürken gösterildiği tarayıcıda sohbet uygulamasının ekran görüntüsü.

Kaynakları temizleme

Azure kaynaklarını temizleme

Bu makalede oluşturulan Azure kaynakları Azure aboneliğinize faturalandırılır. Gelecekte bu kaynaklara ihtiyaç duymayı beklemiyorsanız, daha fazla ücret ödememek için bunları silin.

Azure kaynaklarını silmek ve kaynak kodu kaldırmak için aşağıdaki Azure Geliştirici CLI komutunu çalıştırın:

azd down --purge

GitHub Codespaces'i temizleme

GitHub Codespaces ortamını silmek, hesabınız için elde ettiğiniz ücretsiz çekirdek başına saat yetkilendirmesi miktarını en üst düzeye çıkarmanızı sağlar.

Önemli

GitHub hesabınızın yetkilendirmeleri hakkında daha fazla bilgi için bkz . GitHub Codespaces aylık dahil depolama ve çekirdek saatler.

  1. GitHub Codespaces panosunda (https://github.com/codespaces ) oturum açın.

  2. GitHub deposundan Azure-Samples/azure-search-openai-demo alınan şu anda çalışan Codespaces'ınızı bulun.

    Durumları ve şablonları da dahil olmak üzere çalışan tüm Codespace'lerin ekran görüntüsü.

  3. Codespace bağlam menüsünü açın ve sil'i seçin.

    Silme seçeneğinin vurgulandığı tek bir kod alanının bağlam menüsünün ekran görüntüsü.

Yardım alın

Bu örnek depo sorun giderme bilgileri sunar.

Sorun giderme

Bu bölümde, bu makaleye özgü sorunlar için sorun giderme sunulmaktadır.

Kimlik doğrulama kiracısı sağlama

Kimlik doğrulamanız barındırma uygulamanızdan ayrı bir kiracıda olduğunda, aşağıdaki işlemle bu kimlik doğrulama kiracısını ayarlamanız gerekir.

  1. Aşağıdaki komutu çalıştırarak örneği kimlik doğrulama kiracısı için ikinci bir kiracı kullanacak şekilde yapılandırın.

    azd env set AZURE_AUTH_TENANT_ID <REPLACE-WITH-YOUR-TENANT-ID>
    
    Parametre Purpose
    AZURE_AUTH_TENANT_ID Ayarlanırsa AZURE_AUTH_TENANT_ID , uygulamayı barındıran kiracıdır.
  2. Aşağıdaki komutla çözümü yeniden dağıtın.

    azd up
    

Sonraki adımlar