AI Uygulamaları için Akıllı Dokümantasyon Veritabanları Kurmak

Ham dokümantasyonu bir AI ajanına beslemek, onu çöpte iğne aramaya göndermekle aynı şey. Her yasal sayfa, değişim günlüğü, navigasyon sayfası... hepsi önemli bilgiyi gömüyor. NameOcean'da, dokümantasyonu yapay zeka tabanlı yazılım geliştirme iş akışlarına hazırlamanın en iyi yolunu uzun süredir araştırıyoruz. Bu yazımızda işe yarayan bir yaklaşım paylaşmak istiyoruz.

Sorun: Tüm Sayfalar Eşit Değildir

Çoğu geliştirici bunu öğrenince şaşırır: teknik dokümantasyon sitelerinin büyük bir kısmı aslında yapısal ve yasal zorunluluklar için vardır. İndeks sayfaları, gizlilik politikaları, sürüm geçmişleri, API referans listleri—insan kullanıcılar için çok önemlidir ama bir AI için boşa küçülen bilgiden ibarettir.

Filtrelenmemiş dokümantasyonu vektör veritabanına döktüğünde, AI'nin asında öğrenmesi gereken şeylerle değil, alakasız içerikle uğraşmasını zorluyorsun. Sonuç? Yavaş sorgular, şişmiş embeddings, yanlış sayfaları referans gösteren cevaplar.

İki Aşamalı Sınıflandırma Yöntemi

En verimli çözüm kural tabanlı filtreleme ile seçili LLM sınıflandırmasını birleştirir. Tıpkı bir hastanede ön muayene sistemi gibi düşün.

Birinci Aşama: Hızlı Eleme

URL desenlerine ve temel sayfa yapısına bakarak başla. Çoğu problemi anında çözebilirsin:

• Yasal sayfalar: /legal/, /privacy, /terms, /eula, /cookie gibi yolları ara
• Navigasyon sayfaları: 200 kelimeden kısa, çoğunlukla linklerden oluşan sayfalar
• Sürüm geçmişleri: Genellikle tahmin edilebilir URL yapısına sahip
• Referans sayfaları: Yapıları inceleyerek tanınabilir

Bu adım yerel olarak çalışır, hiç malı olmaz ve sayfaların yüzde 40-60'ını ayıklar.

İkinci Aşama: LLM ile Sınıflandırma

Kalan sayfalar için yerel bir LLM'ye (API değil) hafif veriler gönder:

• Sayfa URL'i
• Başlık
• İçeriğin ilk 200 kelimesi
• Başlık hiyerarşisi

Diátaxis gibi bir çerçeve kullanarak sınıflandır:

• Konseptüel: Açıklamalar ve arka plan bilgisi
• Eğitim: Adım adım rehberli öğrenme
• Nasıl Yapılır: Belirli görevleri tamamlamak için yönergeler
• Örnekler: Kod örnekleri ve demolar
• Yapısal: Navigasyon, referans, yasal içerik

LLM sadece kuralların çözemediği sayfalarla ilgilenir, böylece malı düşük tutarsın.

İçerikleri Akıllı Şekilde Gömme

Gürültüyü ayıkladıktan sonra, anlamsal arama için embedding çok daha etkili hale gelir. Ama dikkat et: dokümantasyon sayfaları token limitini aşabilir.

Sayfayı başlıklarda böl ve ortaya çıkan embeddingleri ortalamasını al. Bu, yapıyı korur—başlıklar, kod blokları, listeler önem taşır.

Sayfa çok uzunsa, markdown yapısı doğal bölme noktaları sunur:

def embed_page(content: str) -> list[float]:
    chunks = re.split(r'(?m)^#{1,3} ', content)
    if len(chunks) == 1:
        return model.encode(content).tolist()
    embeddings = [model.encode(chunk) for chunk in chunks if chunk.strip()]
    avg = np.mean(embeddings, axis=0)
    return (avg / np.linalg.norm(avg)).tolist()

