Kurz: Vytvoření aplikace rozšířené generace načítání ve službě Azure App Service pomocí Azure OpenAI a Azure AI Search (FastAPI)

V tomto kurzu vytvoříte aplikaci RAG (Python Retrieval Augmented Generation) pomocí FastAPI, Azure OpenAI a Azure AI Search a nasadíte ji do Služby Azure App Service. Tato aplikace ukazuje, jak implementovat rozhraní chatu, které načítá informace z vlastních dokumentů a využívá služby Azure AI k poskytování přesných kontextových odpovědí se správnými citacemi. Řešení používá spravované identity pro ověřování bez hesla mezi službami.

V tomto návodu se naučíte, jak:

Nasaďte aplikaci FastAPI, která používá model RAG se službami Azure AI.
Nakonfigurujte Azure OpenAI a Azure AI Search pro hybridní vyhledávání.
Nahrajte a indexujte dokumenty pro použití v aplikaci využívající AI.
Používejte spravované identity pro zabezpečenou komunikaci mezi službami.
Otestujte implementaci RAG místně pomocí produkčních služeb.

Přehled architektury

Než začnete s nasazením, je užitečné porozumět architektuře aplikace, kterou vytvoříte. Následující diagram je z vlastního vzoru RAG pro Azure AI Search:

V tomto kurzu se aplikace Blazer ve službě App Service postará o uživatelské prostředí aplikace i o aplikační server. Neprovádí však samostatný znalostní dotaz na Azure AI Search. Místo toho řekne Azure OpenAI, aby dotazování znalostí určující azure AI Search jako zdroj dat. Tato architektura nabízí několik klíčových výhod:

Integrovaná vektorizace: Funkce integrované vektorizace služby Azure AI Search usnadňují a rychle ingestují všechny dokumenty pro vyhledávání, aniž by bylo potřeba více kódu pro generování vložených objektů.
Zjednodušený přístup k rozhraní API: Použití modelu Azure OpenAI ve vašich datech ve službě Azure AI Search jako zdroje dat pro dokončování Azure OpenAI není potřeba implementovat komplexní vektorové vyhledávání ani generování vkládání. Je to jen jedno volání rozhraní API a Azure OpenAI zpracovává všechno, včetně přípravy výzvy a optimalizace dotazů.
Funkce rozšířeného vyhledávání: Integrovaná vektorizace poskytuje vše potřebné pro rozšířené hybridní vyhledávání sémantickou rerankací, která kombinuje silné stránky párování klíčových slov, vektorové podobnosti a hodnocení založené na umělé inteligenci.
Úplná podpora citace: Odpovědi automaticky zahrnují citace do zdrojových dokumentů, což umožňuje ověřitelné a sledovatelné informace.

Požadavky

Účet Azure s aktivním předplatným – zdarma si vytvořte účet.
Účet GitHubu pro použití GitHub Codespaces – Přečtěte si další informace o GitHub Codespaces.

1. Otevření ukázky pomocí Codespaces

Nejjednodušší způsob, jak začít, je použití GitHub Codespaces, které poskytuje kompletní vývojové prostředí se všemi požadovanými nástroji předinstalovanými.

Přejděte do úložiště GitHub na adrese https://github.com/Azure-Samples/app-service-rag-openai-ai-search-python.
Vyberte tlačítko Kód, vyberte kartu Codespaces a klikněte na Vytvořit codespace na main.
Chvíli počkejte, než se codespace inicializuje. Až budete připraveni, uvidíte v prohlížeči plně nakonfigurované prostředí VS Code.

2. Nasazení ukázkové architektury

V terminálu se přihlaste k Azure pomocí Azure Developer CLI:
```
azd auth login
```
Dokončete proces ověřování podle pokynů.
Zřízení prostředků Azure pomocí šablony AZD:
```
azd provision
```

Po zobrazení výzvy zadejte následující odpovědi:

Otázka	Odpověď
Zadejte nový název prostředí:	Zadejte jedinečný název.
Vyberte předplatné Azure, které chcete použít:	Vyberte předplatné.
Vyberte skupinu prostředků, která se má použít:	Vyberte Vytvořit novou skupinu prostředků.
Vyberte umístění, ve které chcete vytvořit skupinu prostředků:	Vyberte libovolnou oblast. Ve skutečnosti budou prostředky vytvořeny v East US 2.
Zadejte název nové skupiny prostředků:	Zadejte Enter.

