Öğretici: 1. Bölüm - Microsoft Döküm SDK'sı (klasik) ile özel bilgi alma (RAG) uygulaması oluşturmak için proje ve geliştirme ortamını ayarlama

Yalnızca şunlar için geçerlidir:Dökümhane (klasik) portalı. Bu makale yeni Dökümhane portalında kullanılamaz. Yeni portal hakkında daha fazla bilgi edinin.

Uyarı

Bu makaledeki bağlantılar, şu anda görüntülediğiniz Dökümhane (klasik) belgeleri yerine yeni Microsoft Foundry belgelerinde içerik açabilir.

Bu öğreticide, Microsoft Foundry SDK'sı ile özel bilgi alma (RAG) sohbet uygulaması oluşturmak için gereken kaynakları ayarlarsınız. Bu, üç bölümden oluşan bir öğretici serisinin birinci bölümüdür. Kaynakları burada oluşturacak, uygulamayı ikinci bölümde derleyip üçüncü bölümde değerlendirebilirsiniz. Bu bölümde şunları yaparsınız:

• Proje oluştur
• Azure Yapay Zeka Arama dizini oluşturma
• Azure CLI yükleme ve oturum açma
• Python ve paketleri yükleme
• Modelleri projenize dağıtma
• Ortam değişkenlerinizi yapılandırma

Diğer öğreticileri veya hızlı başlangıçları tamamladıysanız, bu öğretici için gereken kaynaklardan bazılarını zaten oluşturmuş olabilirsiniz. Bunu yaptıysanız, bu adımları atlayabilirsiniz.

Önkoşullar

Önemli

Bu makale, merkez tabanlı projeler için eski sistem desteği sağlar. Foundry projeleri için işe yaramaz. Bkz. Ne tür bir projem olduğunu nasıl bilebilirim?

SDK uyumluluk notu: Kod örnekleri için belirli bir Microsoft Döküm SDK'sı sürümü gerekir. Uyumluluk sorunlarıyla karşılaşırsanız hub tabanlı bir projeden Foundry projesine geçiş yapmayı göz önünde bulundurun.

• Etkin aboneliği olan ve Owner veya Contributor rolü atanmış bir Azure hesabı. Hesabınız yoksa ücretsiz bir hesap oluşturun.
• Microsoft Foundry: Bir proje oluşturmak için Sahip veya Katkıda Bulunan rolü.

Merkez tabanlı proje oluşturma

Microsoft Foundry içinde hub tabanlı proje oluşturmak için şu adımları izleyin:

1. Microsoft Foundry'da oturum açın. Yeni Dökümhane açma/kapama düğmesinin kapalı olduğundan emin olun. Bu adımlar Foundry (klasik) için geçerlidir.

   

2. Bundan sonra yapmanız gerekenler, nerede olduğunuzla bağlıdır:

   • Projede değilseniz veya henüz hiç projeniz yoksa: Yeni bir Dökümhane projesi oluşturmak için sağ üstteki Yeni oluştur'u seçin

     

   • Bir projedeyseniz: Proje içerik haritasını seçin ve ardından Yeni kaynak oluştur'u seçin.

     

3. AI hub kaynağı'nı seçin, ardından Sonraki'yi seçin.

4. Proje için bir ad girin.

5. Hub'larınız varsa en son kullandığınız hub'ın seçili olduğunu görürsünüz.

   • Birden fazla hub'a erişiminiz varsa açılan listeden farklı bir hub seçebilirsiniz.

   • Yeni bir tane oluşturmak istiyorsanız açılan listeden Yeni hub oluştur'u seçin.

     

6. Hub'larınız yoksa sizin için varsayılan bir hub oluşturulur.

7. Oluştur'i seçin.

Modelleri dağıtmak

RAG tabanlı sohbet uygulaması oluşturmak için iki modele ihtiyacınız vardır: Azure OpenAI sohbet modeli (gpt-4o-mini) ve Azure OpenAI ekleme modeli (text-embedding-ada-002). Her model için bu adım kümesini kullanarak bu modelleri Foundry projenizde dağıtın.

Bu adımlar, Foundry portalı model kataloğundan bir modeli gerçek zamanlı bir uç noktaya dağıtır:

Tavsiye

Microsoft Foundry portalında sol bölmeyi customize edebileceğinizden, bu adımlarda gösterilenden farklı öğeler görebilirsiniz. Aradığınızı görmüyorsanız ... seçeneğini belirleyin. Sol bölmenin en altında daha fazlası.

1. Sol bölmede Model kataloğu'nu seçin.

2. Model listesinden gpt-4o-mini modelini seçin. Arama çubuğunu kullanarak bulabilirsiniz.

   

