Instrukcja: Tworzenie aplikacji do generowania z rozszerzonym pobieraniem danych w usłudze Azure App Service przy użyciu usług Azure OpenAI i Azure AI Search (FastAPI)

2025-05-20

W tym samouczku utworzysz aplikację do pobierania rozszerzonej generacji języka Python (RAG) przy użyciu interfejsu FastAPI, usługi Azure OpenAI i usługi Azure AI Search oraz wdrożysz ją w usłudze Azure App Service. Ta aplikacja pokazuje, jak zaimplementować interfejs czatu, który pobiera informacje z własnych dokumentów i korzysta z usług sztucznej inteligencji platformy Azure w celu zapewnienia dokładnych, kontekstowych odpowiedzi z odpowiednimi cytatami. Rozwiązanie używa tożsamości zarządzanych do uwierzytelniania bez hasła między usługami.

W tym poradniku nauczysz się, jak:

Wdróż aplikację FastAPI korzystającą ze wzorca RAG z usługami Azure AI.
Konfigurowanie usług Azure OpenAI i Azure AI Search na potrzeby wyszukiwania hybrydowego.
Przekazywanie i indeksowanie dokumentów do użycia w aplikacji opartej na sztucznej inteligencji.
Użyj tożsamości zarządzanych do bezpiecznej komunikacji między usługami.
Przetestuj implementację RAG lokalnie przy użyciu usług produkcyjnych.

Przegląd architektury

Przed rozpoczęciem wdrażania warto zrozumieć architekturę aplikacji, którą utworzysz. Poniższy diagram pochodzi z niestandardowego wzorca RAG dla usługi Azure AI Search:

W tym samouczku aplikacja Blazer w usłudze App Service zajmuje się zarówno interfejsem użytkownika aplikacji, jak i serwerem aplikacji. Jednak nie tworzy oddzielnego zapytania wiedzy w usłudze Azure AI Search. Zamiast tego informuje usługę Azure OpenAI o wykonywanie zapytań merytorycznych określających usługę Azure AI Search jako źródło danych. Ta architektura oferuje kilka kluczowych zalet:

Wektoryzacja zintegrowana: zintegrowane funkcje wektoryzacji usługi Azure AI Search ułatwiają i szybkie pozyskiwanie wszystkich dokumentów do wyszukiwania bez konieczności stosowania większej liczby kodu do generowania osadzania.
Uproszczony dostęp do interfejsu API: użycie wzorca Azure OpenAI On Your Data z usługą Azure AI Search jako źródła danych dla uzupełnień Azure OpenAI eliminuje potrzebę implementacji złożonego wyszukiwania wektorowego i generowania osadzeń. Jest to tylko jedno wywołanie interfejsu API, a usługa Azure OpenAI obsługuje wszystko, w tym inżynierię monitów i optymalizację zapytań.
Zaawansowane możliwości wyszukiwania: zintegrowana wektoryzacja zapewnia wszystko, co jest potrzebne do zaawansowanego wyszukiwania hybrydowego z semantycznymi refrankingami, które łączy mocne strony dopasowywania słów kluczowych, podobieństwa wektorów i klasyfikacji opartej na sztucznej inteligencji.
Pełna obsługa cytatów: odpowiedzi automatycznie zawierają cytaty do dokumentów źródłowych, dzięki czemu informacje są weryfikowalne i możliwe do śledzenia.

Wymagania wstępne

Konto platformy Azure z aktywną subskrypcją — utwórz bezpłatne konto.
Konto usługi GitHub do korzystania z usługi GitHub Codespaces — dowiedz się więcej o usłudze GitHub Codespaces.

1. Otwórz przykład za pomocą usługi Codespaces

Najprostszym sposobem rozpoczęcia pracy jest użycie usługi GitHub Codespaces, która udostępnia kompletne środowisko programistyczne ze wszystkimi wymaganymi wstępnie zainstalowanymi narzędziami.

Przejdź do repozytorium GitHub pod adresem https://github.com/Azure-Samples/app-service-rag-openai-ai-search-python.
Wybierz przycisk Kod, wybierz kartę Codespaces, a następnie kliknij Utwórz przestrzeń kodu w obszarze głównym.
Zaczekaj chwilę na zainicjowanie usługi Codespace. Gdy wszystko będzie gotowe, zobaczysz w przeglądarce w pełni skonfigurowane środowisko programu VS Code.

