Contextator
ENTR

Kaynaklar

Belge Kaynakları

Bir projenin taşıyabileceği dokuz kaynak türü, her yolun önüne eklenen mount adı, ve hepsinde senkronizasyonun ve hataların nasıl işlediği.

Güncelleme:

Bir projenin dokümantasyonu nadiren tek bir yerde yaşar. Bir kaynak o yerlerden biridir ve bir proje ihtiyacı kadar çok kaynak taşıyabilir — hepsi tek bir aranabilir endpoint’te birleşir.

Tür Nedir Kim senkronize eder Sayfa
Local directory Sunucuya bağlanan bir klasör, olduğu yerde taranır. Hiçbir şey kopyalanmaz İndeksleme anında okuyarak Yerel Klasör Kaynağı
Git repository Bir dalın, isteğe bağlı olarak yalnızca bir alt klasörünün shallow checkout’u Her çalıştırmanın başında git fetch, ya da bir push webhook Git Deposu Kaynağı
Upload Sunucuda açılan dosyalar, klasörler ve arşivler (.zip, .tar, .tar.gz/.tgz, .rar) Senkronize edilecek bir şey yok — değiştiğinde tekrar yüklersiniz Yükleme Kaynağı
Notion Dahili bir entegrasyonla paylaşılan, Markdown’a dönüştürülen sayfalar Notion API’si, yalnızca değişen sayfaları yeniden render ederek Notion
Confluence Bir Confluence Cloud ya da Data Center hesabının okuyabildiği ya da sizin adlandırdığınız her space, Markdown’a dönüştürülür Confluence REST API’si, yalnızca sürümü değişen sayfaları yeniden render ederek; Data Center ayrıca bir webhook kabul edebilir Confluence
Dokümantasyon sitesi Herkese açık bir sitenin kendi sitemap’i, llms.txt’i ya da bir crawl’ı, Markdown’a dönüştürülür Sitenin tamamının yeniden çekilmesi; <lastmod> tarihleri olan bir sitemap.xml, değişiklikler için önce iki istekte kontrol edilebilir Dokümantasyon Sitesi Kaynağı
S3 bucket S3 uyumlu bir bucket’ın (AWS S3, MinIO, Ceph, Cloudflare R2) tek bir önekindeki nesneler, önekten arındırılmış anahtarla adlandırılır Öneki listeleyerek, yalnızca ETag’i ya da boyutu değişen nesneleri indirerek S3 bucket’ları
Google Drive Bir Google servis hesabıyla paylaşılan klasörlerin altındaki dosyalar; Docs Markdown’a, Sheets .xlsx’e, Slides .pptx’e dönüşür Kontrol için tek bir changes.list isteği; bir çalıştırma yalnızca Google sürümü ya da checksum’ı değişen dosyaları çeker Google Drive
GitHub issues Tek bir deponun issue’ları ve isteğe bağlı olarak Discussions’ı; her biri yorumlarıyla bir belge Kontrol için tek bir koşullu istek; bir çalıştırma yalnızca son seferden beri değişeni okur GitHub issue’ları

Bir Obsidian vault’u bir Markdown klasörüdür, bu yüzden tek bir ayar çevrilerek local directory ya da upload olarak gelir. Bkz. Obsidian Vault’ları.

Mount adı

Her kaynağın bir adı vardır ve bu ad, katkıda bulunduğu her yolun önüne eklenir:

source "handbook"  contains  install.md   →  indexed as  handbook/install.md
source "api-repo"  contains  install.md   →  indexed as  api-repo/install.md

İki kaynağın çakışmadan aynı dosya adını taşıyabilmesinin, ve her arama sonucunun hangi kaynaktan geldiğini söyleyebilmesinin nedeni budur. Adın oluşturulduktan sonra değiştirilememesinin nedeni de budur — her indekslenmiş yol ve bir ajanın gördüğü her yol onu içerir. Bir kaynak hakkındaki geri kalan her şey düzenlenebilir.

Adlar, proje adlarıyla aynı kuralı izler: 1–63 karakter, küçük harf, rakam, - ve _; bir harf ya da rakamla başlar.

