Tutoriel : Créer une application de génération augmentée de récupération dans Azure App Service avec Azure OpenAI et Azure AI Search (Spring Boot)

Dans ce tutoriel, vous allez créer une application RAG (Java Recovery Augmented Generation) à l’aide de Spring Boot, d’Azure OpenAI et d’Azure AI Search et de la déployer sur Azure App Service. Cette application montre comment implémenter une interface de conversation qui récupère des informations à partir de vos propres documents et tire parti des services Azure AI pour fournir des réponses précises et contextuelles avec des citations appropriées. La solution utilise des identités managées pour l’authentification sans mot de passe entre les services.

Conseil / Astuce

Bien que ce tutoriel utilise Spring Boot, les concepts fondamentaux de la création d’une application RAG avec Azure OpenAI et Azure AI Search s’appliquent à n’importe quelle application web Java. Si vous utilisez une autre option d’hébergement sur App Service, telle que Tomcat ou JBoss EAP, vous pouvez adapter les modèles d’authentification et l’utilisation du Kit de développement logiciel (SDK) Azure présentés ici à votre infrastructure préférée.

Dans ce tutoriel, vous allez apprendre à :

Déployez une application Spring Boot qui utilise le modèle RAG avec les services Azure AI.
Configurez Azure OpenAI et Recherche Azure AI pour la recherche hybride.
Chargez et indexez des documents à utiliser dans votre application basée sur l’IA.
Utilisez des identités managées pour la communication de service à service sécurisée.
Testez votre implémentation RAG localement avec les services de production.

Vue d’ensemble de l’architecture

Avant de commencer le déploiement, il est utile de comprendre l’architecture de l’application que vous allez générer. Le diagramme suivant provient du modèle RAG personnalisé pour Recherche d’IA Azure :

Dans ce tutoriel, l’application Blazer dans App Service s’occupe à la fois de l’expérience utilisateur de l’application et du serveur d’applications. Toutefois, il n’effectue pas de requête de savoir distincte de celle de la recherche cognitive Azure. Au lieu de cela, il indique à Azure OpenAI d’effectuer l’interrogation des connaissances en spécifiant Recherche Azure AI en tant que source de données. Cette architecture offre plusieurs avantages clés :

Vectorisation intégrée : les fonctionnalités de vectorisation intégrées d’Azure AI Search facilitent et rapidement l’ingestion de tous vos documents pour la recherche, sans nécessiter davantage de code pour générer des incorporations.
Accès à l’API simplifié : à l’aide du modèle Azure OpenAI sur vos données avec Recherche AZURE AI comme source de données pour les achèvements Azure OpenAI, il n’est pas nécessaire d’implémenter une recherche vectorielle complexe ou une génération d’incorporation. Il s’agit d’un seul appel d’API et Azure OpenAI gère tout, notamment l’ingénierie rapide et l’optimisation des requêtes.
Fonctionnalités de recherche avancée : la vectorisation intégrée fournit tout ce qui est nécessaire pour la recherche hybride avancée avec la reclassement sémantique, qui combine les forces de la correspondance de mots clés, de la similarité vectorielle et du classement basé sur l’IA.
Prise en charge complète des citations : les réponses incluent automatiquement des citations aux documents sources, rendant vérifiables et traceables des informations.

Conditions préalables

Un compte Azure avec un abonnement actif : créez un compte gratuitement.
Compte GitHub pour utiliser GitHub Codespaces - En savoir plus sur GitHub Codespaces.

1. Ouvrez l’exemple avec Codespaces

Le moyen le plus simple de commencer consiste à utiliser GitHub Codespaces, qui fournit un environnement de développement complet avec tous les outils requis préinstallés.

Accédez au dépôt GitHub à l’adresse https://github.com/Azure-Samples/app-service-rag-openai-ai-search-java.
Sélectionnez le bouton Code , sélectionnez l’onglet Espaces de code, puis cliquez sur Créer un espace de code dans l’espace de code principal.
Attendez quelques instants pour que votre espace de code s’initialise. Une fois prêt, vous verrez un environnement VS Code entièrement configuré dans votre navigateur.