2. Wdrażanie przykładowej architektury

W terminalu zaloguj się do platformy Azure przy użyciu interfejsu wiersza polecenia dla deweloperów platformy Azure:
```
azd auth login
```
Postępuj zgodnie z instrukcjami, aby ukończyć proces uwierzytelniania.
Aprowizuj zasoby platformy Azure za pomocą szablonu AZD:
```
azd provision
```

Po wyświetleniu monitu podaj następujące odpowiedzi:

Pytanie	Odpowiedź
Wprowadź nową nazwę środowiska:	Wpisz unikatową nazwę.
Wybierz subskrypcję platformy Azure do użycia:	Wybierz subskrypcję.
Wybierz grupę zasobów do użycia:	Wybierz pozycję Utwórz nową grupę zasobów.
Wybierz lokalizację, w ramach których chcesz utworzyć grupę zasobów:	Wybierz dowolny region. Zasoby zostaną utworzone w regionie Wschodnie stany USA 2.
Wprowadź nazwę nowej grupy zasobów:	Wpisz Enter.

Poczekaj na zakończenie wdrożenia. Ten proces będzie następujący:
- Utwórz wszystkie wymagane zasoby platformy Azure.
- Wdrażanie aplikacji Blazor w usłudze Azure App Service.
- Skonfiguruj bezpieczne uwierzytelnianie między usługami przy użyciu tożsamości zarządzanych.
- Skonfiguruj niezbędne przypisania ról w celu zapewnienia bezpiecznego dostępu między usługami.
Uwaga / Notatka

Aby dowiedzieć się więcej o sposobie działania tożsamości zarządzanych, zobacz Co to są tożsamości zarządzane dla zasobów platformy Azure? i Jak używać tożsamości zarządzanych w usłudze App Service.
Po pomyślnym wdrożeniu zobaczysz adres URL wdrożonej aplikacji. Zanotuj ten adres URL, ale nie uzyskaj do niego dostępu, ponieważ nadal musisz skonfigurować indeks wyszukiwania.

3. Przekazywanie dokumentów i tworzenie indeksu wyszukiwania

Po wdrożeniu infrastruktury należy przesłać dokumenty oraz utworzyć indeks wyszukiwania, którego będzie używać aplikacja:

W witrynie Azure Portal przejdź do konta magazynu utworzonego przez wdrożenie. Nazwa rozpocznie się od podanej wcześniej nazwy środowiska.
Wybierz pozycję Kontenery z menu nawigacji po lewej stronie i otwórz kontener dokumentów .
Przekaż przykładowe dokumenty, klikając pozycję Przekaż. Możesz użyć przykładowych dokumentów z sample-docs folderu w repozytorium lub własnych plików PDF, Word lub tekstowych.
Przejdź do usługi Azure AI Search w witrynie Azure Portal.
Wybierz pozycję Importuj i wektoryzuj dane , aby rozpocząć proces tworzenia indeksu wyszukiwania.
W kroku Łączenie z danymi :
- Wybierz Azure Blob Storage jako źródło danych.
- Wybierz RAG
- Wybierz konto magazynowe i kontener dokumentów.
- Upewnij się, że wybrano opcję Uwierzytelnianie przy użyciu tożsamości zarządzanej .
- Wybierz Dalej.
W kroku Wektoryzuj tekst :
- Wybierz usługę Azure OpenAI.
- Wybierz text-embedding-ada-002 jako model osadzania. Szablon AZD już wdrożył ten model.
- Wybierz pozycję Tożsamość przypisana przez system na potrzeby uwierzytelniania.
- Zaznacz pole wyboru, aby zaakceptować dodatkowe koszty.
- Wybierz Dalej.
Wskazówka