3. Model ayrıntıları sayfasında Bu modeli kullan'ı seçin.

4. Varsayılan Dağıtım adını bırakın ve Dağıt'ı seçin. Veya model bölgenizde kullanılamıyorsa, sizin için farklı bir bölge seçilir ve projenize bağlanır. Bu durumda Bağlan ve dağıt'ı seçin.

gpt-4o-mini'yi dağıttıktan sonra text-embedding-ada-002 modelini dağıtmak için adımları yineleyin.

Azure Yapay Zeka Arama hizmeti oluşturma

Bu uygulamanın amacı, özel verilerinizdeki model yanıtlarını temel almaktır. Arama dizini, kullanıcının sorusuna göre ilgili belgeleri alır.

Arama dizini oluşturmak için bir Azure Yapay Zeka Arama hizmetine ve bağlantısına ihtiyacınız vardır.

Uyarı

Azure Yapay Zeka Arama hizmeti ve sonraki arama dizinlerinin oluşturulması maliyete neden olur. Kaynağı oluşturmadan önce maliyeti onaylamak için oluşturma sayfasındaki Azure Yapay Zeka Arama hizmetinin fiyatlandırma ve fiyatlandırma katmanlarını denetleyin. Bu öğretici için Temel veya daha yüksek bir fiyatlandırma katmanı kullanın.

Zaten bir Azure Yapay Zeka Arama hizmetiniz varsa sonraki bölüme gidin.

Aksi takdirde, Azure portalını kullanarak bir Azure Yapay Zeka Arama hizmeti oluşturun.

Tavsiye

Bu adım, bu öğretici serisinde Azure portalını kullandığınız tek adımdır. Çalışmanızın geri kalanını Dökümhane portalında veya yerel geliştirme ortamınızda yaparsınız.

1. Azure portalında Azure Yapay Zeka Arama hizmeti oluşturun.
2. Kaynak grubunuzu ve örnek ayrıntılarınızı seçin. Bu sayfadaki fiyatlandırma ve fiyatlandırma seviyelerini denetleyin. Bu öğretici için Temel veya daha yüksek bir fiyatlandırma katmanı kullanın.
3. Sihirbaz aracılığıyla devam edin ve gözden geçir + ata'yı seçerek kaynağı oluşturun.
4. Tahmini maliyet dahil olmak üzere Azure Yapay Zeka Arama hizmetinizin ayrıntılarını onaylayın.
5. Azure Yapay Zeka Arama hizmetini oluşturmak için Create öğesini seçin.

Azure Yapay Zeka Arama projenize bağlama

Projenizin zaten bir Azure Yapay Zeka Arama bağlantısı varsa Azure CLI yükleyin ve oturum açın.

Foundry portalında Azure Yapay Zeka Arama bağlı kaynağı kontrol edin.

1. Foundry'de projenize gidin ve sol bölmeden Yönetim merkezi'ni seçin.

2. Bağlantılı kaynaklar bölümünde Azure Yapay Zeka Arama türünde bir bağlantınız olup olmadığını denetleyin.

3. Azure Yapay Zeka Arama bağlantınız varsa sonraki adımları atlayabilirsiniz.

4. Aksi takdirde, Yeni bağlantı öğesini seçin ve ardından Azure Yapay Zeka Arama.

5. Seçeneklerden Azure Yapay Zeka Arama hizmetinizi bulun ve Bağlantı ekle'ı seçin.

6. Kimlik Doğrulaması için API anahtarı kullanın.

   Önemli

   Api anahtarı seçeneği üretim için önerilmez. Önerilen yaklaşım Microsoft Entra ID kimlik doğrulamasıdır ve bu kimlik doğrulaması için Search Index Data Contributor ve Search Service Contributor rolleri gerekir (Önkoşullar bölümünde yapılandırılır). Daha fazla bilgi için bkz. Roller kullanarak Azure Yapay Zeka Arama'e bağlanma. Bu öğreticide, hızlı bir şekilde devam etmek istiyorsanız API anahtarı kabul edilebilir. Üretime geçmeden önce Entra ID'ye geçiş yapın.

7. Bağlantı ekle'yi seçin.

Yeni bir Python ortamı oluşturma

Seçtiğiniz IDE'de projeniz için yeni bir klasör oluşturun. Bu klasörde bir terminal penceresi açın.

İlk olarak yeni bir Python ortamı oluşturun. Paketleri genel Python yüklemenize yüklemeyin. Python paketleri yüklerken her zaman bir sanal veya conda ortamı kullanın. Aksi takdirde, Python genel yüklemenizi bozabilirsiniz.

