Ragmux

Kullanım senaryoları

Türkçe içerikle RAG: store dili, metadata filtresi ve condense edilmiş sorgular

Türkçe belgeler için Ragmux retrieval kurulumu: kök bulan tam-metin arama için store dili, karma dilli store'lar için metadata filtresi, takip soruları için condense.

Güncelleme: Son gözden geçirme: Ragmux 0.6.0 sürümüne göre doğrulandı

Türkçe, bir retrieval yığınının varsayılanlarının metinle sessizce çeliştiği durumdur. Kelimeler ekle şekil değiştirir; bu yüzden sorudaki biçim çoğu zaman belgedeki biçim değildir. Kullanıcılar bir önceki tur olmadan anlamsız kalan takip soruları yazar. Bir şirket de çoğu zaman aynı politikanın Türkçe ve İngilizce sürümlerini yan yana tutar. Ragmux’un tam olarak bunlara yönelik üç ayarı var ve hiçbiri yalnızca Türkçeye özgü değil: sıradan retrieval kontrolleri bunlar ve bu sayfa Türkçe içeriği örnek alarak üçünü gezdiriyor.

Store dili: ne değiştirir, ne değiştirmez

Bir store’un language değeri varsayılan olarak simple’dır. tr yaparsanız store’un chunk’ları PostgreSQL’in turkish metin arama yapılandırmasıyla indekslenir ve sorgu da aynısıyla ayrıştırılır. İki taraf tek bir ayarı kullandığı için bir kelimenin kökü konusunda anlaşmazlığa düşemezler. Bu her zaman böyle değildi: önceki sürümlerde sorgu yapılandırması ayrı seçilebiliyor, indeks ise simple ile kuruluyordu; böylece bir turkish sorgusu indekste olmayan kökleri arıyor ve eşleşmeleri söylemeden kaybediyordu.

Etkilediği şeyler:

  • Hibrit aramanın tam-metin yarısı. Varsayılan hybrid modu vektör benzerliğini tam-metin sıralamasıyla kaynaştırır ve language ikincisini şekillendirir. vector modunda etki edeceği bir şey yoktur.
  • Token tahminleri. Ragmux’un token tahmin etmesi gereken yerde karakter sayısını simple için 4’e, Türkçe için 3,5’e böler; dokümantasyon bu oranın o200k_base tokenizer’ına karşı ölçüldüğünü söyler. Tahmin chunk boyutlandırmasını, token bildirmeyen bir upstream’in embedding token’larını ve dakikalık token limitindeki getirilen context’i besler. Upstream’in bildirdiği her sayı tahminin yerini alır.

Etkilemediği şeyler:

  • Vektör araması. Embedding modelinin Türkçeyi ne kadar iyi temsil ettiği bunu belirler; store ayarında bunu değiştiren bir şey yoktur. Güvenmeden önce kendi sorularınızı store’un arama testinden geçirin.
  • Bir pg_search store’u. BM25 indeksi globaldir ve PG_SEARCH_TOKENIZER ile bir kez token’lara ayrılır; bu yüzden store dili orada yok sayılır.
  • Karma dilli içerik. Dil algılama yoktur. Bir store’un tek bir dili vardır.

Belge içeren bir store’un dilini değiştirmek bir arka plan işidir: store rebuilding işaretlenir, chunks.fts toplu halde yeniden yazılır, bu sırada aramalar simple ile çalışmaya devam eder ve iş bitince fts_status ready olur. Chunk başına bir tsvector ve bir indeks girdisi daha saklamak gerekir. Bkz. Store language.

Karma Türkçe ve İngilizce: birleştirmeyin, filtreleyin

İki dili de tutan bir store simple’da kalmalıdır; simple kelimeleri yazıldığı gibi indeksler. Türkçe bir sorunun aynı politikanın İngilizce kopyasını getirmesini engellemek için belgeleri yüklerken etiketleyin:

metadata={"lang": "tr", "product": "gateway"}

ve isteği daraltın:

{"model": "…", "messages": […], "ragmux": {"filter": {"lang": "tr"}}}

Filter, anahtarları AND ile birleştirilen bir nesnedir; bir değer eşitlikle eşleşen bir skalerdir (ve tipe duyarlıdır, yani 2026, "2026" ile eşleşmez) ya da {"in": [...]}’dir. Aralık, or ve not yoktur. Aramanın her bacağına o bacağın LIMIT’inden önce uygulanır; bu yüzden seçici bir filter, o kadar eşleşen chunk varsa yine de tam bir top_k döndürür. Bir istek project’in yapacağı şeyi yalnızca daraltabilir; gramer dışı bir filter yanıtı sessizce genişletmek yerine 400 ile başarısız olur. Bkz. Metadata and filters.

