RAGFlow: Bikin RAG Engine yang Ngerti Dokumen Beneran, Lengkap dengan Sitasi

Halo temen-temen, balik lagi sama aku. Kalau kalian udah pernah main-main sama RAG (Retrieval Augmented Generation), pasti tahu rasanya frustrasi waktu bot kalian ngasih jawaban ngawur cuma gara-gara chunking-nya kacau. Dokumen PDF yang isinya penuh tabel, gambar, sama layout dua kolom sering banget dipotong sembarangan sama tool RAG biasa, dan hasilnya jawaban yang keluar jadi ngaco atau malah halusinasi. Nah, di tutorial kali ini aku mau ngenalin kalian ke RAGFlow, sebuah open-source RAG engine yang fokus banget di pemahaman dokumen secara mendalam.

RAGFlow ini beda sama tool RAG kebanyakan yang cuma nge-split teks pakai karakter atau token. Dia punya yang namanya deep document understanding, jadi dia beneran ngerti struktur dokumen kalian: mana yang judul, mana paragraf, mana tabel, mana gambar, bahkan bisa OCR buat dokumen hasil scan. Terus dia pakai template-based intelligent chunking, jadi cara motong dokumennya nyesuain sama jenis dokumennya. Dan yang paling aku suka, tiap jawaban yang dikasih itu ada grounded citations-nya, jadi kalian bisa lihat sumber jawaban itu dari halaman mana, dari potongan teks yang mana. Ini penting banget buat kepercayaan, apalagi kalau kalian mau pakai buat use case serius kayak legal, medis, atau finansial.

Di artikel ini aku bakal ajak kalian dari nol: mulai dari deploy RAGFlow pakai Docker Compose, bikin knowledge base, upload dokumen, milih metode chunking yang pas, konfigurasi chat assistant, sampai akhirnya query pakai HTTP API sama Python SDK lengkap dengan sitasinya. Siapin kopi, kita mulai pelan-pelan.

Introduction: Kenapa RAGFlow Beda

Sebelum masuk ke teknis, aku pengen kalian paham dulu kenapa RAGFlow ini worth buat dipelajari. Masalah paling umum di dunia RAG itu bukan di model LLM-nya, tapi di kualitas retrieval-nya. Prinsip "garbage in, garbage out" itu berlaku banget. Kalau potongan dokumen yang kalian kasih ke LLM itu udah kepotong di tengah tabel, atau nyampur antara footer sama isi, ya jawaban yang keluar juga bakal jelek.

Nah, RAGFlow nyerang masalah ini dari akarnya. Ada beberapa hal yang bikin dia beda:

Pertama, deep document understanding. RAGFlow punya model khusus buat ngenalin layout dokumen. Dia bisa bedain header, paragraf, list, tabel, sama gambar. Buat dokumen yang di-scan atau berupa foto, dia jalanin OCR dulu. Jadi tabel yang biasanya jadi mimpi buruk buat RAG lain, di RAGFlow bisa di-extract dengan strukturnya tetep utuh.

Kedua, template-based chunking. RAGFlow nyediain beberapa template chunking yang udah disesuain sama jenis dokumen. Ada template buat dokumen umum, buku, paper akademik, tabel, resume, presentasi, dan lain-lain. Jadi kalian nggak dipaksa pakai satu strategi chunking buat semua jenis dokumen. Ini yang bikin retrieval-nya jauh lebih relevan.

Ketiga, grounded citations. Tiap jawaban yang keluar dari RAGFlow itu selalu nunjuk ke chunk asal dan halaman dokumennya. Jadi kalau ada yang ragu sama jawaban bot, tinggal cek sumbernya. Ini ngurangin risiko halusinasi secara drastis karena LLM dipaksa jawab berdasarkan konteks yang ada, bukan ngarang.

