Lernprogramm: Teil 1 – Einrichten einer Projekt- und Entwicklungsumgebung zum Erstellen einer benutzerdefinierten RAG-App (Knowledge Retrieval) mit dem Microsoft Foundry SDK

In diesem Tutorial richten Sie die Ressourcen ein, die zum Erstellen einer benutzerdefinierten RAG-Chat-App zur Wissensabfrage mit dem Microsoft Foundry SDK erforderlich sind. Dies ist Teil einer dreiteiligen Lernprogrammreihe. Sie erstellen hier die Ressourcen, erstellen die App in Teil 2 und bewerten sie in Teil 3. In diesem Teil gehen Sie folgendermaßen vor:

Wenn Sie andere Lernprogramme oder Schnellstarts abgeschlossen haben, haben Sie möglicherweise bereits einige der für dieses Lernprogramm erforderlichen Ressourcen erstellt. Wenn Sie dies getan haben, können Sie diese Schritte überspringen.

Voraussetzungen

• Ein Azure-Konto mit einem aktiven Abonnement und der Rolle Besitzer oder Mitwirkender. Erstellen Sie ein kostenloses Konto, falls Sie keines besitzen.
• Microsoft Foundry: Rolle als „Besitzer“ oder „Mitwirkender“, um ein Projekt zu erstellen.

Erstellen eines hubbasierten Projekts

Führen Sie die folgenden Schritte aus, um ein hub-basiertes Projekt in Microsoft Foundry zu erstellen:

1. Melden Sie sich bei Microsoft Foundry an. Stellen Sie sicher, dass der Umschalter "Neue Gießerei " deaktiviert ist. Diese Schritte beziehen sich auf Foundry (klassisch).

   

2. Was Sie als Nächstes tun, hängt davon ab, wo Sie sich befinden:

   • Wenn Sie noch keine Projekte haben: Führen Sie die Schritte unter Schnellstart: Erste Schritte mit Microsoft Foundry aus, um Ihr erstes Projekt zu erstellen.

   • Wenn Sie sich in einem Projekt befinden: Wählen Sie das Projekt Breadcrumb aus, und wählen Sie dann "Neue Ressource erstellen" aus.

     

   • Wenn Sie sich nicht in einem Projekt befinden: Wählen Sie oben rechts Neu erstellen aus, um ein neues Foundry-Projekt zu erstellen.

     

3. Wählen Sie die KI-Hubressource und dann "Weiter" aus.

4. Geben Sie einen Namen für das Projekt ein.

5. Wenn Sie über einen Hub verfügen, sehen Sie, dass der zuletzt verwendete Hub ausgewählt ist.

   • Wenn Sie Zugriff auf mehrere Hubs haben, können Sie in der Dropdownliste einen anderen Hub auswählen.

   • Wenn Sie ein neues Erstellen möchten, wählen Sie im Dropdownmenü " Neuen Hub erstellen " aus.

     

6. Wenn Sie keinen Hub haben, wird ein Standardhub für Sie erstellt.

7. Wählen Sie "Erstellen" aus.

Bereitstellen von Modellen

Sie benötigen zwei Modelle zum Erstellen einer RAG-basierten Chat-App: ein Azure OpenAI-Chatmodell (gpt-4o-mini) und ein Azure OpenAI-Einbettungsmodell (text-embedding-ada-002). Stellen Sie diese Modelle in Ihrem Foundry-Projekt mithilfe dieser Schritte für jedes Modell bereit.

Mit diesen Schritten wird ein Modell auf einem Echtzeitendpunkt aus dem Modellkatalog im Foundry-Portal bereitgestellt:

1. Wählen Sie im linken Bereich den Modellkatalog aus.

2. Wählen Sie das Modell gpt-4o-mini aus der Liste der Modelle aus. Sie können dazu die Suchleiste verwenden.

   

3. Wählen Sie auf der Seite mit den Modelldetails die Option "Dieses Modell verwenden" aus.

4. Behalten Sie den standardmäßig eingestellten Bereitstellungsnamen bei, und wählen Sie Bereitstellen aus. Wenn das Modell in Ihrer Region nicht verfügbar ist, wird für Sie eine andere Region ausgewählt und mit Ihrem Projekt verbunden. Wählen Sie in diesem Fall Verbinden und Bereitstellen aus.

Wiederholen Sie nach der Bereitstellung des Modells gpt-4o-mini die Schritte, um das Modell text-embedding-ada-002 bereitzustellen.

Erstellen eines Azure KI-Suche-Diensts

Ziel dieser Anwendung ist es, die Antworten des Modells in Ihren benutzerdefinierten Daten zu verankern. Der Suchindex ruft relevante Dokumente basierend auf der Frage des Benutzers ab.

