generative-ai-for-beginners / ne

# AGENTS.md

## परियोजना अवलोकन

यो रिपोजिटोरीले जेनेरेटिभ AI को आधारभूत सिद्धान्त र अनुप्रयोग विकास सिकाउने २१-पाठ्यक्रम सार्वभौमिक पाठ्यक्रम समेटेको छ। यो पाठ्यक्रम शुरुवाती प्रयोगकर्ताहरुको लागि डिजाइन गरिएको हो र आधारभूत अवधारणाबाट उत्पादन तयार अनुप्रयोग निर्माणसम्म सबै कुराहरु समेट्छ।

**प्रमुख प्रविधिहरु:**
- Python 3.9+ पुस्तकालयहरु सहित: `openai`, `python-dotenv`, `tiktoken`, `azure-ai-inference`, `pandas`, `numpy`, `matplotlib`
- Node.js सहित TypeScript/JavaScript र पुस्तकालयहरु: `openai` (Azure OpenAI v1 endpoint + Responses API मार्फत), `@azure-rest/ai-inference` (Microsoft Foundry मोडेलहरु)
- Azure OpenAI सेवा, OpenAI API, तथा Microsoft Foundry मोडेलहरु (GitHub मोडेलहरु जुलाई २०२६ को अन्त्यमा सेवा बन्द हुँदैछ)
- अन्तरक्रियात्मक सिकाइका लागि Jupyter नोटबुकहरु
- निरन्तर विकास वातावरणका लागि Dev Containers

**रिपोजिटोरी संरचना:**
- २१ नम्बर सहितका पाठनिर्देशिका (००-२१) जसमा READMEs, कोड उदाहरणहरु र असाइनमेन्टहरु छन्
- विभिन्न कार्यान्वयनहरु: Python, TypeScript, र कहिलेकाहीँ .NET उदाहरणहरु
- ४०+ भाषाहरूका अनुवादहरू सहित अनुवाद निर्देशिका
- केन्द्रीयकृत कन्फिगरेसन `.env` फाइल मार्फत (टेम्पलेटको रूपमा `.env.copy` प्रयोग गर्नुहोस्)

## सेटअप आदेशहरू

### प्रारम्भिक रिपोजिटोरी सेटअप

```bash
# रिपोजिटरी क्लोन गर्नुहोस्
git clone https://github.com/microsoft/generative-ai-for-beginners.git
cd generative-ai-for-beginners

# वातावरण टेम्प्लेट प्रतिलिपि गर्नुहोस्
cp .env.copy .env
# तपाइँका API कुञ्जीहरू र अन्त्यबिन्दुहरूसँग .env सम्पादन गर्नुहोस्
```

### Python वातावरण सेटअप

```bash
# भर्चुअल वातावरण सिर्जना गर्नुहोस्
python3 -m venv venv

# भर्चुअल वातावरण सक्रिय गर्नुहोस्
# macOS/Linux मा:
source venv/bin/activate
# Windows मा:
venv\Scripts\activate

# निर्भरता स्थापना गर्नुहोस्
pip install -r requirements.txt
```

### Node.js/TypeScript सेटअप

```bash
# रुट स्तरका निर्भरता स्थापना गर्नुहोस् (प्रलेखन उपकरणको लागि)
npm install

# व्यक्तिगत पाठ TypeScript उदाहरणहरूको लागि, विशिष्ट पाठमा जानुहोस्:
cd 06-text-generation-apps/typescript/recipe-app
npm install
```

### Dev Container सेटअप (सिफारिस गरिएको)

रिपोजिटोरीमा GitHub Codespaces वा VS Code Dev Containers को लागि `.devcontainer` कन्फिगरेसन समावेश छ:

१. GitHub Codespaces वा Dev Containers एक्सटेन्सन सहित VS Code मा रिपोजिटोरी खोल्नुहोस्
२. Dev Container स्वचालित रूपमा:
   - `requirements.txt` बाट Python निर्भरता स्थापना गर्दछ
   - पोस्ट-क्रिएट स्क्रिप्ट चलाउँछ (`.devcontainer/post-create.sh`)
   - Jupyter कर्नेल सेटअप गर्दछ