Bir kaynak eklemek

Bir proje üzerinde Add source, her tür için bir sekmesi olan bir diyalog açar. Ortak alanlar:

Alan Notlar
Name Mount öneki. Değiştirilemez
Label Listede gösterilen serbest metin. Opsiyonel, değiştirilebilir
Content type Plain Markdown / text, Obsidian vault, Notion export ya da OpenAPI / Swagger — sonuncusu .yaml, .yml ve .json dosyalarını spesifikasyon olarak okur ve birini operasyon başına bir belgeye çevirir
File types Hangi uzantıların indeksleneceği: varsayılan olarak .md ve .mdx, isteğe bağlı .txt, .html/.htm, .csv, .docx ve .pdf. Admin API ile oluşturulan kaynak, kendi türünün varsayılanıyla başlar: upload için .md, .mdx, .txt; Notion ve Confluence için .md; dokümantasyon sitesi için .html, .md, .txt
Language Opsiyonel. Aramanın anahtar sözcük yarısının bu kaynağı hangi dilde okuduğu; ayarlanırsa PostgreSQL sözcüklerini köklerine ayırır (stemming). Varsayılan olarak ayarsızdır — stemming yok, bu da HLY-4015 gibi tanımlayıcıları bozulmadan tutar. Değiştirmek bu kaynağı yeniden indeksler
Version Opsiyonel serbest metin (en fazla 64 karakter), kaynağın indekslediği her dokümana damgalanır, böylece search_docs tek bir sürümü isteyebilir. Birkaç kaynak bir sürümü paylaşabilir. Değiştirmek bu kaynağı yeniden indeksler
Sync every Yeni bir kaynak, bu örneğin SYNC_DEFAULT_INTERVAL_MINUTES değeriyle başlar (operatör değiştirmedikçe bir saat; 0, yeni kaynakların Never — only when asked ile başlamasını sağlar). Seçenekler Never, 5, 15, 30 dakika, saat, 6, 12 saat, gün ya da hafta: sunucu kaynağın değişip değişmediğine bakar ve yalnızca değiştiyse indeksler
Index now Kaynak kaydedilir kaydedilmez bir çalıştırma kuyruğa alınır

Git, Notion, Confluence, dokümantasyon sitesi, S3, Google Drive ve GitHub kaynakları hiçbir şey indekslenmeden kontrol edilebilir: kaynak kaydedildikten sonra satırındaki Test’e (ya da Edit diyaloğundaki Test connection’a) basın. Yeni bir kaynağın diyaloğunda böyle bir düğme yoktur. Test, kaydedilmemiş formu değil, kaynağı kaydedildiği haliyle okur: bir düzenlemeyi test etmeden önce kaydedin.

Bir kaynağın adresini taşımak, kimlik bilgisinin yeniden verilmesini ister. Bir Confluence kaynağının Site URL’si, bir git kaynağının URL’si, bir S3 kaynağının Endpoint’i ve bir GitHub kaynağının API address’i, saklanan kimlik bilgisinin gönderildiği yerlerdir. Bir editor bunları değiştirebilir ama kimlik bilgisini okuyamaz; bu yüzden 0.6.0’dan beri, bir kimlik bilgisi saklanırken host’u (şema, ad ya da port) taşıyan bir düzenleme, aynı istek kimlik bilgisini yeniden vermedikçe ya da kaldırmadıkça (API’de secret: null; dashboard’da token’ı yeniden yazın) ayarın adıyla 400 invalid_request ile reddedilir. Aynı host’ta yalnızca yolu değiştirmek, başka bir şeyi düzenlemek ve kimlik bilgisi saklamayan bir kaynağı (herkese açık bir depo) düzenlemek bundan etkilenmez.

Kaynaklar nasıl senkronize edilir

