Contextator
ENTR

Kaynaklar

Dokümantasyon Sitesi Kaynağı

Herkese açık bir sitenin sitemap'ini, llms.txt'ini ya da bir crawl'ını indekslemek — algılama, beş tavan, robots.txt ve tazelik kontrolü.

Güncelleme:

Herkese açık bir dokümantasyon sitesini kendi sitemap’i, kendi llms.txt’i ya da onu tek bir giriş noktasından crawl ederek indeksleyin — oturum açma yok, kimlik bilgisi yok, hedefe hiçbir şey kurulmuyor.

Kaynak bir iç adrese yalnızca host’una izin verilmişse bağlanır: yaptığı her istek bir Confluence kaynağıyla aynı adres kontrolünden geçer. Neyin reddedildiği ve iç ağdaki bir sitenin nasıl kabul ettirileceği aşağıdaki İç adresler bölümündedir.

Bir tane eklemek

Add source → Documentation site

Alan Notlar
Name Mount öneki. Değiştirilemez
Entry point Bir sitemap.xml, bir llms.txt, ya da crawl’ın başlayacağı sıradan bir sayfa
Entry format Varsayılan olarak Detect from the document. Algılama reddettiğinde elle ayarlayın — sitemap, llms.txt ya da crawl
Index now Kaynak kaydedilir kaydedilmez bir çalıştırmayı kuyruğa alır

Giriş noktasını çekmek, üç formattan hangisi olduğunu algılamak ve ne bulunduğunu bildirmek için Kaynak kaydedildikten sonra satırındaki Test’e (ya da Edit diyaloğundaki Test connection’a) basın — bir sitemap’ten bir sayfa sayısı, llms.txt’ten bir link sayısı ya da bir crawl için başlangıç sayfasının kendisinin sunduğu link sayısı.

Giriş noktası ne olabilir

Contextator, verdiğiniz URL’deki belgeyi okur, uzantısını değil, bu yüzden üçü de herhangi bir yolda çalışır:

  • sitemap.xml — her <loc> çekilecek bir sayfadır. Başka sitemap’lere işaret eden bir <sitemapindex>, WEB_MAX_DEPTH kadar derine ve en fazla WEB_MAX_PAGES iç içe sitemap okunacak şekilde otomatik olarak izlenir.
  • llms.txt — bir sitenin LLM tarafından okunabilir bir indeksi için gelişmekte olan konvansiyon. Sayfadaki her Markdown linki çekilecek bir sayfadır.
  • Tek bir sayfa — bunların dışındaki her şey bir crawl başlatır: o URL’den genişlik öncelikli, onun host’unu paylaşan ve onun yolunun altında kalan linkleri izleyerek.

Algılama, URL’yi değil belgeyi okur. Giriş noktasındaki belge üçünden hiçbirine uymadığında — bir landing page’e yönlendiren bir sitemap, HTML olarak sunulan bir llms.txt — kaynak tahmin etmek yerine reddeder ve Entry format alanını adlandırır, çünkü tahmin etmek, bir sayfayı ya da hiçbir sayfayı indekslemeyen ve yine de başarı bildiren bir kaynak üretir. Bu durumda Entry format’ı elle ayarlayın: bu, yalnızca algılananın bir göstergesi değil, çalışan bir geçersiz kılmadır.

Yayımlanmış bir dokümantasyon ya da yardım merkezi sitesi

Bir dokümantasyon platformunda — GitBook, Outline, BookStack, Wiki.js, bir satıcının yardım merkezi — çalışan bir site, sayfaları oturum açmadan bir tarayıcıda açılabiliyorsa bir kaynak olabilir. Contextator’ın platformu tanıması gerekmez: yayımlıyorsa sitenin sitemap.xml’ini ya da llms.txt’ini, yoksa crawl’ın başlayacağı ön sayfasını verin ve Test’e basın. Test üç biçimden hangisini bulduğunu ve ne kadarını gördüğünü söyler; reddedip Entry format’ı adlandırırsa biçimi elle ayarlayın. Bir oturum açma duvarının arkasındaki site bu yolla ulaşılamaz; platform sayfalarını bir git deposunda tutuyorsa, git kaynağı onları render edilmemiş hâliyle okur.

Beş tavan

