Udostępnij za pośrednictwem


Wprowadzenie do zabezpieczeń dokumentów czatu dla języka Python

Podczas tworzenia aplikacji czatu przy użyciu wzorca RAG z własnymi danymi upewnij się, że każdy użytkownik otrzyma odpowiedź na podstawie swoich uprawnień. Postępuj zgodnie z procesem w tym artykule, aby dodać kontrolę dostępu do dokumentów do aplikacji do czatu.

Autoryzowany użytkownik powinien mieć dostęp do odpowiedzi zawartych w dokumentach aplikacji do czatu.

Zrzut ekranu przedstawiający aplikację do czatu z odpowiedzią z wymaganym dostępem do uwierzytelniania.

Nieautoryzowany użytkownik nie powinien mieć dostępu do odpowiedzi z zabezpieczonych dokumentów, które nie mają autoryzacji do wyświetlenia.

Zrzut ekranu przedstawiający aplikację do czatu z odpowiedzią wskazującą, że użytkownik nie ma dostępu do danych.

Uwaga

W tym artykule użyto co najmniej jednego szablonu aplikacji sztucznej inteligencji jako podstawy przykładów i wskazówek w artykule. Szablony aplikacji sztucznej inteligencji zapewniają dobrze utrzymywane, łatwe w wdrażaniu implementacje referencyjne, które pomagają zapewnić wysokiej jakości punkt wyjścia dla aplikacji sztucznej inteligencji.

Omówienie architektury

Bez funkcji zabezpieczeń dokumentów aplikacja do czatu dla przedsiębiorstw ma prostą architekturę przy użyciu usługi Azure AI Search i usługi Azure OpenAI. Odpowiedź jest określana na podstawie zapytań do usługi Azure AI Search, w której są przechowywane dokumenty, w połączeniu z odpowiedzią z modelu GPT usługi Azure OpenAI. W tym prostym przepływie nie jest używane żadne uwierzytelnianie użytkownika.

Diagram architektury przedstawiający odpowiedź na podstawie zapytań do usługi Azure AI Search, w której są przechowywane dokumenty, w połączeniu z odpowiedzią monitu z usługi Azure OpenAI.

Aby dodać zabezpieczenia dokumentów, należy zaktualizować aplikację do czatu dla przedsiębiorstw:

  • Dodaj uwierzytelnianie klienta do aplikacji czatu za pomocą usługi Microsoft Entra.
  • Dodaj logikę po stronie serwera, aby wypełnić indeks wyszukiwania dostępem użytkowników i grup.

Diagram architektury przedstawiający uwierzytelnianie przy użyciu identyfikatora Entra firmy Microsoft, a następnie przekazanie tego uwierzytelniania do usługi Azure AI Search.

Usługa Azure AI Search nie zapewnia natywnych uprawnień na poziomie dokumentu i nie może różnić wyników wyszukiwania z poziomu indeksu według uprawnień użytkownika. Zamiast tego aplikacja może używać filtrów wyszukiwania, aby upewnić się, że dokument jest dostępny dla określonego użytkownika lub określonej grupy. W indeksie wyszukiwania każdy dokument powinien zawierać pole z możliwością filtrowania, które przechowuje informacje o tożsamości użytkownika lub grupy.

Diagram architektury pokazujący, że aby zabezpieczyć dokumenty w usłudze Azure AI Search, każdy dokument zawiera uwierzytelnianie użytkownika, które jest zwracane w zestawie wyników.

Ponieważ autoryzacja nie jest natywnie zawarta w usłudze Azure AI Search, należy dodać pole do przechowywania informacji o użytkowniku lub grupie, a następnie filtrować wszystkie dokumenty, które nie są zgodne. Aby zaimplementować tę technikę, należy wykonać następujące kroki:

  • Utwórz pole kontroli dostępu do dokumentu w indeksie przeznaczone do przechowywania szczegółów użytkowników lub grup z dostępem do dokumentów.
  • Wypełnij pole kontroli dostępu dokumentu odpowiednimi szczegółami użytkownika lub grupy.
  • Zaktualizuj to pole kontroli dostępu za każdym razem, gdy zmiany w uprawnieniach dostępu użytkowników lub grup są zmieniane.
  • Jeśli aktualizacje indeksu są zaplanowane za pomocą indeksatora, zmiany są pobierane podczas następnego uruchomienia indeksatora. Jeśli nie używasz indeksatora, musisz ręcznie ponownie indeksować.

