Hugging Face Hub’dan Model İndirme ve Yerel Kullanım Rehberi

Yazar:komut.io ekibi
0 Yorum

Makine öğrenmesi dünyasına adım atmak ya da mevcut projenize güçlü bir model entegre etmek istiyorsanız, Hugging Face Hub muhtemelen ilk durağınız olacak. Binlerce önceden eğitilmiş model, veri seti ve demo uygulamasıyla bu platform artık yapay zeka ekosisteminin merkezi haline geldi. Ama “modeli indirdim, şimdi ne yapacağım?” sorusuyla karşılaşmamak için işin teknik detaylarını iyi bilmek gerekiyor. Bu yazıda, Hugging Face Hub’dan model indirmenin farklı yollarını, yerel ortamda nasıl verimli kullanacağınızı ve production ortamında karşılaşabileceğiniz gerçek sorunları ele alacağız.

Ortam Hazırlığı

Her şeyden önce temiz bir Python ortamı kurmak şart. Sistem genelinde kurulum yapmak ileride bağımlılık çakışmalarına davetiye çıkarır. Sanal ortam veya conda kullanmak bu yüzden bir alışkanlık değil, bir zorunluluk.

# Python sanal ortamı oluştur
python3 -m venv hf-env
source hf-env/bin/activate

# Conda tercih ediyorsanız
conda create -n hf-env python=3.10
conda activate hf-env

# Temel paketleri yükle
pip install transformers huggingface_hub torch accelerate
pip install sentencepiece tokenizers datasets

# GPU kullanıyorsanız CUDA destekli PyTorch
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118

Kurulum sonrası Hugging Face CLI’yi yapılandırmak gerekiyor. Token olmadan da pek çok modele erişebilirsiniz ama özel modeller veya gated modeller için token zorunlu. Token almak için huggingface.co adresinde hesap açıp Settings > Access Tokens bölümünden üretebilirsiniz.

# Hugging Face CLI ile giriş yap
huggingface-cli login

# Token'ı direkt parametre olarak da geçebilirsiniz
huggingface-cli login --token hf_xxxxxxxxxxxxxxxxxxxx

# Mevcut oturumu kontrol et
huggingface-cli whoami

Model İndirmenin Farklı Yolları

Hugging Face’de model indirmek için birden fazla yöntem var ve doğru yöntemi seçmek hem disk alanı hem de bant genişliği açısından kritik.

Yöntem 1: Transformers ile Otomatik İndirme

En yaygın yöntem bu. Model ilk kullanıldığında otomatik olarak cache dizinine indirilir.

from transformers import AutoTokenizer, AutoModelForCausalLM
import torch

model_name = "mistralai/Mistral-7B-Instruct-v0.2"

# Tokenizer indir
tokenizer = AutoTokenizer.from_pretrained(model_name)

# Model indir (bu işlem büyük modeller için uzun sürer)
model = AutoModelForCausalLM.from_pretrained(
    model_name,
    torch_dtype=torch.float16,  # Bellek tasarrufu için half precision
    device_map="auto"            # GPU varsa otomatik yerleştir
)

# Basit bir inference örneği
messages = [{"role": "user", "content": "Merhaba, nasılsın?"}]
input_ids = tokenizer.apply_chat_template(messages, return_tensors="pt")

with torch.no_grad():
    output = model.generate(input_ids, max_new_tokens=200, do_sample=True, temperature=0.7)

print(tokenizer.decode(output[0], skip_special_tokens=True))

Bu yöntemde dosyalar varsayılan olarak ~/.cache/huggingface/hub altına indirilir. 7B parametreli bir model yaklaşık 14GB yer tutar. Bunu değiştirmek için:

# Cache dizinini değiştir
export HF_HOME=/mnt/data/huggingface
export HUGGINGFACE_HUB_CACHE=/mnt/data/huggingface/hub

# Bu değişkeni kalıcı yapmak için .bashrc veya .profile'a ekle
echo 'export HF_HOME=/mnt/data/huggingface' >> ~/.bashrc

Yöntem 2: huggingface_hub ile Manuel İndirme

Modeli önce indirip sonra kullanmak istiyorsanız, özellikle offline ortamlar için bu yöntem çok daha kontrollü.

from huggingface_hub import snapshot_download, hf_hub_download

# Tüm model dosyalarını belirli bir dizine indir
local_dir = snapshot_download(
    repo_id="mistralai/Mistral-7B-Instruct-v0.2",
    local_dir="/opt/models/mistral-7b",
    local_dir_use_symlinks=False,  # Sembolik link yerine dosyaları kopyala
    ignore_patterns=["*.msgpack", "*.h5", "flax_model*"]  # Gereksiz dosyaları atla
)

