Öğretici: Azure OpenAI ve Azure AI Search (Spring Boot) ile Azure App Service'te bir alma artırılmış oluşturma uygulaması oluşturma

Bu öğreticide Spring Boot, Azure OpenAI ve Azure AI Search kullanarak bir Java Alma Artırılmış Nesil (RAG) uygulaması oluşturacak ve bunu Azure App Service'e dağıtacaksınız. Bu uygulama, kendi belgelerinizden bilgi alan ve uygun alıntılarla doğru, bağlamsal olarak farkında yanıtlar sağlamak için Azure AI hizmetlerinden yararlanan bir sohbet arabiriminin nasıl uygulandığını gösterir. Çözüm, hizmetler arasında parolasız kimlik doğrulaması için yönetilen kimlikleri kullanır.

Tavsiye

Bu öğreticide Spring Boot kullanılırken, Azure OpenAI ve Azure AI Search ile RAG uygulaması oluşturmanın temel kavramları tüm Java web uygulamaları için geçerlidir. App Service'te Tomcat veya JBoss EAP gibi farklı bir barındırma seçeneği kullanıyorsanız, burada gösterilen kimlik doğrulama desenlerini ve Azure SDK kullanımını tercih ettiğiniz çerçeveye uyarlayabilirsiniz.

Bu eğitimde şunları öğreniyorsunuz:

Azure AI hizmetleriyle RAG deseni kullanan bir Spring Boot uygulaması dağıtın.
Karma arama için Azure OpenAI ve Azure AI Arama'yı yapılandırın.
Yapay zeka destekli uygulamanızda kullanmak üzere belgeleri karşıya yükleyin ve dizinleyin.
Hizmet-hizmet arası güvenli iletişim için yönetilen kimlikleri kullanın.
RAG uygulamanızı üretim hizmetleriyle yerel olarak test edin.

Mimariye genel bakış

Dağıtıma başlamadan önce, oluşturabileceğiniz uygulamanın mimarisini anlamanız yararlı olur. Aşağıdaki diyagram, Azure AI Arama için Özel RAG deseninden alınmıştır.

Bu öğreticide App Service'teki Blazer uygulaması hem uygulama UX'sini hem de uygulama sunucusunu üstlenir. Ancak Azure AI Search için ayrı bir bilgi sorgusu oluşturmaz. Bunun yerine, Azure OpenAI'ye veri kaynağı olarak Azure AI Search'i belirten bilgi sorgulamasını gerçekleştirmesini söyler. Bu mimari çeşitli temel avantajlar sunar:

Tümleşik Vektörleştirme: Azure AI Search'ün tümleşik vektörleştirme özellikleri, ekleme oluşturmak için daha fazla kod gerektirmeden arama için tüm belgelerinizi kolayca ve hızlı bir şekilde almanızı sağlar.
Basitleştirilmiş API Erişimi: Azure OpenAI tamamlamaları için veri kaynağı olarak Azure AI Search kullanan "Azure OpenAI ile Verileriniz" desenini kullanarak, karmaşık vektör araması veya gömme oluşturma işlemi gerçekleştirmeniz gerekmez. Bu yalnızca bir API çağrısıdır ve Azure OpenAI, istem mühendisliği ve sorgu iyileştirme dahil olmak üzere her şeyi işler.
Gelişmiş Arama Özellikleri: Tümleşik vektörleştirme, anahtar sözcük eşleştirme, vektör benzerliği ve yapay zeka destekli derecelendirmenin güçlü yönlerini birleştiren anlamsal yeniden boyutlandırma ile gelişmiş karma arama için gereken her şeyi sağlar.
Tam Alıntı Desteği: Yanıtlar otomatik olarak kaynak belgelere yapılan alıntıları içerir ve bu da bilgileri doğrulanabilir ve izlenebilir hale getirir.

Önkoşullar

Etkin aboneliği olan bir Azure hesabı - Ücretsiz bir hesap oluşturun.
GitHub Codespaces kullanmak için GitHub hesabı - GitHub Codespaces hakkında daha fazla bilgi edinin.