Sie benötigen einen Azure AI Search-Dienst und eine Verbindung, um einen Suchindex zu erstellen.

Wenn Sie bereits über einen Azure AI Search-Dienst verfügen, wechseln Sie zum nächsten Abschnitt.

Erstellen Sie andernfalls einen Azure AI Search-Dienst mithilfe des Azure-Portals.

1. Erstellen Sie einen Azure KI-Suche-Dienst im Azure-Portal.
2. Wählen Sie Ihre Ressourcengruppe und Instanzdetails aus. Überprüfen Sie die Preise und Preisstufen auf dieser Seite. Verwenden Sie für dieses Lernprogramm ein Preisniveau von Basic oder höher.
3. Durchlaufen Sie den Assistenten, und wählen Sie Überprüfen + zuweisen aus, um die Ressource zu erstellen.
4. Bestätigen Sie die Details Ihres Azure AI Search-Diensts, einschließlich der geschätzten Kosten.
5. Wählen Sie Erstellen aus, um den Azure KI-Suche-Dienst zu erstellen.

Verbinden der Azure KI-Suche mit Ihrem Projekt

Wenn Ihr Projekt bereits über eine Azure AI Search-Verbindung verfügt, wechseln Sie zu "Installieren der Azure CLI" und melden Sie sich an.

Suchen Sie im Foundry-Portal nach einer mit Azure AI Search verbundenen Ressource.

1. Wechseln Sie in Foundry zu Ihrem Projekt, und wählen Sie im linken Bereich das Verwaltungscenter aus.

2. Überprüfen Sie im Abschnitt Verbundene Ressourcen, ob bei Ihnen eine Verbindung vom Typ Azure KI-Suche vorhanden ist.

3. Wenn Sie über eine Azure AI Search-Verbindung verfügen, können Sie die nächsten Schritte überspringen.

4. Wählen Sie andernfalls Neue Verbindung > Azure KI-Suche aus.

5. Suchen Sie in den Optionen nach Ihrem Azure KI-Suche-Dienst, und wählen Sie Verbindung hinzufügen aus.

6. Verwenden Sie API-Schlüssel für Authentifizierung.

   Von großer Bedeutung

   Die API-Schlüsseloption wird für die Produktion nicht empfohlen. Der empfohlene Ansatz ist die Microsoft Entra-ID-Authentifizierung , die die Rollen " Indexdatenmitwirkender " und " Mitwirkender des Suchdiensts " erfordert (in den Voraussetzungen konfiguriert). Weitere Informationen finden Sie unter Herstellen einer Verbindung mit Azure KI-Suche mithilfe von Rollen. Für dieses Tutorial ist API-Schlüssel akzeptabel, wenn Sie schnell vorankommen möchten. Wechseln Sie vor der Bereitstellung im Produktivbetrieb zur Entra-ID.

7. Wählen Sie Verbindung hinzufügen aus.

Erstellen einer neuen Python-Umgebung

Erstellen Sie in der IDE Ihrer Wahl einen neuen Ordner für Ihr Projekt. Öffnen Sie ein Terminalfenster in diesem Ordner.

Erstellen Sie zunächst eine neue Python-Umgebung. Installieren Sie keine Pakete in Ihrer globalen Python-Installation. Verwenden Sie beim Installieren von Python-Paketen immer eine virtuelle oder conda-Umgebung. Andernfalls können Sie Ihre globale Installation von Python unterbrechen.

Installieren Sie bei Bedarf Python.

Verwenden Sie Python 3.10 oder höher, aber mindestens Python 3.9 ist erforderlich. Wenn Sie keine geeignete Version von Python installiert haben, befolgen Sie die Anweisungen im VS Code Python-Lernprogramm , um Python am einfachsten auf Ihrem Betriebssystem zu installieren.

Erstellen einer virtuellen Umgebung

Wenn Sie Python 3.10 oder höher bereits installiert haben, erstellen Sie mithilfe der folgenden Befehle eine virtuelle Umgebung:

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

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

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

Wenn Sie die Python-Umgebung aktivieren, verwendet die Ausführung python oder pip über die Befehlszeile den Python-Interpreter im .venv Ordner Ihrer Anwendung.

Pakete installieren

Installieren Sie die erforderlichen Pakete.

1. Erstellen Sie eine Datei mit dem Namen requirements.txt in Ihrem Projektordner. Fügen Sie der Datei die folgenden Pakete hinzu:

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

   Referenzen: Azure AI Projects-Clientbibliothek, azure-ai-inference, python-dotenv.

