Freigeben über

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

  • Artikel

In diesem Tutorial verwenden Sie das Azure KI 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
  • Bereitstellen von Modellen in Ihrem Projekt
  • 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.

Wichtig

Die in diesem Artikel markierten Elemente (Vorschau) sind aktuell als öffentliche Vorschau verfügbar. Diese Vorschauversion wird ohne Vereinbarung zum Servicelevel bereitgestellt und sollte nicht für Produktionsworkloads verwendet werden. Manche Features werden möglicherweise nicht unterstützt oder sind nur eingeschränkt verwendbar. Weitere Informationen finden Sie unter Zusätzliche Nutzungsbestimmungen für Microsoft Azure-Vorschauen.

Voraussetzungen

Erstellen eines Projekts

Um ein Projekt in Azure KI Foundry zu erstellen, führen Sie diese Schritte aus:

  1. Wechseln Sie zur Startseite von Azure KI Foundry.
  2. Wählen Sie + Projekt erstellen aus.
  3. Geben Sie einen Namen für das Projekt ein. Lassen Sie alle anderen Einstellungen unverändert.
  4. Projekte werden in Hubs erstellt. Wenn Neuen Hub erstellen angezeigt wird, wählen Sie dies aus, und geben Sie einen Namen an. Wählen Sie Weiter aus. (Wenn Neuen Hub erstellen nicht angezeigt wird, dann deshalb, weil ein neuer Hub für Sie erstellt wird.)
  5. Wählen Sie Anpassen aus, um die Eigenschaften des Hubs anzugeben.
  6. Verwenden Sie alle gewünschten Werte, mit Ausnahme der Region. Es wird empfohlen, als Region für diese Tutorialreihe entweder USA, Osten2 oder Schweden, Mitte zu verwenden.
  7. Wählen Sie Weiter aus.
  8. Wählen Sie Projekt 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 KI Foundry-Portal bereitgestellt:

  1. Wählen Sie im linken Navigationsbereich Modellkatalog aus.

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

    Screenshot der Modellauswahlseite

  3. Wählen Sie auf der Modelldetailseite die Option Bereitstellen aus.

    Screenshot: Modelldetailseite mit einer Schaltfläche zum Bereitstellen des Modells

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

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.

  1. Erstellen Sie einen Azure KI-Suche-Dienst im Azure-Portal.
  2. Wählen Sie Ihre Ressourcengruppe und Instanzdetails aus. Auf dieser Seite finden Sie Details zu Preisen und Tarifen.
  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 KI-Suche-Diensts (einschließlich der vorkalkulierten Kosten).
  5. 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.

Suchen Sie in Azure KI Foundry nach einer mit Azure KI-Suche verbundenen Ressource.

  1. Wechseln Sie in Azure KI Foundry zu Ihrem Projekt, und wählen Sie im linken Bereich 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 KI-Suche-Verbindung verfügen, können Sie mit dem nächsten Abschnitt fortfahren.

  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.

    Hinweis

    Sie können stattdessen Microsoft Entra ID für Authentifizierung verwenden. In diesem Fall müssen Sie auch die Zugriffssteuerung für den Azure KI-Suche-Dienst konfigurieren. Weisen Sie Ihrem Benutzerkonto die Rollen Mitwirkender für Suchindexdaten und Mitwirkender für Suchdienst zu. Wenn Sie nicht wissen, wie Sie vorgehen sollen, oder nicht über die erforderlichen Berechtigungen verfügen, verwenden Sie den API-Schlüssel für Authentifizierung.

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

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 Service aufzurufen.

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

winget install -e --id Microsoft.AzureCLI

Sie können die Anweisungen unter Installieren der Azure CLI- befolgen, wenn diese Befehle für Ihr Betriebssystem oder Setup nicht funktionieren.

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

az login

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

az login --use-device-code

Erstellen einer neuen Python-Umgebung

Zuerst müssen Sie eine neue Python-Umgebung erstellen, um das Paket zu installieren, das Sie für dieses Tutorial benötigen. 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.8 ist erforderlich. Wenn Sie keine geeignete Version von Python installiert haben, können Sie die Anweisungen im VS Code-Tutorial für Python befolgen, um Python auf Ihrem Betriebssystem zu installieren.

Erstellen einer virtuellen Umgebung

Wenn Sie Python 3.10 oder höher bereits installiert haben, können Sie mit den folgenden Befehlen eine virtuelle Umgebung erstellen:

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

Wenn Sie die Python-Umgebung aktivieren, verwenden Sie beim Ausführen von python oder pip über die Befehlszeile den Python-Interpreter, der im Ordner .venv 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.

Installieren von Paketen

Installieren Sie azure-ai-projects (Vorschau) und azure-ai-inference (Vorschau) zusammen mit anderen erforderlichen Paketen.

  1. 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
azure-ai-inference[prompts]
azure-identity
azure-search-documents
pandas
python-dotenv
opentelemetry-api

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

Konfigurieren von Umgebungsvariablen

Ihre Projektverbindungszeichenfolge ist erforderlich, um Azure OpenAI Service von Ihrem Code aus 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 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.

    Screenshot: Übersichtsseite eines Projekts und des Speicherorts der Verbindungszeichenfolge

  • 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 .env in Ihrer .gitignore-Datei befindet, damit Sie sie nicht versehentlich in Ihr Git-Repository einchecken.

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