1. Codespaces ile örneği açın

Başlamanın en kolay yolu, gerekli tüm araçların önceden yüklenmiş olduğu eksiksiz bir geliştirme ortamı sağlayan GitHub Codespaces'ı kullanmaktır.

konumundaki GitHub deposuna https://github.com/Azure-Samples/app-service-rag-openai-ai-search-javagidin.
Kod düğmesini seçin, Codespaces sekmesini seçin ve Main üzerinde Kod alanı oluştur'a tıklayın.
Codespace'ınızın başlatılması için birkaç dakika bekleyin. Hazır olduğunuzda, tarayıcınızda tam olarak yapılandırılmış bir VS Code ortamı görürsünüz.

2. Örnek mimariyi dağıtın

Terminalde Azure Geliştirici CLI'sini kullanarak Azure'da oturum açın:
```
azd auth login
```
Kimlik doğrulama işlemini tamamlamak için yönergeleri izleyin.
AzD şablonuyla Azure kaynaklarını sağlayın:
```
azd provision
```

İstendiğinde aşağıdaki yanıtları verin:

Soru	Cevap
Yeni bir ortam adı girin:	Benzersiz bir ad yazın.
Kullanılacak azure aboneliğini seçin:	Aboneliği seçin.
Kullanılacak kaynak grubunu seçin:	Yeni kaynak grubu oluştur'u seçin.
Kaynak grubunun oluşturulacağı konumu seçin:	Herhangi bir bölgeyi seçin. Kaynaklar aslında Doğu ABD 2'de oluşturulur.
Yeni kaynak grubu için bir ad girin:	Enter yazın.

Dağıtımın tamamlanmasını bekleyin. Bu işlem:
- Gerekli tüm Azure kaynaklarını oluşturun.
- Uygulamayı Azure App Service'e dağıtın.
- Yönetilen kimlikleri kullanarak güvenli hizmet-hizmet kimlik doğrulamasını yapılandırın.
- Hizmetler arasında güvenli erişim için gerekli rol atamalarını ayarlayın.
Uyarı

Yönetilen kimliklerin nasıl çalıştığı hakkında daha fazla bilgi edinmek için bkz. Azure kaynakları için yönetilen kimlikler nedir? ve App Service ile yönetilen kimlikleri kullanma.
Dağıtım başarılı olduktan sonra dağıtılan uygulamanız için bir URL görürsünüz. Bu URL'yi not edin, ancak arama dizinini ayarlamaya devam etmeniz gerektiğinden bu URL'ye henüz erişemezsiniz.

3. Belgeleri karşıya yükleme ve arama dizini oluşturma

Altyapı dağıtıldığına göre, belgeleri yüklemeniz ve uygulamanın kullanacağı bir arama dizini oluşturmanız gerekir.

Azure portalında dağıtım tarafından oluşturulan depolama hesabına gidin. Ad, daha önce sağladığınız ortam adıyla başlar.
Sol gezinti menüsünden Veri depolama>Kapsayıcıları'nı seçin ve belgeler kapsayıcısını açın.
Yükle'ye tıklayarak örnek belgeleri karşıya yükleyin. Depodaki klasördeki sample-docs örnek belgeleri veya kendi PDF, Word veya metin dosyalarınızı kullanabilirsiniz.
Azure portalında Azure AI Search hizmetinize gidin.
Arama dizini oluşturma işlemini başlatmak için Verileri içeri aktar (yeni) seçeneğini belirleyin.
Verilerinize bağlanın adımında:
- Veri Kaynağı olarak Azure Blob Depolama'yı seçin.
- RAG'ı seçin.
- Depolama hesabınızı ve belgeler kapsayıcısını seçin.
- Yönetilen kimlik kullanarak kimlik doğrulaması yapın'ı seçin.
- sonrakiseçin.
Metninizi vektörleştirin adımında:
- Azure OpenAI hizmetinizi seçin.
- Ekleme modeli olarak text-embedding-ada-002 öğesini seçin. AZD şablonu bu modeli sizin için zaten dağıttı.
- Kimlik doğrulaması için Sistem tarafından atanan kimlik'i seçin.
- Ek maliyetler için onay kutusunu seçin.
- sonrakiseçin.
Tavsiye

