Hugging Face Nasıl Kullanılır? Model Rehberi 2026

Hugging Face, 2023–2026 arasında açık kaynak yapay zeka alanının fiili merkezi haline geldi. 900.000’den fazla model, 200.000 veri kümesi ve onlarca aktif kütüphane barındırıyor; bir bakıma GitHub, PyPI ve arXiv’in ortak bir karışımı. Bu dev platforma nasıl başlarsınız, hangi araçları ne zaman kullanırsınız?

Bu rehberde hesap oluşturmadan model indirmeye, pipeline API’sinden Spaces’e kadar adım adım ilerliyoruz.

Hesap ve Erişim Tokeni

Çoğu açık model indirmek için hesap gerekmez; ancak Llama 3, Mistral gibi “gated” modeller ve Inference API için ücretsiz bir hesap şart.

1. huggingface.co adresinde kayıt olun.
2. Settings → Access Tokens → New Token yoluyla bir token oluşturun.
3. Terminalde oturum açın:

pip install huggingface_hub
huggingface-cli login
# Token'ı yapıştırın

Bu adımdan sonra ~/.cache/huggingface/ altına kaydedilen token, transformers ve huggingface_hub kütüphaneleri tarafından otomatik okunur.

Model Hub’ı Anlamak

Hub’daki her model kartı üç kritik bilgi içerir:

Model kartının sağ üstündeki “Use this model” butonu, kütüphaneye özgü hazır kodu verir. Bunu kopyalamak en hızlı başlangıç yöntemidir.

pipeline ile İlk Çıkarım

Hugging Face’in en pratik arayüzü pipeline. Modeli, tokenizer’ı ve son işleme adımlarını tek bir nesne altında toplar.

from transformers import pipeline

# Duygu analizi — varsayılan model otomatik indirilir
clf = pipeline("sentiment-analysis")
sonuc = clf("Bu ürün gerçekten beklentilerimi karşıladı.")
print(sonuc)
# [{'label': 'POSITIVE', 'score': 0.99}]

Belirli bir model kullanmak istiyorsanız model parametresini geçin:

gen = pipeline(
    "text-generation",
    model="mistralai/Mistral-7B-Instruct-v0.3",
    device_map="auto",   # GPU varsa otomatik kullanır
    max_new_tokens=200,
)
cevap = gen("Yapay zekanın temel bileşenleri nelerdir?")
print(cevap[0]["generated_text"])

device_map="auto" parametresi çok GPU’lu makinelerde model katmanlarını otomatik dağıtır. Tek GPU veya CPU’da da çalışır.

Yaygın pipeline görev tipleri

text-generation        → LLM tamamlama
text2text-generation   → T5, BART gibi seq2seq
summarization          → Özetleme
translation_en_to_tr   → Çeviri
question-answering     → Soru-cevap (extractive)
fill-mask              → BERT tarzı maske doldurma
image-classification   → Görsel sınıflandırma
automatic-speech-recognition → Konuşma tanıma

Model ve Tokenizer’ı Ayrı Yüklemek

pipeline kullanışlı olsa da prodüksiyonda daha fazla kontrol gerekir. Bu durumda model ile tokenizer’ı ayrı yükleyin:

from transformers import AutoTokenizer, AutoModelForCausalLM
import torch

model_id = "google/gemma-2-2b-it"

tokenizer = AutoTokenizer.from_pretrained(model_id)
model = AutoModelForCausalLM.from_pretrained(
    model_id,
    torch_dtype=torch.bfloat16,
    device_map="auto",
)

mesaj = [{"role": "user", "content": "Python'da liste anlamayı açıkla."}]
girdi = tokenizer.apply_chat_template(mesaj, return_tensors="pt").to(model.device)

cikti = model.generate(girdi, max_new_tokens=300, do_sample=True, temperature=0.7)
print(tokenizer.decode(cikti[0], skip_special_tokens=True))

AutoTokenizer ve AutoModelForCausalLM, model kartındaki config.json’ı okuyarak doğru sınıfı otomatik seçer. Bu sayede modeli değiştirdiğinizde kodu düzenlemeniz gerekmez.

Embedding Modelleri

Semantic arama, RAG pipeline’ları veya kümeleme için /terim/embedding (vektör temsili) modellerine ihtiyaç duyarsınız. sentence-transformers kütüphanesi bu işi basitleştirir:

pip install sentence-transformers

from sentence_transformers import SentenceTransformer

model = SentenceTransformer("BAAI/bge-m3")  # Çok dilli, güçlü model

cumleler = [
    "Büyük dil modelleri nasıl çalışır?",
    "LLM mimarisinin temel bileşenleri nelerdir?",
    "Kedi balık yer mi?",
]

vektorler = model.encode(cumleler)
print(vektorler.shape)  # (3, 1024)

