Yapay Zekâ Entegrasyonu

Yapay zekâ sohbetini, LaTeX hata önerilerini, kullanıcı erişimini, kotaları ve isteğe bağlı arama hizmetlerini yapılandırın.

Bu özellik ayaka-notes/ayakaleaf-pro tarafından sağlanır ve v6.3.0 sürümünden itibaren kullanılabilir. Herhangi bir sorunla karşılaşırsanız geri bildiriminizi bekliyoruz.

​

Yapay zekâ asistanı ve LaTeX hata asistanı

Ayakaleaf Pro, yapay zekâ özelliklerini düzenleyiciye 2 şekilde getirir.

• AI Assistant, soruları yanıtlamak ve incelemeniz için düzenleme önerileri sunmak üzere proje belgelerinizi ve geçerli seçiminizi bağlam olarak kullanabilir.
• Error Assistant, bir LaTeX derleme hatasını seçtiğinizde hedefe yönelik bir düzeltme önerir.

​

Toolkit yapılandırması

Toolkit dağıtımınızdaki config/variables.env dosyasına aşağıdakileri ekleyin; örnek URL’yi, anahtarı ve modeli sağlayıcınızdan aldığınız değerlerle değiştirin:

AI_ENABLED=true
AI_BASE_URL=https://ai-gateway.example.com/v1
AI_API_KEY=REPLACE_WITH_YOUR_GATEWAY_API_KEY
AI_MODEL=YOUR_TEXT_MODEL_ID

Gerçek API anahtarlarını dağıtım ortamı dosyanızda tutun ve sürüm denetiminin dışında bırakın. Yukarıdaki değerler yer tutucudur, çalışan kimlik bilgileri değildir.

Yapay zekâ önerilerinin kalitesi seçtiğiniz modele bağlıdır. Zaten bir Codex veya ChatGPT aboneliğiniz varsa, bunu CLIProxyAPI’nin OpenAI uyumlu uç noktası üzerinden bağlayabilirsiniz.

AI_BASE_URL, gerektiğinde sağlayıcının sürüm önekini de içeren OpenAI uyumlu API temel URL’sidir. Bunu dahili olarak biz eklediğimiz için /chat/completions eklemeyin. Ağ geçidi ve model, akışlı (streaming) sohbet tamamlamalarını ve fonksiyon araçlarını desteklemelidir. Her iki özellik de belge bağlamını bu ağ geçidine gönderir; bunları kabul eden bir model kullanıldığında sohbet, yüklenen görselleri ve PDF dosyalarını da gönderebilir.

Toolkit, config/variables.env dosyasını uygulama konteynerine iletir. Burada gösterilen değişken adlarını koruyun; OVERLEAF_ öneki eklemeyin. Bu değişkenleri değiştirdikten sonra Toolkit dizininden uygulama konteynerini yeniden oluşturun:

bin/up -d

​

Ağ geçidi ayarları

Değişken	Varsayılan	Amaç
AI_ENABLED	false	Örnek için sohbeti ve hata önerilerini etkinleştirmek üzere tam olarak true olarak ayarlayın. Ayarlanmamışsa veya başka bir değer verilmişse devre dışı kalırlar. Ayrıca çalışan bir ağ geçidi yapılandırması da gereklidir.
AI_BASE_URL	Yok; zorunlu	OpenAI uyumlu API temel URL’si.
AI_API_KEY	Yok; zorunlu	Sunucu tarafından kullanılan, ilgili ağ geçidine ait API anahtarı.
AI_MODEL	Yok; zorunlu	Varsayılan sohbet yapılandırması ve LaTeX hata önerileri tarafından kullanılan metin modeli.
AI_IMAGE_MODEL	Ayarlanmamış	Aynı ağ geçidinde, aynı API anahtarını kullanan isteğe bağlı görsel destekli model.
AI_PDF_MODEL	Ayarlanmamış	PDF dosyası içeren sohbetler için aynı ağ geçidinde, aynı API anahtarını kullanan isteğe bağlı model. v6.4.0 sürümünden itibaren.
AI_MAX_STEPS	20	Otomatik devamlar dahil, yapay zekâ sohbetinde kullanıcı mesajı başına en fazla araç çağrısı sayısı. Pozitif bir tam sayı kullanın.
AI_PROXY_URL	Ayarlanmamış	Yapay zekâ ağ geçidine yapılan çağrılar için isteğe bağlı HTTP proxy URL’si. Web veya belge arama istemcilerini yapılandırmaz.
AI_TOKEN_QUOTA	0	Her dönem için sohbet ve hata önerileri tarafından paylaşılan, kullanıcı başına token sınırı. Ayarlanmamış veya 0 sınırsız anlamına gelir; sınır için pozitif bir tam sayı kullanın.
AI_TOKEN_QUOTA_PERIOD	month	month her ayın ilk günü 00:00 UTC’de sıfırlanır; week her pazartesi 00:00 UTC’de sıfırlanır. Diğer değerler month olarak kullanılır.