2. Déployer l’exemple d’architecture

Dans le terminal, connectez-vous à Azure à l’aide d’Azure Developer CLI :
```
azd auth login
```
Suivez les instructions pour terminer le processus d’authentification.
Provisionnez les ressources Azure avec le modèle AZD :
```
azd provision
```

Lorsque vous y êtes invité, fournissez les réponses suivantes :

Question	Réponse
Entrez un nouveau nom d’environnement :	Tapez un nom unique.
Sélectionnez un abonnement Azure à utiliser :	Sélectionnez l’abonnement.
Choisissez un groupe de ressources à utiliser :	Sélectionnez Créer un groupe de ressources.
Sélectionnez un emplacement dans lequel créer le groupe de ressources :	Sélectionnez n’importe quelle région. Les ressources seront effectivement créées dans East US 2.
Entrez un nom pour le nouveau groupe de ressources :	Tapez sur Entrée.

Attendez que le déploiement se termine. Ce processus effectue les étapes suivantes :
- Créez toutes les ressources Azure requises.
- Déployez l’application sur Azure App Service.
- Configurez l’authentification de service à service sécurisée à l’aide d’identités managées.
- Configurez les attributions de rôles nécessaires pour sécuriser l’accès entre les services.
Remarque

Pour en savoir plus sur le fonctionnement des identités managées, consultez Qu’est-ce que les identités managées pour les ressources Azure ? et comment utiliser des identités managées avec App Service.
Une fois le déploiement réussi, vous verrez une URL pour votre application déployée. Notez cette URL, mais n’y accédez pas encore, car vous devez toujours configurer l’index de recherche.

3. Charger des documents et créer un index de recherche

Maintenant que l’infrastructure est déployée, vous devez charger des documents et créer un index de recherche que l’application utilisera :

Dans le portail Azure, accédez au compte de stockage créé par le déploiement. Le nom commence par le nom de l’environnement que vous avez fourni précédemment.
SélectionnezConteneurs> de données dans le menu de navigation de gauche et ouvrez le conteneur de documents.
Chargez des exemples de documents en cliquant sur Charger. Vous pouvez utiliser les exemples de documents du sample-docs dossier dans le référentiel, ou vos propres fichiers PDF, Word ou texte.
Accédez à votre service Recherche d’IA Azure dans le portail Azure.
Sélectionnez Importer des données (nouveau) pour démarrer le processus de création d’un index de recherche.
Dans l’étape Se connecter à vos données :
- Sélectionnez Stockage Blob Azure comme source de données.
- Sélectionnez RAG.
- Choisissez votre compte de stockage et le conteneur de documents .
- Sélectionnez S’authentifier à l’aide de l’identité managée.
- Cliquez sur Suivant.
Dans l’étape Vectoriser votre texte :
- Sélectionnez votre service Azure OpenAI.
- Choisissez text-embedding-ada-002 comme modèle d'intégration. Le modèle AZD a déjà déployé ce modèle pour vous.
- Sélectionnez l’identité affectée par le système pour l’authentification.
- Cochez la case accusé de réception pour les coûts supplémentaires.
- Cliquez sur Suivant.
Conseil / Astuce

En savoir plus sur la recherche vectorielle dans recherche Azure AI et les incorporations de texte dans Azure OpenAI.
Dans l'étape Vectoriser et enrichir vos images :
- Conservez les paramètres par défaut.
- Cliquez sur Suivant.
À l’étape Paramètres avancés :
- Vérifiez que l’option Activer le ranker sémantique est sélectionnée.
- (Facultatif) Sélectionnez une planification d’indexation. Cela est utile si vous souhaitez actualiser régulièrement votre index avec les dernières modifications de fichier.
- Cliquez sur Suivant.
Dans l’étape Vérifier et créer :
- Copiez la valeur de préfixe du nom d’objets . Il s’agit de votre nom d’index de recherche.
- Sélectionnez Créer pour démarrer le processus d’indexation.
Attendez que le processus d’indexation se termine. Cela peut prendre quelques minutes en fonction de la taille et du nombre de vos documents.
Pour tester l’importation de données, sélectionnez Démarrer la recherche et essayez une requête de recherche telle que « Parlez-moi de votre entreprise ».
De retour dans votre terminal Codespace, définissez le nom de l’index de recherche en tant que variable d’environnement AZD :
```
azd env set SEARCH_INDEX_NAME <your-search-index-name>
```
Remplacez <your-search-index-name> par le nom d’index que vous avez copié précédemment. AZD utilise cette variable dans les déploiements suivants pour définir le paramètre d’application App Service.