2. Installieren Sie die erforderlichen Pakete:

   pip install -r requirements.txt
   

Überprüfen Des Setups

Überprüfen Sie, ob Ihre Umgebung ordnungsgemäß eingerichtet ist, indem Sie einen Schnelltest ausführen:

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

# This will fail if credentials aren't set up, confirming auth is working
client = AIProjectClient.from_config(credential=DefaultAzureCredential())
print("Setup successful! You're ready to build your RAG app.")

Wenn Sie sehen "Setup successful!", sind Ihre Azure-Anmeldeinformationen und Ihr SDK ordnungsgemäß konfiguriert.

Verweise: Clientbibliothek für Azure AI-Projekte, DefaultAzureCredential.

Erstellen eines Hilfsskripts

Erstellen Sie einen Ordner für Ihre Arbeit. Erstellen Sie eine Datei mit dem Namen config.py in diesem Ordner. Sie verwenden dieses Hilfsskript in den nächsten zwei Teilen der Lernprogrammreihe. Das Skript lädt Ihre Umgebungsvariablen und initialisiert den Azure AI Projects-Client. Fügen Sie den folgenden Code hinzu:

# 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)

Verweise: AIProjectClient, DefaultAzureCredential, load_dotenv.

Umgebungsvariablen konfigurieren

Ihre Projektverbindungszeichenfolge ist erforderlich, um Azure OpenAI in Microsoft Foundry Models aus Ihrem Code aufzurufen. In dieser Schnellstartanleitung speichern Sie diesen Wert in einer .env-Datei, bei der es sich um eine Datei handelt, die Umgebungsvariablen enthält, die Ihre Anwendung lesen kann.

Erstellen Sie eine .env-Datei, und fügen Sie den folgenden Code ein:

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"

• Suchen Sie ihre Verbindungszeichenfolge im Foundry-Projekt, das Sie im Schnellstart des Foundry-Playgrounds erstellt haben. Öffnen Sie das Projekt, und suchen Sie dann die Verbindungszeichenfolge auf der Seite Übersicht. Kopieren Sie die Verbindungszeichenfolge, und fügen Sie sie in die Datei .env ein.

  

• Wenn Sie noch keinen Suchindex haben, behalten Sie den Wert „example-index“ für AISEARCH_INDEX_NAME bei. In Teil 2 dieses Tutorials erstellen Sie den Index mit diesem Namen. Wenn Sie bereits einen Suchindex erstellt haben, den Sie stattdessen verwenden möchten, aktualisieren Sie den Wert so, dass er dem Namen dieses Suchindex entspricht.

• Wenn Sie die Namen der Modelle bei der Bereitstellung geändert haben, aktualisieren Sie die Werte in der Datei .env so, dass sie den verwendeten Namen entsprechen.

Installieren der Azure CLI und Anmelden

Installieren Sie die Azure-Befehlszeilenschnittstelle und die Anmeldung über Ihre lokale Entwicklungsumgebung, damit Sie Ihre Benutzeranmeldeinformationen verwenden können, um Azure OpenAI in Microsoft Foundry Models aufzurufen.

In den meisten Fällen können Sie Azure CLI über Ihr Terminal mit dem folgenden Befehl installieren:

winget install -e --id Microsoft.AzureCLI

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

brew update && brew install azure-cli

Sie können die Anleitung unter Wie man die Azure CLI installiert befolgen, wenn diese Befehle für Ihr Betriebssystem oder Setup nicht funktionieren.

Melden Sie sich nach der Installation der Azure-Befehlszeilenschnittstelle zuerst mit dem Befehl az login an und anschließend über den Browser:

az login

Alternativ können Sie sich manuell über den Browser mit einem Gerätecode anmelden.

az login --use-device-code

Lassen Sie dieses Terminalfenster geöffnet, um Ihre Python-Skripts auch von hier aus auszuführen, nachdem Sie sich angemeldet haben.

Bereinigen von Ressourcen

Um unnötige Azure-Kosten zu vermeiden, löschen Sie die in diesem Lernprogramm erstellten Ressourcen, wenn sie nicht mehr benötigt werden. Zum Verwalten von Ressourcen können Sie das Azure-Portal verwenden.

Löschen Sie sie aber noch nicht, wenn Sie eine Chat-App im nächsten Teil dieser Lernprogrammreihe erstellen möchten.

Nächster Schritt

In diesem Tutorial richten Sie alles ein, was Sie zum Erstellen einer benutzerdefinierten Chat-App mit dem Azure KI SDK benötigen. Im nächsten Teil dieser Tutorialreihe erstellen Sie die benutzerdefinierte App.