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.
Nieautoryzowany użytkownik nie powinien mieć dostępu do odpowiedzi z zabezpieczonych dokumentów, które nie mają autoryzacji do wyświetlenia.
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.
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.
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.
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 true wartoś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 true wartość 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:
- Subskrypcja platformy Azure. Utwórz bezpłatnie
- Uprawnienia konta platformy Azure — Twoje konto platformy Azure musi mieć
- Uprawnienie do zarządzania aplikacjami w usłudze Microsoft Entra ID.
- Microsoft.Authorization/roleAssignments/write permissions, na przykład Administrator dostępu użytkowników lub Właściciel.
- Dostęp jest udzielany usłudze Azure OpenAI w żądanej subskrypcji platformy Azure. Obecnie dostęp do tej usługi jest udzielany tylko przez aplikację. Możesz ubiegać się o dostęp do usługi Azure OpenAI, wypełniając formularz pod adresem https://aka.ms/oai/access.
Potrzebujesz większej liczby wymagań wstępnych w zależności od preferowanego środowiska deweloperskiego.
- Konto usługi GitHub
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).
Rozpocznij proces tworzenia nowego repozytorium GitHub Codespace
main
wAzure-Samples/azure-search-openai-demo
gałęzi repozytorium GitHub.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ę.
Na stronie Tworzenie przestrzeni kodu przejrzyj ustawienia konfiguracji przestrzeni kodu, a następnie wybierz pozycję Utwórz nową przestrzeń kodu
Poczekaj na uruchomienie przestrzeni kodu. Ten proces uruchamiania może potrwać kilka minut.
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
Ukończ proces uwierzytelniania.
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
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
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.
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
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.
Po pomyślnym wdrożeniu aplikacji w terminalu zostanie wyświetlony adres URL.
Wybierz ten adres URL oznaczony
(✓) Done: Deploying service webapp
etykietą, aby otworzyć aplikację czatu w przeglądarce.Zaakceptuj wyskakujące okienko uwierzytelniania aplikacji.
Po wyświetleniu aplikacji do czatu zwróć uwagę w prawym górnym rogu, że użytkownik jest zalogowany.
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
Wybierz kartę z .
What does a product manager do?
Otrzymasz odpowiedź na przykład:
The provided sources do not contain specific information about the role of a Product Manager at Contoso Electronics.
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 oids
role_library.pdf
usługi Azure AI Search dla dokumentu.
Pobieranie adresu URL dokumentu w magazynie
W folderze
.azure
w katalogu głównym projektu znajdź katalog środowiska i otwórz.env
plik z tym katalogiem.AZURE_STORAGE_ACCOUNT
Wyszukaj wpis i skopiuj jego wartość.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
Skopiuj adres URL obiektu blob, aby użyć go później.
Uzyskiwanie identyfikatora użytkownika
- W aplikacji chap wybierz pozycję Ustawienia dewelopera.
- W sekcji Oświadczenia tokenu identyfikatora skopiuj element
objectidentifier
. Jest to znane w następnej sekcji jako .USER_OBJECT_ID
Zapewnianie użytkownikowi dostępu do dokumentu w usłudze Azure Search
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
, ,list
remove_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.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
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 pole oids
indeksu wyszukiwania . Inne opcje toremove
, ,list
remove_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.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
Otwórz witrynę Azure Portal i wyszukaj plik
AI Search
.Wybierz zasób wyszukiwania z listy.
Wybierz pozycję Zarządzanie wyszukiwaniem —> indeksy.
Wybierz indeks gptkbindex.
Wybierz pozycję Widok —> widok JSON.
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 zwracasourcefile
pola ioids
.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
.
Wróć do aplikacji do czatu. Może być konieczne ponowne zalogowanie się.
Wprowadź to samo zapytanie,
role_library
aby zawartość była używana w odpowiedzi azure OpenAI:What does a product manager do?
.Wyświetl wynik, który zawiera teraz odpowiednią odpowiedź z dokumentu biblioteki ról.
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).
Zaloguj się do pulpitu nawigacyjnego usługi GitHub Codespaces (https://github.com/codespaces).
Znajdź aktualnie uruchomione środowisko Codespaces pochodzące z
Azure-Samples/azure-search-openai-demo
repozytorium GitHub.Otwórz menu kontekstowe dla przestrzeni kodu, a następnie wybierz pozycję Usuń.
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.
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ę.Ponownie wdróż rozwiązanie za pomocą następującego polecenia.
azd up
Następne kroki
- Tworzenie aplikacji do czatu przy użyciu architektury rozwiązania najlepszych rozwiązań usługi Azure OpenAI
- Kontrola dostępu w aplikacjach generacyjnych sztucznej inteligencji za pomocą usługi Azure AI Search
- Tworzenie gotowego do użycia rozwiązania OpenAI dla przedsiębiorstw za pomocą usługi Azure API Management
- Wyszukiwanie wektorów przewyższających przy użyciu funkcji pobierania hybrydowego i klasyfikowania