BAAI/bge-m3 Türkçe dahil 100’den fazla dili destekler ve 2026 itibarıyla en dengeli çok dilli embedding modellerinden biridir. Ürettiğiniz vektörleri /blog/pinecone-vs-chromadb-vs-qdrant-pgvector-vektor-veritabani-karsilastirma-2026 adresinde karşılaştırdığımız vektör veri tabanlarından birine kaydedebilirsiniz.

Inference API: Lokal GPU Olmadan Çalışmak

Modelı indirmek yerine Hugging Face’in bulut altyapısını REST API olarak kullanabilirsiniz. Ücretsiz katmanda oran sınırı var; ağır yük için Inference Endpoints veya Pro abonelik gerekir.

import requests

API_URL = "https://api-inference.huggingface.co/models/mistralai/Mistral-7B-Instruct-v0.3"
headers = {"Authorization": "Bearer hf_..."}

def sorgula(yuk):
    yanit = requests.post(API_URL, headers=headers, json=yuk)
    return yanit.json()

cikti = sorgula({"inputs": "Transformer mimarisi nedir?"})
print(cikti)

Prodüksiyona geçmeden önce modeli test etmek veya prototipi hızla çıkarmak için idealdir. /blog/vllm-nedir-acik-kaynak-llm-cikarim-motoru ile kendi inference sunucunuzu kurmaya hazır hissettikten sonra bu API’den geçiş yapabilirsiniz.

Spaces: Sıfır Altyapıyla Demo

Spaces, Gradio veya Streamlit uygulamalarını ücretsiz barındırmanızı sağlar. Yeni bir Space açmak için:

1. huggingface.co/new-space adresine gidin.
2. SDK olarak Gradio seçin.
3. app.py dosyanıza uygulamanızı yazın; requirements.txt ile bağımlılıkları tanımlayın.
4. Git ile push edin — Space otomatik build alır.

Minimal bir Gradio örneği:

# app.py
import gradio as gr
from transformers import pipeline

pipe = pipeline("summarization", model="facebook/bart-large-cnn")

def ozetle(metin):
    return pipe(metin, max_length=130, min_length=30)[0]["summary_text"]

demo = gr.Interface(fn=ozetle, inputs="text", outputs="text", title="Özetleyici")
demo.launch()

Bu dosyayı Space’e push ettiğinizde, bağlantıyı başka herkesle paylaşabilirsiniz. GPU gerektiren uygulamalar için A10G veya T4 donanımlı ücretli Space katmanlarına geçilebilir.

huggingface_hub ile Programatik Erişim

Model kartlarını okumak, dosya listelemek veya kendi modelinizi yüklemek için huggingface_hub Python paketi kullanılır:

from huggingface_hub import HfApi, hf_hub_download

api = HfApi()

# Belirli bir dosyayı indirmek
dosya_yolu = hf_hub_download(
    repo_id="google/gemma-2-2b",
    filename="config.json",
)
print(dosya_yolu)

# Kendi modelinizi yüklemek
api.upload_file(
    path_or_fileobj="./model.safetensors",
    path_in_repo="model.safetensors",
    repo_id="kullanici_adiniz/benim-modelim",
    repo_type="model",
)

Model yüklemek için repo’yu önce api.create_repo() ile oluşturmanız gerekir.

Model Kartı Okuma ve Metadata

Her modelin Hub’daki sayfası bir model kartıdır; README.md dosyasından üretilir. Bu kart pratikte kritik bilgiler barındırır: hangi görev için eğitildi, hangi dil ya da domain, lisans türü, bilinen kısıtlamalar, benchmark sonuçları.

Programatik olarak okumak istiyorsanız:

from huggingface_hub import model_info

info = model_info("mistralai/Mistral-7B-Instruct-v0.3")
print(info.pipeline_tag)       # text-generation
print(info.license)            # apache-2.0
print(info.downloads)          # aylık indirme sayısı
print(info.tags)               # ["transformers", "pytorch", ...]

Lisans bilgisi özellikle ticari kullanım için önemli. apache-2.0 ve mit genellikle kısıtsız ticari kullanıma açıktır; llama3 ve gemma gibi özel lisanslar ek kısıtlar getirebilir. Model kartını okumadan üretime almak risk taşır.

Belirli bir pipeline tipine veya dile göre arama yapmak için Hub API’yi filtreli çağırabilirsiniz:

from huggingface_hub import list_models

turkce_modeller = list_models(
    language="tr",
    pipeline_tag="text-generation",
    sort="downloads",
    direction=-1,
    limit=10,
)
for m in turkce_modeller:
    print(m.id, m.downloads)

Bu sorgu Türkçe metin üretimi için en çok indirilen 10 modeli listeler. Aynı filtreler Hub arayüzünde de çalışır.

Tokenizer Detayları