Bir crawl, hepsi örnek genelinde ortam değişkeni olan beş sınırla sınırlıdır — kaynak başına geçersiz kılma yoktur:

Tavan Değişken Varsayılan
Kaynak başına sayfa WEB_MAX_PAGES 1000
Giriş noktasından link derinliği WEB_MAX_DEPTH 10
İstekler arası gecikme WEB_REQUEST_DELAY_MS 500
Toplam crawl zaman bütçesi WEB_CRAWL_BUDGET_MS 900000 (15 dakika)
robots.txt’e uy WEB_RESPECT_ROBOTS 1 (açık)

Bir tavana çarpmak, senkronizasyonu başarısız kılmak yerine crawl’ı olduğu yerde bitirir — kaynak, ulaştığı sayfaları indeksler ve çalıştırma hangi sınırın onu durdurduğunu söyler. Beşi de .env içindeki, ürünle gelen .env.example’de listelenen, örnek genelindeki WEB_* değişkenleridir — ulaşılan bir tavan için, değişkenlerden birini yükseltmeden önce giriş noktasını daraltmak ya da siteyi birden çok kaynağa bölmek daha iyi bir çözümdür.

WEB_MAX_PAGES indekslenen sayfaları değil, getirilen sayfaları sayar, bilerek: metni yalnızca script’lerinde olduğu için reddedilen bir sayfa, eskimiş bir sitemap bağlantısından gelen bir 404 ya da başarısız bir bağlantı yine de birinin web sunucusu tarafından sunulmuştur, bu yüzden burada hiç kimsenin hesabı olmadığı bir host’u korumak için var olan tek ayara sayılır. Hiç istenmeyen bir URL hiçbir zaman sayılmaz — bir robots.txt reddi ya da başka bir host’ta duran bir bağlantı, süreçten hiçbir şey çıkmadan yerel olarak alınan bir karardır.

robots.txt

Varsayılan olarak uyulur (WEB_RESPECT_ROBOTS=1):

  • Bir Crawl-delay yönergesi, hızı yalnızca WEB_REQUEST_DELAY_MS’in üzerine çıkarabilir — onu düşüremez.
  • robots.txt’in 404 yanıtı vermesi kısıtlama yok olarak okunur — crawl devam eder.
  • robots.txt’in hiç yüklenememesi — bir 5xx ya da bir bağlantı hatası — kuralları okunamayan bir siteyi crawl’lamak yerine senkronizasyonu başarısız kılar.

Headless bir tarayıcı yoktur: HTML yanıtında bulunmak yerine içeriği istemci tarafı JavaScript’le render edilen bir sayfa, tıpkı render edilemeyen bir dosyanın başka herhangi bir kaynakta olduğu gibi, adıyla reddedilir.

Bir sayfa neye dönüşür

Çekilen her sayfa, başka herhangi bir kaynaktan gelen bir .html dosyasının geçtiği aynı HTML→Markdown dönüşümünden geçer — bkz. İçerik Türleri. URL, belgenin yolu olur: uzantıyı, URL’nin bittiği sonek değil, yanıtın içerik türü belirler, ve bir query string atılmak yerine yolun içine hash’lenir, bu yüzden yalnızca query string’i farklı iki URL çakışmaz.

Nasıl taze tutulur

Yalnızca bir sitemap.xml kaynağı ucuz bir tazelik kontrolü alır: iki istek, önce robots.txt sonra sitemap’in kendisi, giriş sayısını ve en yeni <lastmod> tarihini son çalıştırmayla karşılaştırır. İkisi de değişmediyse hiçbir şey yeniden çekilmez. Hiç <lastmod> taşımayan bir sitemap’in karşılaştıracak hiçbir şeyi yoktur, bu yüzden aşağıdaki diğer iki biçim gibi her çalıştırmada baştan sona yeniden çekilir.

llms.txt ve crawl kaynaklarının ucuzca kontrol edilebilecek eşdeğer bir sinyali yoktur, bu yüzden her zamanlanmış çalıştırma, aynı beş tavan içinde kaynağı baştan sona yeniden çeker. Programın kendisinin nasıl ayarlandığı için bkz. İndeksleme.

İç adresler

