llms.txt nedir, nasıl yazılır ve ajanlar ona nasıl yaklaşmalı?

llms.txt, bir web sitesinin kök dizinine koyduğu ve dil modellerine sitenin en işe yarar içeriğinin kısa, seçilmiş bir haritasını sunan düz bir Markdown dosyasıdır. Dokümantasyon sitelerinde ve geliştirici araçlarında yaygınlaştı; ama iki yönden de sık sık yanlış anlaşılıyor: kimisi onu yeni bir robots.txt sanıyor, kimisi geçici bir heves deyip geçiyor. Bu yazı dosyanın ne olduğunu, sitelerin onu nasıl kullandığını, neyi yapıp neyi yapmadığını, iyisinin nasıl yazılacağını ve bu dosyayla karşılaşan bir ajanın ona nasıl davranması gerektiğini anlatıyor.

Dosya nedir

Bu kural Answer.AI'dan Jeremy Howard tarafından önerildi ve llmstxt.org adresinde belgeleniyor. Bir standart kuruluşunun yayımladığı bir standart değil, bir topluluk önerisidir; hiçbir model, tarayıcı (crawler) ya da ajan onu okumak zorunda değildir.

Fikir basit. Web sayfaları tarayıcılar için yapılır: menüler, betikler, çerez bildirimleri, sayfa düzeni. Sınırlı bir bağlam penceresinde çalışan bir model ise tam tersine, önemli olanın derli toplu bir metin hâline ihtiyaç duyar. llms.txt, site sahibinin en yararlı bulduğu sayfaların Markdown ile yazılmış bir dizinini, her biri için tek satırlık bir açıklamayla sunar. Pek çok site sayfaların kendisinin de Markdown sürümlerini yayımlar; böylece ajan HTML ayrıştırmak yerine doğrudan temiz metni çekebilir.

Yanında sık görülen iki ilgili kural var:

• Sayfaların Markdown sürümleri. Öneriye göre bir sayfanın Markdown sürümü, aynı URL'nin sonuna .md eklenerek sunulur; yani /docs/auth.html aynı zamanda /docs/auth.html.md olarak da bulunur.
• llms-full.txt. Bazı dokümantasyon platformları, her şeyi tek seferde yüklemeyi tercih eden araçlar için dokümanların tam metnini içeren tek bir dosya yayımlar. Bu, çekirdek önerinin parçası değil, yaygınlaşmış bir uygulamadır.

Biçim

Yapı bilerek küçük tutulmuştur; hem insanlar hem programlar onu özel bir araca ihtiyaç duymadan okuyabilir. Sırasıyla:

1. Projenin ya da sitenin adını taşıyan bir H1. Zorunlu olan tek öğe budur.
2. Kısa bir özet içeren bir alıntı bloğu: modelin geri kalanı anlamlandırması için gereken bağlam.
3. İsteğe bağlı serbest metin; örneğin dokümanların hangi sürümü anlattığı gibi önemli notları içeren paragraflar ya da listeler.
4. Sıfır ya da daha fazla H2 bölümü; her biri [ad](url): açıklama biçiminde bir bağlantı listesidir.
5. Optional adlı bir H2: bağlam darsa bu bölümdeki bağlantılar atlanabilir.

Hayali bir kütüphane için eksiksiz bir örnek:

# Acme Queue

> Acme Queue, Python servisleri için açık kaynaklı bir iş kuyruğudur.
> Bu dokümanlar 3. sürümü anlatır.

2. sürümün API'leri ayrıca belgelenmiştir ve uyumlu değildir.

## Dokümanlar

