Aracılığıyla paylaş

Öğretici: Azure OpenAI ve Azure AI Search (Spring Boot) ile Azure App Service'de bilgi alma destekli üretim uygulaması oluştur

Bu öğreticide, Spring Boot, Azure OpenAI ve Azure AI Search kullanarak bir Java Retrieval Augmented Generation (RAG) uygulaması oluşturacak ve Azure App Service'e dağıtacaksınız. Bu uygulama, kendi belgelerinizden bilgi alan ve Azure yapay zeka hizmetlerinden yararlanarak, doğru ve uygun alıntılarla bağlamı anlayan yanıtlar sağlayan 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ına uygulanır. 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.

Girişte Spring Boot sohbet arabirimini gösteren ekran görüntüsü.

Bu eğitimde şunları öğreniyorsunuz:

  • Azure'da yapay zeka hizmetleriyle RAG deseni kullanan bir Spring Boot uygulaması dağıtın.
  • Karma arama için Azure OpenAI ve Azure AI Search 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 Search için Özel RAG düzeninden alınmıştır:

Azure OpenAI ve Azure AI Search'e bağlanan bir web uygulamasının ve veri kaynağı olarak Depolama'nın kullanıldığı mimari diyagramı gösteren

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 yapmaz. Bunun yerine, Azure OpenAI'ye veri kaynağı olarak Azure AI Search belirten bilgi sorgulamasını gerçekleştirmesini söyler. Bu mimari çeşitli temel avantajlar sunar:

  • Integrated Vectorization: Azure AI Search 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.
  • Simplified API Access: Azure OpenAI On Your Data desenini kullanarak Azure OpenAI tamamlamaları için veri kaynağı olarak Azure AI Search kullanarak karmaşık vektör araması veya ekleme oluşturma işlemi gerçekleştirmeniz gerekmez. Bu yalnızca bir API çağrısıdır ve OpenAI Azure 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

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.

  1. https://github.com/Azure-Samples/app-service-rag-openai-ai-search-java konumundaki GitHub deposuna gidin.

  2. Kod düğmesini seçin, Codespaces sekmesini seçin ve Main üzerinde Kod alanı oluştur'a tıklayın.

  3. 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

  1. Terminalde, Azure Geliştirici CLI'sını kullanarak Azure oturum açın:

    azd auth login

    Kimlik doğrulama işlemini tamamlamak için yönergeleri izleyin.

  2. AZD şablonuyla Azure kaynaklarını sağlayın:

    azd provision

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

    Soru Cevap
    Yeni bir ortam adı girin: Benzersiz bir ad yazın.
    Kullanılacak bir Azure Aboneliği 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.

  4. Dağıtımın tamamlanmasını bekleyin. Bu işlem:

    • Tüm gerekli Azure kaynaklarını oluşturun.
    • Uygulamayı Azure App Service 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.

  5. 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.

  1. 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.

  2. Sol gezinti menüsünden Veri depolama>Kapsayıcıları'nı seçin ve belgeler kapsayıcısını açın.

  3. Yükle'ye tıklayarak örnek belgeleri karşıya yükleyin. Örnek belgeleri depodaki sample-docs klasöründen veya kendi PDF, Word veya metin dosyalarınızdan kullanabilirsiniz.

    Belgelerin depolama kapsayıcısına nasıl yüklendiğini gösteren ekran görüntüsü.

  4. Azure portalında Azure AI Search hizmetinize gidin.

  5. Arama dizini oluşturma işlemini başlatmak için Verileri içeri aktar (yeni) seçeneğini belirleyin.

    Azure AI Search'te Verileri İçeri Aktar ve Vektörleştir düğmesini gösteren ekran görüntüsü.

  6. Verilerinize bağlanın adımında:

    • Veri Kaynağı olarak Azure Blob Storage 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.

  7. 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 AI Search'te Vektör araması ve Azure OpenAI'de Metin gömme hakkında daha fazla bilgi edinin.

  8. Görüntülerinizi vektörleştirin ve zenginleştirin adımında:

    • Varsayılan ayarları koruyun.
    • sonrakiseçin.

  9. 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.

  10. 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.

  11. Dizin oluşturma işleminin tamamlanmasını bekleyin. Belgelerinizin boyutuna ve sayısına bağlı olarak bu işlem birkaç dakika sürebilir.

  12. Veri içeri aktarmayı test etmek için Aramayı başlat'ı seçin ve "Şirketiniz hakkında bilgi ver" gibi bir arama sorgusu deneyin.

  13. 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:

  1. Codespace terminalinizde AZD ortam değerlerini alın:

    azd env get-values

  2. 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

  3. Azure CLI ile Azure 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ına olanak tanır.

  4. Uygulamayı yerel olarak çalıştırın:

    mvn spring-boot:run

  5. Uygulamanızın 8080 numaralı bağlantı noktasında çalıştığınıgördüğünüzde Tarayıcıda Aç'ı seçin.

  6. Sohbet arabiriminde birkaç soru sormayı deneyin. Yanıt alırsanız uygulamanız Azure OpenAI kaynağına başarıyla bağlanıyor.

  7. Ctrl+C ile geliştirme sunucusunu durdurun.

  8. yeni SEARCH_INDEX_NAME yapılandırmasını Azure 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:

  1. Dağıtımın sonunda sağlanan uygulama URL'sini açın.

  2. Karşıya yüklenen belgelerinizin içeriğiyle ilgili sorular girebileceğiniz bir sohbet arabirimi görürsünüz.

    Blazor sohbet arabirimini gösteren ekran görüntüsü.

  3. 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?

  4. 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.

    Kaynak belgelere alıntılar içeren yanıtı gösteren ekran görüntüsü.

  5. 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?

Ö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 gizli bilgileri yönetmeden Azure OpenAI ve Azure AI Search gibi Azure hizmetleriyle güvenli bir şekilde erişebilir. Bu yaklaşım Zero Trust 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 daha fazla bilgi için bkz. Azure Verilerinizde OpenAI için ağ ve erişim yapılandırması.

Örnek Java uygulamasında, Azure SDKs 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, OpenAIAsyncClientDefaultAzureCredential ile başlatılır ve bu da Azure çalışırken otomatik olarak yönetilen kimliği 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, Spring Boot uygulamanızla Azure hizmetleri arasında güvenli, parolasız iletişim sağlar ve Zero Trust güvenlik için en iyi yöntemleri izler. Java için DefaultAzureCredential ve 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ı semantik derecelendirmeyle 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 ve 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.

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

Bu çözüm, Azure OpenAI Service 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 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 öbek oluşturma 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 özel Azure OpenAI modelleri kullanma.

Daha fazla kaynak

  • Last updated on