W tym artykule proces zabezpieczania dokumentów w usłudze Azure AI Search jest możliwy przy użyciu przykładowych skryptów, które będą uruchamiane jako administrator wyszukiwania. Skrypty kojarzą pojedynczy dokument z jedną tożsamością użytkownika. Możesz podjąć te skrypty i zastosować własne wymagania dotyczące zabezpieczeń i produkcji w celu skalowania do własnych potrzeb.

Określanie konfiguracji zabezpieczeń

Rozwiązanie udostępnia zmienne środowiskowe warunkowe umożliwiające włączenie funkcji niezbędnych do zabezpieczeń dokumentów w tym przykładzie.

Parametr Purpose
AZURE_USE_AUTHENTICATION Po ustawieniu truewartości na wartość umożliwia użytkownikowi logowanie się do aplikacji czatu i uwierzytelniania usługi App Service. Use oid security filter Włącza w ustawieniach dewelopera aplikacji czatu.
AZURE_ENFORCE_ACCESS_CONTROL Jeśli jest ustawiona wartość true, wymaga uwierzytelniania dla dowolnego dostępu do dokumentu. Ustawienia dewelopera dla zabezpieczeń identyfikatorów i grup zostaną włączone i wyłączone, aby nie można było ich wyłączyć z interfejsu użytkownika.
AZURE_ENABLE_GLOBAL_DOCUMENTS_ACCESS Jeśli jest ustawiona wartość true, to ustawienie umożliwia uwierzytelnieni użytkownikom wyszukiwanie dokumentów, które nie mają przypisanych mechanizmów kontroli dostępu, nawet jeśli jest wymagana kontrola dostępu. Ten parametr powinien być używany tylko wtedy, gdy AZURE_ENFORCE_ACCESS_CONTROL jest włączony.
AZURE_ENABLE_UNAUTHENTICATED_ACCESS W przypadku ustawienia na truewartość to to ustawienie umożliwia nieuwierzytelnionym użytkownikom korzystanie z aplikacji, nawet w przypadku wymuszania kontroli dostępu. Ten parametr powinien być używany tylko wtedy, gdy AZURE_ENFORCE_ACCESS_CONTROL jest włączony.

Skorzystaj z poniższych sekcji, aby zrozumieć profile zabezpieczeń obsługiwane w tym przykładzie. Ten artykuł umożliwia skonfigurowanie profilu przedsiębiorstwa.

Przedsiębiorstwo: wymagane konto i filtr dokumentu

Każdy użytkownik witryny musi się zalogować , a witryna zawiera zawartość publiczną dla wszystkich użytkowników. Filtr zabezpieczeń na poziomie dokumentu jest stosowany do wszystkich żądań.

Zmienne środowiskowe:

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

Użycie mieszane: opcjonalne konto i filtr dokumentu

Każdy użytkownik witryny może się zalogować , a witryna zawiera zawartość publiczną dla wszystkich użytkowników. Filtr zabezpieczeń na poziomie dokumentu jest stosowany do wszystkich żądań.

Zmienne środowiskowe:

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

Wymagania wstępne

Środowisko kontenera deweloperskiego jest dostępne ze wszystkimi zależnościami wymaganymi do ukończenia tego artykułu. Kontener deweloperski można uruchomić w usłudze GitHub Codespaces (w przeglądarce) lub lokalnie przy użyciu programu Visual Studio Code.

Aby użyć tego artykułu, potrzebne są następujące wymagania wstępne:

Potrzebujesz większej liczby wymagań wstępnych w zależności od preferowanego środowiska deweloperskiego.

Otwieranie środowiska projektowego

Rozpocznij teraz od środowiska programistycznego, które ma zainstalowane wszystkie zależności, aby ukończyć ten artykuł.

Usługa GitHub Codespaces uruchamia kontener deweloperski zarządzany przez usługę GitHub za pomocą programu Visual Studio Code dla sieci Web jako interfejsu użytkownika. W przypadku najprostszego środowiska programistycznego użyj usługi GitHub Codespaces, aby wstępnie zainstalować odpowiednie narzędzia deweloperskie i zależności, aby ukończyć ten artykuł.

Ważne