Görsel yüklemeleri için AI_IMAGE_MODEL değerini, görsel girdisi kabul eden ve sohbetin kullandığı araçları destekleyen bir modele ayarlayın. Geçmişinde görsel eki bulunan her sohbet isteği, o konuşmadaki sonraki mesajlar da dahil olmak üzere bu modeli kullanır. Bu ayar olmadan görsel istekleri, kendisinin görselleri desteklemesi gereken normal sohbet modelini kullanır. LaTeX hata önerileri AI_MODEL kullanmaya devam eder.

PDF ekleri v6.4.0 ve sonraki sürümlerde sunulmuştur. Kullanıcılar, görsellerde olduğu gibi 2 MB’a kadar PDF dosyaları ekleyebilir. Sohbet her PDF dosyasını olduğu gibi, bir Chat Completions file parçası olarak gönderir; bu nedenle ağ geçidi ve model PDF girdisini kabul etmelidir: OpenAI’nin görsel (vision) modelleri bunu kabul ederken, vLLM gibi birçok kendi kendine barındırılan ağ geçidi görselleri kabul eder ancak PDF dosyalarını reddeder. AI_PDF_MODEL değerini PDF dosyalarını okuyabilen bir modele ayarlayın; geçmişinde PDF dosyası bulunan her sohbet, o konuşmadaki sonraki mesajlar ve görseller dahil olmak üzere bu modeli kullanır; bu nedenle model görselleri de kabul etmelidir. Bu ayar olmadan PDF sohbetleri AI_MODEL kullanır. Model bir PDF dosyasını reddettiğinde sohbet, kullanıcıya yöneticiden AI_PDF_MODEL değerini ayarlamasını istemesini söyler.

Örneğin bir görsel modelini ve haftalık bir yapay zekâ kullanım hakkını etkinleştirmek için:

AI_IMAGE_MODEL=YOUR_IMAGE_CAPABLE_MODEL_ID
AI_TOKEN_QUOTA=100000
AI_TOKEN_QUOTA_PERIOD=week

​

Kullanıcı erişimi ve onay

Örnek düzeyindeki kullanılabilirlik ile kullanıcı izni birbirinden ayrıdır. AI_ENABLED ve ağ geçidi yapılandırması örnek düzeyindeki kullanılabilirliği denetler. Oturum açmış bir kullanıcının ayrıca mevcut hesap denetiminden de geçmesi gerekir: aiFeatures.enabled değeri false olmamalıdır. Bu mevcut veritabanı alanı hem sohbeti hem de LaTeX hata önerilerini denetler. Ayarlanmamışsa, yapay zekâ özellikleri kullanıcı için etkindir.

AI_TOKEN_QUOTA, izin verilen her kullanıcıya eşit olarak uygulanan bir sınırdır; mevcut modül hesap başına ayrı bir sayısal sınır sağlamaz.

Yönetici kullanıcı listesinde bir kullanıcı seçin ve Update account info → AI features öğesini açın. Enable AI features, hesap değişiklikleri kaydedildiğinde aiFeatures.enabled değerini günceller. Sunucu, zaten açık olan bir düzenleyiciden gelen istekler de dahil olmak üzere yeni yapay zekâ isteklerinde geçerli izinleri denetler. İzni olmayan bir kullanıcı düzenleyicide yapay zekâ asistanını görmeye devam eder, ancak mesaj gönderemez.

​