print(f"Model indirildi: {local_dir}")

# Tek bir dosyayı indir
config_file = hf_hub_download(
    repo_id="mistralai/Mistral-7B-Instruct-v0.2",
    filename="config.json",
    local_dir="/tmp/model-config"
)

ignore_patterns parametresi çok işe yarıyor. TensorFlow veya Flax formatlarını kullanmıyorsanız, sadece PyTorch weights’leri indirerek ciddi miktarda disk alanı tasarrufu yapabilirsiniz.

Yöntem 3: CLI ile İndirme

Sunucu ortamında Python script çalıştırmak yerine CLI kullanmak bazen daha pratik.

# Hugging Face CLI ile model indir
huggingface-cli download mistralai/Mistral-7B-Instruct-v0.2 
  --local-dir /opt/models/mistral-7b 
  --local-dir-use-symlinks False

# Belirli dosyaları indir
huggingface-cli download mistralai/Mistral-7B-Instruct-v0.2 
  --include "*.safetensors" "*.json" "*.model" 
  --local-dir /opt/models/mistral-7b

# Token gerektiren model için
huggingface-cli download meta-llama/Llama-2-7b-chat-hf 
  --token hf_xxxxxxxxxxxxxxxxxxxx 
  --local-dir /opt/models/llama2-7b

Gated Modeller ve Erişim İzinleri

Llama 2, Llama 3, Gemma gibi popüler modeller “gated” yani erişim izni gerektiriyor. Bu modellere erişmek için önce Hugging Face üzerinden model sayfasına gidip lisans anlaşmasını kabul etmeniz gerekiyor. Bu işlemi yaptıktan sonra token ile sorunsuz indirme yapabilirsiniz.

import os
from transformers import AutoTokenizer, AutoModelForCausalLM
import torch

# Token'ı environment variable olarak saklamak daha güvenli
os.environ["HUGGING_FACE_HUB_TOKEN"] = "hf_xxxxxxxxxxxxxxxxxxxx"

# Ya da direkt parametre olarak geç
model = AutoModelForCausalLM.from_pretrained(
    "meta-llama/Meta-Llama-3-8B-Instruct",
    token=os.getenv("HUGGING_FACE_HUB_TOKEN"),
    torch_dtype=torch.bfloat16,
    device_map="auto"
)

Dikkat: Token’ları kod içinde hardcode etmeyin. .env dosyası veya environment variable kullanın. .gitignore‘a .env eklemeyi unutmayın.

Quantization ile Bellek Optimizasyonu

7B modeli bile tam precision’da yüklemek 14GB VRAM gerektiriyor. Çoğu geliştirici bu kadar GPU belleğine sahip değil. Quantization bu sorunu çözüyor.

# bitsandbytes kütüphanesini kur
pip install bitsandbytes

# accelerate güncel sürümü
pip install accelerate>=0.26.0
from transformers import AutoTokenizer, AutoModelForCausalLM, BitsAndBytesConfig
import torch

# 4-bit quantization konfigürasyonu
bnb_config = BitsAndBytesConfig(
    load_in_4bit=True,
    bnb_4bit_use_double_quant=True,
    bnb_4bit_quant_type="nf4",
    bnb_4bit_compute_dtype=torch.bfloat16
)

model_name = "mistralai/Mistral-7B-Instruct-v0.2"

tokenizer = AutoTokenizer.from_pretrained(model_name)
model = AutoModelForCausalLM.from_pretrained(
    model_name,
    quantization_config=bnb_config,
    device_map="auto"
)

# 7B model artık yaklaşık 4-5GB VRAM ile çalışır
print(f"Model bellek kullanımı: {model.get_memory_footprint() / 1e9:.2f} GB")

4-bit quantization ile 7B parametreli bir model yaklaşık 4-5GB VRAM’a sığıyor. Kalite kaybı minimal düzeyde ve çoğu kullanım senaryosu için kabul edilebilir. 8-bit için sadece load_in_4bit=True yerine load_in_8bit=True kullanmanız yeterli.

GGUF Formatı ve llama.cpp Entegrasyonu

PyTorch olmadan da model çalıştırmak mümkün. GGUF formatındaki modeller llama.cpp ve Ollama gibi araçlarla CPU üzerinde bile makul hızda çalışıyor.

# Ollama kur (en kolay yol)
curl -fsSL https://ollama.ai/install.sh | sh

# Popüler modelleri Ollama ile çalıştır
ollama run mistral
ollama run llama3
ollama run phi3

# Model listesini gör
ollama list

# Ollama API'yi test et
curl http://localhost:11434/api/generate -d '{
  "model": "mistral",
  "prompt": "Türkiye hakkında kısa bilgi ver",
  "stream": false
}'