Wszystkie konta usługi GitHub mogą korzystać z usługi Codespaces przez maksymalnie 60 godzin bezpłatnych każdego miesiąca z 2 podstawowymi wystąpieniami. Aby uzyskać więcej informacji, zobacz GitHub Codespaces monthly included storage and core hours (Miesięczne miejsca do magazynowania i godzin rdzeni usługi GitHub Codespaces).

  1. Rozpocznij proces tworzenia nowego repozytorium GitHub Codespace main w Azure-Samples/azure-search-openai-demo gałęzi repozytorium GitHub.

  2. Kliknij prawym przyciskiem myszy poniższy przycisk i wybierz pozycję Otwórz link w nowych oknach , aby jednocześnie udostępnić środowisko programistyczne i dokumentację.

    Otwieranie w usłudze GitHub Codespaces

  3. Na stronie Tworzenie przestrzeni kodu przejrzyj ustawienia konfiguracji przestrzeni kodu, a następnie wybierz pozycję Utwórz nową przestrzeń kodu

    Zrzut ekranu przedstawiający ekran potwierdzenia przed utworzeniem nowej przestrzeni kodu.

  4. Poczekaj na uruchomienie przestrzeni kodu. Ten proces uruchamiania może potrwać kilka minut.

  5. W terminalu w dolnej części ekranu zaloguj się do platformy Azure przy użyciu interfejsu wiersza polecenia dla deweloperów platformy Azure.

    azd auth login
    
  6. Ukończ proces uwierzytelniania.

  7. Pozostałe zadania w tym artykule mają miejsce w kontekście tego kontenera deweloperskiego.

Uzyskiwanie wymaganych informacji za pomocą interfejsu wiersza polecenia platformy Azure

Pobierz identyfikator subskrypcji i identyfikator dzierżawy przy użyciu następującego polecenia interfejsu wiersza polecenia platformy Azure. Skopiuj wartość do użycia jako AZURE_TENANT_ID.

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

Jeśli wystąpi błąd dotyczący zasad dostępu warunkowego dzierżawy, potrzebujesz drugiej dzierżawy bez zasad dostępu warunkowego.

  • Pierwsza dzierżawa skojarzona z kontem użytkownika jest używana dla zmiennej środowiskowej AZURE_TENANT_ID .
  • Druga dzierżawa, bez dostępu warunkowego, jest używana dla zmiennej środowiskowej AZURE_AUTH_TENANT_ID w celu uzyskania dostępu do programu Microsoft Graph. W przypadku dzierżaw z zasadami dostępu warunkowego znajdź identyfikator drugiej dzierżawy bez zasad dostępu warunkowego lub utwórz nową dzierżawę.

Ustawianie zmiennych środowiskowych

  1. Uruchom następujące polecenia, aby skonfigurować aplikację dla profilu przedsiębiorstwa .

    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. Uruchom następujące polecenie, aby ustawić dzierżawę, która autoryzuje użytkownika do logowania się do hostowanego środowiska aplikacji. Zastąp element <YOUR_TENANT_ID> identyfikatorem dzierżawy.

    azd env set AZURE_TENANT_ID <YOUR_TENANT_ID>
    

Uwaga

Jeśli masz zasady dostępu warunkowego w dzierżawie użytkownika, musisz określić dzierżawę uwierzytelniania.

Wdrażanie aplikacji czatu na platformie Azure

Wdrożenie obejmuje tworzenie zasobów platformy Azure, przekazywanie dokumentów, tworzenie aplikacji tożsamości firmy Microsoft (klienta i serwera) oraz włączanie tożsamości dla zasobu hostingu.

  1. Uruchom następujące polecenie interfejsu wiersza polecenia dla deweloperów platformy Azure, aby aprowizować zasoby platformy Azure i wdrożyć kod źródłowy:

    azd up
    
  2. Skorzystaj z poniższej tabeli, aby odpowiedzieć na monity dotyczące wdrażania AZD:

    Monit Odpowiedź
    Nazwa środowiska Użyj krótkiej nazwy z informacjami identyfikującymi, takimi jak alias i aplikacja: tjones-secure-chat.
    Subskrypcja Wybierz subskrypcję, w ramach których chcesz utworzyć zasoby.
    Lokalizacja zasobów platformy Azure Wybierz lokalizację w pobliżu siebie.
    Lokalizacja dla documentIntelligentResourceGroupLocation Wybierz lokalizację w pobliżu siebie.
    Lokalizacja dla openAIResourceGroupLocation Wybierz lokalizację w pobliżu siebie.

    Poczekaj 5 lub 10 minut po wdrożeniu aplikacji, aby umożliwić uruchamianie aplikacji.

  3. Po pomyślnym wdrożeniu aplikacji w terminalu zostanie wyświetlony adres URL.

  4. Wybierz ten adres URL oznaczony (✓) Done: Deploying service webapp etykietą, aby otworzyć aplikację czatu w przeglądarce.

    Zrzut ekranu przedstawiający aplikację czatu w przeglądarce z kilkoma sugestiami dotyczącymi wprowadzania danych wejściowych na czacie i polem tekstowym czatu w celu wprowadzenia pytania.

  5. Zaakceptuj wyskakujące okienko uwierzytelniania aplikacji.

  6. Po wyświetleniu aplikacji do czatu zwróć uwagę w prawym górnym rogu, że użytkownik jest zalogowany.

  7. Otwórz ustawienia dewelopera i zwróć uwagę, że obie te opcje są zaznaczone i wyszarzone (wyłączone w celu zmiany).

    • Korzystanie z filtru zabezpieczeń oid
    • Korzystanie z filtru zabezpieczeń grup
  8. Wybierz kartę z .What does a product manager do?

  9. Otrzymasz odpowiedź na przykład: The provided sources do not contain specific information about the role of a Product Manager at Contoso Electronics.

    Zrzut ekranu aplikacji do czatu w przeglądarce pokazujący, że nie można zwrócić odpowiedzi