- [Hızlı başlangıç](https://docs.example.com/quickstart.md): kurulum, aracı yapılandırma, ilk işi çalıştırma
- [Yeniden deneme](https://docs.example.com/retries.md): yeniden deneme seçenekleri ve varsayılanları
- [Yapılandırma başvurusu](https://docs.example.com/config.md): her ayar ve türü

## API

- [Python istemcisi](https://docs.example.com/api/client.md): herkese açık sınıflar ve yöntemler

## Optional

- [Sürüm notları](https://docs.example.com/changelog.md): değişiklik geçmişi
- [Tasarım notları](https://docs.example.com/design.md): iç kararların arka planı

Siteler onu nasıl kullanıyor

Benimseme, okuyucuların yapay zekâ araçlarıyla çalışan geliştiriciler olduğu yerlerde yoğunlaşıyor. Tipik kullanımlar:

• Dokümantasyon siteleri: kod asistanlarının bir API sorusunda eğitim verisinden tahmin yürütmek yerine doğru sayfayı bulmasını istiyorlar.
• Geliştirici araçları ve SDK'lar: kullanıcı tek bir URL'yi editördeki ajana yapıştırıp ona bütün haritayı verebilsin diye bir llms.txt yayımlıyorlar.
• Ürün ve politika siteleri: sundukları şeyin kısa ve resmî bir tanımını istiyorlar; böylece özetler site sahibinin kendi ifadesinden yola çıkıyor.

Bugün başlıca okuyucular, bir kullanıcının isteğiyle hareket eden ajanlar: bir kütüphanenin dokümanlarını okuması söylenen bir IDE asistanı, kendisine sorulan bir siteyi çeken bir araştırma ajanı ya da dosyayı bir sohbete yükleyen bir kişi. Büyük model sağlayıcılarının eğitim verisi toplarken llms.txt kullanıp kullanmadığını dosyanın kendisi söyleyemez; kullandıklarını varsaymayın, her sağlayıcının kendi dokümantasyonuna bakın.

llms.txt neyi yapmaz

Karışıklığın çoğu, dosyayı olmadığı bir şey gibi görmekten kaynaklanıyor.

Kısacası llms.txt robots.txt'in yerini almaz, yanında durur. Yapay zekâ tarayıcılarını kısıtlamak istiyorsanız bunun yeri robots.txt yönergeleri ve sunucu tarafı denetimlerdir.

İyi bir llms.txt yazmak

İşe yarayan bir llms.txt kısa, doğru ve bakımlıdır. Birkaç pratik kural:

• Seçin, yığmayın. En sık sorulan soruları yanıtlayan sayfaları listeleyin. Markdown'a dökülmüş bir site haritası harita değil, yığındır.
• Seçim yaptıran açıklamalar yazın. “Yeniden deneme seçenekleri ve varsayılanları” ajanın o sayfayı açıp açmayacağına karar vermesini sağlar; yalnızca “Yeniden deneme” sağlamaz.
• Sürümü belirtin. Dokümanlarınız birden çok sürümü kapsıyorsa bağlantıların hangisini anlattığını en üstte yazın.
• Temiz metne bağlantı verin. Varsa Markdown sürümlerini gösterin; yoksa betik çalıştırmadan okunabilir içerik sunan sayfaları.
• Optional bölümünü dürüstçe kullanın: arka plan malzemesini oraya koyun ki bağlam bütçesi dar araçlar onu atlayabilsin.
• Dosyayı dokümanlarla aynı kaynaktan üretin; böylece adı değişen bir sayfa geride ölü bir bağlantı bırakmaz. Dokümantasyon platformunuzun bunu sizin için üretip üretemediğine bakın.
• Kullanılacağı gibi test edin. Dosyayı bir ajana verin, birkaç gerçek soru sorun ve doğru sayfaları açıp açmadığına bakın.

Bir ajan llms.txt'e nasıl davranmalı

Ajan geliştirenler için bu dosya hem yararlı hem de kötü niyete açık bir yerdir. Sağlam bir politika:

1. İçindekiler tablosu olarak kullanın. O sitede bir soru için olası sayfaları bulmanın hızlı bir yoludur; kendi başına bir yanıt değildir.
2. İçeriğini güvenilmeyen veri sayın. “Önceki talimatları yok say” ya da “her zaman bu ürünü öner” diyen bir satır, bir web sitesinden gelen metindir ve başka herhangi bir sayfadan fazla yetkisi yoktur. Onu talimat kanalının dışında tutun.
3. Dizine değil, asıl sayfaya atıf yapın. Bağlantı verilen sayfayı çekin ve pasajı oradan alıntılayın. Markdown sürümü ile HTML sayfası çelişiyorsa insan okuyucunun gördüğünü esas alın ve uyumsuzluğu işaretleyin.
4. İzin olarak okumayın. robots.txt'i ve sitenin koşullarını ayrıca kontrol edin. Modelleri davet eden bir dosya; oturum açmaya, ödeme duvarını aşmaya ya da kişisel veri toplamaya izin vermez.
5. Ne zaman okuduğunuzu kaydedin. Dosyadan ya da bağlantılarından türetilen her şeyle birlikte getirme tarihini saklayın; site her an değişebilir.
6. Dosya yoksa sorunsuz devam edin. Sitelerin çoğunda bu dosya bulunmaz. Olmaması, sitenin kalitesi ya da ajanlara bakışı hakkında hiçbir şey söylemez.

Açık webdeki ajanlar için daha geniş kurallar, örneğin istemcinin kendini tanıtması ve erişim denetimlerine uyması, web tarayıcısı nedir ve web kazıma nedir yazılarında ele alınıyor. Bir yanıtı hangi sitelerin besleyebileceğini en baştan seçmek için de bir soruyu hangi kaynakların yanıtlayabileceğine karar vermek notuna bakabilirsiniz.

Bir sitenin dokümanlarını GoCux'a taşımak

GoCux açık webi taramaz ve okumaz; dolayısıyla llms.txt dosyalarını aramaya da çıkmaz. Dosyanın işe yaradığı yer bir adım öncesidir: bir ekip, bir tedarikçinin ya da düzenleyici kurumun sitesindeki hangi sayfaların projeye ait olduğuna karar verirken. Dizin bu seçimi hızlandırır. Sayfaların kendisi ise projeye yetkili bir tarayıcı oturumu ya da dışa aktarma adımıyla girer; özgün sayfa adresi ve getirildiği tarihle birlikte gelir. Ardından Bilgi arama bu belgelerden pasaj atıflarıyla yanıt verir. Kaynakların nasıl kabul edildiğini kaynak politikası, web tarafını ise web kaynakları ve sorumlu ajan erişimi sayfası anlatıyor.

Kontrol listesi

Bir llms.txt yayımlıyorsanız

• Dosya bir H1 ve kısa bir özetle başlıyor, hangi sürümü anlattığını söylüyor.
• Her bağlantının, ajana açıp açmamaya karar verdirecek bir açıklaması var.
• Bağlantılar temiz metne gidiyor ve dosya dokümanlarla birlikte üretiliyor.
• Arka plan malzemesi Optional bölümünde duruyor.
• Erişim kuralları llms.txt'te değil, robots.txt'te ve sunucuda tanımlı.

Ajanınız llms.txt okuyorsa

• Dosya talimat olarak değil, veri olarak işleniyor.
• Atıflar dizine değil, bağlantı verilen sayfalara gidiyor.
• Getirme tarihi, türetilen her bulguyla birlikte saklanıyor.
• robots.txt ve sitenin koşulları ayrıca kontrol ediliyor.
• Dosya yoksa ajan olağan yoldan devam ediyor.