## विकास कार्यप्रवाह

### वातावरण चरहरू

API पहुँच आवश्यक पर्ने सबै पाठहरू `.env` मा परिभाषित वातावरण चरहरू प्रयोग गर्छन्:

- `OPENAI_API_KEY` - OpenAI API का लागि
- `AZURE_OPENAI_API_KEY` - Microsoft Foundry मा Azure OpenAI का लागि (Azure OpenAI सेवा अब Microsoft Foundry को भाग: https://ai.azure.com)
- `AZURE_OPENAI_ENDPOINT` - Azure OpenAI अन्त बिन्दु URL (Foundry स्रोत अन्त बिन्दु)
- `AZURE_OPENAI_DEPLOYMENT` - च्याट पूरा गर्ने मोडेल डिप्लोयमेन्ट नाम (पाठ्यक्रम पूर्वनिर्धारित: `gpt-5-mini`)
- `AZURE_OPENAI_EMBEDDINGS_DEPLOYMENT` - एम्बेडिङ मोडेल डिप्लोयमेन्ट नाम (पाठ्यक्रम पूर्वनिर्धारित: `text-embedding-3-small`)
- `AZURE_OPENAI_API_VERSION` - API संस्करण (पूर्वनिर्धारित: `2024-10-21`)
- `HUGGING_FACE_API_KEY` - Hugging Face मोडेलहरूको लागि
- `AZURE_INFERENCE_ENDPOINT` - Microsoft Foundry मोडेलहरूको अन्त बिन्दु (बहु-प्रदाता मोडेल सूची)
- `AZURE_INFERENCE_CREDENTIAL` - Microsoft Foundry मोडेलहरूको API कुञ्जी (`GITHUB_TOKEN` को स्थानमा)
- `AZURE_INFERENCE_CHAT_MODEL` - नॉन-रिजोनिङ मोडेल (जस्तै `Llama-3.3-70B-Instruct`) जसलाई `temperature` उदाहरणहरूले प्रयोग गर्छन्, किनकि reasoning मोडेलहरूले स्याम्पलिङ नियन्त्रण समर्थन गर्दैनन्

### मोडेल सम्मेलनहरू (महत्त्वपूर्ण)

- **पूर्वनिर्धारित च्याट मोडेल `gpt-5-mini` हो** - हालको, अप्रचलित नभएको **reasoning** मोडेल। २०२६ सम्म पुराना temperature-सक्षम "mini" मोडेलहरू (`gpt-4o-mini`, `gpt-4.1-mini`) *अप्रचलित हुँदैछन्*, त्यसैले पाठ्यक्रम GPT-5 परिवारमा केन्द्रित छ।
- **Reasoning मोडेलहरूले `temperature` र `top_p` स्वीकार गर्दैनन्**, र `max_output_tokens` (Responses API) / `max_completion_tokens` (च्याट पूरा गर्न) प्रयोग गर्दछन् `max_tokens` को सट्टा। `gpt-5-mini` कल गर्ने नमूनाहरूमा `temperature`/`top_p`/`max_tokens` नथप्नुहोस्।
- **`temperature` देखाउनको लागि**, नमूनाहरू Microsoft Foundry मोडेलहरूको अन्त बिन्दु (`AZURE_INFERENCE_CHAT_MODEL`) मार्फत **Llama** मोडेल (`Llama-3.3-70B-Instruct`) प्रयोग गर्छन्। reasoning मोडेलहरूलाई स्याम्पलिङ नियन्त्रणको सट्टा प्रॉम्प्ट इन्जिनियरिङ + reasoning नियन्त्रणले मार्गदर्शन गर्नुहोस्।
- **फाइन-ट्युनिङ (पाठ १८)** ले `gpt-4.1-mini` राख्छ: GPT-5 ले मात्र पुनर्संरचना फाइन-ट्युनिङ (RFT) समर्थन गर्छ, देखाइएको सुपरभाइज्ड फाइन-ट्युनिङ (SFT) होइन।
- पाठ २० (Mistral) र २१ (Meta) ले `temperature`/`max_tokens` राख्छ किनभने तिनीहरू Mistral/Llama मोडेलहरू लक्षित गर्छन्, जुन तिनीहरूलाई समर्थन गर्छन्।

### Python उदाहरणहरू चलाउने तरिका

```bash
# पाठ सिकाइ निर्देशनामा जानुहोस्
cd 06-text-generation-apps/python

# पायथन स्क्रिप्ट चलाउनुहोस्
python aoai-app.py
```

### TypeScript उदाहरणहरू चलाउने तरिका

```bash
# टाइपस्क्रिप्ट अनुप्रयोग निर्देशकिमा जानुहोस्
cd 06-text-generation-apps/typescript/recipe-app

# टाइपस्क्रिप्ट कोड निर्माण गर्नुहोस्
npm run build

# अनुप्रयोग चलाउनुहोस्
npm start
```

### Jupyter नोटबुकहरू चलाउने तरिका

```bash
# रिपोजिटोरी मूलमा Jupyter सुरु गर्नुहोस्
jupyter notebook

# वा Jupyter विस्तारसहित VS Code प्रयोग गर्नुहोस्
```

### फरक पाठ प्रकारहरूसँग काम गर्ने तरिका

- **"Learn" पाठहरू**: README.md कागजात र अवधारणामा केन्द्रित
- **"Build" पाठहरू**: Python र TypeScript मा कार्यरत कोड उदाहरणहरू समावेश गर्छ
- प्रत्येक पाठसँग थियोरी, कोड वाकथ्रुहरू, र भिडियो सामग्री लिंक सहित README.md हुन्छ

## कोड शैली मार्गनिर्देशनहरू

### Python

- वातावरण चर व्यवस्थापनका लागि `python-dotenv` प्रयोग गर्नुहोस्
- API अन्तर्क्रियाका लागि `openai` लाइब्रेरी इम्पोर्ट गर्नुहोस्
- लिन्टिंगका लागि `pylint` प्रयोग गर्नुहोस् (केही उदाहरणहरूमा सहजताका लागि `# pylint: disable=all` छ)
- PEP 8 नामकरण सम्मेलनहरू पालना गर्नुहोस्
- API क्रेडेन्शियलहरू `.env` फाइलमा राख्नुहोस्, कहिल्यै कोडमा नराख्नुहोस्

### TypeScript

- वातावरण चरहरूको लागि `dotenv` प्याकेज प्रयोग गर्नुहोस्
- प्रत्येक एपको लागि `tsconfig.json` मा TypeScript कन्फिगरेसन
- Azure OpenAI का लागि `openai` प्याकेज प्रयोग गर्नुहोस् (क्लाइन्टलाई `/openai/v1/` endpoint मा पोइन्ट गरी `client.responses.create` कल गर्नुहोस्); Microsoft Foundry मोडेलका लागि `@azure-rest/ai-inference` प्रयोग गर्नुहोस्
- विकासका लागि `nodemon` प्रयोग गरेर अटो-रिलोड
- चलाउनुअघि बनाउनुहोस्: `npm run build` अनि `npm start`

### सामान्य सम्मेलनहरू

- कोड उदाहरणहरू सरल र शैक्षिक राख्नुहोस्
- महत्त्वपूर्ण अवधारणाहरू व्याख्या गर्ने टिप्पणीहरू समावेश गर्नुहोस्
- प्रत्येक पाठको कोड स्व-निहित र चलाउन योग्य हुनु पर्छ
- सुसंगत नामाकरण प्रयोग गर्नुहोस्: Azure OpenAI को लागि `aoai-` उपसर्ग, OpenAI API को लागि `oai-`, Microsoft Foundry मोडेलहरू लागि `githubmodels-` (GitHub Models युगबाट रहिआएको पूर्वसर्ग)

## दस्तावेजीकरण दिशानिर्देशहरू

### मार्कडाउन शैली

- सबै URL हरू `[पाठ](../../url)` ढाँचामा सुरक्षित गर्नुहोस्, कुनै अतिरिक्त स्थान बिना
- सापेक्ष लिंकहरु `./` वा `../` बाट सुरु हुनुपर्छ
- सबै Microsoft डोमेन लिंकहरुमा ट्र्याकिङ ID हुनु आवश्यक छ: `?WT.mc_id=academic-105485-koreyst`
- URL मा देश-विशिष्ट लोकलहरु नराख्नुहोस् (जस्तै `/en-us/` बाट बच्नुहोस्)
- छविहरू `./images` फोल्डरमा वर्णनात्मक नामहरूसँग राख्नुहोस्
- फाइल नामहरूमा अंग्रेजी अक्षरहरू, अंकहरू र ड्यास प्रयोग गर्नुहोस्

### अनुवाद समर्थन

- रिपोजिटोरीले ४०+ भाषाहरूलाई स्वचालित GitHub Actions मार्फत समर्थन गर्छ
- अनुवादहरू `translations/` निर्देशिकामा राखिन्छ
- आंशिक अनुवादहरू पेश नगर्नुहोस्
- मेसिन अनुवादहरू स्वीकार्य छैनन्
- अनुवादित छविहरू `translated_images/` निर्देशिकामा संग्रहित छन्

## परीक्षण र प्रमाणीकरण

### पूर्व-प्रस्तुतीकरण जाँचहरू

यो रिपोजिटोरी प्रमाणीकरणको लागि GitHub Actions प्रयोग गर्छ। PR पेश गर्नु अघि:

१. **Markdown लिंकहरू जाँच गर्नुहोस्**:
   ```bash
   # validate-markdown.yml वर्कफ्लोले जाँच गर्दछ:
   # - भत्किएका सापेक्ष पथहरू
   # - पथहरूमा अझै नभएका ट्र्याकिङ ID हरू
   # - URL हरूमा अझै नभएका ट्र्याकिङ ID हरू
   # - देशको लोकेल सहितका URL हरू
   # - भत्किएका बाह्य URL हरू
   ```

२. **म्यानुअल परीक्षण**:
   - Python उदाहरणहरू परीक्षण गर्नुहोस्: venv सक्रिय पार्नुहोस् र स्क्रिप्ट चलाउनुहोस्
   - TypeScript उदाहरणहरू परीक्षण गर्नुहोस्: `npm install`, `npm run build`, `npm start`
   - वातावरण चरहरू ठीकरूपमा कन्फिगर गरिएको छ कि छैन जाँच्नुहोस्
   - API कुञ्जीहरूले कोड उदाहरणहरूसँग काम गर्छन् कि छैन सुनिश्चित गर्नुहोस्

३. **कोड उदाहरणहरू**:
   - सबै कोड त्रुटिविना चल्छ सुनिश्चित गर्नुहोस्
   - जहाँ लागू हुन्छ, Azure OpenAI र OpenAI API दुवैसँग परीक्षण गर्नुहोस्
   - जहाँ समर्थन छ Microsoft Foundry मोडेलहरूसँग उदाहरणहरू काम गर्छन् कि छैन जाँच्नुहोस्

### कुनै स्वचालित टेस्ट छैनन्

यो शैक्षिक रिपोजिटोरी हो जुन टुटोरियल र उदाहरणहरूमा केन्द्रित छ। कुनै एकाइ परीक्षण वा एकीकरण परीक्षणहरू चलाउन छैनन्। प्रमाणीकरण मुख्य रूपमा:
- कोड उदाहरणहरूको म्यानुअल परीक्षण
- Markdown प्रमाणीकरणका लागि GitHub Actions
- शैक्षिक सामग्रीको समुदाय समीक्षा

## पुल रिक्वेस्ट दिशानिर्देशहरू

### पेश गर्नु अघि

१. जहाँ लागू हुन्छ, Python र TypeScript दुबैमा कोड परिवर्तनहरू परीक्षण गर्नुहोस्
२. Markdown प्रमाणीकरण चलाउनुहोस् (स्वचालित रूपमा PR मा ट्रिगर हुन्छ)
३. सबै Microsoft URL मा ट्र्याकिङ ID सुनिश्चित गर्नुहोस्
४. सापेक्ष लिंकहरू सही छन् कि छैन जाँच्नुहोस्
५. छविहरू ठीकसँग सन्दर्भित छन् कि छैन सुनिश्चित गर्नुहोस्

### PR शीर्षक ढाँचा

- वर्णनात्मक शीर्षकहरू प्रयोग गर्नुहोस्: `[Lesson 06] Fix Python example typo` वा `Update README for lesson 08`
- जहाँ लागू हुन्छ समस्या नम्बरहरू सन्दर्भ गर्नुहोस्: `Fixes #123`

### PR वर्णन

- के परिवर्तन भयो र किन स्पष्ट गर्नुहोस्
- सम्बन्धित समस्याहरूको लिंक दिनुहोस्
- कोड परिवर्तनका लागि कुन उदाहरणहरू परीक्षण गरियो उल्लेख गर्नुहोस्
- अनुवाद PR का लागि, पूर्ण अनुवादका लागि सबै फाइलहरू समावेश गर्नुहोस्

### योगदान आवश्यकताहरू

- Microsoft CLA मा हस्ताक्षर गर्नुहोस् (पहिलो PR मा स्वचालित)
- परिवर्तन गर्नु अघि रिपोजिटोरीलाई आफ्नो खाता मा फोर्क गर्नुहोस्
- प्रत्येक तर्कसंगत परिवर्तनको लागि एउटा PR (असम्बन्धित सुधारहरू मिलाउनुहोस् न)
- सम्भव भएमा PR लाई केन्द्रित र सानो राख्नुहोस्

## सामान्य कार्यप्रवाहहरू

### नयाँ कोड उदाहरण थप्ने तरिका

१. उपयुक्त पाठ निर्देशिकामा जानुहोस्
२. `python/` वा `typescript/` उपनिर्देशिका मा उदाहरण सिर्जना गर्नुहोस्
३. नामकरण सम्मेलन पालन गर्नुहोस्: `{provider}-{example-name}.{py|ts|js}`
४. वास्तविक API क्रेडेन्शियलसहित परीक्षण गर्नुहोस्
५. नयाँ वातावरण चरहरू पाठको README मा कागजात गर्नुहोस्

### दस्तावेजीकरण अद्यावधिक गर्ने तरिका

१. पाठ निर्देशिकामा README.md सम्पादन गर्नुहोस्
२. Markdown दिशानिर्देशहरू पालना गर्नुहोस् (ट्र्याकिङ ID, सापेक्ष लिंकहरू)
३. अनुवाद अद्यावधिकहरूले GitHub Actions मार्फत व्यवस्थापन हुन्छन् (म्यानुअल सम्पादन नगर्नुहोस्)
४. सबै लिंकहरू मान्य छन् कि छैन जाँच्नुहोस्

### Dev Containers सँग काम गर्ने तरिका

१. रिपोजिटोरीमा `.devcontainer/devcontainer.json` समाविष्ट छ
२. पोस्ट-क्रिएट स्क्रिप्टले Python निर्भरता स्वचालित रूपमा स्थापना गर्छ
३. Python र Jupyter का एक्सटेन्सनहरू पूर्व-कन्फिगर गरिएको छ
४. वातावरण `mcr.microsoft.com/devcontainers/universal:2.11.2` मा आधारित छ

## प्रकाशन र तैनाती

यो अध्ययनको लागि रिपोजिटोरी हो - कुनै तैनाती प्रक्रिया छैन। पाठ्यक्रमले निम्नबाट उपभोग गरिन्छ:

१. **GitHub रिपोजिटोरी**: कोड र कागजातमा सिधा पहुँच
२. **GitHub Codespaces**: पूर्व-कन्फिगर सेटअप सहित छिटो विकास वातावरण
३. **Microsoft Learn**: सामग्री आधिकारिक सिकाइ प्लेटफर्ममा सिन्डिकेट हुन सक्छ
४. **docsify**: Markdown बाट निर्मित दस्तावेजीकरण साइट (हेर्नुहोस् `docsifytopdf.js` र `package.json`)

### दस्तावेजीकरण साइट निर्माण गर्ने तरिका

```bash
# कागजातबाट PDF बनाउनुहोस् (आवश्यक परे)
npm run convert
```

## समस्या समाधान

### सामान्य समस्या

**Python इम्पोर्ट त्रुटिहरू**:
- भर्चुअल वातावरण सक्रिय छ कि छैन सुनिश्चित गर्नुहोस्
- `pip install -r requirements.txt` चलाउनुहोस्
- Python संस्करण ३.९+ छ कि छैन जाँच्नुहोस्

**TypeScript बनाउने त्रुटिहरू**:
- विशेष एप निर्देशिकामा `npm install` चलाउनुहोस्
- Node.js संस्करण उपयुक्त छ कि छैन हेर्नुहोस्
- `node_modules` खाली गरेर आवश्यकता अनुसार पुनः स्थापना गर्नुहोस्

**API प्रमाणीकरण त्रुटिहरू**:
- `.env` फाइल छ र मानहरू ठीक छन् कि छैन पक्का गर्नुहोस्
- API कुञ्जीहरू वैध र अवधी समाप्त नभएको हुनुपर्छ
- तपाईंको क्षेत्रको लागि अन्त बिन्दु URL ठीक छन् कि छैन जाँच्नुहोस्

**वातावरण चरहरू हराएको**:
- `.env.copy` लाई `.env` मा प्रतिलिपि गर्नुहोस्
- तपाईँ काम गरिरहेको पाठको सबै चाहिने मानहरू भर्नुहोस्
- `.env` अपडेट गरेपछि तपाईंको अनुप्रयोग पुनः सुरु गर्नुहोस्

## अतिरिक्त स्रोतहरू

- [पाठ्यक्रम सेटअप मार्गदर्शन](./00-course-setup/README.md?WT.mc_id=academic-105485-koreyst)
- [योगदान गर्ने दिशानिर्देशहरू](./CONTRIBUTING.md)
- [व्यवहार संहिता](./CODE_OF_CONDUCT.md)
- [सुरक्षा नीति](./SECURITY.md)
- [Azure AI डिस्कोर्ड](https://aka.ms/genai-discord?WT.mc_id=academic-105485-koreyst)
- [उन्नत कोड नमूनाहरूको सङ्ग्रह](https://aka.ms/genai-beg-code?WT.mc_id=academic-105485-koreyst)

## परियोजना-विशेष नोटहरू

- यो **शैक्षिक रिपोजिटोरी** हो जुन सिकाइमा केन्द्रित छ, उत्पादन कोडमा होइन
- उदाहरणहरू जानाजानी साधारण र अवधारणाहरू सिकाउन केन्द्रित छन्
- कोड गुणस्तरलाई शैक्षिक स्पष्टतासँग सन्तुलनमा राखिएको छ
- प्रत्येक पाठ स्व-निहित छ र स्वतन्त्र रूपमा पूरा गर्न सकिन्छ
- रिपोजिटोरीले एक भन्दा बढी API प्रदायकहरू समर्थन गर्छ: Azure OpenAI, OpenAI, Microsoft Foundry मोडेलहरू, र अफलाइन प्रदायकहरू जस्तै Foundry Local र Ollama
- सामग्री बहुभाषिक छ र स्वचालित अनुवाद कार्यप्रवाहहरू छन्
- प्रश्न र समर्थनका लागि सक्रिय समुदाय डिस्कोर्डमा छ

---

<!-- CO-OP TRANSLATOR DISCLAIMER START -->
**अस्वीकरण**:
यो दस्तावेज़ AI अनुवाद सेवा [Co-op Translator](https://github.com/Azure/co-op-translator) प्रयोग गरेर अनुवाद गरिएको हो। हामी सही हुन प्रयास गर्छौं, तर कृपया जानकार हुनुस् कि स्वचालित अनुवादमा त्रुटिहरू वा अशुद्धताहरू हुन सक्छन्। मूल दस्तावेज़ यसको मूल भाषामा आधिकारिक स्रोत मानिनुपर्छ। महत्वपूर्ण जानकारीका लागि व्यावसायिक मानव अनुवाद सिफारिस गरिन्छ। यस अनुवादको प्रयोगबाट उत्पन्न कुनै पनि गलत बुझाइ वा त्रुटिको लागि हामी जिम्मेवार छैनौं।
<!-- CO-OP TRANSLATOR DISCLAIMER END -->