Otwieranie dostępu do dokumentu dla użytkownika

Włącz swoje uprawnienia dla dokładnego dokumentu, aby uzyskać odpowiedź. Wymagają one kilku informacji:

  • Azure Storage
    • Nazwa konta
    • Nazwa kontenera
    • Adres URL obiektu blob/dokumentu dla role_library.pdf
  • Identyfikator użytkownika w identyfikatorze Entra firmy Microsoft

Gdy te informacje będą znane, zaktualizuj pole indeksu oidsrole_library.pdf usługi Azure AI Search dla dokumentu.

Pobieranie adresu URL dokumentu w magazynie

  1. W folderze .azure w katalogu głównym projektu znajdź katalog środowiska i otwórz .env plik z tym katalogiem.

  2. AZURE_STORAGE_ACCOUNT Wyszukaj wpis i skopiuj jego wartość.

  3. Użyj następujących poleceń interfejsu wiersza polecenia platformy Azure, aby uzyskać adres URL obiektu blob role_library.pdf w kontenerze zawartości .

    az storage blob url \
        --account-name <REPLACE_WITH_AZURE_STORAGE_ACCOUNT \
        --container-name 'content' \
        --name 'role_library.pdf' 
    
    Parametr Purpose
    --account-name Nazwa konta w usłudze Azure Storage
    --container-name Nazwa kontenera w tym przykładzie to content
    --nazwa Nazwa obiektu blob w tym kroku to role_library.pdf
  4. Skopiuj adres URL obiektu blob, aby użyć go później.

Uzyskiwanie identyfikatora użytkownika

  1. W aplikacji chap wybierz pozycję Ustawienia dewelopera.
  2. W sekcji Oświadczenia tokenu identyfikatora skopiuj element objectidentifier. Jest to znane w następnej sekcji jako .USER_OBJECT_ID
  1. Użyj następującego skryptu oids , aby zmienić pole w usłudze Azure AI Search dla role_library.pdf , aby mieć do niego dostęp.

    ./scripts/manageacl.sh \
        -v \
        --acl-type oids \
        --acl-action add \
        --acl <REPLACE_WITH_YOUR_USER_OBJECT_ID> \
        --url <REPLACE_WITH_YOUR_DOCUMENT_URL>
    
    Parametr Purpose
    -v Pełne dane wyjściowe.
    --acl-type Identyfikatory obiektów grup lub użytkowników (OID): oids
    --acl-action Dodaj do pola Indeks wyszukiwania. Inne opcje to remove, , listremove_all.
    --Acl Grupa lub użytkownik USER_OBJECT_ID
    --url Lokalizacja pliku w usłudze Azure Storage, taka jak https://MYSTORAGENAME.blob.core.windows.net/content/role_library.pdf. Nie otaczaj adresu URL cudzysłowami w poleceniu interfejsu wiersza polecenia.
  2. Dane wyjściowe konsoli dla tego polecenia wyglądają następująco:

    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. Opcjonalnie użyj następującego polecenia, aby sprawdzić, czy twoje uprawnienie znajduje się na liście plików w usłudze 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>
    
    Parametr Purpose
    -v Pełne dane wyjściowe.
    --acl-type Grupa lub użytkownik (identyfikatory): oids
    --acl-action Wyświetl poleoidsindeksu wyszukiwania . Inne opcje to remove, , listremove_all.
    --Acl Grupa lub użytkownik USER_OBJECT_ID
    --url Lokalizacja pliku w usłudze Azure Storage, taka jak https://MYSTORAGENAME.blob.core.windows.net/content/role_library.pdf. Nie otaczaj adresu URL cudzysłowami w poleceniu interfejsu wiersza polecenia.
  4. Dane wyjściowe konsoli dla tego polecenia wyglądają następująco:

    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]
    

    Tablica na końcu danych wyjściowych zawiera USER_OBJECT_ID i służy do określenia, czy dokument jest używany w odpowiedzi z usługą Azure OpenAI.