Metadata düzenlemeleri ucuzdur: PATCH /admin/api/documents/{id} nesneyi tek bir satır güncellemesiyle değiştirir; hiçbir chunk yeniden yazılmaz ve hiçbir şey yeniden işlenmez.

Takip soruları: condense

“Peki yarı zamanlı çalışanlar için?” tek başına işe yarar hiçbir şey getirmez. query_strategy: condense ile bir chat modeli son birkaç turu ve yeni mesajı alır ve son mesajın dilinde, kendi başına anlaşılır tek bir arama sorgusu yazar. Embed edilen ve aranan, ham takip sorusu değil o sorgudur.

Açmadan önce bilinmesi gereken davranışlar:

  • Yalnızca geçmiş varsa çalışır. Tek kullanıcı mesajlı bir istek olduğu gibi kullanılır, ekstra çağrı yapılmaz.
  • Tek deneme, beş saniye, asla ölümcül değil. Hata, zaman aşımı ya da kullanılamaz bir cevapta son kullanıcı mesajı kullanılır ve hata log’lanır.
  • Maliyeti vardır. Çağrı isteğin gecikmesine eklenir; token’ları isteğin satırına eklenir ve project’in limitlerine sayılır.
  • Konuşmayı görür. Metin, chat modeline gittiği gibi condense connection’ının sağlayıcısına gider. Konuşma hassassa o connection’ın nerede çalıştığı önemlidir; on-prem veri akışı sayfası yerleri listeler.

Bkz. Query strategy. İlişkili bir ayar olan retrieval_policy: auto, Türkçe ve İngilizce ifadeleri bilen kural tabanlı bir sınıflandırıcıyla yalın bir selamlaşma ya da onay için retrieval’ı atlar. “Merhaba, iade nasıl yapılır?” sınıflandırıcının bilmediği kelimeler içerdiği için retrieval yapar; ve bir condense project’inde yalın bir “evet” atlanmaz, çünkü condense edilmiş sorgu onu gerçek bir soruya çevirir. Bkz. Retrieval policy.

Somut bir örnek: bir iade politikası asistanı

Bir perakendeci iade politikasını Türkçe ve İngilizce, ürün hattı başına bir set olacak şekilde PDF olarak tutuyor. İkisini de içerdiği için store simple’da; her belge {"lang": "tr"|"en", "product": "..."} ile yükleniyor ve Türkçe mağazanın project’i kendi backend’i üzerinden her istekte "filter": {"lang": "tr"} gönderiyor. Project, küçük bir yerel chat connection’ıyla condense kullanıyor; böylece iadelerle ilgili bir sorudan sonra gelen “ya kargo ücreti?” iadelerde kargo ücretleri hakkında bir soruya dönüşüyor.

Perakendeci sonra mağazayı ona yöneltmeden önce on gerçek müşteri sorusunu store’un arama testinden geçiriyor ve her biri için hangi parçanın ilk sırada çıktığını okuyor. Hiçbir ayarın yerini tutmadığı kısım bu kontroldür: bir ekip embedding modelinin ve chunk boyutunun kendi belgelerine uyup uymadığını böyle öğrenir.

Perakendeci daha sonra store’da yalnızca Türkçe içerik tutarsa language’i tr yapar, fts_status ready olana kadar bekler ve hiçbir şeyi yeniden yüklemeden kök bulan eşleşme elde eder.

fts_config olan bir store’u yükseltmek

Bir store’un fts_config’i simple dışındaysa sorguları artık simple ile ayrıştırılır: language ayarlanana kadar (turkish için tr) kök bulan eşleşme durur. Ragmux, pgvector backend’indeki her etkilenen store için başlangıçta, ayarlanacak dili adlandıran bir uyarı log’lar. Store’u bir language ile, simple bile olsa, kaydetmek uyarıyı susturur.

Bunun uymadığı durumlar

  • Taranmış belgeler. OCR yoktur; metin katmanı olmayan bir tarama reddedilir. Bkz. Özel belge soru-cevabı.
  • Tek store, çok dil, kök bulmalı. Bir store’un tek bir dili vardır. Türkçe ve İngilizcenin ikisi de kök bulmalı olacaksa iki store ve iki project gerekir.
  • Birden çok dilli ParadeDB. Bir pg_search kurulumu tüm veritabanı için bir kez token’lara ayırır, bu yüzden store başına kök bulamaz.