Kullanım ve sıfırlama

Yöneticinin AI features sekmesi, geçerli dönemin Usage, Limit ve Reset düğmesini tek bir satırda gösterir. Kullanım, sekme açıldığında okunur; sürekli olarak yenilenmez. En güncel sayıyı görmek için bir sohbet veya hata önerisi tamamlandıktan sonra sekmeyi yeniden açın. Sıfırlama hemen etkili olur ve yalnızca o kullanıcının geçerli dönem sayacını temizler, ardından görüntülenen kullanımı yeniden yükler. Hesap formunun geri kalanının kaydedilmesini gerektirmez.

Sohbet ve hata önerisi kullanımı tek bir Redis sayacını paylaşır; bu sayaç, bir istek tamamlandıktan sonra model sağlayıcısının bildirdiği toplam token sayısına göre güncellenir. Buna model adımları boyunca girdi ve çıktı token’ları dahildir. Girdi; konuşma geçmişini, belge bağlamını ve araç sonuçlarını içerebilir, bu nedenle bir takip mesajı yalnızca yeni mesajın kendisinden daha fazla token tüketebilir. Sınır Unlimited olduğunda bile kullanım kaydedilir. Token toplamı bildirilmeyen istekler sayaca eklenmez; geçmişte kaydedilmemiş kullanım modül tarafından yeniden oluşturulamaz.

Kota denetimleri akış başlamadan önce yapılır. Bir istek veya birkaç eşzamanlı istek, sonraki istekler engellenmeden önce kalan hakkı aşabilir. Bu, katı bir sağlayıcı harcama sınırı değil, bir kullanım hakkıdır. Kota sorgusu başarısız olursa isteğe izin verilir ve hata günlüğe kaydedilir.

Her iki özellik de AI_TOKEN_QUOTA kullanır; hata önerilerinin ayrı bir istek sayısı sınırı yoktur. Sayacı sıfırlamak izni, onayı, yapılandırılmış sınırı veya sağlayıcının kendi faturalandırma kayıtlarını değiştirmez. Sayaçlar UTC dönem anahtarlarını kullanır ve 40 gün sonra sona erer; Redis verilerini korumak, uygulama yeniden başlatmalarında geçerli kullanımı korur.

​

İsteğe bağlı arama hizmetleri

Web araması, Tavily uyumlu bir API kullanır. Bir arama API anahtarı yapılandırıldığında kullanılabilir. Bu ayarlar yapay zekâ ağ geçidinden bağımsızdır:

Değişken	Varsayılan	Amaç
TAVILY_API_KEY	Ayarlanmamış	Arama API anahtarı. WEB_SEARCH_API_KEY değerine göre önceliklidir.
WEB_SEARCH_API_KEY	Ayarlanmamış	Arama API anahtarı için alternatif ad.
WEB_SEARCH_URL	https://api.tavily.com/search	Arama uç noktası; özel uç noktalar Tavily istek ve yanıt biçimini kabul etmelidir.
WEB_SEARCH_MAX_RESULTS	5	Arama başına istenen sonuç sayısı; hizmetin desteklediği pozitif bir tam sayı kullanın.
WEB_SEARCH_DEPTH	basic	Arama derinliği; normalde basic veya advanced.
WEB_SEARCH_PROVIDER	tavily	Mevcut uygulama yalnızca Tavily uyumlu protokolü destekler; bu değeri değiştirmek başka bir bağdaştırıcı seçmez.
DOCS_MCP_URL	https://docs.overleaf.com/~gitbook/mcp	Belge arama uç noktası. Belge aramasını devre dışı bırakmak için boş bir dize olarak ayarlayın.

Örneğin:

TAVILY_API_KEY=REPLACE_WITH_YOUR_SEARCH_API_KEY
WEB_SEARCH_MAX_RESULTS=5
WEB_SEARCH_DEPTH=basic
DOCS_MCP_URL=https://docs.overleaf.com/~gitbook/mcp

Belge araması, yapılandırılmış GitBook MCP uç noktasının searchDocumentation aracını çağırır ve JSON veya SSE yanıtlarını kabul eder. Bu, belge araması için bir MCP istemcisidir. Ayakaleaf dışındaki yapay zekâ istemcilerinin bir proje üzerinde çalışmasına izin vermek için bkz. MCP Server.