Hugging Face’deki GGUF modellerini manuel olarak indirmek için:

# TheBloke gibi hesaplarda GGUF versiyonları bulunur
huggingface-cli download TheBloke/Mistral-7B-Instruct-v0.2-GGUF 
  mistral-7b-instruct-v0.2.Q4_K_M.gguf 
  --local-dir /opt/models/gguf/

# llama.cpp ile çalıştır
./llama.cpp/main 
  -m /opt/models/gguf/mistral-7b-instruct-v0.2.Q4_K_M.gguf 
  -n 512 
  -p "Sen yardımcı bir asistansın. Kullanıcı: Merhaba! Asistan:" 
  --temp 0.7 
  --repeat-penalty 1.1

Q4_K_M gibi kısaltmalar quantization seviyesini gösterir. Q4 4-bit demek, K_M ise “medium” kalite anlamına geliyor. Kalite ve boyut dengesi için Q4_K_M veya Q5_K_M iyi başlangıç noktaları.

Offline Ortamda Model Kullanımı

Production ortamlarının önemli bir kısmı internet erişimine sahip değil. Bu senaryoda modeli önceden indirip offline kullanmak gerekiyor.

from transformers import AutoTokenizer, AutoModelForCausalLM
import torch

# Offline mod - internet bağlantısı olmadan yerel dizinden yükle
model_path = "/opt/models/mistral-7b"

tokenizer = AutoTokenizer.from_pretrained(
    model_path,
    local_files_only=True  # Sadece yerel dosyalara bak
)

model = AutoModelForCausalLM.from_pretrained(
    model_path,
    local_files_only=True,
    torch_dtype=torch.float16,
    device_map="auto"
)

# TRANSFORMERS_OFFLINE environment variable ile de ayarlayabilirsiniz
# export TRANSFORMERS_OFFLINE=1
# export HF_DATASETS_OFFLINE=1

Sistemde bu modeli servis etmek için basit bir FastAPI wrapper’ı:

from fastapi import FastAPI
from pydantic import BaseModel
from transformers import AutoTokenizer, AutoModelForCausalLM, pipeline
import torch

app = FastAPI()

# Uygulama başlarken modeli yükle
model_path = "/opt/models/mistral-7b"
tokenizer = AutoTokenizer.from_pretrained(model_path, local_files_only=True)
model = AutoModelForCausalLM.from_pretrained(
    model_path,
    local_files_only=True,
    torch_dtype=torch.float16,
    device_map="auto"
)

pipe = pipeline(
    "text-generation",
    model=model,
    tokenizer=tokenizer,
    max_new_tokens=512,
    do_sample=True,
    temperature=0.7,
    top_p=0.95
)

class InferenceRequest(BaseModel):
    prompt: str
    max_tokens: int = 256

@app.post("/generate")
async def generate_text(request: InferenceRequest):
    result = pipe(request.prompt, max_new_tokens=request.max_tokens)
    return {"generated_text": result[0]["generated_text"]}

@app.get("/health")
async def health_check():
    return {"status": "ok", "model": model_path}
# Servisi başlat
uvicorn main:app --host 0.0.0.0 --port 8080 --workers 1

# Test et
curl -X POST http://localhost:8080/generate 
  -H "Content-Type: application/json" 
  -d '{"prompt": "Türkiyenin başkenti nedir?", "max_tokens": 100}'

Embedding Modelleri ve Vektör Veritabanı Entegrasyonu

Büyük dil modellerinin yanı sıra embedding modelleri de sıkça kullanılıyor. Semantik arama, RAG uygulamaları ve belge benzerlik hesaplamaları için şart.

from sentence_transformers import SentenceTransformer
import numpy as np

# Türkçe destekli çok dilli embedding modeli
model = SentenceTransformer("sentence-transformers/paraphrase-multilingual-mpnet-base-v2")

# Metin listesini embed et
sentences = [
    "Ankara Türkiye'nin başkentidir.",
    "İstanbul Türkiye'nin en kalabalık şehridir.",
    "Python programlama dili çok kullanışlıdır.",
    "Makine öğrenmesi yapay zekanın alt dalıdır."
]

embeddings = model.encode(sentences, batch_size=32, show_progress_bar=True)
print(f"Embedding boyutu: {embeddings.shape}")  # (4, 768)

# Cosine similarity hesapla
from sklearn.metrics.pairwise import cosine_similarity

query = "Türkiye'nin nüfusu en fazla olan şehri hangisi?"
query_embedding = model.encode([query])

similarities = cosine_similarity(query_embedding, embeddings)[0]
most_similar_idx = np.argmax(similarities)
print(f"En benzer cümle: {sentences[most_similar_idx]}")
print(f"Benzerlik skoru: {similarities[most_similar_idx]:.4f}")