Dowiedz się więcej na temat wyszukiwania wektorów w usłudze Azure AI Search i osadzania tekstu w usłudze Azure OpenAI.
W kroku Wektoryzacja i wzbogacanie obrazów :
- Zachowaj ustawienia domyślne.
- Wybierz Dalej.
W kroku Ustawienia zaawansowane :
- Upewnij się, że wybrano opcję Włącz rangę semantyczną .
- (Opcjonalnie) Wybierz harmonogram indeksowania. Jest to przydatne, jeśli chcesz regularnie odświeżać indeks przy użyciu najnowszych zmian w pliku.
- Wybierz Dalej.
W kroku Przeglądanie i tworzenie :
- Skopiuj wartość prefiksu nazwy obiektów . Jest to nazwa indeksu wyszukiwania.
- Wybierz pozycję Utwórz , aby rozpocząć proces indeksowania.
Poczekaj na zakończenie procesu indeksowania. Może to potrwać kilka minut w zależności od rozmiaru i liczby dokumentów.
Aby przetestować importowanie danych, wybierz pozycję Rozpocznij wyszukiwanie i spróbuj wykonać zapytanie wyszukiwania, takie jak "Powiedz mi o firmie".
Po powrocie do terminalu usługi Codespace ustaw nazwę indeksu wyszukiwania jako zmienną środowiskową AZD:
```
azd env set SEARCH_INDEX_NAME <your-search-index-name>
```
Zastąp ciąg <your-search-index-name> nazwą indeksu skopiowaną wcześniej. AZD używa tej zmiennej w kolejnych wdrożeniach, aby ustawić konfigurację aplikacji App Service.

4. Testowanie aplikacji i wdrażanie

Jeśli wolisz przetestować aplikację lokalnie przed wdrożeniem lub po nim, możesz uruchomić ją bezpośrednio z poziomu usługi Codespace:

W terminalu usługi Codespace pobierz wartości środowiska AZD:
```
azd env get-values
```
Otwórz .env. Korzystając z danych wyjściowych terminalu, zaktualizuj następujące wartości w odpowiednich miejscach <input-manually-for-local-testing>.
- AZURE_OPENAI_ENDPOINT
- AZURE_SEARCH_SERVICE_URL
- AZURE_SEARCH_INDEX_NAME
Zaloguj się do platformy Azure przy użyciu interfejsu wiersza polecenia platformy Azure:
```
az login
```
Dzięki temu biblioteka klienta tożsamości platformy Azure w przykładowym kodzie może odbierać token uwierzytelniania dla zalogowanego użytkownika.

Uruchom aplikację lokalnie:

pip install -r requirements.txt
uvicorn main:app

Gdy zobaczysz, że aplikacja uruchomiona na porcie 8000 jest dostępna , wybierz pozycję Otwórz w przeglądarce.
Spróbuj zadać kilka pytań w interfejsie czatu. Jeśli otrzymasz odpowiedź, aplikacja łączy się pomyślnie z zasobem usługi Azure OpenAI.
Zatrzymaj serwer deweloperski za pomocą Ctrl+C.
Zastosuj nową SEARCH_INDEX_NAME konfigurację na platformie Azure i wdróż przykładowy kod aplikacji:
```
azd up
```

5. Testowanie wdrożonej aplikacji RAG

Po pełnym wdrożeniu i skonfigurowaniu aplikacji można teraz przetestować funkcję RAG:

Otwórz adres URL aplikacji podany na końcu wdrożenia.
Zostanie wyświetlony interfejs czatu, w którym można wprowadzić pytania dotyczące zawartości przekazanych dokumentów.
Spróbuj zadać pytania specyficzne dla zawartości dokumentów. Na przykład, jeśli przekazałeś dokumenty w folderze sample-docs, możesz wypróbować następujące pytania:
- Jak firma Contoso korzysta z moich danych osobowych?
- W jaki sposób składasz roszczenie o gwarancji?
Zwróć uwagę, że odpowiedzi obejmują cytaty odwołujące się do dokumentów źródłowych. Te cytaty pomagają użytkownikom zweryfikować dokładność informacji i znaleźć więcej szczegółów w materiale źródłowym.
Przetestuj możliwości wyszukiwania hybrydowego, zadając pytania, które mogą korzystać z różnych metod wyszukiwania:
- Pytania dotyczące konkretnej terminologii (dobre dla wyszukiwania słów kluczowych).
- Pytania dotyczące pojęć, które mogą być opisane przy użyciu różnych terminów (dobre dla wyszukiwania wektorów).
- Złożone pytania wymagające zrozumienia kontekstu (dobre dla klasyfikacji semantycznej).

Uprzątnij zasoby

Po zakończeniu pracy z aplikacją możesz usunąć wszystkie zasoby, aby uniknąć ponoszenia dodatkowych kosztów:

azd down --purge

To polecenie usuwa wszystkie zasoby skojarzone z aplikacją.

Najczęściej zadawane pytania

Jak przykładowy kod pobiera cytaty z ukończonych czatów usługi Azure OpenAI?
Jaka jest zaleta korzystania z tożsamości zarządzanych w tym rozwiązaniu?
W jaki sposób tożsamość zarządzana przypisana przez system jest używana w tej architekturze i przykładowej aplikacji?
W jaki sposób wyszukiwanie hybrydowe z semantycznym rankerem zaimplementowano w przykładowej aplikacji?
Dlaczego wszystkie zasoby są tworzone w regionie Wschodnie USA 2?
Czy mogę używać własnych modeli OpenAI zamiast modeli udostępnianych przez platformę Azure?
Jak mogę poprawić jakość odpowiedzi?

Jak przykładowy kod pobiera cytaty z ukończonych czatów usługi Azure OpenAI?

Próbka pobiera cytaty, korzystając ze źródła danych zintegrowanego z usługą Azure AI Search dla aplikacji czatu. Po zażądaniu dokończenia czatu, odpowiedź zawiera obiekt citations w kontekście wiadomości. Przykładowa aplikacja przekazuje obiekt odpowiedzi do kodu klienta, który wyodrębnia cytaty w następujący sposób:

fetch('/api/chat/completion', {
    // ...
})
// ...
.then(data => {

    // ...
    const message = choice.message;
    const content = message.content;
    
    // Extract citations from context
    const citations = message.context?.citations || [];
    
    // ...
})