Azure OpenAI'de Azure AI Arama ve Metin ekleme işlemlerindeki Vektör araması hakkında daha fazla bilgi edinin.
Görüntülerinizi vektörleştirin ve zenginleştirin adımında:
- Varsayılan ayarları koruyun.
- sonrakiseçin.
Gelişmiş ayarlar adımında:
- Anlam derecesini etkinleştir seçeneğinin belirlendiğinden emin olun.
- (İsteğe bağlı) Dizin oluşturma zamanlamasını seçin. Dizininizi en son dosya değişiklikleriyle düzenli aralıklarla yenilemek istiyorsanız bu yararlı olur.
- sonrakiseçin.
Gözden geçir ve oluştur adımında:
- Nesne adı ön eki değerini kopyalayın. Bu, arama dizini adınızdır.
- Dizin oluşturma işlemini başlatmak için Oluştur'u seçin.
Dizin oluşturma işleminin tamamlanmasını bekleyin. Belgelerinizin boyutuna ve sayısına bağlı olarak bu işlem birkaç dakika sürebilir.
Veri içeri aktarmayı test etmek için Aramayı başlat'ı seçin ve "Şirketiniz hakkında bilgi ver" gibi bir arama sorgusu deneyin.
Codespace terminalinize dönüp arama dizini adını AZD ortam değişkeni olarak ayarlayın:
```
azd env set SEARCH_INDEX_NAME <your-search-index-name>
```
<your-search-index-name> 'i daha önce kopyaladığınız dizin adıyla değiştirin. AZD, App Service uygulama ayarını ayarlamak için sonraki dağıtımlarda bu değişkeni kullanır.

4. Uygulamayı test edin ve dağıtın

Uygulamayı dağıtımdan önce veya sonra yerel olarak test etmek isterseniz, uygulamayı doğrudan Codespace'inizden çalıştırabilirsiniz:

Codespace terminalinizde AZD ortam değerlerini alın:
```
azd env get-values
```
src/main/resources/application.properties dosyasını açın. Terminal çıkışını kullanarak ilgili yer tutucularda <input-manually-for-local-testing>aşağıdaki değerleri güncelleştirin:
- azure.openai.endpoint
- azure.search.url
- azure.search.index.name
Azure CLI ile Azure'da oturum açın:
```
az login
```
Bu, örnek koddaki Azure Identity istemci kitaplığının oturum açmış kullanıcı için bir kimlik doğrulama belirteci almasını sağlar.
Uygulamayı yerel olarak çalıştırın:
```
mvn spring-boot:run
```
Uygulamanızın 8080 numaralı bağlantı noktasında çalıştığınıgördüğünüzde Tarayıcıda Aç'ı seçin.
Sohbet arabiriminde birkaç soru sormayı deneyin. Yanıt alırsanız uygulamanız Azure OpenAI kaynağına başarıyla bağlanıyor.
Ctrl+C ile geliştirme sunucusunu durdurun.
Azure'da yeni SEARCH_INDEX_NAME yapılandırmayı uygulayın ve örnek uygulama kodunu dağıtın:
```
azd up
```

5. Dağıtılan RAG uygulamasını test edin

Uygulama tam olarak dağıtılıp yapılandırıldığında artık RAG işlevini test edebilirsiniz:

Dağıtımın sonunda sağlanan uygulama URL'sini açın.
Karşıya yüklenen belgelerinizin içeriğiyle ilgili sorular girebileceğiniz bir sohbet arabirimi görürsünüz.
Belgelerinizin içeriğine özgü sorular sormayı deneyin. Örneğin, belgeleri sample-docs klasörüne yüklediyseniz şu soruları deneyebilirsiniz:
- Contoso kişisel verilerimi nasıl kullanır?
- Nasıl garanti talebi oluşturursunuz?
Yanıtların kaynak belgelere başvuran alıntıları nasıl içerdiğine dikkat edin. Bu alıntılar, kullanıcıların bilgilerin doğruluğunu doğrulamasına ve kaynak malzemede daha fazla ayrıntı bulmasına yardımcı olur.
Farklı arama yaklaşımlarından yararlanabilecek sorular sorarak karma arama özelliklerini test edin:
- Belirli terminolojiyle ilgili sorular (anahtar sözcük araması için iyidir).
- Farklı terimler kullanılarak açıklanabilecek kavramlar hakkındaki sorular (vektör araması için iyidir).
- Bağlamı anlamanızı gerektiren karmaşık sorular (anlamsal derecelendirme için iyidir).

Kaynakları temizle

Uygulamayla işiniz bittiğinde, daha fazla maliyet oluşmasını önlemek için tüm kaynakları silebilirsiniz:

azd down --purge

Bu komut, uygulamanızla ilişkili tüm kaynakları siler.

Sıkça sorulan sorular

Örnek kod Azure OpenAI sohbet tamamlamalarından alıntıları nasıl alır?
Bu çözümde yönetilen kimlikleri kullanmanın avantajı nedir?
Sistem tarafından atanan yönetilen kimlik bu mimaride ve örnek uygulamada nasıl kullanılır?
Örnek uygulamada semantik ranker ile karma arama nasıl uygulanır?
Tüm kaynaklar neden Doğu ABD 2'de oluşturulur?
Azure tarafından sağlanan modeller yerine kendi OpenAI modellerimi kullanabilir miyim?
Yanıtların kalitesini nasıl geliştirebilirim?

Örnek kod Azure OpenAI sohbet tamamlamalarından alıntıları nasıl alır?

Örnek, sohbet istemcisi için veri kaynağı olarak AzureSearchChatExtensionConfiguration öğesini kullanarak alıntıları alır. Sohbet tamamlaması istendiğinde, yanıt ileti bağlamında bir Citations nesne içerir. Kod bu alıntıları aşağıdaki gibi ayıklar:

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