Web sayfalarını okuma özelliği v6.4.0 ve sonraki sürümlerde sunulmuştur. Sohbet, kullanıcının verdiği bir bağlantı veya bir arama sonucu gibi bir sayfayı URL’si üzerinden okuyabilir. Sayfayı, harici URL’lerden dosya getiren hizmetle aynı olan bağlantılı URL proxy’si aracılığıyla getirir; bu nedenle External URL bölümünde açıklanan ağ kısıtlamaları bunun için de geçerlidir. Başka bir ayar gerekmez.

Arama sorguları yapılandırılmış arama hizmetine gider. Arama sonuçları daha sonra yapay zekâ ağ geçidine yapılan isteklere dahil edilebilir. Sohbetin Tools menüsü, kullanıcıların istekleri için Web ve Documentation seçeneklerini etkinleştirmesine veya devre dışı bırakmasına olanak tanır; bir aracın modelin kullanımına sunulabilmesi için sunucuda da yapılandırılmış olması gerekir.

​

Soru&Cevap

Yapay zekâ asistanı düzenleyicide görünmüyor

Cevap: Yapay zekâ asistanı, düzenleyicinin sol çubuğunda yalnızca AI_ENABLED=true olduğunda ve AI_BASE_URL, AI_API_KEY ve AI_MODEL değerlerinin tümü ayarlandığında görünür. Bunlardan biri eksikse yapay zekâ asistanı tüm kullanıcılar için gizlenir.

config/variables.env dosyasını değiştirdikten sonra konteyneri bin/up -d ile yeniden oluşturun. Yalnızca tarayıcıyı yenilemek yeni değişkenleri uygulamaz. Yönetici panelindeki Enable AI features anahtarı yapay zekâ asistanını göstermez veya gizlemez; yalnızca kullanıcının mesaj gönderip gönderemeyeceğini belirler.

Mesaj gönderiyorum ancak yapay zekâ asistanı yanıt vermiyor

Cevap: Önce kullanıcının yapay zekâ asistanında gösterilen yapay zekâ onay kartını kabul ettiğini kontrol edin. Bundan önce mesaj gönderilemez.

Ardından web hizmeti günlüğünde hata olup olmadığına bakın:

bin/logs web

Günlük mesajı	Anlamı
workbench AI chat requested but no AI gateway is configured	Çalışan konteynerde AI_ENABLED, AI_BASE_URL, AI_API_KEY veya AI_MODEL değerlerinden biri eksik. Konteyneri bin/up -d ile yeniden oluşturun.
workbench chat stream error	Ağ geçidi bir hata döndürdü. Kullanıcı “The AI service returned an error” mesajını görür. Günlüğe kaydedilen hata, ağ geçidinin durum kodunu ve mesajını gösterir.
workbench chat failed	İstek, akıştan önce veya akış sırasında başarısız oldu; örneğin ağ geçidine ulaşılamadığı için.

Sağlayıcınızın panelinde hiç kullanım görünmüyorsa istek sağlayıcıya ulaşmamıştır. Yaygın nedenler şunlardır:

• AI_BASE_URL yanlıştır; örneğin eksik veya fazladan bir /v1 vardır ya da sonuna /chat/completions eklenmiştir.
• Sunucu ağ geçidine ulaşamıyordur. Giden trafiğin bir proxy üzerinden geçmesi gerekiyorsa AI_PROXY_URL değerini ayarlayın.
• AI_MODEL, ağ geçidinin tanıdığı bir model kimliği değildir.

Sağlayıcı istekleri gösteriyor ancak sohbet yine de başarısız oluyorsa, modelin akışlı sohbet tamamlamalarını ve fonksiyon araçlarını desteklediğini kontrol edin.

Sohbet geçmişi saklanıyor mu?

Cevap: Hayır. Bir sohbet yalnızca açık tarayıcı sekmesinde tutulur. Sayfayı yenilemek veya kapatmak sohbeti temizler ve Start new chat mevcut sohbetin yerini alır. Önceki sohbetlerin bir listesi yoktur ve her proje aynı anda tek bir sohbet gösterir.