README.md

---
language:
- tr
license: apache-2.0
base_model: Qwen/Qwen3-14B
library_name: transformers
tags:
- qwen3
- qwen
- turkish
- teknofest
- tubitak
- project-assistant
- report-writing
- merged-lora
pipeline_tag: text-generation
---

# Pusula AI

Pusula AI, TEKNOFEST ve TÜBİTAK proje geliştirme süreçleri için eğitilmiş Türkçe bir proje danışmanı asistanıdır.

Bu repo, `Qwen/Qwen3-14B` taban modeli üzerine LoRA yöntemiyle fine-tune edilmiş ve base model ile merge edilerek yayınlanmış tam model dosyalarını içerir.

## Kullanım Alanı

Model özellikle şu konular için tasarlanmıştır:

- TEKNOFEST / TÜBİTAK proje raporu yazımı
- KTR / ÖTR bölümleri
- Sistem mimarisi
- Risk analizi
- Test planı
- Başarı ölçütleri
- Özgün değer
- Jüri hazırlığı
- Teknik rapor dili düzeltme
- Alan dışı soruları reddetme
- Ölçülmemiş sayısal değerleri uydurmama
- Eksik bilgi varsa kullanıcıdan net bilgi isteme

## Temel Model

```text
Qwen/Qwen3-14B
```

## Model Türü

Bu sürüm **merged full model** olarak yüklenmiştir. Yani LoRA adapter base model içine birleştirilmiştir. Kullanım sırasında ayrıca PEFT adapter yüklemeye gerek yoktur.

## Eğitim Ayarları

| Parametre | Değer |
|---|---:|
| Fine-tune tipi | LoRA |
| Yayınlanan sürüm | Merged full model |
| Precision | BF16 |
| Sequence length | 4096 |
| LoRA rank | 64 |
| LoRA alpha | 128 |
| Epoch | 2 |
| Learning rate | 5e-5 |
| Effective batch size | 16 |
| Train örnek sayısı | 4947 |
| Eval örnek sayısı | 261 |
| Eğitim tarihi | 2026-06 |

## Eğitim ve Hızlı Test Metrikleri

Aşağıdaki değerler Colab eğitim çıktısına göre güncellenmelidir. Eğer `training_artifacts/` klasöründe loglar yüklendiyse ayrıntılı sonuçlar oradan incelenebilir.

| Metrik | Değer |
|---|---:|
| Final Training Loss | Colab çıktısından güncellenecek |
| Final Validation Loss | Colab çıktısından güncellenecek |
| Validation Perplexity | Colab çıktısından güncellenecek |
| Davranış Kontrol Başarı Oranı | Colab çıktısından güncellenecek |
| Alan Dışı Red Başarısı | Colab çıktısından güncellenecek |
| Dosya İsteği Güvenli Cevap Başarısı | Colab çıktısından güncellenecek |
| Sayı Uydurmama Başarısı | Colab çıktısından güncellenecek |

Not: Davranış kontrol metrikleri, notebook içindeki sabit test soruları üzerinden yapılan hızlı kontrol sonuçlarıdır. Daha kapsamlı değerlendirme için ayrı bir test seti ve insan/LLM hakem değerlendirmesi önerilir.

## Sistem Promptu

```text
Sen Pusula adlı TEKNOFEST/TÜBİTAK proje danışmanı asistanısın.
Proje raporu, KTR/ÖTR, sistem mimarisi, risk analizi, test planı, özgün değer ve jüri hazırlığı konularında Türkçe, net ve uygulanabilir cevap ver.
Alan dışı sorularda kısa şekilde reddet.
Bilmediğin veya ölçülmemiş bilgiyi uydurma; eksik bilgi varsa kullanıcıdan iste.
```

## Örnek Kullanım

```python
from transformers import AutoTokenizer, AutoModelForCausalLM
import torch

model_id = "Rudblest/Pusula_Ai"

tokenizer = AutoTokenizer.from_pretrained(model_id)

model = AutoModelForCausalLM.from_pretrained(
    model_id,
    device_map="auto",
    dtype=torch.bfloat16,
)

model.eval()

system_prompt = """Sen Pusula adlı TEKNOFEST/TÜBİTAK proje danışmanı asistanısın.
Proje raporu, KTR/ÖTR, sistem mimarisi, risk analizi, test planı, özgün değer ve jüri hazırlığı konularında Türkçe, net ve uygulanabilir cevap ver.
Alan dışı sorularda kısa şekilde reddet.
Bilmediğin veya ölçülmemiş bilgiyi uydurma; eksik bilgi varsa kullanıcıdan iste."""

question = "KTR'de risk analizi nasıl yazılır?"

messages = [
    {"role": "system", "content": system_prompt},
    {"role": "user", "content": question},
]

prompt = tokenizer.apply_chat_template(
    messages,
    tokenize=False,
    add_generation_prompt=True,
    enable_thinking=False,
)

inputs = tokenizer(prompt, return_tensors="pt").to(model.device)

with torch.no_grad():
    outputs = model.generate(
        **inputs,
        max_new_tokens=450,
        do_sample=False,
        pad_token_id=tokenizer.eos_token_id,
    )

answer = tokenizer.decode(
    outputs[0][inputs["input_ids"].shape[-1]:],
    skip_special_tokens=True
)

print(answer)
```

## Örnek Soru Türleri

Model şu tarz sorular için uygundur:

```text
KTR'de risk analizi nasıl yazılır?
İnsansız deniz aracı projesinde sistem mimarisi nasıl anlatılır?
TEKNOFEST raporunda özgün değer bölümü nasıl güçlendirilir?
Henüz test yapmadım ama %98 başarı yazabilir miyim?
Bu bölümü Word formatına uygun hale getirir misin?
```

## Önerilen Kullanım Formatı

Modelden daha iyi sonuç almak için proje bağlamını şu formatta vermek önerilir:

```text
Proje amacı:
Kullanılan donanımlar:
Yazılım altyapısı:
Sensörler:
Test ortamı:
Başarı kriterleri:
Kısıtlar:
İstenen rapor bölümü:
```

## Sınırlamalar

Bu model genel sohbet asistanı değildir. TEKNOFEST/TÜBİTAK proje geliştirme, teknik rapor yazımı ve jüri hazırlığı alanına odaklanmıştır.

Modelin ölçülmemiş başarı oranı, test sonucu, maliyet, gecikme, menzil veya performans değeri üretmesi beklenmez. Bu tür değerler kullanıcı tarafından verilmemişse hedef veya ölçüm planı olarak ifade edilmelidir.

Model hukuki, tıbbi, finansal veya kişisel yaşam danışmanlığı için tasarlanmamıştır. Alan dışı sorularda kısa şekilde reddetmesi beklenir.

## Eğitim Verisi Notu

Eğitim verisi; TEKNOFEST/TÜBİTAK proje raporu yazımı, sistem mimarisi, risk analizi, test planı, özgün değer, jüri hazırlığı, hata düzeltme, alan dışı reddetme ve ölçülmemiş metrikleri uydurmama davranışlarına odaklanan Türkçe instruction-output örneklerinden oluşur.

## Artifacts

Eğer yüklendiyse eğitim kayıtları ve test çıktıları şu klasörde bulunabilir:

```text
training_artifacts/
```

Önerilen dosyalar:

- `training_log.csv`
- `test_outputs_after_finetune.csv`
- `behavior_checks.csv`
- `training_validation_loss_combined.png`

## Lisans

Apache-2.0