Sprawdź, czy usługa Azure AI Search zawiera USER_OBJECT_ID

  1. Otwórz witrynę Azure Portal i wyszukaj plik AI Search.

  2. Wybierz zasób wyszukiwania z listy.

  3. Wybierz pozycję Zarządzanie wyszukiwaniem —> indeksy.

  4. Wybierz indeks gptkbindex.

  5. Wybierz pozycję Widok —> widok JSON.

  6. Zastąp kod JSON następującym kodem JSON.

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

    Spowoduje to przeszukanie wszystkich dokumentów, w których oids pole ma dowolną wartość, i zwraca sourcefilepola i oids .

  7. Jeśli element role_library.pdf nie ma identyfikatora oid, wróć do sekcji Zapewnianie użytkownikowi dostępu do dokumentu w usłudze Azure Search i wykonaj kroki.

Weryfikowanie dostępu użytkownika do dokumentu

Jeśli wykonano kroki, ale nie widzisz poprawnej odpowiedzi, sprawdź, czy USER_OBJECT_ID jest poprawnie ustawiona w usłudze Azure AI Search dla tego elementu role_library.pdf.

  1. Wróć do aplikacji do czatu. Może być konieczne ponowne zalogowanie się.

  2. Wprowadź to samo zapytanie, role_library aby zawartość była używana w odpowiedzi azure OpenAI: What does a product manager do?.

  3. Wyświetl wynik, który zawiera teraz odpowiednią odpowiedź z dokumentu biblioteki ról.

    Zrzut ekranu przedstawiający aplikację czatu w przeglądarce z zwróconą odpowiedzią.

Czyszczenie zasobów

Czyszczenie zasobów platformy Azure

Zasoby platformy Azure utworzone w tym artykule są rozliczane z subskrypcją platformy Azure. Jeśli nie spodziewasz się, że te zasoby będą potrzebne w przyszłości, usuń je, aby uniknąć naliczania dodatkowych opłat.

Uruchom następujące polecenie interfejsu wiersza polecenia dla deweloperów platformy Azure, aby usunąć zasoby platformy Azure i usunąć kod źródłowy:

azd down --purge

Czyszczenie usługi GitHub Codespaces

Usunięcie środowiska Usługi GitHub Codespaces gwarantuje, że możesz zmaksymalizować ilość bezpłatnych godzin na godziny korzystania z konta.

Ważne

Aby uzyskać więcej informacji na temat uprawnień konta usługi GitHub, zobacz Artykuł GitHub Codespaces monthly included storage and core hours (Miesięczne miejsca do magazynowania i godzin rdzeni w usłudze GitHub).

  1. Zaloguj się do pulpitu nawigacyjnego usługi GitHub Codespaces (https://github.com/codespaces).

  2. Znajdź aktualnie uruchomione środowisko Codespaces pochodzące z Azure-Samples/azure-search-openai-demo repozytorium GitHub.

    Zrzut ekranu przedstawiający wszystkie uruchomione obszary Codespace, w tym ich stan i szablony.

  3. Otwórz menu kontekstowe dla przestrzeni kodu, a następnie wybierz pozycję Usuń.

    Zrzut ekranu przedstawiający menu kontekstowe dla pojedynczej przestrzeni kodu z wyróżnioną opcją usuwania.

Uzyskaj pomoc

To przykładowe repozytorium oferuje informacje dotyczące rozwiązywania problemów.

Rozwiązywanie problemów

Ta sekcja zawiera informacje dotyczące rozwiązywania problemów specyficznych dla tego artykułu.

Zapewnianie dzierżawy uwierzytelniania

Jeśli uwierzytelnianie znajduje się w oddzielnej dzierżawie od aplikacji hostingowej, należy ustawić dzierżawę uwierzytelniania przy użyciu następującego procesu.

  1. Uruchom następujące polecenie, aby skonfigurować przykład, aby użyć drugiej dzierżawy dla dzierżawy uwierzytelniania.

    azd env set AZURE_AUTH_TENANT_ID <REPLACE-WITH-YOUR-TENANT-ID>
    
    Parametr Purpose
    AZURE_AUTH_TENANT_ID Jeśli AZURE_AUTH_TENANT_ID jest ustawiona, jest to dzierżawa, która hostuje aplikację.
  2. Ponownie wdróż rozwiązanie za pomocą następującego polecenia.

    azd up
    

Następne kroki