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

AGENTS.md

Prezentare generală a proiectului

Acest depozit conține un curriculum cuprinzător de 21 de lecții care predau elementele fundamentale ale AI Generativ și dezvoltarea aplicațiilor. Cursul este conceput pentru începători și acoperă totul, de la concepte de bază până la construirea aplicațiilor pregătite pentru producție.

Tehnologii cheie:

Python 3.9+ cu biblioteci: openai, python-dotenv, tiktoken, azure-ai-inference, pandas, numpy, matplotlib
TypeScript/JavaScript cu Node.js și biblioteci: openai (Azure OpenAI prin endpoint-ul v1 + API-ul Responses), @azure-rest/ai-inference (Microsoft Foundry Models)
Serviciul Azure OpenAI, API-ul OpenAI și Microsoft Foundry Models (GitHub Models va fi retras la sfârșitul lunii iulie 2026)
Jupyter Notebooks pentru învățare interactivă
Dev Containers pentru un mediu de dezvoltare consistent

Structura depozitului:

21 directoare numerotate pentru lecții (00-21) conținând README-uri, exemple de cod și teme
Implementări multiple: exemple în Python, TypeScript și uneori .NET
Directorul de traduceri cu peste 40 de versiuni în limbi diferite
Configurare centralizată prin fișierul .env (folosește .env.copy ca șablon)

Comenzi de configurare

Configurarea inițială a depozitului

# Clonați depozitul
git clone https://github.com/microsoft/generative-ai-for-beginners.git
cd generative-ai-for-beginners

# Copiați șablonul de mediu
cp .env.copy .env
# Editați .env cu cheile API și punctele finale

Configurarea mediului Python

# Creează mediu virtual
python3 -m venv venv

# Activează mediul virtual
# Pe macOS/Linux:
source venv/bin/activate
# Pe Windows:
venv\Scripts\activate

# Instalează dependențele
pip install -r requirements.txt

Configurarea Node.js/TypeScript

# Instalează dependențele la nivel de root (pentru uneltele de documentație)
npm install

# Pentru exemplele TypeScript ale unei lecții individuale, navigați la lecția specifică:
cd 06-text-generation-apps/typescript/recipe-app
npm install

Configurarea Dev Container (Recomandat)

Depozitul include o configurație .devcontainer pentru GitHub Codespaces sau VS Code Dev Containers:

Deschide depozitul în GitHub Codespaces sau VS Code cu extensia Dev Containers
Dev Container va face următoarele automat:
- Instalează dependențele Python din requirements.txt
- Rulează scriptul post-creare (.devcontainer/post-create.sh)
- Configurează kernelul Jupyter

Fluxul de lucru pentru dezvoltare

Variabile de mediu

Toate lecțiile care necesită acces la API folosesc variabile de mediu definite în .env:

OPENAI_API_KEY - Pentru API-ul OpenAI
AZURE_OPENAI_API_KEY - Pentru Azure OpenAI în Microsoft Foundry (Serviciul Azure OpenAI este acum parte a Microsoft Foundry: https://ai.azure.com)
AZURE_OPENAI_ENDPOINT - URL-ul endpoint-ului Azure OpenAI (endpoint-ul resursei Foundry)
AZURE_OPENAI_DEPLOYMENT - Numele implementării modelului de completare chat (implicitul cursului: gpt-5-mini)
AZURE_OPENAI_EMBEDDINGS_DEPLOYMENT - Numele implementării modelului de embeddings (implicitul cursului: text-embedding-3-small)
AZURE_OPENAI_API_VERSION - Versiunea API-ului (implicit: 2024-10-21)
HUGGING_FACE_API_KEY - Pentru modelele Hugging Face
AZURE_INFERENCE_ENDPOINT - Endpoint-ul Microsoft Foundry Models (catalog de modele multi-furnizor)
AZURE_INFERENCE_CREDENTIAL - Cheia API Microsoft Foundry Models (înlocuiește GITHUB_TOKEN care se retrage)
AZURE_INFERENCE_CHAT_MODEL - Un model fără abilitate de raționament (ex: Llama-3.3-70B-Instruct) folosit în exemplele cu temperature, deoarece modelele de raționament nu suportă controale de eșantionare

Convenții pentru modele (important)

Modelul implicit de chat este gpt-5-mini - un model actual, de raționament, care nu este depreciat. Din 2026, modelele mai vechi "mini" capabile de temperatura (gpt-4o-mini, gpt-4.1-mini) sunt în proces de retragere, astfel că curriculum-ul se standardizează pe familia GPT-5.
Modelele de raționament resping temperature și top_p și folosesc în schimb max_output_tokens (Responses API) / max_completion_tokens (completări chat) în loc de max_tokens. Nu adăuga temperature/top_p/max_tokens în exemplele care apelează gpt-5-mini.
Pentru a demonstra temperature, exemplele folosesc un model Llama (Llama-3.3-70B-Instruct) prin endpoint-ul Microsoft Foundry Models (AZURE_INFERENCE_CHAT_MODEL). Modelele de raționament se dirijează prin inginerie de prompt + controale de raționament în loc de ajustări de eșantionare.
Fine-tuning (lecția 18) păstrează gpt-4.1-mini: GPT-5 suportă numai fine-tuning cu întărire (RFT), nu fine-tuning supravegheat (SFT) prezentat acolo.
Lecțiile 20 (Mistral) și 21 (Meta) păstrează temperature/max_tokens pentru că țintesc modele Mistral/Llama, care le suportă.

Executarea exemplelor Python

# Navigați la directorul lecției
cd 06-text-generation-apps/python

# Rulați un script Python
python aoai-app.py

Executarea exemplelor TypeScript

# Navigați la directorul aplicației TypeScript
cd 06-text-generation-apps/typescript/recipe-app

# Construiți codul TypeScript
npm run build

# Rulați aplicația
npm start

Executarea Jupyter Notebooks

# Porniți Jupyter în rădăcina depozitului
jupyter notebook

# Sau folosiți VS Code cu extensia Jupyter

Lucrul cu tipuri diferite de lecții

Lecții „Learn”: Se concentrează pe documentația README.md și concepte
Lecții „Build”: Include exemple de cod funcționale în Python și TypeScript
Fiecare lecție are un README.md cu teorie, explicații de cod și linkuri către conținut video

Linii directoare pentru stilul codului

Python

Folosește python-dotenv pentru gestionarea variabilelor de mediu
Importă biblioteca openai pentru interacțiuni cu API-ul
Folosește pylint pentru linting (unele exemple includ # pylint: disable=all pentru simplitate)
Urmează convențiile de denumire PEP 8
Stochează credențialele API în fișierul .env, niciodată în cod

TypeScript

Folosește pachetul dotenv pentru variabile de mediu
Configurarea TypeScript în tsconfig.json pentru fiecare aplicație
Folosește pachetul openai pentru Azure OpenAI (direcționează clientul către endpoint-ul /openai/v1/ și apelează client.responses.create); folosește @azure-rest/ai-inference pentru Microsoft Foundry Models
Folosește nodemon pentru dezvoltare cu reîncărcare automată
Construiește înainte de rulare: npm run build apoi npm start

Convenții Generale

Păstrează exemplele de cod simple și educaționale
Include comentarii care explică conceptele cheie
Codul fiecărei lecții ar trebui să fie autonom și executabil
Folosește denumiri consistente: prefix aoai- pentru Azure OpenAI, oai- pentru OpenAI API, githubmodels- pentru Microsoft Foundry Models (prefix moștenit din era GitHub Models)

Linii directoare pentru documentație

Stil Markdown

Toate URL-urile trebuie încadrate în format [text](../../url) fără spații suplimentare
Link-urile relative trebuie să înceapă cu ./ sau ../
Toate link-urile către domenii Microsoft trebuie să includă ID de urmărire: ?WT.mc_id=academic-105485-koreyst
Evită localizările specifice pe țări în URL-uri (evită /en-us/)
Imaginile sunt stocate în folderul ./images cu denumiri descriptive
Folosește caractere englezești, cifre și cratime în numele fișierelor

Suport pentru traduceri

Depozitul suportă peste 40 de limbi prin GitHub Actions automatizate
Traducerile sunt stocate în directorul translations/
Nu trimite traduceri parțiale
Traducerile automate nu sunt acceptate
Imaginile traduse sunt stocate în directorul translated_images/

Testare și validare

Verificări înainte de trimitere

Acest depozit folosește GitHub Actions pentru validare. Înainte de a trimite PR-uri:

Verifică link-urile Markdown:

# Fluxul de lucru validate-markdown.yml verifică:
# - Căi relative rupte
# - Lipsa ID-urilor de urmărire pe căi
# - Lipsa ID-urilor de urmărire pe URL-uri
# - URL-uri cu localizare de țară
# - URL-uri externe rupte

Testare manuală:
- Testează exemplele Python: activează venv și rulează scripturile
- Testează exemplele TypeScript: npm install, npm run build, npm start
- Verifică configurarea corectă a variabilelor de mediu
- Verifică dacă cheile API funcționează cu exemplele de cod
Exemple de cod:
- Asigură-te că tot codul rulează fără erori
- Testează cu ambele Azure OpenAI și API OpenAI când este aplicabil
- Verifică dacă exemplele funcționează cu Microsoft Foundry Models acolo unde sunt suportate

Fără teste automate

Acesta este un depozit educațional axat pe tutoriale și exemple. Nu există teste unitare sau de integrare de rulat. Validarea se face în principal prin:

Testare manuală a exemplelor de cod
GitHub Actions pentru validarea Markdown-ului
Revizuire comunitară a conținutului educațional

Linii directoare pentru Pull Request-uri

Înainte de trimitere

Testează modificările de cod în Python și TypeScript când este cazul
Rulează validarea Markdown (se declanșează automat la PR)
Asigură-te că ID-urile de urmărire sunt prezente pe toate URL-urile Microsoft
Verifică validitatea link-urilor relative
Verifică dacă imaginile sunt referențiate corect

Formatul titlului PR-ului

Folosește titluri descriptive: [Lesson 06] Corectare greșeală în exemplul Python sau Actualizare README pentru lecția 08
Referințe la numerele problemelor când este cazul: Fixes #123

Descrierea PR-ului

Explică ce a fost modificat și de ce
Leagă problemele relevante
Pentru modificări de cod, specifică ce exemple au fost testate
Pentru PR-urile de traducere, include toate fișierele pentru o traducere completă

Cerințe pentru contribuție

Semnează CLA Microsoft (automat la primul PR)
Fă fork la depozit în contul tău înainte de a face schimbări
Un PR per schimbare logică (nu combina corecturi nelegate)
Păstrează PR-urile concentrate și mici când este posibil

Fluxuri de lucru Comune

Adăugarea unui nou exemplu de cod

Navighează la directorul lecției corespunzătoare
Creează exemplul în subdirectorul python/ sau typescript/
Urmează convenția de denumire: {provider}-{example-name}.{py|ts|js}
Testează cu credențiale API reale
Documentează orice variabile de mediu noi în README-ul lecției

Actualizarea documentației

Editează README.md în directorul lecției
Urmează liniile directoare Markdown (ID-uri de urmărire, link-uri relative)
Actualizările traducerilor sunt gestionate de GitHub Actions (nu edita manual)
Testează dacă toate link-urile sunt valide

Lucrul cu Dev Containers

Depozitul include .devcontainer/devcontainer.json
Scriptul post-creare instalează automat dependențele Python
Extensiile pentru Python și Jupyter sunt preconfigurate
Mediul este bazat pe mcr.microsoft.com/devcontainers/universal:2.11.2

Implementare și publicare

Acesta este un depozit de învățare - nu există un proces de implementare. Curriculum-ul este destinat pentru:

Depozitul GitHub: Acces direct la cod și documentație
GitHub Codespaces: Mediu de dezvoltare instant cu configurare predefinită
Microsoft Learn: Conținutul poate fi publicat pe platforma oficială de învățare
docsify: Site de documentație construit din Markdown (vezi docsifytopdf.js și package.json)

Construirea site-ului de documentație

# Generează PDF din documentație (dacă este necesar)
npm run convert

Depanare

Probleme frecvente

Erori de import Python:

Asigură-te că mediul virtual este activat
Rulează pip install -r requirements.txt
Verifică versiunea Python este 3.9+

Erori de build TypeScript:

Rulează npm install în directorul aplicației specifice
Verifică compatibilitatea versiunii Node.js
Șterge node_modules și reinstalează dacă este necesar

Erori de autentificare API:

Verifică dacă fișierul .env există și are valorile corecte
Verifică dacă cheile API sunt valide și nu au expirat
Asigură-te că URL-urile endpoint-ului sunt corecte pentru regiunea ta

Variabile de mediu lipsă:

Copiază .env.copy în .env
Completează toate valorile cerute pentru lecția la care lucrezi
Repornește aplicația după actualizarea .env

Resurse suplimentare

Note specifice proiectului

Acesta este un depozit educațional axat pe învățare, nu pe cod de producție
Exemplele sunt intenționat simple și concentrate pe predarea conceptelor
Calitatea codului este echilibrată cu claritatea educațională
Fiecare lecție este autonomă și poate fi finalizată independent
Depozitul suportă multiple furnizori API: Azure OpenAI, OpenAI, Microsoft Foundry Models și furnizori offline precum Foundry Local și Ollama
Conținutul este multilingv cu fluxuri de lucru automate pentru traduceri
Comunitate activă pe Discord pentru întrebări și suport

Declinare a responsabilității: Acest document a fost tradus folosind serviciul de traducere AI Co-op Translator. În timp ce ne străduim pentru acuratețe, vă rugăm să rețineți că traducerile automate pot conține erori sau inexactități. Documentul original în limba sa nativă trebuie considerat sursa autorizată. Pentru informații critice, se recomandă traducerea profesională realizată de un om. Nu ne asumăm responsabilitatea pentru eventualele neînțelegeri sau interpretări greșite care decurg din utilizarea acestei traduceri.

About