Her kaynak her indeksleme çalıştırmasının başında senkronize edilir, birbiri ardına, sonra taranır:

  1. git kaynakları dalın ucunu çeker; Notion kaynakları değişen sayfaları çeker; Confluence kaynakları sürümü değişen sayfaları çeker; dokümantasyon sitesi kaynakları siteyi yeniden getirir; S3, Google Drive ve GitHub kaynakları yalnızca değişeni indirir; local ve upload kaynaklarının çekecek bir şeyi yoktur.
  2. Her kaynağın klasörü, seçtiği dosya türleri için taranır.
  3. Yollar kaynak adıyla öneklenir ve indeksleyiciye verilir.

Tek bir kaynak satırında Sync’e basmak, başlıktaki Re-index ile aynı çalıştırmayı kuyruğa alır — kaynak başına değil, proje başına bir kuyruk vardır.

Zamanlanmış bir kaynak vadesi geldiğinde her zaman senkronize edilmez: sunucu önce kaynağın değişip değişmediğine bakar, değişmediyse senkronizasyonu atlar. Bu kontrol her şeyi göremez — Notion entegrasyonundan paylaşımı kaldırılan bir sayfa baktığı hiçbir şeyi oynatmaz — bu yüzden son başarılı senkronizasyonu SYNC_MAX_SKIP_HOURS değerinden (varsayılan 24 saat; 0 kapatır) eski olan kaynak yine de senkronize edilir. Bkz. Yapılandırma ve Notion.

S3 bucket’ları

Bir S3 bucket kaynağı (0.6.0’da yeni), tek bir önek altındaki, uzantısını kaynağın okuduğu (varsayılan olarak .md, .mdx ve .txt) nesneleri yansıtır ve herhangi bir klasör gibi indeksler. Önek adlardan çıkarılır: önek guides iken handbook adlı bir kaynaktaki guides/nested/a.md nesnesi handbook/nested/a.md olur. İstekler AWS Signature V4 ile imzalanır ve SDK olmadan gönderilir.

  • Endpoint. AWS S3 için boş bırakın (yalnızca https, bölge Region’dan). MinIO, Ceph, R2 ya da başka bir S3 uyumlu sunucu için adresini verin. Özel bir endpoint, host adı SOURCE_ALLOWED_HOSTS’ta listelenmedikçe reddedilir; loopback ve link-local, ne listelenirse listelensin reddedilmeye devam eder.
  • Anahtar çifti tek bir kimlik bilgisidir, bir access key ID ve bir secret access key; SECRET_KEY ile şifrelenmiş saklanır, bir daha döndürülmez ya da gösterilmez. Geçici kimlik bilgileri (session token) kabul edilmez, instance-profile ya da IRSA kimlik bilgileri de. Anahtara bucket üzerinde s3:ListBucket, önek üzerinde s3:GetObject verin, başka bir şey vermeyin.
  • Bir kontrolün maliyeti. Zamanlanmış bir kontrol öneki listeler ve hiçbir şey indirmez; kaynak yalnızca liste değiştiyse çalışır. Bir çalıştırma yalnızca ETag’i ya da boyutu değişen nesneleri çeker ve kaybolan nesnelerin belgelerini, ancak bütün indirmeler başarılı olduktan sonra kaldırır. Kaynağa belgelerini tutan en dar öneki verin.
  • Sınırlar. Bir kaynak en fazla S3_MAX_OBJECTS nesne indeksler (varsayılan 5 000), anahtar sırasındaki ilkleri; çalıştırmanın notu geri kalanın indekslenmediğini büyük harflerle söyler. Başarısız bir çalıştırma hiçbir şeyi ilerletmez, bu yüzden bir sonraki kontrol onu yeniden çalıştırır.
  • Dışa ve içe aktarma. Proje dışa aktarımı kaynağın ayarlarını taşır, anahtar çiftini taşımaz; içe aktarılmış bir S3 kaynağı zamanlanmamış gelir ve kimlik bilgisinin yeniden girilmesini ister.

Google Drive