Sohbet yanıtında, içerik rehber olarak listede karşılık gelen alıntıya referans vermek için [doc#] biçimini kullanır ve bu da kullanıcıların bilgileri orijinal kaynak belgelerine geri takip etmelerini sağlar. Daha fazla bilgi için bakınız:

Bu çözümde yönetilen kimlikleri kullanmanın avantajı nedir?

Yönetilen kimlikler, kimlik bilgilerini kodunuzda veya yapılandırmanızda depolama gereksinimini ortadan kaldırır. Uygulama, yönetilen kimlikleri kullanarak parolaları yönetmeden Azure hizmetlerine, Azure OpenAI ve Azure AI Search gibi hizmetlere güvenli bir şekilde erişebilir. Bu yaklaşım Sıfır Güven güvenlik ilkelerini izler ve kimlik bilgilerinin açığa çıkarma riskini azaltır.

Sistem tarafından atanan yönetilen kimlik bu mimaride ve örnek uygulamada nasıl kullanılır?

AZD dağıtımı Azure App Service, Azure OpenAI ve Azure AI Search için sistem tarafından atanan yönetilen kimlikler oluşturur. Ayrıca her biri için ilgili rol atamalarını yapar ( main.bicep dosyasına bakın). Gerekli rol atamaları hakkında bilgi için bkz. Verilerinizde Azure OpenAI için ağ ve erişim yapılandırması.

Örnek Java uygulamasında Azure SDK'ları güvenli kimlik doğrulaması için bu yönetilen kimliği kullanır, bu nedenle kimlik bilgilerini veya gizli dizileri herhangi bir yerde depolamanız gerekmez. Örneğin, OpenAIAsyncClient ile başlatılır DefaultAzureCredentialve Azure'da çalışırken yönetilen kimliği otomatik olarak kullanır:

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

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

Benzer şekilde, Azure AI Search için veri kaynağı yapılandırılırken yönetilen kimlik kimlik doğrulaması için belirtilir:

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

Bu kurulum, Sıfır Güven güvenliğine yönelik en iyi yöntemleri izleyerek Spring Boot uygulamanızla Azure hizmetleri arasında güvenli, parolasız iletişim sağlar. DefaultAzureCredential ve Java için Azure Identity istemci kitaplığı hakkında daha fazla bilgi edinin.

Örnek uygulamada semantik ranker ile karma arama nasıl uygulanır?

Örnek uygulama, Azure OpenAI ve Azure AI Search Java SDK'larını kullanarak karma aramayı anlam sıralamasıyla yapılandırır. Arka uçta veri kaynağı aşağıdaki gibi ayarlanır:

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");

Bu yapılandırma, uygulamanın vektör aramasını (anlamsal benzerlik), anahtar sözcük eşleştirmeyi ve anlam sıralamasını tek bir sorguda birleştirmesini sağlar. Semantik dereceleyici, sonuçları yeniden sıralayarak en uygun ve bağlamsal olarak uygun yanıtları döndürür. Bu yanıtlar daha sonra Azure OpenAI tarafından yanıt oluşturmak için kullanılır.

Anlamsal yapılandırma adı, tümleşik vektörleştirme işlemi tarafından otomatik olarak tanımlanır. Arama dizini adını ön ek olarak kullanır ve sonek olarak -semantic-configuration ekler. Bu, semantik yapılandırmanın karşılık gelen dizinle benzersiz olarak ilişkilendirilmesini sağlar ve tutarlı bir adlandırma kuralı izler.

Tüm kaynaklar neden Doğu ABD 2'de oluşturulur?

Örnekte gpt-4o-mini ve text-embedding-ada-002 modelleri kullanılmaktadır ve her ikisi de Doğu ABD 2'deki Standart dağıtım türüyle kullanılabilir. Bu modeller ayrıca, yakın zamanda emekliye ayrılmak üzere planlanmadığı için seçilir ve örnek dağıtım için istikrar sağlar. Model kullanılabilirliği ve dağıtım türleri bölgeye göre farklılık gösterebilir, bu nedenle örneğin çalışmasını sağlamak için Doğu ABD 2 seçilir. Farklı bir bölge veya model kullanmak istiyorsanız, aynı bölgede aynı dağıtım türü için kullanılabilen modelleri seçtiğinizden emin olun. Kendi modellerinizi seçerken kesintileri önlemek için hem kullanılabilirlik hem de kullanımdan kaldırma tarihlerini denetleyin.

Model kullanılabilirliği: Azure OpenAI Hizmeti modelleri
Model kullanımdan kaldırma tarihleri: Azure OpenAI Hizmeti model değişiklikleri ve emeklilikleri.

Azure tarafından sağlanan modeller yerine kendi OpenAI modellerimi kullanabilir miyim?

Bu çözüm, Azure OpenAI Hizmeti ile çalışacak şekilde tasarlanmıştır. Kodu diğer OpenAI modellerini kullanacak şekilde değiştirebilirsiniz ancak tümleşik güvenlik özelliklerini, yönetilen kimlik desteğini ve bu çözümün sağladığı Azure AI Search ile sorunsuz tümleştirmeyi kaybedersiniz.

Yanıtların kalitesini nasıl geliştirebilirim?

Yanıt kalitesini şu şekilde geliştirebilirsiniz:

Daha kaliteli, daha ilgili belgeleri yükleme.
Azure AI Search dizin oluşturma işlem hattında öbekleme stratejilerini ayarlama. Ancak, bu öğreticide gösterilen tümleşik vektörleştirme ile öbeklemesi özelleştiremezsiniz.
Uygulama kodunda farklı istem şablonlarıyla denemeler yapın.
AzureSearchChatExtensionParameters sınıfındaki diğer özelliklerle aramada ince ayarlamalar.
Belirli bir etki alanınız için daha özelleştirilmiş Azure OpenAI modelleri kullanma.

Daha fazla kaynak

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Last updated on 2025-11-18