Počkejte, až se nasazení dokončí. Tento proces bude:
- Vytvořte všechny požadované prostředky Azure.
- Nasaďte aplikaci do služby Azure App Service.
- Nakonfigurujte zabezpečené ověřování mezi službami pomocí spravovaných identit.
- Nastavte potřebná přiřazení rolí pro zabezpečený přístup mezi službami.
Poznámka:

Další informace o tom, jak spravované identity fungují, najdete v tématu Co jsou spravované identity pro prostředky Azure? a jak používat spravované identity se službou App Service.
Po úspěšném nasazení se zobrazí adresa URL nasazené aplikace. Poznamenejte si tuto adresu URL, ale zatím k ní nemáte přístup, protože stále potřebujete nastavit index vyhledávání.

3. Nahrání dokumentů a vytvoření indexu vyhledávání

Teď, když je infrastruktura nasazená, musíte nahrát dokumenty a vytvořit vyhledávací index, který bude aplikace používat:

Na webu Azure Portal přejděte k účtu úložiště vytvořenému nasazením. Název začne názvem prostředí, který jste zadali dříve.
V levé navigační nabídce vyberteKontejnery> dat a otevřete kontejner dokumentů.
Kliknutím na Nahrát nahrajte ukázkové dokumenty. Můžete použít ukázkové dokumenty ze sample-docs složky v úložišti nebo vlastní soubory PDF, Word nebo textové soubory.
Na webu Azure Portal přejděte ke službě Azure AI Search.
Výběrem možnosti Importovat data (nová) zahájíte proces vytváření indexu vyhledávání.
V kroku Připojení k datům :
- Jako zdroj dat vyberte Azure Blob Storage .
- Vyberte RAG.
- Zvolte svůj účet úložiště a kontejner dokumentů .
- Vyberte Ověřit pomocí spravované identity.
- Vyberte Další.
V kroku Vektorizace textu :
- Vyberte službu Azure OpenAI.
- Jako model vkládání zvolte text-embedding-ada-002 . Šablona AZD už pro vás tento model nasadila.
- Vyberte identitu přiřazenou systémem pro ověřování.
- Zaškrtněte potvrzovací políčko pro dodatečné náklady.
- Vyberte Další.
Návod

Přečtěte si další informace o vektorovém vyhledávání ve službě Azure AI Search a vkládání textu v Azure OpenAI.
Ve fázi Převeďte a obohaťte své obrázky:
- Ponechte výchozí nastavení.
- Vyberte Další.
V kroku Upřesnit nastavení :
- Ujistěte se, že je vybráno Povolit sémantický ranker.
- (Volitelné) Vyberte plán indexování. To je užitečné, pokud chcete index pravidelně aktualizovat nejnovějšími změnami souboru.
- Vyberte Další.
V kroku Zkontrolovat a vytvořit :
- Zkopírujte hodnotu předpony názvu objektu . Je to název indexu vyhledávání.
- Výběrem možnosti Vytvořit zahájíte proces indexování.
Počkejte na dokončení procesu indexování. V závislosti na velikosti a počtu dokumentů to může trvat několik minut.
Import dat otestujete tak, že vyberete Začít hledat a vyzkoušíte vyhledávací dotaz typu Řekněte mi o vaší společnosti.
Zpátky v terminálu Codespace nastavte název indexu vyhledávání jako proměnnou prostředí AZD:
```
azd env set SEARCH_INDEX_NAME <your-search-index-name>
```
Nahraďte <your-search-index-name> dříve zkopírovaným názvem indexu. AZD použije tuto proměnnou v následných nasazeních k nastavení nastavení aplikace app Service.

4. Otestování aplikace a nasazení

Pokud dáváte přednost místnímu testování aplikace před nebo po nasazení, můžete ji spustit přímo z codespace:

V terminálu Codespace získejte hodnoty prostředí AZD:
```
azd env get-values
```
Otevřít .env. Pomocí výstupu terminálu aktualizujte následující hodnoty v příslušných zástupných symbolech <input-manually-for-local-testing>:
- AZURE_OPENAI_ENDPOINT
- AZURE_SEARCH_SERVICE_URL
- AZURE_SEARCH_INDEX_NAME
Přihlaste se k Azure pomocí Azure CLI:
```
az login
```
To umožňuje klientské knihovně Azure Identity v ukázkovém kódu přijímat ověřovací token pro přihlášeného uživatele.