Keempat, semuanya open-source dan self-hosted. Kalian bisa jalanin di server sendiri, data kalian nggak kemana-mana, dan kalian bisa pakai model LLM apapun, baik itu OpenAI, model lokal via Ollama, atau provider lain. Buat kalian yang concern sama privasi data, ini nilai plus yang gede.

Oke, cukup teorinya. Sekarang kita langsung praktek deploy.

Instalasi: Deploy RAGFlow Pakai Docker Compose

Cara paling gampang dan direkomendasiin buat jalanin RAGFlow itu pakai Docker Compose. RAGFlow ini sebenernya bukan satu aplikasi tunggal, tapi kumpulan beberapa service: ada web server-nya sendiri, ada Elasticsearch atau Infinity buat vector store, ada MySQL buat metadata, MinIO buat object storage, sama Redis. Docker Compose bakal ngurusin semua itu sekaligus.

Persiapan Sistem

Sebelum mulai, pastiin sistem kalian memenuhi requirement minimal. RAGFlow ini lumayan berat karena ada Elasticsearch di dalamnya, jadi jangan coba-coba di mesin kentang ya temen-temen. Berikut yang kalian butuhin:

• CPU minimal 4 core
• RAM minimal 16 GB (direkomendasiin, 8 GB bisa tapi bakal berat)
• Disk minimal 50 GB
• Docker versi 24 ke atas
• Docker Compose versi 2.26 ke atas

Ada satu hal penting yang sering bikin orang gagal deploy: Elasticsearch butuh setting vm.maxmapcount yang cukup tinggi. Kalau kelewat, container Elasticsearch bakal crash terus. Jadi kita set dulu.

# Cek nilai vm.maxmapcount saat ini
sysctl vm.maxmapcount

Kalau di bawah 262144, set jadi 262144
sudo sysctl -w vm.maxmapcount=262144

Biar permanen setelah reboot, tambahin ke sysctl.conf
echo "vm.maxmapcount=262144" | sudo tee -a /etc/sysctl.conf

Clone Repo dan Jalanin

Setelah itu, tinggal clone repo RAGFlow dan masuk ke folder docker-nya.

# Clone repository RAGFlow
git clone https://github.com/infiniflow/ragflow.git
cd ragflow/docker

Lihat file konfigurasi environment
cat .env | grep RAGFLOWIMAGE

Di file .env itu ada variabel penting namanya RAGFLOWIMAGE. Default-nya biasanya pakai image versi slim yang lebih kecil dan nggak nyertain model embedding bawaan. Kalau kalian mau versi lengkap yang udah include embedding model, edit variabel ini.

# Edit .env, ganti image ke versi full (tanpa suffix -slim)
Contoh: RAGFLOWIMAGE=infiniflow/ragflow:v0.20.0

nano .env

# Jalanin semua service pakai docker compose
Flag -d biar jalan di background (detached)
docker compose -f docker-compose.yml up -d

Cek status semua container
docker compose -f docker-compose.yml ps

Pantau log server sampai muncul tanda sudah siap
docker logs -f ragflow-server

# RAGFlow default jalan di port 80
Buka di browser: http://localhost:80 atau http://IP-SERVER-KAMU

# Simpan konfigurasi dasar buat semua contoh berikutnya
RAGFLOWBASEURL = "http://localhost:80"  # ganti sesuai alamat server kamu

RAGFLOWAPIKEY = "ragflow-xxxxxxxxxxxxxxxxxxxxx"  # API key dari menu pengaturan


Header standar buat semua request HTTP API
HEADERS = {
    "Authorization": f"Bearer {RAGFLOWAPIKEY}",

    "Content-Type": "application/json",
}

import requests

RAGFLOWBASEURL = "http://localhost:80"

RAGFLOWAPIKEY = "ragflow-xxxxxxxxxxxxxxxxxxxxx"

HEADERS = {
    "Authorization": f"Bearer {RAGFLOWAPIKEY}",

    "Content-Type": "application/json",
}