4. Tester l’application et déployer

Si vous préférez tester l’application localement avant ou après le déploiement, vous pouvez l’exécuter directement à partir de votre Codespace :

Dans votre terminal Codespace, obtenez les valeurs d’environnement AZD :
```
azd env get-values
```
Ouvrez src/main/resources/application.properties. À l’aide de la sortie du terminal, mettez à jour les valeurs suivantes, dans les espaces réservés respectifs <input-manually-for-local-testing> :
- azure.openai.endpoint
- azure.search.url
- azure.search.index.name
Connectez-vous à Azure avec Azure CLI :
```
az login
```
Cela permet à la bibliothèque cliente Azure Identity dans l’exemple de code de recevoir un jeton d’authentification pour l’utilisateur connecté.
Exécutez l’application localement :
```
mvn spring-boot:run
```
Lorsque vous voyez Votre application s’exécuter sur le port 8080 est disponible, sélectionnez Ouvrir dans le navigateur.
Essayez de poser quelques questions dans l’interface de conversation. Si vous obtenez une réponse, votre application se connecte correctement à la ressource Azure OpenAI.
Arrêtez le serveur de développement avec Ctrl+C.
Appliquez la nouvelle SEARCH_INDEX_NAME configuration dans Azure et déployez l’exemple de code d’application :
```
azd up
```

5. Tester l’application RAG déployée

Avec l’application entièrement déployée et configurée, vous pouvez maintenant tester la fonctionnalité RAG :

Ouvrez l’URL de l’application fournie à la fin du déploiement.
Vous voyez une interface de conversation dans laquelle vous pouvez entrer des questions sur le contenu de vos documents chargés.
Essayez de poser des questions spécifiques au contenu de vos documents. Par exemple, si vous avez chargé les documents dans le dossier sample-docs , vous pouvez essayer ces questions :
- Comment Contoso utilise-t-il mes données personnelles ?
- Comment déposer une réclamation de garantie ?
Notez comment les réponses incluent des citations qui font référence aux documents sources. Ces citations aident les utilisateurs à vérifier la précision des informations et à trouver plus de détails dans le matériel source.
Testez les fonctionnalités de recherche hybride en posant des questions susceptibles de bénéficier de différentes approches de recherche :
- Questions avec une terminologie spécifique (bonne pour la recherche de mots clés).
- Questions sur les concepts qui peuvent être décrits à l’aide de différents termes (bon pour la recherche vectorielle).
- Questions complexes nécessitant une bonne compréhension du contexte, ce qui convient au classement sémantique.

Nettoyer les ressources

Lorsque vous avez terminé avec l’application, vous pouvez supprimer toutes les ressources pour éviter d’entraîner d’autres coûts :

azd down --purge

Cette commande supprime toutes les ressources associées à votre application.

Questions fréquentes

Comment l’exemple de code récupère-t-il des citations à partir des achèvements de conversation Azure OpenAI ?
Quel est l’avantage de l’utilisation d’identités managées dans cette solution ?
Comment l’identité managée affectée par le système est-elle utilisée dans cette architecture et cet exemple d’application ?
Comment la recherche hybride avec l’éditeur de classement sémantique est-elle implémentée dans l’exemple d’application ?
Pourquoi toutes les ressources sont créées dans l'Est des États-Unis 2 ?
Puis-je utiliser mes propres modèles OpenAI plutôt que ceux fournis par Azure ?
Comment puis-je améliorer la qualité des réponses ?