Spusťte aplikaci místně:

pip install -r requirements.txt
uvicorn main:app

Až uvidíte výstup vaší aplikace spuštěný na portu 8000 je dostupný, vyberte Otevřít v prohlížeči.
Zkuste se zeptat na několik otázek v rozhraní chatu. Pokud obdržíte odpověď, vaše aplikace se úspěšně připojuje k prostředku Azure OpenAI.
Zastavte vývojový server pomocí Ctrl+C.
Použijte novou SEARCH_INDEX_NAME konfiguraci v Azure a nasaďte vzorový kód aplikace:
```
azd up
```

5. Otestování nasazené aplikace RAG

S plně nasazenou a nakonfigurovanou aplikací teď můžete otestovat funkčnost RAG:

Otevřete adresu URL aplikace zadanou na konci nasazení.
Uvidíte rozhraní chatu, kde můžete zadat otázky týkající se obsahu nahraných dokumentů.
Zkuste klást otázky, které jsou specifické pro obsah vašich dokumentů. Pokud jste například nahráli dokumenty do složky sample-docs , můžete vyzkoušet tyto otázky:
- Jak společnost Contoso používá moje osobní údaje?
- Jak podat žádost o záruku?
Všimněte si, jak odpovědi obsahují citace, které odkazují na zdrojové dokumenty. Tyto citace pomáhají uživatelům ověřit přesnost informací a najít další podrobnosti ve zdrojovém materiálu.
Otestujte možnosti hybridního vyhledávání tím, že položíte otázky, které můžou těžit z různých přístupů k hledání:
- Dotazy týkající se konkrétní terminologie (vhodné pro vyhledávání klíčových slov)
- Dotazy týkající se konceptů, které mohou být popsány pomocí různých termínů (vhodné pro vektorové vyhledávání).
- Složité otázky, které vyžadují pochopení kontextu (vhodné pro sémantické řazení).

Vyčistěte zdroje

Až budete s aplikací hotovi, můžete odstranit všechny prostředky, abyste se vyhnuli dalším nákladům:

azd down --purge

Tento příkaz odstraní všechny prostředky přidružené k vaší aplikaci.

Nejčastější dotazy

Jak ukázkový kód získává citace z výstupů z chatu Azure OpenAI?
Jaká je výhoda používání spravovaných identit v tomto řešení?
Jak se používá spravovaná identita přiřazená systémem v této architektuře a ukázkové aplikaci?
Jak je hybridní vyhledávání pomocí sémantického rankeru implementované v ukázkové aplikaci?
Proč se všechny prostředky vytvářejí ve východním USA 2?
Můžu místo těch, které poskytuje Azure, používat vlastní modely OpenAI?
Jak můžu zlepšit kvalitu odpovědí?

Jak ukázkový kód načítá citace z výstupu chatu Azure OpenAI?

Ukázka načte citace pomocí zdroje dat ve službě Azure AI Search pro chatovacího klienta. Když je požadováno dokončení chatu, odpověď obsahuje citations objekt v kontextu zprávy. Ukázková aplikace předá objekt odpovědi do klientského kódu, který extrahuje citace následujícím způsobem:

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

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

Ve zprávě odpovědi obsah používá [doc#] notaci k odkazování na odpovídající citaci v seznamu, což uživatelům umožňuje trasovat informace zpět do původních zdrojových dokumentů. Další informace najdete tady:

Jaká je výhoda používání spravovaných identit v tomto řešení?

Spravované identity eliminují potřebu ukládat přihlašovací údaje do kódu nebo konfigurace. Pomocí spravovaných identit může aplikace bezpečně přistupovat ke službám Azure, jako je Azure OpenAI a Azure AI Search, bez správy tajných kódů. Tento přístup se řídí principy zabezpečení nulové důvěryhodnosti a snižuje riziko vystavení přihlašovacích údajů.

Jak se používá spravovaná identita přiřazená systémem v této architektuře a ukázkové aplikaci?

Nasazení AZD vytvoří spravované identity přiřazené systémem pro Azure App Service, Azure OpenAI a Azure AI Search. Také se přiřazuje příslušné role pro každou z nich (viz soubor main.bicep ). Pro informace o požadovaných přiřazeních rolí naleznete v části Konfigurace sítě a přístupu pro Azure OpenAI v rámci vašich dat.

V ukázkové aplikaci FastAPI používají sady Azure SDK tuto spravovanou identitu k zabezpečenému ověřování, takže nemusíte ukládat přihlašovací údaje ani tajné kódy nikde. Například klient AsyncAzureOpenAI je inicializován s DefaultAzureCredential, což automaticky využívá spravovanou identitu při spuštění v 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"
)

