Imported from venturemavenwill/azureaifundamentals (generative-ai-for-beginners/translations/de/AGENTS.md). Install upstream with npx skills add venturemavenwill/azureaifundamentals --skill de. Copyright stays with the author.

AGENTS.md

Projektübersicht

Dieses Repository enthält einen umfassenden Lehrplan mit 21 Lektionen, der die Grundlagen der Generativen KI und die Anwendungsentwicklung vermittelt. Der Kurs ist für Anfänger konzipiert und deckt alles von den Grundkonzepten bis hin zum Aufbau produktionsreifer Anwendungen ab.

Wichtige Technologien:

Python 3.9+ mit Bibliotheken: openai, python-dotenv, tiktoken, azure-ai-inference, pandas, numpy, matplotlib
TypeScript/JavaScript mit Node.js und Bibliotheken: openai (Azure OpenAI über den v1-Endpunkt + Responses API), @azure-rest/ai-inference (Microsoft Foundry Modelle)
Azure OpenAI Service, OpenAI API und Microsoft Foundry Modelle (GitHub Models wird Ende Juli 2026 eingestellt)
Jupyter Notebooks für interaktives Lernen
Dev Containers für eine konsistente Entwicklungsumgebung

Repository-Struktur:

21 nummerierte Lektion-Ordner (00-21) mit READMEs, Code-Beispielen und Aufgaben
Mehrere Implementierungen: Python, TypeScript und manchmal .NET Beispiele
Übersetzungsverzeichnis mit 40+ Sprachversionen
Zentrale Konfiguration über .env Datei (verwenden Sie .env.copy als Vorlage)

Einrichtungsbefehle

Erste Repository-Einrichtung

# Klonen Sie das Repository
git clone https://github.com/microsoft/generative-ai-for-beginners.git
cd generative-ai-for-beginners

# Kopiere die Umgebungs-Vorlage
cp .env.copy .env
# Bearbeiten Sie die .env mit Ihren API-Schlüsseln und Endpunkten

Python-Umgebung einrichten

# Virtuelle Umgebung erstellen
python3 -m venv venv

# Virtuelle Umgebung aktivieren
# Auf macOS/Linux:
source venv/bin/activate
# Auf Windows:
venv\Scripts\activate

# Abhängigkeiten installieren
pip install -r requirements.txt

Node.js/TypeScript-Einrichtung

# Installieren Sie Abhängigkeiten auf Root-Ebene (für Dokumentationstools)
npm install

# Für einzelne TypeScript-Beispiele zu Lektionen navigieren Sie zur jeweiligen Lektion:
cd 06-text-generation-apps/typescript/recipe-app
npm install

Dev Container Einrichtung (Empfohlen)

Das Repository beinhaltet eine .devcontainer-Konfiguration für GitHub Codespaces oder VS Code Dev Containers:

Repository in GitHub Codespaces oder VS Code mit Dev Containers-Erweiterung öffnen
Dev Container wird automatisch:
- Python-Abhängigkeiten aus requirements.txt installieren
- Post-Create-Skript ausführen (.devcontainer/post-create.sh)
- Jupyter Kernel einrichten

Entwicklungsablauf

Umgebungsvariablen

Alle Lektionen, die API-Zugriff benötigen, verwenden Umgebungsvariablen, die in .env definiert sind:

OPENAI_API_KEY - Für OpenAI API
AZURE_OPENAI_API_KEY - Für Azure OpenAI in Microsoft Foundry (Azure OpenAI Service ist jetzt Teil von Microsoft Foundry: https://ai.azure.com)
AZURE_OPENAI_ENDPOINT - Azure OpenAI Endpunkt-URL (Foundry Ressource Endpunkt)
AZURE_OPENAI_DEPLOYMENT - Chat Completion Modell Deployment Name (Kursstandard: gpt-5-mini)
AZURE_OPENAI_EMBEDDINGS_DEPLOYMENT - Embeddings Modell Deployment Name (Kursstandard: text-embedding-3-small)
AZURE_OPENAI_API_VERSION - API Version (Standard: 2024-10-21)
HUGGING_FACE_API_KEY - Für Hugging Face Modelle
AZURE_INFERENCE_ENDPOINT - Microsoft Foundry Models Endpunkt (Multi-Provider Model-Katalog)
AZURE_INFERENCE_CREDENTIAL - Microsoft Foundry Models API Schlüssel (ersetzt das auslaufende GITHUB_TOKEN)
AZURE_INFERENCE_CHAT_MODEL - Ein Nicht-Reasoning-Modell (z.B. Llama-3.3-70B-Instruct), das für die temperature Beispiele verwendet wird, da Reasoning-Modelle keine Sampling-Kontrollen unterstützen

Modell-Konventionen (wichtig)

Standard-Chatmodell ist gpt-5-mini - ein aktuelles, nicht veraltetes Reasoning-Modell. Ab 2026 werden die älteren temperaturfähigen "mini" Modelle (gpt-4o-mini, gpt-4.1-mini) ausgephast, daher verwendet der Lehrplan die GPT-5 Familie.
Reasoning-Modelle lehnen temperature und top_p ab, und verwenden stattdessen max_output_tokens (Responses API) / max_completion_tokens (Chat Completions) anstelle von max_tokens. Fügen Sie nicht temperature/top_p/max_tokens in Beispiele ein, die gpt-5-mini aufrufen.
Um temperature zu demonstrieren, verwenden Beispiele ein Llama Modell (Llama-3.3-70B-Instruct) über den Microsoft Foundry Models Endpunkt (AZURE_INFERENCE_CHAT_MODEL). Steuern Sie Reasoning-Modelle lieber mit Prompt Engineering + Reasoning-Kontrollen anstelle von Sampling-Reglern.
Feinabstimmung (Lektion 18) verwendet weiterhin gpt-4.1-mini: GPT-5 unterstützt nur Verstärkungsfeinabstimmung (RFT), nicht die dort gezeigte überwachte Feinabstimmung (SFT).
Lektionen 20 (Mistral) und 21 (Meta) behalten temperature/max_tokens bei, da sie Mistral/Llama Modelle ansprechen, welche diese unterstützen.

Ausführen von Python-Beispielen

# Navigiere zum Unterrichtsverzeichnis
cd 06-text-generation-apps/python

# Führe ein Python-Skript aus
python aoai-app.py

Ausführen von TypeScript-Beispielen

# Navigiere zum TypeScript-App-Verzeichnis
cd 06-text-generation-apps/typescript/recipe-app

# Baue den TypeScript-Code
npm run build

# Starte die Anwendung
npm start

Ausführen von Jupyter Notebooks

# Starte Jupyter im Wurzelverzeichnis des Repositories
jupyter notebook

# Oder verwende VS Code mit der Jupyter-Erweiterung

Arbeiten mit verschiedenen Lektionstypen

"Learn" Lektionen: Fokus auf README.md Dokumentation und Konzepte
"Build" Lektionen: Enthalten funktionierenden Code in Python und TypeScript
Jede Lektion hat ein README.md mit Theorie, Code-Erklärungen und Links zu Video-Inhalten

Code-Stil Richtlinien

Python

Verwendung von python-dotenv zur Verwaltung von Umgebungsvariablen
Import der openai Bibliothek für API-Interaktionen
Verwendung von pylint zum Linting (einige Beispiele enthalten # pylint: disable=all zur Vereinfachung)
Folgen Sie den Namenskonventionen von PEP 8
API-Anmeldedaten in .env Datei speichern, niemals im Code

TypeScript

Verwendung des dotenv Pakets für Umgebungsvariablen
TypeScript-Konfiguration in tsconfig.json für jede App
Verwendung des openai Pakets für Azure OpenAI (Client zeigt auf /openai/v1/ Endpunkt und nutzt client.responses.create); Verwendung von @azure-rest/ai-inference für Microsoft Foundry Modelle
Verwendung von nodemon für Entwicklung mit automatischem Reload
Vor dem Ausführen bauen: npm run build dann npm start

Allgemeine Konventionen

Halten Sie Code-Beispiele einfach und lehrreich
Kommentare einfügen, die wichtige Konzepte erklären
Der Code jeder Lektion sollte eigenständig und ausführbar sein
Konsistente Namensgebung: aoai- Präfix für Azure OpenAI, oai- für OpenAI API, githubmodels- für Microsoft Foundry Modelle (Legacy-Präfix aus der GitHub Models Ära)

Dokumentationsrichtlinien

Markdown-Stil

Alle URLs müssen im Format [Text](../../URL) ohne zusätzliches Leerzeichen eingebettet sein
Relative Links müssen mit ./ oder ../ beginnen
Alle Links zu Microsoft-Domains müssen eine Tracking-ID enthalten: ?WT.mc_id=academic-105485-koreyst
Vermeiden Sie länderspezifische Lokalisierungen in URLs (vermeiden Sie /en-us/)
Bilder im Ordner ./images mit beschreibenden Namen speichern
Verwenden Sie im Dateinamen englische Buchstaben, Zahlen und Bindestriche

Übersetzungsunterstützung

Das Repository unterstützt über 40 Sprachen über automatisierte GitHub Actions
Übersetzungen werden im Verzeichnis translations/ gespeichert
Bitte keine teilweisen Übersetzungen einreichen
Maschinelle Übersetzungen werden nicht akzeptiert
Übersetzte Bilder werden im Verzeichnis translated_images/ gespeichert

Tests und Validierung

Vor dem Einreichen prüfen

Dieses Repository verwendet GitHub Actions zur Validierung. Vor dem Einreichen von PRs:

Markdown Links prüfen:

# Der Workflow validate-markdown.yml überprüft:
# - Fehlerhafte relative Pfade
# - Fehlende Tracking-IDs bei Pfaden
# - Fehlende Tracking-IDs bei URLs
# - URLs mit Landeslokalisierung
# - Fehlerhafte externe URLs

Manuelles Testen:
- Testen Sie Python-Beispiele: Aktivieren Sie venv und führen Sie Skripte aus
- Testen Sie TypeScript-Beispiele: npm install, npm run build, npm start
- Verifizieren Sie, dass Umgebungsvariablen korrekt konfiguriert sind
- Prüfen Sie, dass API-Schlüssel mit den Code-Beispielen funktionieren
Code-Beispiele:
- Stellen Sie sicher, dass allen Code fehlerfrei läuft
- Testen Sie sowohl mit Azure OpenAI als auch OpenAI API, wenn zutreffend
- Verifizieren Sie, dass Beispiele mit Microsoft Foundry Modellen funktionieren, sofern unterstützt

Keine automatischen Tests

Dies ist ein edukatives Repository, das sich auf Tutorials und Beispiele konzentriert. Es gibt keine Unit- oder Integrationstests zum Ausführen. Validierung erfolgt hauptsächlich durch:

Manuelles Testen der Code-Beispiele
GitHub Actions zur Markdown-Validierung
Community-Review der Bildungsinhalte

Pull Request Richtlinien

Vor dem Einreichen

Ändern Sie Code und testen Sie in Python und TypeScript, wenn zugänglich
Führen Sie die Markdown-Validierung aus (wird automatisch beim PR ausgelöst)
Stellen Sie sicher, dass Tracking-IDs für alle Microsoft URLs vorhanden sind
Prüfen Sie, dass relative Links gültig sind
Verifizieren Sie die korrekte Referenzierung von Bildern

PR-Titel-Format

Verwenden Sie aussagekräftige Titel: [Lesson 06] Fix Python example typo oder Update README for lesson 08
Verweisen Sie auf Issue-Nummern, wenn zutreffend: Fixes #123

PR-Beschreibung

Erklären Sie, was geändert wurde und warum
Verlinken Sie zu verwandten Issues
Für Codeänderungen spezifizieren Sie, welche Beispiele getestet wurden
Für Übersetzungs-PRs fügen Sie alle Dateien für eine vollständige Übersetzung hinzu

Beitragserfordernisse

Unterzeichnen Sie die Microsoft CLA (automatisch beim ersten PR)
Forken Sie das Repository in Ihr Konto, bevor Sie Änderungen vornehmen
Ein PR pro logische Änderung (nicht unrelated fixes kombinieren)
Halten Sie PRs fokussiert und möglichst klein

Übliche Arbeitsabläufe

Hinzufügen eines neuen Code-Beispiels

Navigieren Sie zum passenden Lektion-Ordner
Erstellen Sie Beispiel im python/ oder typescript/ Unterverzeichnis
Folgen Sie der Namenskonvention: {provider}-{example-name}.{py|ts|js}
Testen Sie mit echten API-Zugangsdaten
Dokumentieren Sie alle neuen Umgebungsvariablen im Lektion README

Aktualisieren der Dokumentation

Bearbeiten Sie README.md im Lektion-Ordner
Befolgen Sie die Markdown-Richtlinien (Tracking-IDs, relative Links)
Übersetzungen werden von GitHub Actions verwaltet (nicht manuell bearbeiten)
Testen Sie, dass alle Links gültig sind

Arbeiten mit Dev Containers

Repository enthält .devcontainer/devcontainer.json
Post-Create-Skript installiert Python-Abhängigkeiten automatisch
Erweiterungen für Python und Jupyter sind vorkonfiguriert
Die Umgebung basiert auf mcr.microsoft.com/devcontainers/universal:2.11.2

Deployment und Veröffentlichung

Dies ist ein Lern-Repository - es gibt keinen Deployment-Prozess. Der Lehrplan wird genutzt über:

GitHub Repository: Direkter Zugriff auf Code und Dokumentation
GitHub Codespaces: Sofortige Entwicklungsumgebung mit vorkonfigurierter Einrichtung
Microsoft Learn: Inhalte können auf der offiziellen Lernplattform bereitgestellt werden
docsify: Dokumentationsseite aus Markdown gebaut (siehe docsifytopdf.js und package.json)

Erstellen der Dokumentationsseite

# PDF aus der Dokumentation erstellen (falls erforderlich)
npm run convert

Fehlerbehebung

Häufige Probleme

Python Importfehler:

Stellen Sie sicher, dass die virtuelle Umgebung aktiviert ist
Führen Sie pip install -r requirements.txt aus
Überprüfen Sie, dass Python Version 3.9+ verwendet wird

TypeScript Build-Fehler:

Führen Sie npm install im jeweiligen App-Verzeichnis aus
Überprüfen Sie, ob die Node.js Version kompatibel ist
Löschen Sie node_modules und installieren Sie bei Bedarf neu

API-Authentifizierungsfehler:

Verifizieren Sie, dass .env Datei existiert und korrekte Werte enthält
Überprüfen Sie, dass API-Schlüssel gültig und nicht abgelaufen sind
Stellen Sie sicher, dass die Endpunkt-URLs für Ihre Region korrekt sind

Fehlende Umgebungsvariablen:

Kopieren Sie .env.copy nach .env
Füllen Sie alle erforderlichen Werte für die jeweilige Lektion aus
Starten Sie Ihre Anwendung nach Aktualisierung der .env neu

Zusätzliche Ressourcen

Projektspezifische Hinweise

Dies ist ein edukatives Repository, das sich auf Lernen und nicht auf produktiven Code konzentriert
Beispiele sind bewusst einfach gehalten und fokussieren auf die Vermittlung von Konzepten
Die Codequalität ist ausgewogen zwischen Qualität und pädagogischer Klarheit
Jede Lektion ist eigenständig und kann unabhängig abgeschlossen werden
Das Repository unterstützt mehrere API-Anbieter: Azure OpenAI, OpenAI, Microsoft Foundry Modelle und Offline-Anbieter wie Foundry Local und Ollama
Inhalte sind mehrsprachig mit automatisierten Übersetzungs-Workflows
Aktive Community auf Discord für Fragen und Support

Haftungsausschluss: Dieses Dokument wurde mit dem KI-Übersetzungsdienst Co-op Translator übersetzt. Obwohl wir uns um Genauigkeit bemühen, beachten Sie bitte, dass automatisierte Übersetzungen Fehler oder Ungenauigkeiten enthalten können. Das Originaldokument in seiner Ursprungssprache gilt als maßgebliche Quelle. Bei kritischen Informationen wird eine professionelle menschliche Übersetzung empfohlen. Wir übernehmen keine Haftung für Missverständnisse oder Fehlinterpretationen, die aus der Verwendung dieser Übersetzung entstehen.

About