Türkçe belgeler için retrieval kurun

  1. Store'u language değeri tr olarak oluşturun

    embedding_connection_id ile birlikte language tr olarak POST /admin/api/rag-stores çağırın. Dil, chunk'ların tam-metin arama için nasıl token'lara ayrıldığını ve sorgunun onlara karşı nasıl ayrıştırıldığını belirler; böylece ikisi her zaman uyumlu kalır. Zaten belge içeren bir store'u, önce GET ile okuduğunuz tam mevcut gövdeyi, fts_config hariç (kullanımdan kalktı; farklı bir language ile birlikte gönderilmesi 400 verir), ve yeni language değerini PUT /admin/api/rag-stores/{id} ile göndererek ya da dashboard'daki dil seçicisiyle değiştirirsiniz; bu bir arka plan yeniden inşasını başlatır.

  2. Belgeleri bir metadata nesnesiyle yükleyin

    {"lang": "tr", "product": "gateway"} gibi bir metadata alanıyla multipart/form-data olarak POST /admin/api/rag-stores/{id}/documents çağırın. Alan o isteğin her dosyasına uygulanır; PATCH /admin/api/documents/{id} onu sonradan hiçbir şeyi yeniden işlemeden değiştirir.

  3. Sonucu store'un arama testiyle kontrol edin

    Gerçek bir Türkçe soruyla POST /admin/api/rag-stores/{id}/search çağırın ve isabetleri okuyun. Yanıt, dilin o aramaya uygulanıp uygulanmadığını bildirir; yalnızca vektör aramasında ve yeniden inşa sürerken uygulanmaz.

  4. Konuşmalı project'ler için condense'i açın

    Project'in önce GET ile okuduğunuz tam mevcut gövdesini (yalnız RAG alanları atlandığında değerini korur, diğerleri korumaz) ve query_strategy condense olarak PUT /admin/api/projects/{id} ile gönderin ya da dashboard'dan değiştirin. history_turns_for_query (1 ile 10, varsayılan 3) yeniden yazımın kaç önceki turu gördüğünü söyler; query_model_connection_id küçük bir chat connection'ını adlandırır, null ise project'in chat connection'ı (route'u varsa ilk route hedefi) kullanılır.

  5. Bir chat isteğini ragmux.filter ile daraltın

    POST /v1/chat/completions isteğine "ragmux": {"filter": {"lang": "tr"}} ekleyin. Gramer dışı bir filter yok sayılmaz, 400 ve invalid_ragmux koduyla reddedilir.

Sıkça sorulan sorular

Türkçe için language değeri hangisi?
tr. İndeksleme ve sorgu ayrıştırma için PostgreSQL'in yerleşik turkish metin arama yapılandırmasını seçer. Kabul edilen değerler simple ve sabit bir ISO 639-1 kod listesidir; listenin dışındaki bir kod 400 ile reddedilir.
Tek bir store hem Türkçe hem İngilizce belge tutabilir mi?
Evet, ama dilini simple'da tutun. Ragmux bir belgenin dilini algılamaz ve bir store'un tek bir dili vardır; karma bir store kelimeleri yazıldığı gibi, kök bulma ve stop word olmadan indeksler. Her belgeyi lang gibi bir metadata ile etiketleyin ve sorgu anında ona göre filtreleyin.
Store dili vektör aramasını değiştirir mi?
Hayır. Hibrit aramanın tam-metin yarısını ve token tahminlerini yönetir. Vektör benzerliğini store'un kullandığı embedding modeli belirler; yani Türkçeyi iyi işleyip işlemediği o modelin bir özelliğidir ve arama testi bunu kendi sorularınızla kontrol etmenizi sağlar.
Dil ayarı ParadeDB backend'iyle çalışır mı?
Hayır. pg_search backend'i store dilini yok sayar, çünkü BM25 indeksi globaldir ve PG_SEARCH_TOKENIZER ile bir kez token'lara ayrılır. Store yanıtı bu durumda language_applies_to_search değerini false bildirir.
Dil değişikliği uygulanırken aramalara ne olur?
Çalışmaya devam ederler. Store fts_status olarak rebuilding bildirir ve arka plan işi bitene kadar simple ile aranır; sonuçlar geçerli ama kök bulmasız kalır. Büyük bir store için dakikalar planlayın.
Condense maliyet ve gecikme ekler mi?
Evet, aramadan önce beş saniyelik bütçeli bir chat completion. Token'ları isteğin satırına eklenir ve project'in limitlerine sayılır. Hata verirse, zaman aşımına uğrarsa ya da kullanılamaz bir cevap dönerse retrieval son kullanıcı mesajını kullanır ve istek yine başarılı olur.
Selamlaşma atlama Türkçeyi anlıyor mu?
retrieval_policy auto, yalnızca bilinen selamlaşma ya da onay ifadelerinden oluşan bir mesajı atlayan, Türkçe ve İngilizce için kural tabanlı bir sınıflandırıcı kullanır. Selamlaşmayı bir soruyla karıştıran bir mesaj, örneğin Merhaba, iade nasıl yapılır?, yine retrieval yapar.

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