Bir Google Drive kaynağı (0.6.0’da yeni), adlandırdığınız ve bir Google servis hesabıyla paylaşılan klasörlerin altındaki ağaçları indeksler. Hesap, kaynağın sahip olduğu tek kimliktir: hiçbir kullanıcı oturum açmaz ve istenen tek scope drive.readonly’dir.

  1. Bir Google Cloud projesinde Google Drive API’yi etkinleştirin.
  2. Bir servis hesabı oluşturun ve JSON türünde bir anahtar ekleyin; Google onu bir kez indirmenize izin verir.
  3. Her klasörü hesabın e-posta adresiyle (anahtar dosyasının client_email’i) Viewer olarak paylaşın.
  4. Dashboard’da Add source → Google Drive’ı seçin, klasör bağlantılarını ya da kimliklerini yapıştırın, anahtar dosyasını yükleyin ya da yapıştırın.
  • Anahtar SECRET_KEY ile şifrelenmiş saklanır, bir daha döndürülmez ya da gösterilmez. Kaynak başına bir servis hesabı kullanın: klasör listesi indekslenenleri sınırlar, hesabın görebildiklerini değil. 3 Mayıs 2024’te ya da sonra oluşturulan bir Google Cloud organizasyonu, bir yönetici politikayı gevşetene dek varsayılan olarak anahtar oluşturmayı engeller; workload identity federation ve kullanıcı OAuth’u desteklenmez.
  • Dışa aktarma biçimleri. Bir Google Doc Markdown olarak, bir Sheet .xlsx olarak, bir Slides sunumu .pptx olarak dışa aktarılır; son ikisi herhangi bir yükleme gibi dönüştürülür. Google’ın 10 MB dışa aktarma sınırını aşan bir Google dosyası adıyla reddedilir ve çalıştırma sürer. Diğer Google dosyaları (Forms, Drawings, Sites) ve kısayollar atlanır, çalıştırmanın notunda sayılır.
  • Bir kontrolün maliyeti. Tek bir changes.list isteği; hiçbir şey listelenmez ya da indirilmez. Bir çalıştırma klasörleri gezer ve yalnızca Google sürümü ya da checksum’ı değişen dosyaları çeker.
  • Sınırlar. Bir kaynak en fazla GDRIVE_MAX_FILES dosya indeksler (varsayılan 5 000) ve not, geri kalanın indekslenmediğini büyük harflerle söyler.
  • Ağ. Google istemci kütüphanesi yoktur. İstekler yalnızca oauth2.googleapis.com ve www.googleapis.com’a, https üzerinden, egress guard’dan geçerek gider ve hiçbir izin listesi ayarı geçerli değildir.
  • Paylaşılan sürücüler doğrulanmadı: desteklenmiyor sayın.
  • Dışa ve içe aktarma. Proje dışa aktarımı klasörleri ve ayarları taşır, anahtarı taşımaz; içe aktarılmış bir Drive kaynağı anahtarının yeniden girilmesini ister.

GitHub issue’ları ve Discussions