Gerekirse Python yükleyin

Python 3.10 veya üzerini kullanın, ancak en az Python 3.9 gereklidir. Python'in uygun bir sürümü yüklü değilse, işletim sisteminize Python yüklemenin en kolay yolu için VS Code Python Öğreticisi yönergeleri izleyin.

Sanal ortam oluşturma

Zaten Python 3.10 veya üzeri yüklüyse, aşağıdaki komutları kullanarak bir sanal ortam oluşturun:

Windows

py -3 -m venv .venv
.venv\scripts\activate

Linux

python3 -m venv .venv
source .venv/bin/activate

macOS

python3 -m venv .venv
source .venv/bin/activate

Python ortamını etkinleştirdiğinizde, komut satırından python veya pip çalıştırmak, uygulamanızın .venv klasöründeki Python yorumlayıcısını kullanır.

Uyarı

Python sanal ortamından çıkmak için deactivate komutunu kullanın. Daha sonra gerektiğinde yeniden etkinleştirebilirsiniz.

Paketleri yükleme

Gerekli paketleri yükleyin.

1. Proje klasörünüzde requirements.txt adlı bir dosya oluşturun. Dosyaya aşağıdaki paketleri ekleyin:

   azure-ai-projects==1.0.0b10
   azure-ai-inference[prompts]
   azure-identity
   azure-search-documents
   pandas
   python-dotenv
   opentelemetry-api
   

   Referanslar: Azure AI Projects istemci kitaplığı, azure-ai-inference, python-dotenv.

2. Gerekli paketleri yükleyin:

   pip install -r requirements.txt
   

Ortam değişkenlerini yapılandırma

Azure OpenAI'yi Microsoft Foundry Modellerinde kodunuzdan çağırmak için proje bağlantı dizesi gereklidir. Bu hızlı başlangıçta, bu değeri .env uygulamanızın okuyabileceği ortam değişkenlerini içeren bir dosyaya kaydedersiniz.

Bir .env dosya oluşturun ve aşağıdaki kodu yapıştırın:

AIPROJECT_CONNECTION_STRING=<your-connection-string>
AISEARCH_INDEX_NAME="example-index"
EMBEDDINGS_MODEL="text-embedding-ada-002"
INTENT_MAPPING_MODEL="gpt-4o-mini"
CHAT_MODEL="gpt-4o-mini"
EVALUATION_MODEL="gpt-4o-mini"

• Foundry oyun alanı hızlı başlangıç kılavuzu içinde oluşturduğunuz Foundry projesinde bağlantı dizesini bulun. Projeyi açın, ardından Overview sayfasında bağlantı dizesi bulun. bağlantı dizesi kopyalayın ve .env dosyasına yapıştırın.

  

• Henüz bir arama dizininiz yoksa, AISEARCH_INDEX_NAME için "example-index" değerini koruyun. Bu öğreticinin 2. Bölümünde bu adı kullanarak dizini oluşturacaksınız. Bunun yerine kullanmak istediğiniz bir arama dizini oluşturduysanız, değeri bu arama dizininin adıyla eşleşecek şekilde güncelleştirin.

• Dağıttığınızda modellerin adlarını değiştirdiyseniz, dosyadaki .env değerleri kullandığınız adlarla eşleşecek şekilde güncelleştirin.

Tavsiye

VS Code'da çalışıyorsanız, değişiklikleri .env dosyaya kaydettikten sonra terminal penceresini kapatıp yeniden açın.

Uyarı

.env öğesinin .gitignore dosyanızda bulunduğundan emin olun, böylece yanlışlıkla git deponuza göndermemiş olursunuz.

Azure CLI yükleme ve oturum açma

Azure CLI yükler ve kodunuzun Foundry aracılığıyla Azure hizmetleri çağırmak için kullanıcı kimlik bilgilerinizi kullanabilmesi için yerel geliştirme ortamınızdan oturum açarsınız.

Çoğu durumda, aşağıdaki komutu kullanarak terminalinizden Azure CLI yükleyebilirsiniz:

Windows

winget install -e --id Microsoft.AzureCLI

Linux

curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash

macOS

brew update && brew install azure-cli

> bu komutlar belirli bir işletim sisteminiz veya kurulumunuz için çalışmıyorsa Azure CLI

Azure CLI yükledikten sonra az login komutunu kullanarak oturum açın ve tarayıcıyı kullanarak oturum açın:

az login

Alternatif olarak, tarayıcı üzerinden bir cihaz koduyla el ile oturum açabilirsiniz.

az login --use-device-code

Oturum açtığınıza göre python betiklerinizi buradan da çalıştırmak için bu terminal penceresini açık tutun.

