Tutorial: Teil 1 – Einrichten einer Projekt- und Entwicklungsumgebung zum Erstellen einer benutzerdefinierten Wissensabruf-App (RAG) mit dem Azure KI Foundry SDK

2025-06-27

In diesem Lernprogramm verwenden Sie das Azure AI Foundry SDK (und andere Bibliotheken), um eine Chat-App für Ihr Einzelhandelsunternehmen namens Contoso Trek zu erstellen, zu konfigurieren und auszuwerten. Ihr Einzelhandelsunternehmen ist auf Campingausrüstung und Outdoorkleidung spezialisiert. Die Chat-App soll Fragen zu Ihren Produkten und Diensten beantworten. Beispielsweise kann die Chat-App Fragen wie „Welches Zelt ist am wasserdichtesten?“ oder „Was ist der beste Schlafsack für kaltes Wetter?“ beantworten.

Dieses Tutorial ist der erste Teil eines dreiteiligen Tutorials. In diesem Teil 1 werden Sie darauf vorbereitet, Code in Teil 2 zu schreiben und Ihre Chat-App in Teil 3 auszuwerten. In diesem Teil gehen Sie folgendermaßen vor:

Erstellen eines Projekts
Erstellen eines Azure KI-Suchindex
Installieren der Azure CLI und Anmelden
Installieren von Python und Paketen
Stellen Sie Modelle in Ihrem Projekt bereit
Konfigurieren von Umgebungsvariablen

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 hier überspringen.

Dieses Tutorial ist der erste Teil eines dreiteiligen Tutorials.

Voraussetzungen

Hinweis

In diesem Lernprogramm wird ein hubbasiertes Projekt verwendet. Die hier gezeigten Schritte und Code funktionieren nicht für ein Foundry-Projekt. Weitere Informationen finden Sie unter Projekttypen.

Ein Azure-Konto mit einem aktiven Abonnement. Erstellen Sie ein kostenloses Konto, falls Sie keines besitzen.

Erstellen eines hubbasierten Projekts

Führen Sie die folgenden Schritte aus, um ein hubbasiertes Projekt in Azure AI Foundry zu erstellen:

Melden Sie sich bei Azure KI Foundry an.
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 in der Schnellstartanleitung aus: Erste Schritte mit Azure AI Foundry , 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.
Wählen Sie die KI-Hubressource und dann "Weiter" aus.
Geben Sie einen Namen für das Projekt ein.
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 einen neuen Hub erstellen möchten, wählen Sie Neuen Hub erstellen aus, und geben Sie einen Namen an.
Wenn Sie keinen Hub haben, wird ein Standardhub für Sie erstellt.
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 Azure KI Foundry-Projekt mithilfe dieser Schritte für jedes Modell bereit.

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

Tipp

Da Sie den linken Bereich im Azure AI Foundry-Portal anpassen können, werden möglicherweise unterschiedliche Elemente angezeigt als in diesen Schritten. Wenn Sie nicht sehen, wonach Sie suchen, wählen Sie ... Mehr am unteren Rand des linken Bereichs.

Wählen Sie im linken Bereich den Modellkatalog aus.
Wählen Sie das Modell gpt-4o-mini aus der Liste der Modelle aus. Sie können dazu die Suchleiste verwenden.
Wählen Sie auf der Modelldetailseite die Option Bereitstellen aus.
Behalten Sie den Standard-Bereitstellungsnamen bei. 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, Ihre benutzerdefinierten Daten als Grundlage für die Modellantworten zu verwenden. Der Suchindex wird verwendet, um relevante Dokumente basierend auf der Frage des Benutzers abzurufen.

Für die Erstellung eines Suchindex benötigen Sie einen Azure KI-Suche-Dienst und eine Verbindung.

Hinweis

Die Erstellung eines Azure KI-Suche-Diensts und der Suchindizes ist mit Kosten verbunden. Details zu Preisen und Tarifen für den Azure KI-Suche-Dienst finden Sie auf der Erstellungsseite. Dort können Sie die Kosten überprüfen, bevor Sie die Ressource erstellen. Für dieses Tutorial wird die Verwendung des Tarifs Basic oder höher empfohlen.

Wenn Sie bereits über einen Azure KI-Suche-Dienst verfügen, können Sie direkt mit dem nächsten Abschnitt fortfahren.

Andernfalls können Sie einen Azure KI-Suche-Dienst über das Azure-Portal erstellen.

Tipp

Dieser Schritt ist das einzige Mal, dass Sie das Azure-Portal in dieser Tutorialreihe verwenden. Der Rest Ihrer Arbeit erfolgt im Azure KI Foundry-Portal oder in Ihrer lokalen Entwicklungsumgebung.

Erstellen Sie einen Azure KI-Suche-Dienst im Azure-Portal.
Wählen Sie Ihre Ressourcengruppe und Instanzdetails aus. Auf dieser Seite finden Sie Details zu Preisen und Preisstufen.
Durchlaufen Sie den Assistenten, und wählen Sie Überprüfen + zuweisen aus, um die Ressource zu erstellen.
Bestätigen Sie die Details Ihres Azure KI-Suche-Diensts (einschließlich der vorkalkulierten Kosten).
Wählen Sie Erstellen aus, um den Azure KI-Suche-Dienst zu erstellen.

Verbinden der Azure KI-Suche mit Ihrem Projekt