def buatknowledgebase(nama, chunkmethod="naive"):
    """Bikin dataset (knowledge base) baru lewat HTTP API."""
    url = f"{RAGFLOWBASEURL}/api/v1/datasets"
    payload = {
        "name": nama,
        # chunkmethod: naive = General, qa, manual, table, paper, dll

        "chunkmethod": chunkmethod,

        "embeddingmodel": "text-embedding-3-large@OpenAI",
    }
    resp = requests.post(url, headers=HEADERS, json=payload)
    resp.raiseforstatus()
    data = resp.json()
    datasetid = data["data"]["id"]

    print(f"Knowledge base '{nama}' dibuat, ID: {datasetid}")
    return datasetid


if name == "main":
    dsid = buatknowledgebase("Dokumentasi Produk", chunkmethod="naive")

import requests

RAGFLOWBASEURL = "http://localhost:80"

RAGFLOWAPIKEY = "ragflow-xxxxxxxxxxxxxxxxxxxxx"


def uploaddokumen(datasetid, pathfile):
    """Upload satu file ke dataset. Pakai multipart, bukan JSON."""
    url = f"{RAGFLOWBASEURL}/api/v1/datasets/{datasetid}/documents"

    # Untuk upload file, hanya kirim Authorization, jangan set Content-Type manual
    headers = {"Authorization": f"Bearer {RAGFLOWAPIKEY}"}

    with open(pathfile, "rb") as f:
        files = {"file": f}
        resp = requests.post(url, headers=headers, files=files)
    resp.raiseforstatus()
    data = resp.json()
    docid = data["data"][0]["id"]

    print(f"Dokumen ter-upload, ID: {docid}")
    return docid


def parsedokumen(datasetid, docids):
    """Trigger parsing + chunking untuk daftar dokumen."""
    url = f"{RAGFLOWBASEURL}/api/v1/datasets/{datasetid}/chunks"

    headers = {
        "Authorization": f"Bearer {RAGFLOWAPIKEY}",

        "Content-Type": "application/json",
    }
    payload = {"documentids": docids}

    resp = requests.post(url, headers=headers, json=payload)
    resp.raiseforstatus()

    print("Parsing dimulai, cek status di UI atau via API.")

if name == "main":
    datasetid = "ISIDATASETIDKAMU"

    docid = uploaddokumen(datasetid, "./panduan-produk.pdf")
    parsedokumen(datasetid, [docid])

import requests

RAGFLOWBASEURL = "http://localhost:80"

RAGFLOWAPIKEY = "ragflow-xxxxxxxxxxxxxxxxxxxxx"

HEADERS = {
    "Authorization": f"Bearer {RAGFLOWAPIKEY}",

    "Content-Type": "application/json",
}

def buatchatassistant(nama, datasetids):
    """Bikin chat assistant yang terhubung ke knowledge base."""
    url = f"{RAGFLOWBASEURL}/api/v1/chats"
    payload = {
        "name": nama,
        "datasetids": datasetids,
        "prompt": {
            "similaritythreshold": 0.2,

            "topn": 6,
            "keywordssimilarityweight": 0.3,
            # Instruksi biar bot jawab hanya dari konteks + selalu sitasi
            "prompt": (
                "Kamu asisten dokumentasi. Jawab HANYA berdasarkan konteks "
                "knowledge base. Kalau tidak ada di konteks, bilang tidak tahu. "
                "Selalu sertakan sitasi."
            ),
        },
        "llm": {"temperature": 0.2},
    }
    resp = requests.post(url, headers=HEADERS, json=payload)
    resp.raiseforstatus()
    chatid = resp.json()["data"]["id"]

    print(f"Chat assistant dibuat, ID: {chatid}")
    return chatid


if name == "main":
    chatid = buatchatassistant("Bot Dokumentasi", ["ISIDATASETIDKAMU"])

import requests

RAGFLOWBASEURL = "http://localhost:80"

RAGFLOWAPIKEY = "ragflow-xxxxxxxxxxxxxxxxxxxxx"