Kurulumunuzu doğrulama

Hızlı bir test çalıştırarak ortamınızın doğru ayarlandığını doğrulayın:

import os
from azure.identity import DefaultAzureCredential
import azure.ai.projects

# Check the SDK version
print(f"Azure AI Projects SDK version: {azure.ai.projects.__version__}")

# Test that you can connect to your project
project = AIProjectClient.from_connection_string(
    conn_str=os.environ["AIPROJECT_CONNECTION_STRING"], credential=DefaultAzureCredential()
)
print("✓ Setup verified! Ready to build your RAG app.")

"Setup successful!" görürseniz, Azure kimlik bilgileriniz ve SDK'nız doğru yapılandırılır.

Tavsiye

Bu öğretici için Azure AI Projects SDK sürümü 1.0.0b10 gerekmektedir. Yukarıda görüntülenen SDK sürümü uyumluluğu doğrulamanıza yardımcı olur. Farklı bir sürümünüz varsa yöntemi from_connection_string() kullanılamayabilir. Gerekli sürümü yüklemek için komutunu çalıştırın pip install azure-ai-projects==1.0.0b10.

Başvurular: Azure AI Projeleri istemci kitaplığı, DefaultAzureCredential.

Yardımcı betik oluşturma

Çalışmanız için bir klasör oluşturun. Bu klasörde config.py adlı bir dosya oluşturun. Öğretici serisinin sonraki iki bölümünde bu yardımcı betiği kullanacaksınız. Betik, ortam değişkenlerinizi yükler ve Azure AI Projeleri istemcisini başlatır. Aşağıdaki kodu ekleyin:

# ruff: noqa: ANN201, ANN001

import os
import sys
import pathlib
import logging
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.inference.tracing import AIInferenceInstrumentor

# load environment variables from the .env file
from dotenv import load_dotenv

load_dotenv()

# Set "./assets" as the path where assets are stored, resolving the absolute path:
ASSET_PATH = pathlib.Path(__file__).parent.resolve() / "assets"

# Configure an root app logger that prints info level logs to stdout
logger = logging.getLogger("app")
logger.setLevel(logging.INFO)
logger.addHandler(logging.StreamHandler(stream=sys.stdout))


# Returns a module-specific logger, inheriting from the root app logger
def get_logger(module_name):
    return logging.getLogger(f"app.{module_name}")


# Enable instrumentation and logging of telemetry to the project
def enable_telemetry(log_to_project: bool = False):
    AIInferenceInstrumentor().instrument()

    # enable logging message contents
    os.environ["AZURE_TRACING_GEN_AI_CONTENT_RECORDING_ENABLED"] = "true"

    if log_to_project:
        from azure.monitor.opentelemetry import configure_azure_monitor

        project = AIProjectClient.from_connection_string(
            conn_str=os.environ["AIPROJECT_CONNECTION_STRING"], credential=DefaultAzureCredential()
        )
        tracing_link = f"https://ai.azure.com/tracing?wsid=/subscriptions/{project.scope['subscription_id']}/resourceGroups/{project.scope['resource_group_name']}/providers/Microsoft.MachineLearningServices/workspaces/{project.scope['project_name']}"
        application_insights_connection_string = project.telemetry.get_connection_string()
        if not application_insights_connection_string:
            logger.warning(
                "No application insights configured, telemetry will not be logged to project. Add application insights at:"
            )
            logger.warning(tracing_link)

            return

        configure_azure_monitor(connection_string=application_insights_connection_string)
        logger.info("Enabled telemetry logging to project, view traces at:")
        logger.info(tracing_link)

Başvurular: AIProjectClient, DefaultAzureCredential, load_dotenv.

Uyarı

Bu betik, henüz azure.monitor.opentelemetryyüklemediğiniz bir paketi de kullanır. Öğretici serisinin sonraki bölümünde bu paketi yükleyeceksiniz.

Kaynakları temizle

Gereksiz Azure maliyetlerle karşılaşmamak için, artık gerekli değilse bu öğreticide oluşturduğunuz kaynakları silin. Kaynakları yönetmek için Azure portal kullanabilirsiniz.

Ancak bu öğretici serisinin sonraki bölümünde bir sohbet uygulaması oluşturmak istiyorsanız bunları henüz silmeyin.

Sonraki adım

Bu öğreticide, Azure AI SDK'sı ile özel bir sohbet uygulaması oluşturmak için ihtiyacınız olan her şeyi ayarlarsınız. Bu öğretici serisinin sonraki bölümünde özel uygulamayı oluşturacaksınız.

Part 2: Azure AI SDK