tr

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

AGENTS.md

Proje Genel Bakışı

Bu depo, Üretken Yapay Zeka temel bilgileri ve uygulama geliştirmeyi öğreten kapsamlı 21 derslik bir müfredat içerir. Kurs, yeni başlayanlar için tasarlanmış olup temel kavramlardan üretime hazır uygulamalar oluşturmaya kadar her şeyi kapsar.

Ana Teknolojiler:

• Python 3.9+ ve kütüphaneler: openai, python-dotenv, tiktoken, azure-ai-inference, pandas, numpy, matplotlib
• Node.js ile TypeScript/JavaScript ve kütüphaneler: openai (Azure OpenAI v1 endpoint ve Responses API), @azure-rest/ai-inference (Microsoft Foundry Modelleri)
• Azure OpenAI Servisi, OpenAI API ve Microsoft Foundry Modelleri (GitHub Modelleri Temmuz 2026 sonunda kullanımdan kalkıyor)
• Etkileşimli öğrenme için Jupyter Notebooks
• Tutarlı geliştirme ortamı için Dev Containers

Depo Yapısı:

• 21 numaralandırılmış ders dizinleri (00-21) içinde README’ler, kod örnekleri ve ödevler
• Birden çok uygulama: Python, TypeScript ve bazen .NET örnekleri
• 40+ dil versiyonları içeren çeviri dizini
• Merkezi yapılandırma .env dosyası ile (şablon olarak .env.copy kullanılabilir)

Kurulum Komutları

Başlangıç Depo Kurulumu

# Depoyu klonlayın
git clone https://github.com/microsoft/generative-ai-for-beginners.git
cd generative-ai-for-beginners

# Ortam şablonunu kopyalayın
cp .env.copy .env
# API anahtarlarınız ve uç noktalarınızla .env dosyasını düzenleyin

Python Ortamının Kurulumu

# Sanal ortam oluştur
python3 -m venv venv

# Sanal ortamı aktifleştir
# macOS/Linux üzerinde:
source venv/bin/activate
# Windows üzerinde:
venv\Scripts\activate

# Bağımlılıkları yükle
pip install -r requirements.txt

Node.js/TypeScript Kurulumu

# Kök düzeyde bağımlılıkları yükleyin (dokümantasyon araçları için)
npm install

# Bireysel ders TypeScript örnekleri için, belirli derse gidin:
cd 06-text-generation-apps/typescript/recipe-app
npm install

Dev Container Kurulumu (Önerilir)

Depo, GitHub Codespaces veya VS Code Dev Containers için .devcontainer yapılandırmasını içerir:

1. Depoyu GitHub Codespaces veya Dev Containers eklentisi ile VS Code’da açın
2. Dev Container otomatik olarak:
   • requirements.txt dosyasından Python bağımlılıklarını yükler
   • Post-create scriptini çalıştırır (.devcontainer/post-create.sh)
   • Jupyter çekirdeğini kurar

Geliştirme İş Akışı

Ortam Değişkenleri

API erişimi gerektiren tüm dersler .env dosyasında tanımlanan ortam değişkenlerini kullanır:

• OPENAI_API_KEY - OpenAI API için
• AZURE_OPENAI_API_KEY - Microsoft Foundry’de Azure OpenAI için (Azure OpenAI Servisi artık Microsoft Foundry’nin parçası: https://ai.azure.com)
• AZURE_OPENAI_ENDPOINT - Azure OpenAI uç nokta URL’si (Foundry kaynak uç noktası)
• AZURE_OPENAI_DEPLOYMENT - Chat tamamlama modeli dağıtım adı (kurs varsayılanı: gpt-5-mini)
• AZURE_OPENAI_EMBEDDINGS_DEPLOYMENT - Embeddings modeli dağıtım adı (kurs varsayılanı: text-embedding-3-small)
• AZURE_OPENAI_API_VERSION - API sürümü (varsayılan: 2024-10-21)
• HUGGING_FACE_API_KEY - Hugging Face modelleri için
• AZURE_INFERENCE_ENDPOINT - Microsoft Foundry Modeller uç noktası (çok sağlayıcılı model kataloğu)
• AZURE_INFERENCE_CREDENTIAL - Microsoft Foundry Modeller API anahtarı (GITHUB_TOKEN yerine geçer)
• AZURE_INFERENCE_CHAT_MODEL - temperature örneklerinde kullanılan, örnekleme kontrollerini desteklemeyen bir akıl yürütme modeli olmayan model (ör. Llama-3.3-70B-Instruct)

Model Kuralları (önemli)

• Varsayılan sohbet modeli gpt-5-mini - güncel, kullanımdan kalkmamış bir akıl yürütme modeli. 2026 itibarıyla daha eski, sıcaklık destekli "mini" modeller (gpt-4o-mini, gpt-4.1-mini) kullanımdan kaldırılmaktadır, bu nedenle müfredat GPT-5 ailesine standartlaştırılmıştır.
• Akıl yürütme modelleri temperature ve top_p parametrelerini reddeder, ve max_output_tokens (Responses API) / max_completion_tokens (sohbet tamamlama) kullanır; max_tokens kullanılmaz. gpt-5-mini çağıran örneklere temperature/top_p/max_tokens eklemeyin.
• temperature göstermek için örneklerde Microsoft Foundry Modeller uç noktası (AZURE_INFERENCE_CHAT_MODEL) üzerinden bir Llama modeli (Llama-3.3-70B-Instruct) kullanılır. Akıl yürütme modellerini örnekleme düğmeleri yerine prompt mühendisliği ve akıl yürütme kontrolleriyle yönlendirin.
• Mikro eğitim (ders 18) gpt-4.1-mini modelini korur: GPT-5 yalnızca pekiştirmeli mikro eğitim (RFT) destekler, orada gösterilen denetimli mikro eğitim (SFT) değil.
• Dersler 20 (Mistral) ve 21 (Meta) temperature/max_tokens parametrelerini korur çünkü Mistral/Llama modellerini hedeflerler, bu parametreleri desteklerler.

Python Örneklerini Çalıştırma

# Ders dizinine gidin
cd 06-text-generation-apps/python

# Bir Python betiği çalıştırın
python aoai-app.py

TypeScript Örneklerini Çalıştırma

# TypeScript uygulama dizinine gidin
cd 06-text-generation-apps/typescript/recipe-app

# TypeScript kodunu derleyin
npm run build

# Uygulamayı çalıştırın
npm start

Jupyter Notebooks Çalıştırma

# Depo kökünde Jupyter'i başlat
jupyter notebook

# Veya Jupyter eklentisi ile VS Code'u kullanın

Farklı Ders Türleriyle Çalışma

• "Öğren" dersleri: README.md belgeleri ve kavramlara odaklanır
• "İnşa et" dersleri: Python ve TypeScript'te çalışan kod örnekleri içerir
• Her dersin teori, kod açıklamaları ve video bağlantıları içeren bir README.md dosyası vardır

Kod Stili Kılavuzları

Python

• Ortam değişkenleri yönetimi için python-dotenv kullanın
• API etkileşimleri için openai kütüphanesini içe aktarın
• Linting için pylint kullanın (bazı örneklerde basitlik için # pylint: disable=all bulunmaktadır)
• PEP 8 isimlendirme kurallarına uyun
• API kimlik bilgilerini .env dosyasına kaydedin, kodda asla tutmayın

TypeScript

• Ortam değişkenleri için dotenv paketi kullanın
• Her uygulama için tsconfig.json TypeScript yapılandırması
• Azure OpenAI için openai paketini kullanın (istemciyi /openai/v1/ endpoint’ine yönlendirin ve client.responses.create çağırın); Microsoft Foundry Modelleri için @azure-rest/ai-inference kullanın
• Otomatik yenileme ile geliştirme için nodemon kullanın
• Çalıştırmadan önce inşa edin: npm run build sonra npm start

Genel Kurallar

• Kod örneklerini basit ve öğretici tutun
• Anahtar kavramları açıklayan yorumlar ekleyin
• Her dersin kodu kendi içinde tamamlanabilir ve çalıştırılabilir olmalı
• Tutarlı isimlendirme kullanın: Azure OpenAI için aoai- ön eki, OpenAI API için oai-, Microsoft Foundry Modelleri için githubmodels- (GitHub Modelleri döneminden kalan eski ön ek)

Dokümantasyon Kılavuzları

Markdown Stili

• Tüm URL’ler fazladan boşluk olmadan [text](../../url) formatında olmalı
• Göreceli bağlantılar ./ veya ../ ile başlamalı
• Microsoft alan adlarına yapılan tüm bağlantılar izleme kimliği içermeli: ?WT.mc_id=academic-105485-koreyst
• URL'lerde ülkeye özel yerel ayarlar olmamalı (örneğin /en-us/ kullanımından kaçının)
• Görseller ./images klasöründe açıklayıcı adlarla saklanır
• Dosya adlarında İngilizce harfler, sayılar ve tire kullanılmalı

Çeviri Desteği

• Depo, otomatik GitHub Actions ile 40+ dil desteği sunar
• Çeviriler translations/ dizininde tutulur
• Kısmi çeviriler gönderilmemelidir
• Makine çevirileri kabul edilmez
• Çevrilmiş görseller translated_images/ dizininde saklanır

Test ve Doğrulama

Gönderim Öncesi Kontroller

Bu depo doğrulama için GitHub Actions kullanır. PR göndermeden önce:

1. Markdown Bağlantılarını Kontrol Edin:

   # The validate-markdown.yml iş akışı şunları kontrol eder:
   # - Kırık göreli yollar
   # - Yollarda eksik takip kimlikleri
   # - URL'lerde eksik takip kimlikleri
   # - Ülke yerel ayarına sahip URL'ler
   # - Kırık dış URL'ler

2. Manuel Test:

   • Python örneklerini test edin: Sanal ortamı etkinleştirin ve betikleri çalıştırın
   • TypeScript örneklerini test edin: npm install, npm run build, npm start
   • Ortam değişkenlerinin doğru yapılandırıldığını doğrulayın
   • Kod örnekleriyle API anahtarlarının çalıştığını kontrol edin

3. Kod Örnekleri:

   • Tüm kodun hatasız çalıştığından emin olun
   • Uygunsa hem Azure OpenAI hem OpenAI API ile test edin
   • Desteklenen yerlerde Microsoft Foundry Modellerle çalıştığını doğrulayın

Otomatik Test Yok

Bu eğitim amaçlı bir depo olup birim testi veya entegrasyon testi yoktur. Doğrulama öncelikle şunlardan oluşur:

• Kod örneklerinin manuel testi
• Markdown doğrulama için GitHub Actions
• Eğitim içeriğinin topluluk incelemesi

Çekme İsteği (Pull Request) Kılavuzları

Göndermeden Önce

1. Uygun ise hem Python hem TypeScript’te kod değişikliklerini test edin
2. Markdown doğrulamasını çalıştırın (PR ile otomatik tetiklenir)
3. Tüm Microsoft URL’lerinde izleme kimliklerinin varlığını doğrulayın
4. Göreceli bağlantıların geçerli olduğunu kontrol edin
5. Görsellerin doğru referanslandığını doğrulayın

PR Başlık Formatı

• Açıklayıcı başlıklar kullanın: [Lesson 06] Python örneğinde yazım hatası düzeltme veya Ders 08 için README güncellemesi
• Uygunsa ilgili issue numaralarına referans verin: Fixes #123

PR Açıklaması

• Ne değiştirildi ve neden açıkça belirtin
• İlgili issue’lara bağlantı verin
• Kod değişikliklerinde hangi örneklerin test edildiğini açıklayın
• Çeviri PR’lerinde tamamlanmış çeviri için tüm dosyalar dahil edilmeli

Katkı Koşulları

• Microsoft CLA’ya imza atın (ilk PR’de otomatik)
• Değişiklik yapmadan önce depoyu kendi hesabınıza fork edin
• Her mantıksal değişiklik için bir PR oluşturun (ilgili olmayan düzeltmeleri birleştirmeyin)
• Mümkün olduğunca PR’leri odaklı ve küçük tutun

Ortak İş Akışları

Yeni Bir Kod Örneği Ekleme

1. İlgili ders dizinine gidin
2. python/ veya typescript/ alt dizininde örnek oluşturun
3. İsimlendirme kurallarına uyun: {provider}-{örnek-ismi}.{py|ts|js}
4. Gerçek API kimlik bilgileriyle test edin
5. Yeni ortam değişkenlerini ders README’sinde belgeleyin

Dokümantasyonu Güncelleme

1. Ders dizinindeki README.md dosyasını düzenleyin
2. Markdown kurallarına uyun (izleme kimlikleri, göreceli bağlantılar)
3. Çeviriler GitHub Actions tarafından otomatik güncellenir (manuel değişiklik yapmayın)
4. Tüm bağlantıların geçerli olduğundan emin olun

Dev Containers ile Çalışma

1. Depoda .devcontainer/devcontainer.json dosyası bulunur
2. Post-create script otomatik olarak Python bağımlılıklarını yükler
3. Python ve Jupyter için eklentiler önceden yapılandırılmıştır
4. Ortam mcr.microsoft.com/devcontainers/universal:2.11.2 temel alınmıştır

Dağıtım ve Yayınlama

Bu öğrenme amaçlı bir depo - dağıtım süreci yoktur. Müfredat şu yollardan tüketilir:

1. GitHub Deposu: Koda ve dokümantasyona doğrudan erişim
2. GitHub Codespaces: Önceden yapılandırılmış anlık geliştirme ortamı
3. Microsoft Learn: İçerik resmi öğrenme platformuna entegre edilebilir
4. docsify: Markdown’dan oluşturulmuş dokümantasyon sitesi (docsifytopdf.js ve package.json bakınız)

Dokümantasyon Sitesi Oluşturma

# Gerekirse belgelerden PDF oluşturun
npm run convert

Sorun Giderme

Yaygın Sorunlar

Python İçe Aktarma Hataları:

• Sanal ortamın etkinleştirildiğinden emin olun
• pip install -r requirements.txt komutunu çalıştırın
• Python sürümünün 3.9+ olduğundan emin olun

TypeScript Derleme Hataları:

• Belirli uygulama dizininde npm install çalıştırın
• Node.js sürümünün uyumlu olduğunu kontrol edin
• Gerekirse node_modules klasörünü temizleyip yeniden yükleyin

API Kimlik Doğrulama Hataları:

• .env dosyasının mevcut ve doğru değerler içerdiğini doğrulayın
• API anahtarlarının geçerli ve süresinin dolmamış olduğunu kontrol edin
• Bölgenize uygun uç nokta URL’lerinin doğru olduğundan emin olun

Eksik Ortam Değişkenleri:

• .env.copy dosyasını .env olarak kopyalayın
• Üzerinde çalıştığınız derse ait tüm gerekli değerleri doldurun
• .env güncellendikten sonra uygulamanızı yeniden başlatın

Ek Kaynaklar

• Kurs Kurulum Kılavuzu
• Katkı Sağlama Kılavuzları
• Davranış Kuralları
• Güvenlik Politikası
• Azure AI Discord
• Gelişmiş Kod Örnekleri Koleksiyonu

Projeye Özel Notlar

• Bu bir eğitim deposu olup üretim kodu için değil
• Örnekler bilinçli olarak basit ve kavram öğretmeye odaklıdır
• Kod kalitesi eğitimde açıklıkla dengelenmiştir
• Her ders bağımsızdır ve tek başına tamamlanabilir
• Depo birden çok API sağlayıcısını destekler: Azure OpenAI, OpenAI, Microsoft Foundry Modelleri ve offline sağlayıcılar (Foundry Local, Ollama gibi)
• İçerik çok dilli olup otomatik çeviri iş akışları vardır
• Sorular ve destek için Discord’da aktif bir topluluk mevcuttur

Feragatname: Bu belge, AI çeviri hizmeti Co-op Translator kullanılarak çevrilmiştir. Doğruluk için çaba sarf etsek de, otomatik çevirilerin hata veya yanlışlık içerebileceğini lütfen unutmayınız. Orijinal belge, kendi dilinde yetkili kaynak olarak kabul edilmelidir. Kritik bilgiler için profesyonel insan çevirisi önerilir. Bu çevirinin kullanımı sonucu ortaya çıkabilecek yanlış anlamalardan veya yanlış yorumlamalardan sorumlu değiliz.