Burada yerel bir sentence transformer kullan. API maliyetlerini ve gecikmesini ortadan kaldırırsın; teknik dokümantasyon için yerel modeller yeterince iyi çalışıyor.

Hibrit Bilgi Ağı Oluştur

Gerçek güç iki tür ilişkiyi birleştirdiğinde ortaya çıkar:

Açık Linkler: Yazar tarafından yazılan hyperlink'ler. Yüksek güven seviyesi ve bilinçli yapıyı yansıtır.

Anlamsal Bağlantılar: Embedding benzerliği aracılığıyla keşfedilen ilişkiler. İki sayfanın cosine benzerliği 0.75'ten yüksekse (bizim kullandığımız eşik), açıkça linked olmasa da kavramsal olarak ilişkilidir.

Bunları yönlü kenarlar olarak grafikte sakla. Anlamsal kenarlar için benzerlik puanını ağırlık olarak kullan. Link kenarları ağırlıksızdır.

Önemli bir optimizasyon: sayfa başına komşu sayısını sınırla (20 iyi bir başlangıçtır). Yoksa massive bağlantı merkezi oluşur ve gezinti kafa karıştırıcı hale gelir. Anlamsal grafik oluştururken navigasyon, yasal ve referans sayfalarını hariç tut.

Son Ürün: Taşınabilir SQLite Veritabanı

Her şey tek bir SQLite veritabanında yaşar:

• Temiz markdown formatında dokümantasyon
• Sayfa sınıflandırmaları
• Embeddings (vektör veya serialized blob olarak)
• Ağırlıklandırılmış grafik kenarları
• URL ve metadata

Bu güçlüdür çünkü:

• Taşınabilir: Istediğin yere taşı, çevrimdışı kullan
• Sorgulanabilir: AI, SQL yazabiliyor. LLM'ler gerçekten iyidirler bunda.
• Filtrelenebilir: "Sadece authentication hakkında eğitim ve nasıl yapılır sayfalarını göster"
• Gezilir: Ajanlar bilgi ağını dolaşabilir, bir sayfadan anlamsal olarak ilişkili diğer sayfaya geçebilir

Pratik İş Akışı

Tam pipeline şöyle görünür:

1. Dokümantasyon sitesini tarayıcıya geç (yönlendirmeleri yönet, robots.txt'ye saygı göster, JavaScript'le oluşturulan içeriği handle et)
2. HTML'i temizle ve kullanılabilir markdown'a çevir
3. Sayfaları sınıflandır (kurallarla başla, belirsizler için LLM kullan)
4. Gömme yap yerel modellerle, uzun sayfaları başlıklarda bölerek
5. Grafik oluştur açık linkler ve anlamsal kenarlarla
6. Her şeyi sakla SQLite'da

Artık AI'nın eliminde, ham HTML yığınının yerine, küratörlü ve yapılandırılmış bir bilgi tabanı var.

Neden Geliştiriciler İçin Önemli?

İç kod yardımcısı, IDE entegrasyonu veya takım bilgi sistemi geliştiriyor olsun, dokümantasyon kalitesi çarpan etkisi yaratır. Akıllı yapılandırmayla AI, gürültü yerine gerçek içeriğe zaman harcıyor. Sorgular hızlanıyor. Cevaplar daha alakalı oluyor. Ve bilgi tabanını tamamen kontrol ediyorsun—tarafından bağımlılığı yok, API maliyeti yok, sahiplik dokümantasyonunu üçüncü parti servislere gönderme endişesi yok.

Burada bahsettiğimiz framework, küçük tek ürün dokümantasyonundan devasa çok ürün ekosistemine kadar ölçekleniyor. Ana fikir basit: dokümantasyonu yukarıda filtreleyip yapılandırmak, AI'nın aşağıda gürültüde boğulmaktan kurtarır.