HEADERS = {
    "Authorization": f"Bearer {RAGFLOWAPIKEY}",

    "Content-Type": "application/json",
}

def buatsession(chatid, nama="sesi-baru"):

    url = f"{RAGFLOWBASEURL}/api/v1/chats/{chatid}/sessions"
    resp = requests.post(url, headers=HEADERS, json={"name": nama})
    resp.raiseforstatus()
    return resp.json()["data"]["id"]

def tanya(chatid, sessionid, pertanyaan):
    """Kirim pertanyaan, ambil jawaban + referensi sitasi."""
    url = f"{RAGFLOWBASEURL}/api/v1/chats/{chatid}/completions"

    payload = {
        "question": pertanyaan,
        "sessionid": sessionid,

        "stream": False,  # non-streaming biar gampang di-parse
    }
    resp = requests.post(url, headers=HEADERS, json=payload)
    resp.raiseforstatus()

    data = resp.json()["data"]

    print("JAWABAN:")
    print(data["answer"])

    # Bagian reference berisi chunk sumber yang jadi dasar jawaban
    referensi = data.get("reference", {})
    chunks = referensi.get("chunks", [])
    print("\nSUMBER SITASI:")
    for i, c in enumerate(chunks):
        namadok = c.get("documentname", "tak dikenal")

        cuplikan = c.get("content", "")[:120]
        print(f"  [{i}] {namadok}: {cuplikan}...")
    return data

if name == "main":
    chatid = "ISICHATIDKAMU"
    sessionid = buatsession(chatid)

    tanya(chatid, sessionid, "Bagaimana cara reset password di produk ini?")

# Install SDK resmi RAGFlow
pip install ragflow-sdk

from ragflowsdk import RAGFlow

Inisialisasi client
rag = RAGFlow(
    apikey="ragflow-xxxxxxxxxxxxxxxxxxxxx",

    baseurl="http://localhost:80",
)

Ambil dataset yang sudah ada berdasarkan nama
datasets = rag.listdatasets(name="Dokumentasi Produk")

dataset = datasets[0]
print(f"Dataset: {dataset.name}, jumlah dokumen: {dataset.documentcount}")

Ambil chat assistant yang sudah dibuat
assistants = rag.listchats(name="Bot Dokumentasi")

assistant = assistants[0]

Buat session lalu tanya
session = assistant.createsession(name="sesi-sdk")
jawaban = session.ask("Apa saja fitur utama produk ini?", stream=False)

print("JAWABAN:")
print(jawaban.content)

Loop referensi untuk lihat sitasi
print("\nSITASI:")
for ref in jawaban.reference:
    print(f"  - {ref.get('document_name')} (hal. {ref.get('page', '?')})")

SDK ini juga support streaming kalau kalian mau nampilin jawaban token per token kayak ChatGPT. Tinggal set stream=True dan iterasi hasilnya. Buat aplikasi produksi yang butuh UX responsif, streaming ini penting banget.

Best Practices

Setelah lumayan lama main sama RAGFlow, ada beberapa hal yang aku pelajari dan pengen aku share biar kalian nggak jatuh di lubang yang sama.

Pertama, selalu verifikasi hasil chunking sebelum produksi. Jangan langsung percaya sama chunking otomatis. Buka visual inspection, lihat apakah tabel ke-extract dengan bener, apakah ada chunk yang kepotong aneh. Sepuluh menit ngecek chunking bisa nyelametin kalian dari jam-jam debugging jawaban ngawur nanti.

Kedua, pilih template chunking sesuai jenis dokumen, jangan asal General buat semua. Aku udah beberapa kali ketemu kasus di mana ganti dari General ke template yang lebih spesifik (misal Paper buat dokumen ilmiah) langsung ningkatin kualitas jawaban secara signifikan. Kalau knowledge base kalian isinya campur banyak jenis dokumen, pertimbangin pisahin jadi beberapa knowledge base dengan template masing-masing.