Podobně při konfiguraci zdroje dat pro Azure AI Search se pro ověřování zadává spravovaná identita:

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
)

Toto nastavení umožňuje zabezpečenou komunikaci bez hesla mezi vaší aplikací FastAPI a službami Azure podle osvědčených postupů pro zabezpečení nulové důvěryhodnosti. Přečtěte si další informace o DefaultAzureCredential a klientské knihovně Azure Identity pro Python.

Jak je hybridní vyhledávání pomocí sémantického rankeru implementované v ukázkové aplikaci?

Ukázková aplikace konfiguruje hybridní vyhledávání pomocí sémantického řazení pomocí sady Azure OpenAI SDK. V back-endu je zdroj dat nastavený takto:

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
        }
    }
}

Tato konfigurace umožňuje aplikaci kombinovat vektorové vyhledávání (sémantické podobnosti), porovnávání klíčových slov a sémantické řazení v jednom dotazu. Sémantický ranker přeřadí výsledky tak, aby vrátily nejrelevantnější a kontextově nejvhodnější odpovědi, které pak využívá Azure OpenAI k generování odpovědí.

Sémantický název konfigurace je automaticky definován integrovaným vektorizačním procesem. Používá název indexu vyhledávání jako předponu a připojí -semantic-configuration jako příponu. Tím se zajistí, že sémantická konfigurace je jedinečně přidružená k odpovídajícímu indexu a dodržuje konzistentní zásady vytváření názvů.

Proč jsou všechny prostředky vytvořeny v oblasti Východní USA 2?

Ukázka používá modely gpt-4o-mini a text-embedding-ada-002 , z nichž obě jsou dostupné s typem nasazení Standard v oblasti USA – východ 2. Tyto modely se také vyberou, protože nebudou brzy vyřazeny, což zajišťuje stabilitu pro ukázkovou implementaci. Dostupnost modelu a typy nasazení se mohou lišit podle oblasti, takže je vybrána oblast Východní USA 2, aby ukázka fungovala. Pokud chcete použít jinou oblast nebo modely, nezapomeňte vybrat modely, které jsou dostupné pro stejný typ nasazení ve stejné oblasti. Při výběru vlastních modelů zkontrolujte jejich dostupnost i data vyřazení, abyste se vyhnuli přerušení.

Dostupnost modelu: Modely služby Azure OpenAI
Termíny uvedení modelu mimo provoz: Odstavení a vyřazení modelu služby Azure OpenAI.

Můžu místo těch, které poskytuje Azure, používat vlastní modely OpenAI?

Toto řešení je navržené tak, aby fungovalo se službou Azure OpenAI. I když byste mohli kód upravit tak, aby používal jiné modely OpenAI, ztratili byste integrované funkce zabezpečení, podporu spravované identity a bezproblémovou integraci se službou Azure AI Search, kterou toto řešení poskytuje.

Jak můžu zlepšit kvalitu odpovědí?

Kvalitu odezvy můžete zlepšit:

Nahrávání dokumentů vyšší kvality a s větší relevancí.
Úprava strategií vytváření částí v indexačním procesu Azure AI Search. Nemůžete ale přizpůsobit bloky dat pomocí integrované vektorizace zobrazené v tomto kurzu.
Experimentování s různými šablonami výzvy v kódu aplikace
Vyladění hledání jinými vlastnostmi ve zdroji type: "azure_search dat
Použití specializovaných modelů Azure OpenAI pro vaši konkrétní doménu

Další zdroje informací

Váš názor

Byla tato stránka užitečná?

Last updated on 2025-11-18