Comment l’exemple de code récupère-t-il des citations à partir des achèvements de conversation Azure OpenAI ?

L’exemple récupère des citations à l’aide de la AzureSearchChatExtensionConfiguration comme source de données pour le client de chat. Lorsqu'une complétion de chat est demandée, la réponse inclut un objet Citations dans le contexte du message. Le code extrait ces citations comme suit :

public static ChatResponse fromChatCompletions(ChatCompletions completions) {
    ChatResponse response = new ChatResponse();
    
    if (completions.getChoices() != null && !completions.getChoices().isEmpty()) {
        var message = completions.getChoices().get(0).getMessage();
        if (message != null) {
            response.setContent(message.getContent());

            if (message.getContext() != null && message.getContext().getCitations() != null) {
                var azureCitations = message.getContext().getCitations();
                for (int i = 0; i < azureCitations.size(); i++) {
                    var azureCitation = azureCitations.get(i);
                    
                    Citation citation = new Citation();
                    citation.setIndex(i + 1);
                    citation.setTitle(azureCitation.getTitle());
                    citation.setContent(azureCitation.getContent());
                    citation.setFilePath(azureCitation.getFilepath());
                    citation.setUrl(azureCitation.getUrl());
                    
                    response.getCitations().add(citation);
                }
            }
        }
    }
    
    return response;
}