Ketiga, atur similarity threshold dengan hati-hati. Nilai default kadang terlalu longgar, bikin chunk nggak relevan ikut masuk dan ngerusak jawaban. Kalau kalian lihat bot sering ngasih jawaban yang nyerempet-nyerempet nggak jelas, coba naikin threshold-nya sedikit demi sedikit. Sebaliknya kalau bot sering bilang "tidak tahu" padahal jawabannya ada, turunin threshold-nya.

Keempat, manfaatin hybrid search. RAGFlow gabungin semantic search sama keyword search. Buat dokumen yang penuh istilah teknis, nama produk, atau kode spesifik, keyword search itu penting banget karena semantic search kadang meleset di istilah langka. Atur keyword similarity weight naik kalau domain kalian penuh jargon.

Kelima, selalu aktifin dan tampilkan sitasi. Ini bukan cuma soal fitur keren. Sitasi itu bikin user percaya, dan yang lebih penting, bikin kalian gampang audit kalau ada jawaban salah. Kalian bisa langsung lacak jawaban salah itu berasal dari chunk mana, terus perbaiki di sumbernya.

Keenam, perhatiin resource server. RAGFlow itu berat karena Elasticsearch. Pantau penggunaan RAM dan disk secara rutin. Kalau knowledge base kalian gede banget, pertimbangin pakai Infinity sebagai vector store alternatif yang lebih ringan, atau tambah RAM server. Jangan sampai container mati di tengah proses parsing dokumen penting.

Ketujuh, jaga API key baik-baik. API key RAGFlow punya akses penuh ke semua dataset kalian. Jangan pernah hard-code di kode yang dipush ke repo publik. Pakai environment variable atau secret manager. Ini basic tapi sering banget kelupaan.

Kedelapan, buat production, pikirin strategi update dokumen. Kalau dokumen sumber berubah, kalian harus re-parse. Bikin pipeline otomatis pakai API yang aku contohin tadi biar knowledge base selalu sinkron sama sumber aslinya. Dokumen yang basi itu sama bahayanya sama jawaban yang salah.

Conclusion

Oke temen-temen, kita udah nyampe di ujung tutorial. Kita udah bahas cukup banyak: mulai dari kenapa RAGFlow beda dari tool RAG biasa, deploy pakai Docker Compose, bikin knowledge base dan upload dokumen, milih metode chunking yang pas, konfigurasi chat assistant, sampai query pakai HTTP API dan Python SDK lengkap dengan sitasi.

Yang paling aku pengen kalian bawa pulang dari artikel ini adalah bahwa kualitas RAG itu ditentuin di tahap retrieval, bukan cuma di model LLM-nya. RAGFlow ngasih kalian kontrol penuh di tahap itu: deep document understanding buat ngerti struktur dokumen, template chunking buat motong dengan pinter, hybrid search buat retrieval yang akurat, dan grounded citations buat jawaban yang bisa dipercaya dan diverifikasi. Kombinasi ini bikin RAGFlow jadi pilihan yang serius buat use case produksi, apalagi buat domain yang nggak boleh salah kayak legal, medis, atau layanan pelanggan.

Saran aku, jangan berhenti di tutorial ini. Coba deploy sendiri, masukin dokumen kalian yang sebenernya, terus eksperimen sama berbagai template chunking dan setting retrieval. Rasain sendiri gimana perubahan kecil di konfigurasi bisa ngefek gede ke kualitas jawaban. Karena pada akhirnya, RAG yang bagus itu hasil dari eksperimen dan iterasi, bukan sekali setup langsung jadi.

Kalau kalian ada pertanyaan atau nemu insight menarik waktu nyoba RAGFlow, jangan sungkan share ke aku. Selamat ngoprek temen-temen, dan semoga bot RAG kalian makin pinter dan makin bisa dipercaya. Sampai ketemu di tutorial berikutnya.