Zelfstudie: Deel 1: Een project- en ontwikkelomgeving instellen voor het bouwen van een aangepaste RAG-app (Knowledge Retrieval) met de Microsoft Foundry SDK

In deze zelfstudie stelt u de resources in die nodig zijn om een aangepaste rag-chat-app (Knowledge Retrieval) te bouwen met de Microsoft Foundry SDK. Dit is deel één van een driedelige reeks zelfstudies. U maakt hier de resources, bouwt de app in deel twee en evalueert deze in deel drie. In dit gedeelte gaat u het volgende doen:

Als u andere handleidingen of quickstarts hebt voltooid, hebt u mogelijk al enkele middelen gemaakt die nodig zijn voor deze handleiding. Als u dat hebt gedaan, kunt u deze stappen overslaan.

Vereiste voorwaarden

• Een Azure-account waaraan de rol Eigenaar of Inzender is toegewezen. Als u nog geen account hebt, maakt u gratis een account.
• Microsoft Foundry: Rol van Eigenaar of Bijdrager vereist om een project te maken.

Een hub-project maken

Voer de volgende stappen uit om een hubproject te maken in Microsoft Foundry:

1. Meld u aan bij Microsoft Foundry. Zorg ervoor dat de wisselknop New Foundry is uitgeschakeld. Deze stappen verwijzen naar Foundry (klassiek).

   

2. Wat u vervolgens doet, is afhankelijk van waar u bent:

   • Als u geen bestaande projecten hebt: volg de stappen in quickstart: Ga aan de slag met Microsoft Foundry om uw eerste project te maken.

   • Als u in een project bent: selecteer de breadcrumb van het project en selecteer vervolgens Nieuwe resource maken.

     

   • Als u zich niet in een project bevinden: selecteer Nieuwe maken in de rechterbovenhoek om een nieuw Foundry-project te maken

     

3. Selecteer AI-hubresource en selecteer Vervolgens Volgende.

4. Voer een naam in voor het project.

5. Als u een hub hebt, ziet u degene die u het laatst hebt gebruikt geselecteerd.

   • Als u toegang hebt tot meer dan één hub, kunt u een andere hub selecteren in de vervolgkeuzelijst.

   • Als u een nieuwe wilt maken, selecteert u Een nieuwe hub maken in de vervolgkeuzelijst.

     

6. Als u geen hub hebt, wordt er een standaard voor u gemaakt.

7. Klik op Creëren.

Modellen implementeren

U hebt twee modellen nodig om een op RAG gebaseerde chat-app te bouwen: een Azure OpenAI-chatmodel (gpt-4o-mini) en een Azure OpenAI-insluitingsmodel (text-embedding-ada-002). Implementeer deze modellen in uw Foundry-project met behulp van deze set stappen voor elk model.

Met deze stappen implementeert u een model naar een realtime-eindpunt vanuit de modelcatalogus van de Foundry-portal:

1. Selecteer modelcatalogus in het linkerdeelvenster.

2. Selecteer het gpt-4o-minimodel in de lijst met modellen. U kunt de zoekbalk gebruiken om deze te vinden.

   

3. Selecteer Dit model gebruiken op de pagina met modeldetails.

4. Laat de standaardimplementatienaam staan en selecteer Implementeren. Of als het model niet beschikbaar is in uw regio, wordt er een andere regio voor u geselecteerd en verbonden met uw project. In dit geval selecteert u Verbinding maken en implementeren.

Nadat u de gpt-4o-mini hebt geïmplementeerd, herhaalt u de stappen om het model tekst-insluiten-ada-002 te implementeren.

Een Azure AI-Search-service maken

Het doel van deze toepassing is om de modelreacties in uw aangepaste gegevens te gronden. De zoekindex haalt relevante documenten op op basis van de vraag van de gebruiker.

U hebt een Azure AI Search-service en verbinding nodig om een zoekindex te maken.

Als u al een Azure AI Search-service hebt, gaat u naar de volgende sectie.

Anders maakt u een Azure AI Search-service met behulp van Azure Portal.

1. Maak een Azure AI-Search-service in Azure Portal.
2. Selecteer uw resourcegroep en instantiegegevens. Controleer de prijzen en prijscategorieën op deze pagina. Gebruik voor deze zelfstudie een prijscategorie basic of hoger.
3. Ga door met de wizard en selecteer Beoordelen en toewijzen om de resource te maken.
4. Bevestig de details van uw Azure AI Search-service, inclusief de geschatte kosten.
5. Selecteer Maken om de Azure AI-Search-service te maken.

Azure AI Search verbinden met uw project

Als uw project al een Azure AI Search-verbinding heeft, gaat u naar De Azure CLI installeren en meldt u zich aan.

Controleer in de Foundry-portal op een met Azure AI Search verbonden resource.

1. Ga in Foundry naar uw project en selecteer Beheercentrum in het linkerdeelvenster.

2. Kijk in de sectie Verbonden resources of u een verbinding hebt van het type Azure AI Search.

3. Als u een Azure AI Search-verbinding hebt, kunt u de volgende stappen overslaan.

4. Anders selecteert u Nieuwe verbinding en vervolgens Azure AI Search.

5. Zoek uw Azure AI-Search-service in de opties en selecteer Verbinding toevoegen.