Yaygın Hatalar ve Çözümleri

Gerçek hayatta en sık karşılaşılan sorunlar ve çözümleri:

OutOfMemoryError sorunu en yaygın karşılaşılan sorun. Çözüm yolları:

  • torch_dtype=torch.float16 veya torch.bfloat16 kullan
  • 4-bit veya 8-bit quantization aktifleştir
  • device_map="auto" yerine device_map="cpu" ile CPU’ya yükle
  • Daha küçük model versiyonu seç (3B, 1B gibi)

Connection timeout veya download hatası durumunda:

  • HF_ENDPOINT environment variable ile mirror kullan
  • VPN bağlantısı kontrol et
  • --resume-download flag’i ile yarım kalan indirmeyi devam ettir

Model dosyaları bozuk görünüyorsa:

# Cache'i temizle ve yeniden indir
huggingface-cli delete-cache

# Belirli bir model cache'ini sil
rm -rf ~/.cache/huggingface/hub/models--mistralai--Mistral-7B-Instruct-v0.2

# Dosya bütünlüğünü kontrol et
huggingface-cli scan-cache

Tokenizer uyumsuzluğu yaşıyorsanız use_fast=False parametresini deneyin:

tokenizer = AutoTokenizer.from_pretrained(model_name, use_fast=False)

Disk ve Bellek Yönetimi

Production ortamında model yönetimi disiplin gerektiriyor. Aynı modelin birden fazla versiyonu birikiyor, cache dolup taşıyor.

# Hugging Face cache boyutunu kontrol et
du -sh ~/.cache/huggingface/

# Hangi modeller cache'te var
huggingface-cli scan-cache

# İnteraktif cache temizleme
huggingface-cli delete-cache

# Belirli bir tarihten önce kullanılmayan modelleri bul
find /opt/models -maxdepth 1 -type d -atime +30 -ls
# Python'dan cache yönetimi
from huggingface_hub import scan_cache_dir, delete_cache_files

# Cache bilgilerini al
cache_info = scan_cache_dir()
print(f"Toplam cache boyutu: {cache_info.size_on_disk_str}")

# Kullanılmayan revision'ları temizle
delete_strategy = cache_info.delete_revisions(*[
    revision.commit_hash
    for repo in cache_info.repos
    for revision in repo.revisions
    if revision.last_accessed < some_threshold
])

delete_strategy.execute()

Systemd Service ile Model Servisi

Modeli her boot’ta otomatik başlatmak için systemd service dosyası:

# /etc/systemd/system/llm-api.service
cat > /etc/systemd/system/llm-api.service << 'EOF'
[Unit]
Description=LLM API Service
After=network.target

[Service]
Type=simple
User=mluser
WorkingDirectory=/opt/llm-api
Environment="HF_HOME=/opt/models"
Environment="TRANSFORMERS_OFFLINE=1"
Environment="CUDA_VISIBLE_DEVICES=0"
ExecStart=/opt/llm-api/venv/bin/uvicorn main:app --host 0.0.0.0 --port 8080 --workers 1
Restart=always
RestartSec=10
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target
EOF

# Servisi aktifleştir
systemctl daemon-reload
systemctl enable llm-api
systemctl start llm-api
systemctl status llm-api

Sonuç

Hugging Face Hub, model indirme ve yerel kullanım konusunda şu ana kadar geliştirilmiş en kapsamlı ekosistemi sunuyor. Basit bir from_pretrained() çağrısından başlayıp quantization, offline deployment ve production servislerine kadar geniş bir yelpazede ihtiyaçlarınızı karşılayabiliyor.

Başlangıç için en kritik noktalar şunlar: cache dizinini kontrol altında tutun, büyük modeller için mutlaka quantization kullanın, token’larınızı güvenli saklayın ve offline ortamlar için modeli önceden indirip local_files_only=True ile yükleyin.

GGUF + Ollama kombinasyonu hobi projeleri ve geliştirme ortamları için çok pratik. Production için ise PyTorch tabanlı yaklaşım daha esnek ve kontrol edilebilir oluyor. Hangi yolu seçeceğiniz büyük ölçüde donanım kapasitesine ve kullanım senaryosuna bağlı.

En önemli tavsiye: Küçük modelle başlayın, ihtiyaca göre büyüyün. 1B veya 3B parametreli modeller birçok görev için yeterince iyi çalışırken kaynak kullanımı açısından çok daha makul kalıyor. İlk kurulum sonrası ince ayar yapmak her zaman mümkün.

Bir yanıt yazın

E-posta adresiniz yayınlanmayacak. Gerekli alanlar * ile işaretlenmişlerdir