What is RAGFlow and how do I use it for document QA?

RAGFlow is a framework for building retrieval-augmented generation pipelines. You ingest, chunk, embed, retrieve, and generate answers with citations to reduce hallucinations and improve accuracy.

How should I chunk documents in RAGFlow?

Use semantic or hybrid chunking with 600–1,000 token chunks and 50–100 token overlap. For code, chunk by function or class and include surrounding context.

Which vector database works best with RAGFlow?

Choose a store that supports hybrid search, metadata filters, and reranking—Qdrant, Weaviate, Pinecone, or a local option are all common choices.

How do I prevent hallucinations in a RAGFlow app?

Enforce a cite‑or‑silence policy, add an answerability check before generation, and keep prompts strict about using only retrieved context.

What metrics should I track to evaluate RAGFlow?

Monitor retrieval hit rate, answer faithfulness, latency, and cost per 100 queries, and maintain a small but representative evaluation set.

RAGFlow Nasıl Kullanılır: Güvenilir RAG Uygulamaları Oluşturmak İçin Pratik Bir Kılavuz

Eğer bir retrieval-augmented generation (RAG) sistemi oluşturmayı denediyseniz, muhtemelen klasik sorunlu noktalara denk gelmişsinizdir: halüsinasyonlar, güvenilmez veri alma, yavaş işlem hatları ve karmaşık belge ön işleme. RAGFlow, belge alımını, parçalamayı, vektörleştirmeyi, almayı ve üretmeyi daha fazla kontrol ve gözlemlenebilirlikle düzenlemenize yardımcı olan uçtan uca bir iş akışı aracı olarak devreye giriyor.

Bu kılavuz, pratik ve çözüm odaklı bir yaklaşım sunmaktadır. Temiz bir kurulumda size yol gösterecek, gerçek belgeler için RAGFlow'u nasıl kullanacağınızı gösterecek ve halüsinasyonları gerçekten azaltan ve cevap kalitesini artıran kalıpları paylaşacağız.

RAGFlow nedir ve neden kullanılır?

RAGFlow, Retrieval-Augmented Generation işlem hatları oluşturmak için bir sistemdir. Tipik bir RAG kurulumunda şunları yaparsınız:

Belgeleri alırsınız (PDF'ler, web sayfaları, slaytlar, kod vb.)

İçeriği alınabilir birimlere ayırırsınız

Anlamsal arama için öbekleri vektörlere gömersiniz

Soru sorulduğunda en alakalı ilk k öbeği alırsınız

Bir LLM kullanarak temellendirilmiş bir cevap oluşturursunuz

RAGFlow, daha hızlı yineleme yapabilmeniz ve daha güvenilir uygulamalar sunabilmeniz için belirli varsayılanlar, iş akışı blokları ve koruma rayları ekler. Özellikle şunları istiyorsanız kullanışlıdır:

Tutarlı öbekleme ve meta veri: Daha iyi veri alma, daha iyi öbeklerle başlar.

Takılabilir gömme ve LLM'ler: OpenAI, yerel modeller veya kurumsal uç noktaları değiştirin.

Değerlendirmeler ve koruma rayları: Veri alma kalitesini ölçün ve halüsinasyonları azaltın.

Dağıtılabilir işlem hatları: Daha az yeniden yazma ile not defterinden üretime geçin.

Hızlı başlangıç: Sıfırdan çalışan bir RAGFlow işlem hattına

Aşağıda uyarlayabileceğiniz minimum, uçtan uca bir iş akışı bulunmaktadır. Ortamınız farklı olsa bile, sıra ve koruma rayları taşınabilirdir.

1) Ortamınızı hazırlayın

Anahtarlarınızla bir .env oluşturun:

OPENAI_API_KEY (veya başka bir LLM sağlayıcısı)

EMBEDDINGS_API_KEY (ayrı bir sağlayıcı kullanılıyorsa)

VECTOR_DB_URL (örn. Pinecone, Weaviate, Qdrant veya yerel)

Klasörlerle bir proje dizini ayarlayın, örneğin ragflow-project/:

data/raw/ (kaynak dosyalar)

data/processed/ (temizlenmiş öbekler)

configs/ (işlem hattı ayarları için YAML/JSON)

eval/ (veri kümeleri ve raporlar)

2) Temiz meta verilerle belgeleri alın

İyi meta veri = daha iyi veri alma. Başlıkları, yazarları, tarihleri ve kaynakları normalleştirin.

Güvenilir bir ayrıştırıcı ile PDF'leri ve slaytları metne dönüştürün

Yapıyı koruyun: başlıklar, listeler, kod blokları ve tablolar

Her bir öbeğe meta veri ekleyin: source, section, page, timestamp, version

İpucu: Alıntılar ve yeniden alımı desteklemek için bir doc_id ve chunk_id bulundurun.