W komunikacie odpowiedzi zawartość używa notacji [doc#], aby odwołać się do odpowiadającego cytatu na liście, umożliwiając użytkownikom śledzenie informacji do oryginalnych dokumentów źródłowych. Aby uzyskać więcej informacji, zobacz:

Jaka jest zaleta korzystania z tożsamości zarządzanych w tym rozwiązaniu?

Zarządzane tożsamości eliminują potrzebę przechowywania poświadczeń w kodzie lub konfiguracji. Korzystając z tożsamości zarządzanych, aplikacja może bezpiecznie uzyskiwać dostęp do usług platformy Azure, takich jak Azure OpenAI i Azure AI Search, bez konieczności zarządzania hasłami. Takie podejście jest zgodne z zasadami zabezpieczeń Zero Trust i zmniejsza ryzyko ujawnienia poświadczeń.

W jaki sposób tożsamość zarządzana przypisana przez system jest używana w tej architekturze i przykładowej aplikacji?

Wdrożenie AZD tworzy tożsamości zarządzane przypisane przez system dla usług Azure App Service, Azure OpenAI i Azure AI Search. Tworzy również odpowiednie przypisania ról dla każdego z nich (zobacz plik main.bicep ). Aby uzyskać informacje na temat wymaganych przypisań ról, zobacz Konfiguracja sieci i dostępu dla usługi Azure OpenAI On Your Data.

W przykładowej aplikacji FastAPI zestawy SDK platformy Azure używają tej tożsamości zarządzanej do bezpiecznego uwierzytelniania, więc nie trzeba przechowywać poświadczeń ani wpisów tajnych w dowolnym miejscu. Na przykład AsyncAzureOpenAI klient jest inicjowany za pomocą DefaultAzureCredential, co automatycznie używa tożsamości zarządzanej podczas uruchamiania na platformie Azure.

self.credential = DefaultAzureCredential()
token_provider = get_bearer_token_provider(
    self.credential,
    "https://cognitiveservices.azure.com/.default"
)

self.openai_client = AsyncAzureOpenAI(
    azure_endpoint=self.openai_endpoint,
    azure_ad_token_provider=token_provider,
    api_version="2024-10-21"
)

Podobnie podczas konfigurowania źródła danych dla usługi Azure AI Search tożsamość zarządzana jest określana na potrzeby uwierzytelniania:

data_source = {
    "type": "azure_search",
    "parameters": {
        "endpoint": self.search_url,
        "index_name": self.search_index_name,
        "authentication": {
            "type": "system_assigned_managed_identity"
        },
        # ...
    }
}

response = await self.openai_client.chat.completions.create(
    model=self.gpt_deployment,
    messages=messages,
    extra_body={
        "data_sources": [data_source]
    },
    stream=False
)

Ta konfiguracja umożliwia bezpieczną, bez hasła komunikację między aplikacją FastAPI i usługami platformy Azure, zgodnie z najlepszymi rozwiązaniami dotyczącymi zabezpieczeń Zero Trust. Dowiedz się więcej o bibliotece klienta DefaultAzureCredential i bibliotece klienta tożsamości platformy Azure dla języka Python.

W jaki sposób wyszukiwanie hybrydowe z semantycznym rankerem zaimplementowano w przykładowej aplikacji?

Przykładowa aplikacja konfiguruje wyszukiwanie hybrydowe z semantycznym rankingiem przy użyciu zestawu AZURE OpenAI SDK. W zapleczu źródło danych jest skonfigurowane w następujący sposób:

data_source = {
    "type": "azure_search",
    "parameters": {
        # ...
        "query_type": "vector_semantic_hybrid",
        "semantic_configuration": f"{self.search_index_name}-semantic-configuration",
        "embedding_dependency": {
            "type": "deployment_name",
            "deployment_name": self.embedding_deployment
        }
    }
}

Ta konfiguracja umożliwia aplikacji łączenie wyszukiwania wektorowego (podobieństwa semantycznego), dopasowywania słów kluczowych i klasyfikacji semantycznej w jednym zapytaniu. Semantyczny ranker zmienia kolejność wyników, aby zwracać najbardziej trafne i kontekstowo odpowiednie odpowiedzi, które są następnie używane przez Azure OpenAI do generowania odpowiedzi.

Nazwa konfiguracji semantycznej jest automatycznie definiowana przez zintegrowany proces wektoryzacji. Używa ona nazwy indeksu wyszukiwania jako prefiksu i dołączania -semantic-configuration jako sufiksu. Gwarantuje to, że konfiguracja semantyczna jest unikatowo skojarzona z odpowiednim indeksem i jest zgodna z spójną konwencją nazewnictwa.

Dlaczego wszystkie zasoby są tworzone w East US 2?

W przykładzie użyto modeli gpt-4o-mini i text-embedding-ada-002, które są dostępne w standardowym typie wdrożenia w regionie wschód USA 2. Te modele są również wybierane, ponieważ nie są one zaplanowane na wycofanie wkrótce, zapewniając stabilność wdrożenia próbnego. Dostępność modelu i typy wdrożeń mogą się różnić w zależności od regionu, dlatego wybrano Wschodnie USA 2, aby upewnić się, że przykład jest gotowy do użycia. Jeśli chcesz użyć innego regionu lub modeli, wybierz modele, które są dostępne dla tego samego typu wdrożenia w tym samym regionie. Podczas wybierania własnych modeli sprawdź zarówno ich dostępność, jak i daty wycofania, aby uniknąć zakłóceń.

Dostępność modelu: modele usługi Azure OpenAI Service
Daty wycofania modeli: wycofanie i zakończenie wsparcia dla modeli usługi Azure OpenAI Service.

Czy mogę używać własnych modeli OpenAI zamiast modeli udostępnianych przez platformę Azure?

To rozwiązanie jest przeznaczone do pracy z usługą Azure OpenAI Service. Chociaż można zmodyfikować kod tak, aby korzystał z innych modeli OpenAI, utracisz zintegrowane funkcje zabezpieczeń, obsługę tożsamości zarządzanych i bezproblemową integrację z usługą Azure AI Search, którą zapewnia to rozwiązanie.

Jak mogę poprawić jakość odpowiedzi?

Jakość odpowiedzi można poprawić, wykonując następujące czynności:

Przesyłanie dokumentów o wyższej jakości i większej relewantności.
Dostosowywanie strategii fragmentowania w potoku indeksowania w Azure AI Search. Nie można jednak dostosować dzielenia na fragmenty za pomocą zintegrowanej wektoryzacji pokazanej w tym samouczku.
Eksperymentowanie z różnymi szablonami monitów w kodzie aplikacji.
Dostrajanie wyszukiwania za pomocą innych właściwości w type: "azure_search źródle danych.
Korzystanie z bardziej wyspecjalizowanych modeli usługi Azure OpenAI dla określonej domeny.

Udostępnij za pośrednictwem