Giriş noktasını bir editör yazar ve sunucu ona bağlanır, bu yüzden bir web kaynağının nereye bağlanabileceği sınırlıdır. Kaynağın yaptığı her istek — sayfalar, robots.txt, her sitemap (bir sitemap index’inin çocukları dahil) ve llms.txt; Test, tazelik kontrolü ve senkronizasyon için aynı şekilde — kontrolden geçer. Kontrol, bağlantının gerçekte kullandığı adres üzerinde, DNS’ten sonra ve her yönlendirmede yeniden çalışır. En fazla 5 yönlendirme izlenir. Hem http hem https serbesttir; yalnızca-https kuralı yoktur.

  • Her zaman reddedilir: loopback, link-local (bulut metadata adresi 169.254.169.254 dahil), belirtilmemiş ve multicast adresleri, ve ayrılmış 240.0.0.0/4 bloğu. Hiçbir ayar bunları kaldırmaz. Bir IPv4 adresi taşıyan IPv6 adresi (IPv4-eşlenmiş, çevrilmiş, uyumlu ve NAT64 biçimleri) o IPv4 adresi gibi değerlendirilir.
  • İzin verilmedikçe reddedilir: özel adresler — 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16, fc00::/7, kullanımdan kaldırılmış site-local fec0::/10, 100.64.0.0/10 ve 198.18.0.0/15.

0.3.1’e yükseltme. 0.3.1’den önce bir web kaynağı her adrese bağlanırdı. İç bir adresteki siteyi okuyan bir web kaynağı, yükseltmeden sonra host’u WEB_ALLOWED_HOSTS’ta listelenene kadar çalışmaz (virgülle ayrılmış host adları; şema, port ya da yol yok). Değer .env içinde ayarlanır ve instance yeniden başlatılır:

WEB_ALLOWED_HOSTS=docs.corp.example

Bir ret, kuralı kaynağın satırında ve Test mesajında adlandırır, örneğin:

refused: `docs.corp.example` resolves to a private address; list `docs.corp.example` in WEB_ALLOWED_HOSTS to allow it

Liste yalnızca özel adres kuralını ve yalnızca web kaynakları için kaldırır; SOURCE_ALLOWED_HOSTS ve GIT_ALLOWED_HOSTS ayrı listelerdir ve burada bir host’u kabul ettirmez. Helm’de key config.webAllowedHosts’tur (bkz. Kubernetes Üzerinde Çalıştırma).

Sık karşılaşılan sorunlar

Belirti Neden ve çözüm
Reddedildi: özel bir adrese çözümleniyor Sitenin host’unu WEB_ALLOWED_HOSTS’a ekleyin ve yeniden başlatın
Kaynak reddediyor ve Entry format’ı adlandırıyor Algılama, giriş noktasının ne olduğunu söyleyemedi — bir landing page’e yönlendiren bir sitemap, HTML olarak sunulan bir llms.txt. Formatı elle ayarlayın
İndeksten bir sayfa eksik WEB_MAX_PAGES ya da WEB_MAX_DEPTH’in ötesinde kalıyor, robots.txt tarafından dışlandı ya da içeriğini istemci tarafı JavaScript’le render ediyor
Çalıştırma bir tavanda durdu Kaynağın satırı hangisini adlandırır — sayfa, derinlik ya da zaman bütçesi. Ayarı yükseltmeden önce giriş noktasını daraltın ya da siteyi kaynaklara bölün
Senkronizasyon robots.txt’te başarısız oldu Hiç okunamadı (5xx ya da bir bağlantı hatası), bu bir izin olarak sayılmaz. Bir 404 sorun olmazdı
Bir sayfa served as …, which is not a page this source can read diyerek reddediliyor Host, bu kaynağın okumadığı bir içerik türü gönderiyor — bir .md dosyasında application/octet-stream yaygın olanıdır. Yalnızca HTML, Markdown ve düz metin okunur
Senkronizasyon başarısız oluyor ve mevcut belgeleri silmeyi reddettiğini söylüyor Çalıştırma, kaynak zaten belge tutarken hiçbir şey indekslemedi — bir CDN’in kısa süreliğine bir landing page ile yanıtladığı bir sitemap, yeniden adlandırılmış bir llms.txt. Belgeler, kaybolmuş sayılıp silinmek yerine tutulur; giriş noktasını kontrol edin, sonra yeniden senkronize edin

Gezinmek için ok tuşları, açmak için Enter.