Tokenizer, modellerle çalışırken en çok gözden kaçan bileşendir. Metnin token’lara nasıl bölündüğü hem bağlam penceresi kullanımını hem de çıktı kalitesini etkiler.

from transformers import AutoTokenizer

tokenizer = AutoTokenizer.from_pretrained("mistralai/Mistral-7B-Instruct-v0.3")

metin = "Yapay zeka modellerini yerel olarak çalıştırmak artık çok daha kolay."
tokenlar = tokenizer.encode(metin)
print(len(tokenlar))  # token sayısı
print(tokenizer.convert_ids_to_tokens(tokenlar))  # token listesi

/terim/tokenization sürecini anlamak özellikle uzun belgelerle çalışırken önemli: her modelin maksimum bağlam uzunluğu farklı ve metni token sayısından tahmin etmek güçtür. 1.000 Türkçe kelime yaklaşık 1.500–2.000 token tutar; bu oran dile ve tokenizer tipine göre değişir. /blog/llm-tokenization-nedir-token-sayma-baglam-penceresi adresinde bu konuyu daha ayrıntılı bulabilirsiniz.

Chat modellerinde girdiyi manuel biçimlendirmek yerine apply_chat_template kullanın; her model ailesinin farklı konuşma şablonu var ve şablonu yanlış uygulamak çıktıyı bozar:

mesajlar = [
    {"role": "system", "content": "Sen yardımcı bir asistansın."},
    {"role": "user", "content": "Python'da liste üreteci ne işe yarar?"},
]
girdi = tokenizer.apply_chat_template(mesajlar, tokenize=False, add_generation_prompt=True)
print(girdi)
# <s>[INST] Sen yardımcı bir asistansın. ... [/INST]

datasets Kütüphanesi

Hub sadece model barındırmaz; 200.000’den fazla veri kümesi de bulunur. datasets kütüphanesi bunları tek satırla yükler:

from datasets import load_dataset

ds = load_dataset("squad", split="train")
print(ds[0])
# {'id': '...', 'title': 'Beyaz Saray', 'context': '...', 'question': '...', 'answers': {...}}

Büyük veri kümeleri için streaming=True parametresi, tüm veri setini diske indirmeden yinelemeli erişim sağlar:

ds = load_dataset("wikipedia", "20231101.tr", split="train", streaming=True)
for ornek in ds.take(5):
    print(ornek["title"])

Bu yaklaşım özellikle /blog/fine-tuning-vs-rag-llm-proje-stratejisi kararı alırken veri kümesini hızla incelemek için kullanışlıdır.

Performans İpuçları

Modeli üretim ortamında çalıştırırken dikkat edilmesi gereken birkaç nokta:

Kuantizasyon: Büyük modellerde GPU belleği kritik. bitsandbytes ile 4-bit yükleme bellek kullanımını %70’e kadar azaltır:

from transformers import BitsAndBytesConfig

bnb_config = BitsAndBytesConfig(load_in_4bit=True, bnb_4bit_compute_dtype=torch.bfloat16)
model = AutoModelForCausalLM.from_pretrained(model_id, quantization_config=bnb_config)

Flash Attention 2: Desteklenen modellerde attn_implementation="flash_attention_2" parametresi özellikle uzun bağlamlarda belirgin hız kazandırır. /blog/flash-attention-nedir-transformer-bellek-optimizasyonu adresinde bu mekanizmanın ayrıntılarını bulabilirsiniz.

Toplu işleme (batch): pipeline nesnesi liste girdi alır; tek tek çağırmak yerine toplu iletmek verimi artırır:

metinler = ["Metin 1", "Metin 2", "Metin 3"]
sonuclar = pipe(metinler, batch_size=8)

Yaygın Hatalar ve Çözümleri

OSError: We couldn't connect to huggingface.co Ağ kısıtlaması varsa önce huggingface-cli download ile modeli indirip local_files_only=True parametresiyle yükleyin.

CUDA out of memory Model boyutunu torch_dtype=torch.float16 veya 4-bit kuantizasyon ile düşürün. Alternatif olarak device_map="auto" ile CPU offload devreye alın.

Gated model erişimi reddedildi Model kartındaki “Access request” formunu doldurun. Llama 3 için Meta’nın lisans sayfasında onay gerektiriyor; genellikle dakikalar içinde onaylanır.

tokenizer.apply_chat_template bulunamıyor transformers>=4.34 gerektirir. pip install -U transformers ile güncelleyin.

Hangi Durumda Hangi Yolu Seçmeli

Hugging Face’i bir araç seti olarak düşünmek faydalı: Hub modeli barındırır, transformers yerel çalıştırır, Inference API bulut çıkarımı sağlar, Spaces demo katmanı olur. Bu dört bileşenin ne zaman kullanılacağını kavramak, geliştirme sürecini ciddi ölçüde kısaltır.