6. Api-sleutel gebruiken voor verificatie.

   Belangrijk

   De optie API-sleutel wordt niet aanbevolen voor productie. De aanbevolen benadering is Verificatie van Microsoft Entra-id , waarvoor de rollen Inzender voor zoekindexgegevens en Inzender voor zoekservices zijn vereist (geconfigureerd in vereisten). Zie Verbinding maken met Azure AI Search met behulp van rollen voor meer informatie. Voor deze tutorial is API-sleutel acceptabel als u snel wilt doorgaan. Schakel over naar Entra-id voordat u naar productie implementeert.

7. Selecteer Verbinding toevoegen.

Een nieuwe Python-omgeving maken

Maak in de IDE van uw keuze een nieuwe map voor uw project. Open een terminalvenster in die map.

Maak eerst een nieuwe Python-omgeving. Installeer geen pakketten in uw globale Python-installatie. Gebruik altijd een virtuele of conda-omgeving bij het installeren van Python-pakketten. Anders kunt u de globale installatie van Python verbreken.

Installeer Python indien nodig

Gebruik Python 3.10 of hoger, maar ten minste Python 3.9 is vereist. Als u geen geschikte versie van Python hebt geïnstalleerd, volgt u de instructies in de VS Code Python-zelfstudie voor de eenvoudigste manier om Python op uw besturingssysteem te installeren.

Een virtuele omgeving maken

Als Python 3.10 of hoger al is geïnstalleerd, maakt u een virtuele omgeving met behulp van de volgende opdrachten:

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

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

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

Wanneer u de Python-omgeving activeert, gebruikt de uitvoering van python of pip vanaf de opdrachtregel de Python-interpreter in de .venv map van uw toepassing.

Pakketten installeren

Installeer de vereiste pakketten.

1. Maak een bestand met de naam requirements.txt in de projectmap. Voeg de volgende pakketten toe aan het bestand:

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

   Verwijzingen: Azure AI Projects-clientbibliotheek, azure-ai-inference, python-dotenv.

2. Installeer de vereiste pakketten:

   pip install -r requirements.txt
   

Omgevingsvariabelen configureren

Uw projectverbindingsreeks is vereist om Azure OpenAI in Microsoft Foundry Models aan te roepen vanuit uw code. In deze quickstart slaat u deze waarde op in een .env bestand. Dit is een bestand dat omgevingsvariabelen bevat die door uw toepassing kunnen worden gelezen.

Maak een .env bestand en plak de volgende code:

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"

• Zoek uw verbindingsreeks in het Foundry-project dat u hebt gemaakt met de Foundry Playground Quickstart. Open het project en zoek vervolgens de verbindingsreeks op de pagina Overzicht. Kopieer de verbindingsreeks en plak deze in het .env bestand.

  

• Als u nog geen zoekindex hebt, houdt u de waarde 'example-index' voor AISEARCH_INDEX_NAME. In deel 2 van deze zelfstudie maakt u de index met deze naam. Als u eerder een zoekindex hebt gemaakt die u wilt gebruiken, werkt u de waarde bij zodat deze overeenkomt met de naam van die zoekindex.

• Als u de namen van de modellen bij het implementeren ervan hebt gewijzigd, werkt u de waarden in het .env bestand bij zodat deze overeenkomen met de namen die u hebt gebruikt.

De Azure CLI installeren en u aanmelden

U installeert de Azure CLI en meldt u zich aan vanuit uw lokale ontwikkelomgeving, zodat u uw gebruikersreferenties kunt gebruiken om Azure OpenAI aan te roepen in Microsoft Foundry-modellen.

In de meeste gevallen kunt u Azure CLI installeren vanuit uw terminal met behulp van de volgende opdracht:

winget install -e --id Microsoft.AzureCLI

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

brew update && brew install azure-cli

U kunt de instructies volgen voor het installeren van de Azure CLI als deze opdrachten niet werken voor uw specifieke besturingssysteem of installatie.

Nadat u de Azure CLI hebt geïnstalleerd, meldt u zich aan met behulp van de az login opdracht en meldt u zich aan met behulp van de browser:

az login

U kunt zich ook handmatig aanmelden via de browser met een apparaatcode.

az login --use-device-code

Houd dit terminalvenster open om uw Python-scripts hier ook uit te voeren, nu u zich hebt aangemeld.

Uw installatie controleren

Controleer of uw omgeving correct is ingesteld door een snelle test uit te voeren:

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

Als u ziet "Setup successful!", zijn uw Azure-referenties en SDK correct geconfigureerd.

Verwijzingen: Azure AI Projects-clientbibliotheek, DefaultAzureCredential.

Helperscript maken

Maak een map voor uw werk. Maak een bestand met de naam config.py in deze map. U gebruikt dit helperscript in de volgende twee delen van de reeks zelfstudies. Het script laadt uw omgevingsvariabelen en initialiseert de Azure AI Projects-client. Voeg de volgende code toe:

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

Verwijzingen: AIProjectClient, DefaultAzureCredential, load_dotenv.

Hulpmiddelen opruimen

Als u onnodige Azure-kosten wilt voorkomen, verwijdert u de resources die u in deze zelfstudie hebt gemaakt als ze niet meer nodig zijn. Als u resources wilt beheren, kunt u Azure Portal gebruiken.

Maar verwijder ze nog niet als u een chat-app wilt bouwen in het volgende deel van deze reeks zelfstudies.

Volgende stap

In deze zelfstudie stelt u alles in wat u nodig hebt om een aangepaste chat-app te bouwen met de Azure AI SDK. In het volgende deel van deze zelfstudiereeks bouwt u de aangepaste app.