Wenn Sie in Ihrem Projekt bereits über eine Verbindung für Azure KI-Suche verfügen, können Sie direkt mit der Installation der Azure CLI fortfahren und sich anmelden.

Im Azure KI Foundry Portal überprüfen Sie, ob eine Ressource mit Azure AI Search verbunden ist.

Wechseln Sie in Azure KI Foundry zu Ihrem Projekt, und wählen Sie im linken Bereich Verwaltungscenter aus.
Überprüfen Sie im Abschnitt Verbundene Ressourcen, ob bei Ihnen eine Verbindung vom Typ Azure KI-Suche vorhanden ist.
Wenn Sie über eine Azure KI-Suche-Verbindung verfügen, können Sie mit dem nächsten Abschnitt fortfahren.
Wählen Sie andernfalls Neue Verbindung > Azure KI-Suche aus.
Suchen Sie in den Optionen nach Ihrem Azure KI-Suche-Dienst, und wählen Sie Verbindung hinzufügen aus.
Verwenden Sie API-Schlüssel für Authentifizierung.

Von großer Bedeutung

Die API-Schlüsseloption wird für die Produktion nicht empfohlen. Um die empfohlene Microsoft Entra ID-Authentifizierungsoption auszuwählen und zu verwenden, müssen Sie auch die Zugriffssteuerung für den Azure KI Suchdienst konfigurieren. Weisen Sie Ihrem Benutzerkonto die Rollen Mitwirkender für Suchindexdaten und Mitwirkender für Suchdienst zu. Weitere Informationen finden Sie unter Herstellen einer Verbindung mit Azure KI Search mithilfe von Rollen und rollenbasierter Zugriffssteuerung im Azure AI Foundry-Portal.
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.

Zuerst müssen Sie eine neue Python-Umgebung erstellen. Installieren Sie KEINE Pakete in Ihrer globalen Python-Installation. Sie sollten beim Installieren von Python-Paketen immer eine virtuelle oder Conda-Umgebung verwenden, andernfalls können Sie die globale Python-Installation beschädigen.

Installieren Sie bei Bedarf Python.

Es wird empfohlen, Python 3.10 oder höher zu verwenden, 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 eine virtuelle Umgebung mit den folgenden Befehlen:

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, bedeutet dies, dass Sie beim Ausführen von python oder pip über die Befehlszeile den Python-Interpreter verwenden, der im .venv-Ordner Ihrer Anwendung enthalten ist.

Hinweis

Sie können den Befehl deactivate verwenden, um die virtuelle Python-Umgebung zu beenden, und sie später bei Bedarf reaktivieren.

Pakete installieren

Installieren Sie erforderliche Pakete.

Erstellen Sie zunächst 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
```
Installieren Sie die erforderlichen Pakete:
```
pip install -r requirements.txt
```

Erstellen eines Hilfsskripts

Erstellen Sie einen Ordner für Ihre Arbeit. Erstellen Sie eine Datei namens config.py in diesem Ordner. Dieses Hilfsskript wird in den nächsten beiden Teilen der Tutorialreihe verwendet. 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)

Hinweis

Dieses Skript verwendet auch ein Paket, das Sie noch nicht installiert haben, azure.monitor.opentelemetry. Sie installieren dieses Paket im nächsten Teil der Tutorialreihe.

Umgebungsvariablen konfigurieren

Ihre Projektverbindungszeichenfolge ist erforderlich, um Azure OpenAI in Azure AI 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 in dem Azure KI Foundry-Projekt, das Sie im Azure KI Foundry-Playground-Schnellstart 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.

Tipp

Wenn Sie in VS Code arbeiten, schließen Sie das Terminalfenster, und öffnen Sie es erneut, nachdem Sie Änderungen in der Datei .env gespeichert haben.

Warnung

Stellen Sie sicher, dass sich Ihr .env in Ihrer .gitignore-Datei befindet, damit Sie es nicht versehentlich in Ihr Git-Repository einchecken.

Installieren der Azure CLI und Anmelden

Sie installieren die Azure CLI und melden sich in Ihrer lokalen Entwicklungsumgebung an, damit Sie Ihre Benutzeranmeldeinformationen verwenden können, um Azure OpenAI in Azure AI 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-Skripte auch von hier aus auszuführen, nachdem Sie sich angemeldet haben.

Bereinigen von Ressourcen

Um unnötige Azure-Kosten zu vermeiden, sollten Sie die in diesem Tutorial erstellten Ressourcen löschen, 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 Ihre Chat-App im nächsten Teil dieser Tutorialreihe 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.

Teil 2: Erstellen einer benutzerdefinierte Chat-App mit dem Azure KI SDK

Freigeben über

Tutorial: Teil 1 – Einrichten einer Projekt- und Entwicklungsumgebung zum Erstellen einer benutzerdefinierten Wissensabruf-App (RAG) mit dem Azure KI Foundry SDK

Voraussetzungen

Erstellen eines hubbasierten Projekts

Bereitstellen von Modellen

Erstellen eines Azure KI-Suche-Diensts

Verbinden der Azure KI-Suche mit Ihrem Projekt

Erstellen einer neuen Python-Umgebung

Installieren Sie bei Bedarf Python.

Erstellen einer virtuellen Umgebung

Pakete installieren

Erstellen eines Hilfsskripts

Umgebungsvariablen konfigurieren

Installieren der Azure CLI und Anmelden

Bereinigen von Ressourcen

Nächster Schritt

Feedback

Zusätzliche Ressourcen