Bir GitHub issues kaynağı (0.6.0’da yeni), tek bir deponun issue’larını ve isteğe bağlı olarak Discussions’ını, yorumlar aynı belgede olacak şekilde her biri bir belge olarak indeksler: <ad>/issues/<numara>.md ve <ad>/discussions/<numara>.md. Git repository kaynağından farklı bir kaynaktır: deponun dosyaları ve wiki’si git ile gelir, bu kaynak ikisini de hiç okumaz. İkisini de istiyorsanız ikisini de ekleyin.

  • Kapsam. Closed issues too işaretlenmedikçe kapalı issue’lar dışarıda kalır; pull request’ler hiç indekslenmez. Her Discussion, açık ya da kapalı, bir belgedir. Issue metni sık sık adlar ve yapıştırılmış kimlik bilgileri taşır ve yazıldığı gibi indekslenir.
  • Token isteğe bağlıdır. Token olmadan kaynak, herkese açık bir deponun issue’larını GitHub’ın anonim hız sınırı altında okur. Token ile özel depoları da okur ve Discussions’ı açabilir; GitHub bunu yalnızca oturum açmış bir çağırana yanıtlar: token olmadan Discussions’ı işaretlemek 400 invalid_request ile reddedilir. Issues (ve Discussions) için okuma erişimi olan ince ayarlı bir kişisel erişim token’ı işe yarar; GitHub App’ler desteklenmez. Token şifrelenmiş saklanır.
  • GitHub Enterprise Server. API address’i sunucunun REST tabanına ayarlayın (https://ghe.example.com/api/v3), yalnızca https. Özel bir adresteki sunucu SOURCE_ALLOWED_HOSTS’ta adlandırılmalıdır.
  • Bir kontrolün maliyeti. Tek bir koşullu istek (ETag); hiçbir şey değişmediyse GitHub 304 yanıtlar. Bir çalıştırma yalnızca son seferden beri değişeni okur.
  • Silinenler tam çalıştırmalarda bulunur. Silinmiş ya da taşınmış bir issue, bir sonraki tam çalıştırmaya dek aranabilir kalır: ilk çalıştırma, ayarlar değiştikten sonraki çalıştırma ya da son tam çalıştırması SYNC_MAX_SKIP_HOURS’tan (o kapalıysa 24 saat) eski olan çalıştırma.
  • Sınırlar. Bir kaynak en fazla GITHUB_MAX_ISSUES issue ve GITHUB_MAX_DISCUSSIONS Discussion indeksler (her biri için varsayılan 5 000). Bir hız sınırı çalıştırmayı sıfırlanma zamanıyla error olarak bitirir ve hiçbir imleci ilerletmez.
  • Dışa ve içe aktarma. Proje dışa aktarımı depoyu ve ayarları taşır, token’ı taşımaz; içe aktarılmış bir kaynak zamanlanmamış gelir ve tokensız olan herkese açık kaynak gibi çalışır.

Bir kaynak başarısız olduğunda

Senkronize olamayan bir kaynak kendi satırında raporlar ve diğerleri yine indekslenir. Projenin durumu bir özetle error olur:

2/3 sources synced; notion: API token is invalid

Önemlisi, içeriği hiç okunamayan bir kaynak, daha önce katkıda bulunduğu dokümanları korur. İptal edilmiş bir Notion paylaşımı ya da ulaşılamayan bir git host’u, bir kaynağı boşaltmaz, yalnızca bayatlatır. Nedeni düzeltin ve o satırda Sync’e basın.

Düzenleme ve kaldırma

Kaynağın ürettiğini değiştiren bir ayarı değiştirmek — yol, dal, alt klasör, dosya türleri, içerik türü — otomatik olarak bir indeksleme çalıştırması kuyruğa alır, bu yüzden bir kaynak asla sessizce bayat kalmaz.

Bir kaynağı silmek, dokümanlarını, chunk’larını ve somutlaştırdığı dosyaları kaldırır. Proje indekslenirken reddedilir.

Ne indekslenir

Yalnızca kaynağın seçtiği dosya türleri: varsayılan olarak .md ve .mdx, isteğe bağlı olarak .txt, .html/.htm, .csv, .docx ve .pdf. Her şey girerken Markdown’a dönüşür — dönüşüm kenarda, bir kez olur; böylece chunker, embedder ve read_document tek bir format görür. .yaml, .yml ve .json bu listede değildir: yalnızca OpenAPI / Swagger içerik türüyle okunurlar ve okunan bir spesifikasyon tek bir belge değil, operasyon başına bir belge olur.

Her zaman atlanır:

  • gizli dosyalar ve gizli klasörler (.git/, .obsidian/, …)
  • node_modules, dist, build, vendor, __pycache__
  • işaret ettiği yer ne olursa olsun sembolik linkler
  • IGNORE_GLOBS ile eşleşen her şey
Tür Neye dönüşür Korunan Kaybedilen
.md, .mdx, .txt kendisi, değişmeden her şey hiçbir şey
.html, .htm turndown + GFM ile Markdown başlıklar, listeler, tablolar, kod, bağlantılar, <title> script’ler, stil sayfaları, svg, gömülü görsel verisi (alt metni kalır)
.docx mammoth ile Markdown, sonra aynı dönüştürücü Word’ün kendi başlık stilleri, numaralı ve madde imli listeler, tablolar, bağlantılar görseller, dipnotlar, yorumlar, izlenen değişiklikler
.csv bir GFM tablosu, her 200 satırda bir ## Rows n–m bölümü her bölümün üstündeki başlık, tırnaklı virgüller ve satır sonları, ;/tab/pipe ayraçları verinin hiçbir şeyi; hücre içi satır sonları <br> olur
.pdf glif konumlarından yeniden kurulan Markdown yazı tipi boyutuna göre başlıklar, satır sonları arasında yeniden birleştirilip tire kaldırılan paragraflar, madde imli ve numaralı listeler, kolon hizalı tablolar, iki kolonlu okuma sırası, düşürülen üst/alt bilgi satırları dipnotlar, şekiller, ve kolonları hizalı olmayan her tablo

Görseller ve diğer ikili dosyalar indekslenmez. OCR da yoktur, bu yüzden dönüştürülemeyen bir dosya — taranmış bir PDF, şifreli bir PDF, tamamı görsel olan bir Word dosyası, bu türlerden herhangi birinin bozuk bir kopyası, hiç metne dönüşmeyen bir sayfa ya da e-tablo — reddedilir, indekslenmez: dosyayı adıyla anan gerekçe kaynağın satırında gösterilir ve kaynağın geri kalanı normal şekilde indekslenir. Bir ret hiçbir zaman senkronizasyonu ya da projeyi başarısız kılmaz: artımlı bir çalıştırmada dosya zaten sahip olduğu belgeyi korur, ve bir rebuild onu yalnızca yeni nesle dahil etmez — hiç okunamayan bir kaynağa uygulanan kuralın aynısı.

Dönüştürme kendi worker thread’inde çalışır, pano ve MCP endpoint’ini sunan thread’de değil, bu yüzden yavaş bir dosya hiçbir zaman bir aramayı engellemez ve heap’ini tüketen bir parser yalnızca o dosyayı başarısız kılar. Boyut tavanları, tek bir dosyanın dönüşürken neye mal olabileceğini sınırlar — bir belge için MAX_CONVERTED_FILE_BYTES, akla yatkın olmayan bir sayfa sayısı iddia eden bir PDF için MAX_PDF_PAGES, bir .docx içindeki bir zip bomb’una karşı MAX_DOCX_UNPACKED_BYTES — ve CONVERSION_TIMEOUT_MS / CONVERSION_IDLE_MS, bir dosyanın ve boşta bir worker’ın ne kadar çalışmasına izin verildiğini sınırlar. Tüm varsayılanlar ve her birinin ne durdurduğu: Yapılandırma.

Uzun bir PDF, MAX_STORED_DOCUMENT_BYTES’a karşı nereye düşer (1 MB UTF-8, bunun ötesinde saklanan önek read_document’ın sunduğu şeydir ve content_truncated ayarlanır — kesme saklanan metin üzerinde olduğu ve parçalar üzerinde olmadığı için belge her durumda tamamen aranabilir kalır). 80, 200, 600 ve 1600 yoğun sayfalık üretilmiş kılavuzlar üzerinde ölçülmüştür (yaklaşık 95 karakterlik 42 satır, bir üst/alt bilgi satırı, her onuncu sayfada bir bölüm başlığı):

Sayfa Markdown Sayfa başına Çıkarma
80 316 KiB 4,0 KiB 0,18 sn
200 795 KiB 4,0 KiB 0,21 sn
600 2393 KiB 4,0 KiB 0,61 sn
1600 6414 KiB 4,0 KiB 1,73 sn

Tavan kabaca 250 yoğun sayfada ısırır — daha gevşek gerçek dünya kılavuzları bunu 300–400 sayfaya kadar uzatır. Çıkarma sayfa başına yaklaşık bir milisaniyeye mal olur ve içerik hash’i dosyanın değiştiğini söyledikten sonra bir kez gerçekleşir. Bunların hiçbirinden önce, girişte sınırlanan şey dosyanın kendisidir: upload’da UPLOAD_MAX_FILE_BYTES (varsayılan 50 MB), her kaynakta ise bir PDF ya da DOCX dönüştürülürken MAX_CONVERTED_FILE_BYTES (varsayılan 32 MiB).

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