Dans la réponse de conversation, le contenu utilise la notation [doc#] pour référencer la citation correspondante dans la liste, ce qui permet aux utilisateurs de retracer les informations jusqu'aux documents sources. Pour plus d’informations, consultez :

Quel est l’avantage de l’utilisation d’identités managées dans cette solution ?

Les identités managées éliminent la nécessité de stocker les informations d’identification dans votre code ou configuration. En utilisant des identités managées, l’application peut accéder en toute sécurité aux services Azure tels qu’Azure OpenAI et Recherche Azure AI sans gérer les secrets. Cette approche suit les principes de sécurité Confiance Zéro et réduit le risque d’exposition des informations d’identification.

Comment l’identité managée affectée par le système est-elle utilisée dans cette architecture et cet exemple d’application ?

Le déploiement AZD crée des identités managées affectées par le système pour Azure App Service, Azure OpenAI et Recherche Azure AI. Il effectue également des attributions de rôle respectives pour chacun d’eux (voir le fichier main.bicep ). Pour plus d’informations sur les attributions de rôles requises, consultez La configuration réseau et d’accès pour Azure OpenAI sur vos données.

Dans l’exemple d’application Java, les kits de développement logiciel (SDK) Azure utilisent cette identité managée pour l’authentification sécurisée. Vous n’avez donc pas besoin de stocker des informations d’identification ou des secrets n’importe où. Par exemple, il OpenAIAsyncClient est initialisé avec DefaultAzureCredential, qui utilise automatiquement l’identité managée lors de l’exécution dans Azure :

@Bean
public TokenCredential tokenCredential() {
   return new DefaultAzureCredentialBuilder().build();
}

@Bean
public OpenAIAsyncClient openAIClient(TokenCredential tokenCredential) {
   return new OpenAIClientBuilder()
         .endpoint(openAiEndpoint)
         .credential(tokenCredential)
         .buildAsyncClient();
}

De même, lors de la configuration de la source de données pour Azure AI Search, l’identité managée est spécifiée pour l’authentification :

AzureSearchChatExtensionConfiguration searchConfiguration =
   new AzureSearchChatExtensionConfiguration(
      new AzureSearchChatExtensionParameters(appSettings.getSearch().getUrl(), appSettings.getSearch().getIndex().getName())
         .setAuthentication(new OnYourDataSystemAssignedManagedIdentityAuthenticationOptions())
         // ...
   );

Cette configuration permet une communication sécurisée sans mot de passe entre votre application Spring Boot et vos services Azure, en suivant les meilleures pratiques pour la sécurité Confiance Zéro. En savoir plus sur DefaultAzureCredential et la bibliothèque cliente Azure Identity pour Java.

Comment la recherche hybride avec l’éditeur de classement sémantique est-elle implémentée dans l’exemple d’application ?

L’exemple d’application configure la recherche hybride avec le classement sémantique à l’aide des SDKs Java Azure OpenAI et Azure AI Search. Dans le back-end, la source de données est configurée comme suit :

AzureSearchChatExtensionParameters parameters = new AzureSearchChatExtensionParameters(
   appSettings.getSearch().getUrl(),
   appSettings.getSearch().getIndex().getName())
    // ...
    .setQueryType(AzureSearchQueryType.VECTOR_SEMANTIC_HYBRID)
    .setEmbeddingDependency(new OnYourDataDeploymentNameVectorizationSource(appSettings.getOpenai().getEmbedding().getDeployment()))
    .setSemanticConfiguration(appSettings.getSearch().getIndex().getName() + "-semantic-configuration");

Cette configuration permet à l’application de combiner la recherche vectorielle (similarité sémantique), la correspondance de mots clés et le classement sémantique dans une seule requête. L’éditeur de classement sémantique réorganise les résultats pour retourner les réponses les plus pertinentes et contextuellement appropriées, qui sont ensuite utilisées par Azure OpenAI pour générer des réponses.

Le nom de configuration sémantique est automatiquement défini par le processus de vectorisation intégré. Il utilise le nom de l’index de recherche comme préfixe et ajoute -semantic-configuration comme suffixe. Cela garantit que la configuration sémantique est associée de manière unique à l’index correspondant et suit une convention de nommage cohérente.

Pourquoi toutes les ressources sont-elles créées dans USA Est 2 ?

L’exemple utilise les modèles gpt-4o-mini et text-embedding-ada-002, qui sont tous deux disponibles avec le type de déploiement Standard dans l'Est des États-Unis 2. Ces modèles sont également choisis parce qu’ils ne sont pas prévus pour la mise hors service prochainement, ce qui offre une stabilité pour l’exemple de déploiement. La disponibilité du modèle et les types de déploiement peuvent varier selon la région, USA Est 2 est donc sélectionnée pour garantir que l’exemple fonctionne d’emblée. Si vous souhaitez utiliser une autre région ou des modèles, veillez à sélectionner des modèles disponibles pour le même type de déploiement dans la même région. Lorsque vous choisissez vos propres modèles, vérifiez à la fois leur disponibilité et leurs dates de mise hors service pour éviter les interruptions.

Disponibilité des modèles : modèles du service Azure OpenAI
Dates de mise hors service du modèle : Dépréciations et mises hors service du modèle Azure OpenAI Service.

Puis-je utiliser mes propres modèles OpenAI plutôt que ceux fournis par Azure ?

Cette solution est conçue pour fonctionner avec Azure OpenAI Service. Bien que vous puissiez modifier le code pour utiliser d’autres modèles OpenAI, vous perdez les fonctionnalités de sécurité intégrées, la prise en charge de l’identité managée et l’intégration transparente à Azure AI Search que cette solution fournit.

Comment puis-je améliorer la qualité des réponses ?

Vous pouvez améliorer la qualité de la réponse en effectuant les actions suivantes :

Chargement de documents de qualité supérieure, plus pertinents.
Ajustement des stratégies de segmentation dans le pipeline d’indexation Azure AI Search. Toutefois, vous ne pouvez pas personnaliser la segmentation avec la vectorisation intégrée présentée dans ce tutoriel.
Expérimentation avec différents modèles de requêtes dans le code de l’application.
Réglage précis de la recherche avec d’autres propriétés dans la classe AzureSearchChatExtensionParameters.
Utilisation de modèles Azure OpenAI plus spécialisés pour votre domaine spécifique.

Plus de ressources

Rétroaction

Cette page vous a-t-elle été utile ?

Last updated on 2025-11-18