3) İçeriğinize uygun bir öbekleme stratejisi seçin

Öbekleme, veri alma kalitesini ve gecikmeyi güçlü bir şekilde etkiler.

Anlatı belgeleri için: anlamsal öbekleme (başlıklara/paragraflara göre bölme)

Teknik belgeler için: hibrit öbekleme kullanın (anlamsal + sabit pencere)

Kod için: küçük bir kayan pencereyle fonksiyon/sınıfa göre öbekleyin

Başlamak için önerilen ayarlar:

chunk_size: 600–1.000 belirteç

chunk_overlap: 50–100 belirteç

max_depth: parçalanmayı önlemek için iç içe geçmiş bölümleri 2-3 seviye ile sınırlayın

4) Gömme ve bir vektör deposu seçin

Güçlü bir genel amaçlı gömme modeliyle başlayın (örn. text‑embedding‑3‑large veya modern bir yerel model). Gizlilik önemliyse, kendinden barındırılan gömmeleri değerlendirin.

Aşağıdakileri destekleyen bir vektör veritabanı kullanın:

Hibrit arama (yoğun + anahtar kelime)

Filtreler (meta veri kısıtlamaları)

Toplu ekleme ve dizin metrikleri

Test edilecek dizin ayarları:

İlk veri alma için top_k = 5–10

similarity_metric = cosine (veya belirli modeller için dot)

Fazlalığı azaltmak için maksimum marjinal alaka düzeyini (MMR) etkinleştirin

5) Veri alma düzenlemesi

İki aşamalı bir alıcı uygulayın:

Hızlı aday hatırlama

Hibrit arama (BM25 + yoğun)

Büyük top_k (örn. 30–50)

Yeniden sıralama

Çapraz kodlayıcı yeniden sıralayıcı veya LLM tabanlı puanlama

Son top_k'ye indirin (örn. 5–8)

Güvenilir belgelerle cevapları kısıtlamak için meta veri filtreleri ekleyin: source:"handbook" AND section:"benefits" AND version:"v2".

6) Yapı ile temellendirilmiş oluşturma

İsteminiz, kanıt zayıf olduğunda alıntıları ve reddetmeyi zorunlu kılmalıdır.

Örnek sistem istemi:

Dikkatli bir asistansınız. YALNIZCA sağlanan bağlam tarafından desteklenen bilgilerle yanıtlayın.
- Kaynakları satır içi olarak [doc_id:chunk_id] olarak belirtin.
- Bağlam yetersizse, "Sağlanan belgelerde yeterli bilgi yok." deyin.
- Gerçekleri icat etmeyin.

Kullanıcı istemi şablonu:

Soru: {query}
Bağlam:
{top_chunks}
Talimatlar:
- Önce kısa bir cevap verin, sonra ayrıntıları verin.
- Her olgusal iddiadan sonra alıntılar ekleyin.

7) Halüsinasyonları azaltmak için koruma rayları ekleyin

Cevaplanabilirlik kontrolü: Oluşturmadan önce küçük bir modele sorun: “Alınan öbeklerde doğrudan kanıt var mı?” Yoksa, açıklığa kavuşturucu bir soru döndürün.

Alıntı-veya-sessizlik ilkesi: Alıntıları olmayan çıktıları engelleyin.

Kurumsal içerik için Toksiklik/PII filtreleri.

8) Değerlendirme ve sürekli iyileştirme

Aşağıdakilerle bir eval/ seti oluşturun:

50–200 gerçek kullanıcı sorusu

Temel gerçek cevaplar (veya güvenilir referanslar)

Uygulanabilir olduğunda beklenen kaynaklar (belge kimlikleri)

Ölç:

Veri alma isabet oranı (altın kaynak ilk k'de görünüyor mu?)

Cevap doğruluğu (alıntı destekli ifadeler)

Gecikme (uçtan uca p95)

Maliyet (100 sorgu başına)

Şunu yineleyin:

Öbek boyutu ve örtüşme

Gömme modeli seçimi

Yeniden sıralayıcıya karşı daha yüksek ilk k

İstemin yapısı ve kısıtlamaları

Tam bir RAGFlow işlem hattı: Örnek yapılandırma

Aşağıda araç zincirinize uyarlayabileceğiniz kavramsal bir yapılandırma bulunmaktadır. Gerekirse sağlayıcı adlarını değiştirin.

project: product-handbook-rag
io:
input_path: data/raw/
output_index: product-handbook-index
parsing:
pdf:
strategy: auto
keep_layout: true
extract_tables: true
markdown:
preserve_headings: true
chunking:
method: semantic_hybrid
target_tokens: 800
<a15>overlap_tokens: 80</a16><a16>windowing: 2</a17><a17>metadata:</a18><a18>fields: [doc_id, title, section, page, version, source]</a19>embeddings:
provider: openai
model: text-embedding-3-large
vectorstore:
type: qdrant
url: ${VECTOR_DB_URL}
<a25>similarity: cosine</a26><a26>retrieval:</a27><a27>hybrid: true</a28><a28>lexical_weight: 0.35</a29><a29>semantic_weight: 0.65</a30><a30>candidate_top_k: 40</a31><a31>rerank:</a32><a32>enabled: true</a33><a33>model: bge-reranker-large</a34><a34>final_top_k: 7</a35><a35>generation:</a36><a36>llm: gpt-4o</a37><a37>temperature: 0.2</a38><a38>cite_or_silence: true</a39><a39>guardrails:</a40><a40>answerability_check: true</a41><a41>pii_filter: true</a42><a42>toxicity_filter: moderate</a43><a43>monitoring:</a44><a44>log_traces: true</a45><a45>latency_budget_ms: 3500</a46>cost_budget_per_100: 1.25

Farklı içerik türleri için RAGFlow nasıl kullanılır

Ürün kılavuzları ve el kitapları

Net bölüm sınırlarıyla anlamsal öbeklemeyi tercih edin

Güncel olmayan cevapları önlemek için sürümü ve geçerlilik tarihini ekleyin

Katı filtreler kullanın: her zaman version = latest gerektirin

Bilgi tabanları ve SSS

Kesin cevaplar için daha küçük öbekler (400–600 belirteç) kullanın

Aday havuzunu artırın ve tam snippet'i bulmak için yeniden sıralamaya güvenin

Sözcüksel arama yoluyla hatırlamayı artırmak için otomatik olarak kanonik S/C çiftleri oluşturun

Mühendislik belgeleri ve kodu

Fonksiyon/modül bazında öbekleyin ve meta verilere içe aktarma grafiklerini ekleyin

Üst-alt veri alımını etkinleştirin: fonksiyon + doküman dizisi bağlamını döndürün

İlgili sembollere öncelik vermek için kod farkında bir yeniden sıralayıcı kullanın

Yasal ve uyumluluk

Paragraf düzeyinde alıntılar gerektirin

Eksik bağlam için ret mantığı ekleyin

Ayrı bir dizinde düzenleyici onaylı kaynaklardan oluşan altın bir set tutun

Gerçekten işe yarayan istem kalıpları

Önce cevaplayın sonra alıntılayın: Üstte kısa cevap; her iddiadan sonra satır içi alıntılar

Veri alma zinciri: Modelden önce her öbeği özetlemesini, ardından sentezlemesini isteyin

Sorgu yeniden yazma: Veri almadan önce kullanıcı sorgularını eş anlamlılar ve alan terimleriyle genişletin

Zıt istemler: "A seçeneğinin bağlama göre neden B'den daha iyi olduğunu açıklayın." Bu, kanıt kullanımını zorlar

Örnek sorgu yeniden yazma adımı:

Orijinal: "Ücretli izin devretme politikamız nedir?"
Yeniden yazma: "ücretli izin devretme politikası; tatil devri; maksimum saat; politika sürümü en son"

Gözlemlenebilirlik ve geri bildirim döngüleri

Hangi öbeklerin kullanıldığını, puanlarını ve hangilerinin göz ardı edildiğini günlüğe kaydedin

Kısa bir gerekçeyle birlikte başparmak yukarı/aşağı yakalayın; bunu alıcı ayarlamasına geri besleyin

Herhangi bir model değişikliği dağıtmadan önce değerlendirme setinizde haftalık regresyon testleri çalıştırın

Performans ayarlama hile sayfası

Cevaplar genel hissediliyorsa: candidate_top_k'yi artırın ve daha güçlü bir yeniden sıralayıcı ekleyin

Cevaplar ayrıntıları kaçırıyorsa: öbek boyutunu küçültün; sözcüksel ağırlığı biraz artırın

Alıntılar aynı öbeği tekrarlıyorsa: MMR'yi etkinleştirin ve çeşitliliği artırın

Gecikme yüksekse: gömmeleri önbelleğe alın, sorgu yeniden yazımlarını önceden hesaplayın, daha küçük bir yeniden sıralayıcı kullanın

Maliyetler artarsa: oluşturma sıcaklığını düşürün, istemleri kısaltın, ilk geçiş için daha küçük bir LLM deneyin

Güvenlik ve yönetişim esasları

Saklanan vektörleri şifreleyin ve meta verilerdeki hassas alanları düzeltin

Dizin başına erişim kontrolü kullanın; ekibe veya veri hassasiyetine göre segmentlere ayırın

Bir veri soyu kaydı tutun: belge kaynağı URL'si, sağlama toplamı ve alım zaman damgası

Örnek olay anlık görüntüsü: Dağınık PDF'lerden güvenilir cevaplara

Bir destek ekibi 1.200 sayfalık PDF aldı. İlk veri alma tutarsızdı; temsilciler bota güvenmiyordu. Anlamsal-hibrit öbeklemeye (800 belirteç, 80 örtüşme) geçtikten, çapraz kodlayıcı yeniden sıralamayı etkinleştirdikten ve alıntı-veya-sessizliği zorunlu kıldıktan sonra, ilk k isabet oranı %62'den %89'a yükseldi ve temsilci benimsemesi ikiye katlandı. Anahtar daha büyük bir LLM değildi—daha temiz öbekler ve daha katı veri almaydı.

Araç ipucu: Bir AI kenar çubuğu ile hızlı yineleme

Belirtmekte fayda var: birçok belgede istemlerle ve veri alma snippet'leriyle denemeler yapıyorsanız, doğrudan tarayıcıdan PDF'ler, web sayfaları ve kod üzerinde sohbet etmenizi sağlayan bir AI asistanı yinelemeyi hızlandırabilir. Bu arada, Sider.AI (https://sider.ai/), üzerinde bulunduğunuz sayfadan bağlam çekmenizi, özetlemenizi ve istemleri hızlı bir şekilde iyileştirmenizi sağlayan bir AI kenar çubuğu sunar. İşlem hattını resmileştirmeden önce RAG istemlerini prototipleme ve öbek kalitesini test etme için kullanışlıdır.

RAGFlow Sorun Giderme: Hızlı düzeltmeler

“Model kendinden emin ama yanlış.”

Cevaplanabilirlik kontrolünü etkinleştirin; sıcaklığı düşürün; alıntılar gerektirin

“Arama neredeyse aynı kopyaları döndürüyor.”

MMR'yi açın; bir yeniden sıralayıcı ekleyin; öbek örtüşmesini azaltın

“Gecikme zirvede artıyor.”

Toplu gömmeler; sorgu yeniden yazımlarını önbelleğe alın; akış oluşturma kullanın

“Eski politikalar görünmeye devam ediyor.”

version = latest üzerinde filtre uygulayın; güncel olmayan belgeleri kullanımdan kaldırın veya mezar taşına yerleştirin

Sonraki adımlar: RAGFlow'unuzu üretimde güvenilir hale getirin

Küçük, güvenilir bir külliyatla başlayın; önce öbeklemeyi ve filtreleri mükemmelleştirin

LLM'yi yükseltmeden önce bir yeniden sıralayıcı ekleyin

100 soruluk bir değerlendirme seti oluşturun ve haftalık olarak isabet oranını takip edin

Veri almayı sürekli ayarlamak için kullanıcı geri bildirimini bağlayın

Temel çıkarımlar:

Veri alma kalitesi, RAG için model boyutunu yener

Öbekleme, meta veri ve yeniden sıralama temel kollarınızdır

Alıntı-veya-sessizlik gibi koruma rayları güveni önemli ölçüde artırır

Gözlemlenebilirlik ve değerlendirmeye erken yatırım yapın

Bu uygulamalarla RAGFlow, ister bir yardım botuna, bir geliştirici yardımcı pilotuna veya bir dahili bilgi asistanına güç veriyor olun, temellendirilmiş cevaplar için güvenilir bir omurga haline gelir.

SSS

S1:RAGFlow nedir ve belge KA için nasıl kullanırım? RAGFlow, veri alma artırılmış oluşturma işlem hatları oluşturmak için bir çerçevedir. Halüsinasyonları azaltmak ve doğruluğu artırmak için alıntılarla yanıtları alırsınız, öbeklersiniz, gömersiniz, alırsınız ve oluşturursunuz.

S2:RAGFlow'da belgeleri nasıl öbeklemeliyim? 600–1.000 belirteç öbekleri ve 50–100 belirteç örtüşmesiyle anlamsal veya hibrit öbekleme kullanın. Kod için, fonksiyon veya sınıf bazında öbekleyin ve çevreleyen bağlamı ekleyin.

S3:Hangi vektör veritabanı RAGFlow ile en iyi şekilde çalışır? Hibrit aramayı, meta veri filtrelerini ve yeniden sıralamayı destekleyen bir mağaza seçin—Qdrant, Weaviate, Pinecone veya yerel bir seçenek yaygın seçeneklerdir.

S4:Bir RAGFlow uygulamasında halüsinasyonları nasıl önlerim? Bir alıntı-veya-sessizlik ilkesi uygulayın, oluşturmadan önce bir cevaplanabilirlik kontrolü ekleyin ve istemleri yalnızca alınan bağlamı kullanma konusunda katı tutun.

S5:RAGFlow'u değerlendirmek için hangi metrikleri izlemeliyim? Veri alma isabet oranını, cevap doğruluğunu, gecikmeyi ve 100 sorgu başına maliyeti izleyin ve küçük ama temsili bir değerlendirme seti tutun.