Tutorial Lengkap txtai: Database Embeddings All-in-One untuk Semantic Search dan LLM Workflows

txtai adalah framework Python open-source yang menggabungkan database embeddings, pipeline AI, dan workflow orchestration dalam satu platform terpadu. Dikembangkan oleh NeuML, txtai memungkinkan developer membangun aplikasi AI yang powerful — mulai dari semantic search, question answering, hingga RAG (Retrieval-Augmented Generation) — tanpa perlu mengelola banyak library terpisah.

Dalam tutorial ini, kita akan mempelajari cara menggunakan txtai secara menyeluruh, mulai dari instalasi dasar hingga penggunaan lanjutan untuk membangun aplikasi AI yang production-ready.

Mengapa txtai?

Sebelum membahas teknis, penting untuk memahami mengapa txtai menjadi pilihan populer:

Instalasi

Instalasi Dasar

pip install txtai

Instalasi dengan Fitur Tambahan

txtai memiliki beberapa optional dependencies yang bisa diinstal sesuai kebutuhan:

# Instalasi dengan dukungan API server
pip install txtai[api]

Instalasi dengan dukungan pipeline (summarization, translation, dll)
pip install txtai[pipeline]

Instalasi dengan semua fitur
pip install txtai[all]

Instalasi dengan dukungan database SQL
pip install txtai[database]

Instalasi dengan dukungan graph
pip install txtai[graph]

Verifikasi Instalasi

import txtai
print(f"txtai version: {txtai.version}")

from txtai.embeddings import Embeddings
embeddings = Embeddings()
print("txtai berhasil diinstal!")

Basic Usage: Embeddings Database

Membuat Index Sederhana

Konsep utama txtai adalah Embeddings — sebuah database yang menyimpan dan mencari data berdasarkan kesamaan semantik, bukan keyword matching.

from txtai.embeddings import Embeddings

Inisialisasi embeddings dengan model default
embeddings = Embeddings(path="sentence-transformers/all-MiniLM-L6-v2")

Data contoh
data = [
    "Kucing adalah hewan peliharaan yang populer di seluruh dunia",
    "Python adalah bahasa pemrograman yang mudah dipelajari",
    "Machine learning mengubah cara kita memproses data",
    "Jakarta adalah ibu kota Indonesia",
    "Deep learning adalah subset dari machine learning",
    "Anjing dikenal sebagai sahabat terbaik manusia",
    "JavaScript digunakan untuk pengembangan web",
    "Natural language processing membantu komputer memahami bahasa manusia",
    "Bandung terkenal dengan kuliner dan udara sejuknya",
    "Transfer learning mempercepat proses training model AI"
]

Index data
embeddings.index([(i, text, None) for i, text in enumerate(data)])

Cari dokumen yang mirip
results = embeddings.search("bahasa pemrograman untuk data science", 3)
for score, idx in results:
    print(f"Score: {score:.4f} | {data[idx]}")

Output:

Score: 0.5823 | Python adalah bahasa pemrograman yang mudah dipelajari
Score: 0.4215 | Machine learning mengubah cara kita memproses data
Score: 0.3891 | JavaScript digunakan untuk pengembangan web

Indexing dengan Metadata

txtai juga mendukung penyimpanan metadata bersama dengan teks:

from txtai.embeddings import Embeddings

embeddings = Embeddings(
    path="sentence-transformers/all-MiniLM-L6-v2",
    content=True  # Aktifkan penyimpanan konten
)

Data dengan metadata
documents = [
    {"id": "doc1", "text": "Panduan instalasi Python untuk pemula", "category": "tutorial", "difficulty": "beginner"},
    {"id": "doc2", "text": "Optimasi query database PostgreSQL", "category": "database", "difficulty": "advanced"},
    {"id": "doc3", "text": "Membangun REST API dengan FastAPI", "category": "tutorial", "difficulty": "intermediate"},
    {"id": "doc4", "text": "Pengenalan Docker untuk deployment aplikasi", "category": "devops", "difficulty": "beginner"},
    {"id": "doc5", "text": "Arsitektur microservices dengan Kubernetes", "category": "devops", "difficulty": "advanced"},
]

Index dokumen
embeddings.index([(doc["id"], doc) for doc in documents])

Pencarian semantik
results = embeddings.search("cara deploy aplikasi", 3)
for result in results:
    print(f"Score: {result['score']:.4f} | {result['text']} | Category: {result['category']}")

Menyimpan dan Memuat Index

# Simpan index ke disk
embeddings.save("myindex")


Muat index dari disk
loadedembeddings = Embeddings()
loadedembeddings.load("myindex")

Gunakan index yang sudah dimuat
results = loadedembeddings.search("machine learning", 3)

from txtai.embeddings import Embeddings

embeddings = Embeddings(
    path="sentence-transformers/all-MiniLM-L6-v2",
    content=True
)

articles = [
    {"id": 1, "text": "Tutorial Python untuk analisis data", "author": "Ruby", "views": 1500, "category": "python"},
    {"id": 2, "text": "Machine learning dengan scikit-learn", "author": "Ahmad", "views": 2300, "category": "ml"},
    {"id": 3, "text": "Deep learning menggunakan PyTorch", "author": "Ruby", "views": 1800, "category": "ml"},
    {"id": 4, "text": "Web scraping dengan BeautifulSoup", "author": "Siti", "views": 900, "category": "python"},
    {"id": 5, "text": "Visualisasi data dengan Matplotlib", "author": "Ruby", "views": 3200, "category": "python"},
    {"id": 6, "text": "Natural language processing dengan spaCy", "author": "Ahmad", "views": 1100, "category": "nlp"},
]

embeddings.index([(a["id"], a) for a in articles])

SQL query: cari artikel oleh Ruby dengan views > 1000
results = embeddings.search(
    "SELECT id, text, views FROM txtai WHERE author = 'Ruby' AND views > 1000 ORDER BY views DESC"
)
for result in results:
    print(f"ID: {result['id']} | Views: {result['views']} | {result['text']}")

Kombinasi semantic search dengan SQL filter
results = embeddings.search(
    "SELECT id, text, score FROM txtai WHERE similar('artificial intelligence') AND category = 'ml' LIMIT 3"
)
for result in results:
    print(f"Score: {result['score']:.4f} | {result['text']}")

from txtai.pipeline import Summary

summary = Summary()

text = """
Artificial intelligence (AI) telah mengalami perkembangan pesat dalam beberapa tahun terakhir.
Teknologi ini telah diterapkan dalam berbagai bidang, mulai dari kesehatan, keuangan, hingga
transportasi. Salah satu cabang AI yang paling banyak digunakan adalah machine learning,
yang memungkinkan komputer belajar dari data tanpa diprogram secara eksplisit. Deep learning,
subset dari machine learning yang menggunakan neural network berlapis, telah mencapai
hasil yang mengesankan dalam pengenalan gambar, pemrosesan bahasa alami, dan generasi konten.
Namun, pengembangan AI juga menghadapi tantangan seperti bias dalam data, kebutuhan komputasi
yang besar, dan pertanyaan etika seputar penggunaan teknologi ini.
"""

result = summary(text)
print(f"Ringkasan: {result}")

from txtai.pipeline import Translation

translate = Translation()

Terjemahkan dari Indonesia ke Inggris
textid = "Saya sedang belajar pemrograman Python untuk analisis data"
result = translate(textid, "id", "en")

print(f"Terjemahan: {result}")

Terjemahkan dari Inggris ke Indonesia
texten = "Machine learning is transforming the way we process information"
result = translate(texten, "en", "id")

print(f"Terjemahan: {result}")

from txtai.pipeline import Extractor

extractor = Extractor(
    embeddings=embeddings,  # Gunakan embeddings yang sudah dibuat
    path="google/flan-t5-base"
)

Konteks dokumen
documents = [
    "Python dirilis pertama kali pada tahun 1991 oleh Guido van Rossum",
    "FastAPI adalah framework web Python modern yang dirilis pada 2018",
    "Django adalah framework web Python yang pertama dirilis pada 2005",
    "Flask adalah micro web framework yang dibuat oleh Armin Ronacher",
]

Ajukan pertanyaan
questions = [
    "Siapa yang membuat Python?",
    "Kapan FastAPI dirilis?",
    "Apa itu Flask?",
]

for question in questions:
    answer = extractor([(question, question, question, False)], documents)
    print(f"Q: {question}")
    print(f"A: {answer[0][1]}\n")

from txtai.pipeline import Labels

labels = Labels()

texts = [
    "Harga saham BBCA naik 2% hari ini",
    "Timnas Indonesia menang 3-0 melawan Thailand",
    "Gempa bumi berkekuatan 5.5 SR terjadi di Sulawesi",
    "Film terbaru Marvel mendapat rating tinggi dari kritikus",
]

categories = ["ekonomi", "olahraga", "bencana", "hiburan"]

for text in texts:
    result = labels(text, categories)
    toplabel = categories[result[0][0]]
    confidence = result[0][1]
    print(f"{text}")
    print(f"  -> Kategori: {toplabel} (confidence: {confidence:.4f})\n")

from txtai.embeddings import Embeddings
from txtai.pipeline import Extractor

Siapkan knowledge base
embeddings = Embeddings(
    path="sentence-transformers/all-MiniLM-L6-v2",
    content=True
)

knowledgebase = [
    {"id": 1, "text": "PT RUBYTHALIB DATA KONSULTA adalah perusahaan konsultan data dan AI yang berlokasi di Jakarta."},
    {"id": 2, "text": "Perusahaan menyediakan layanan konsultasi machine learning, data engineering, dan AI implementation."},
    {"id": 3, "text": "Ruby Abdullah adalah Direktur Utama PT RUBYTHALIB DATA KONSULTA."},
    {"id": 4, "text": "Layanan utama meliputi pengembangan model AI, data pipeline, dan pelatihan AI untuk korporasi."},
    {"id": 5, "text": "Kantor berlokasi di Indonesia Stock Exchange Building, SCBD, Jakarta Selatan."},
]

embeddings.index([(doc["id"], doc) for doc in knowledgebase])


Setup RAG dengan Extractor
extractor = Extractor(
    embeddings=embeddings,
    path="google/flan-t5-base"
)

Tanya-jawab berdasarkan knowledge base
questions = [
    "Di mana lokasi kantor perusahaan?",
    "Siapa direktur utama perusahaan?",
    "Apa saja layanan yang ditawarkan?",
]

contextdocs = [doc["text"] for doc in knowledgebase]


for q in questions:
    answer = extractor([(q, q, q, False)], contextdocs)
    print(f"Q: {q}")
    print(f"A: {answer[0][1]}\n")

RAG dengan LLM Integration

txtai mendukung integrasi dengan berbagai LLM provider untuk RAG yang lebih canggih:

from txtai.embeddings import Embeddings
from txtai.pipeline import LLM

Setup embeddings
embeddings = Embeddings(
    path="sentence-transformers/all-MiniLM-L6-v2",
    content=True
)

Data knowledge base
docs = [
    {"id": 1, "text": "Python 3.12 dirilis pada Oktober 2023 dengan peningkatan performa signifikan."},
    {"id": 2, "text": "Fitur baru Python 3.12 termasuk improved error messages dan f-string improvements."},
    {"id": 3, "text": "Python 3.12 memiliki performa 5% lebih cepat dibanding Python 3.11."},
    {"id": 4, "text": "Type parameter syntax baru diperkenalkan di Python 3.12 untuk generic classes."},
]

embeddings.index([(d["id"], d) for d in docs])

Setup LLM
llm = LLM("google/flan-t5-base")

RAG: Retrieve relevant docs, then generate answer
query = "Apa yang baru di Python 3.12?"
results = embeddings.search(query, 3)

Gabungkan konteks
context = "\n".join([r["text"] for r in results])
prompt = f"""Berdasarkan informasi berikut:
{context}

Jawab pertanyaan: {query}
Jawaban:"""

answer = llm(prompt)
print(f"Q: {query}")
print(f"A: {answer}")

Workflows: Orkestrasi Pipeline

Workflows memungkinkan Anda menggabungkan multiple pipeline menjadi satu alur kerja yang terintegrasi:

from txtai.embeddings import Embeddings
from txtai.pipeline import Summary, Translation, Labels
from txtai.workflow import Workflow, Task

Inisialisasi pipeline
summary = Summary()
translate = Translation()

Definisikan workflow
workflow = Workflow([
    Task(lambda x: summary(x, maxlength=50)),    # Step 1: Ringkas teks
    Task(lambda x: translate(x, "en", "id")),     # Step 2: Terjemahkan ke Indonesia
])

Jalankan workflow
texts = [
    """Artificial intelligence has made significant progress in recent years.
    Large language models can now generate human-like text, write code, and
    answer complex questions. These advances are transforming industries
    from healthcare to finance.""",
    """Cloud computing enables businesses to scale their infrastructure
    on demand. Major providers like AWS, Google Cloud, and Azure offer
    comprehensive services for computing, storage, and machine learning."""
]

results = list(workflow(texts))
for i, result in enumerate(results):
    print(f"Hasil {i+1}: {result}\n")

API Server

txtai menyediakan built-in API server yang bisa langsung digunakan untuk serving:

Konfigurasi YAML

Buat file config.yml:

# Embeddings configuration
path: sentence-transformers/all-MiniLM-L6-v2
content: true

Writable index
writable: true

Menjalankan API Server

# Install dependency API
pip install txtai[api]

Jalankan server
CONFIG=config.yml uvicorn "txtai.api:app" --host 0.0.0.0 --port 8080

Menggunakan API

import requests

BASEURL = "http://localhost:8080"


Tambah dokumen
requests.post(f"{BASEURL}/add", json=[
    {"id": "1", "text": "Tutorial Python untuk pemula"},
    {"id": "2", "text": "Machine learning dengan scikit-learn"},
    {"id": "3", "text": "Deep learning menggunakan TensorFlow"},
])

Index dokumen
requests.get(f"{BASEURL}/index")


Cari dokumen
response = requests.get(f"{BASEURL}/search", params={"query": "belajar AI", "limit": 3})
results = response.json()
for r in results:
    print(f"Score: {r['score']:.4f} | {r['text']}")

API Server dengan Docker

FROM python:3.11-slim

WORKDIR /app
RUN pip install txtai[api]

COPY config.yml .

EXPOSE 8080
CMD ["uvicorn", "txtai.api:app", "--host", "0.0.0.0", "--port", "8080"]

docker build -t txtai-api .
docker run -p 8080:8080 -v $(pwd)/config.yml:/app/config.yml txtai-api

Hybrid Search

txtai mendukung hybrid search yang menggabungkan semantic search dengan keyword search (BM25):

from txtai.embeddings import Embeddings

embeddings = Embeddings(
    path="sentence-transformers/all-MiniLM-L6-v2",
    content=True,
    hybrid=True,  # Aktifkan hybrid search
    scoring={
        "method": "bm25",
        "terms": True
    }
)

documents = [
    {"id": 1, "text": "Tutorial penggunaan library Pandas untuk analisis data tabular"},
    {"id": 2, "text": "Pandas adalah hewan langka yang dilindungi di China"},
    {"id": 3, "text": "Manipulasi DataFrame dengan Pandas: groupby, merge, dan pivot"},
    {"id": 4, "text": "Membaca file CSV dan Excel menggunakan Pandas library Python"},
    {"id": 5, "text": "Habitat panda raksasa di pegunungan Sichuan terancam deforestasi"},
]

embeddings.index([(d["id"], d) for d in documents])

Semantic search saja mungkin bingung antara Pandas (library) vs Panda (hewan)
Hybrid search lebih akurat karena menggabungkan konteks semantik + keyword matching
results = embeddings.search("Pandas Python library data analysis", 3)
for r in results:
    print(f"Score: {r['score']:.4f} | {r['text']}")

Graph Database

txtai juga mendukung graph database untuk menyimpan relasi antar dokumen:

from txtai.embeddings import Embeddings

embeddings = Embeddings(
    path="sentence-transformers/all-MiniLM-L6-v2",
    content=True,
    graph={
        "approximate": False,
        "topics": {}
    }
)

documents = [
    {"id": 1, "text": "Python adalah bahasa pemrograman populer untuk data science"},
    {"id": 2, "text": "Pandas library digunakan untuk manipulasi data di Python"},
    {"id": 3, "text": "NumPy menyediakan operasi array numerik untuk Python"},
    {"id": 4, "text": "Scikit-learn library machine learning berbasis Python dan NumPy"},
    {"id": 5, "text": "TensorFlow framework deep learning dari Google"},
    {"id": 6, "text": "PyTorch framework deep learning dari Meta"},
]

embeddings.index([(d["id"], d) for d in documents])

Query graph untuk menemukan dokumen yang terhubung
graph = embeddings.graph
print(f"Total nodes: {graph.count()}")

Cari dokumen yang terhubung dengan topik tertentu
results = embeddings.search("Python data science ecosystem", 5)
for r in results:
    print(f"Score: {r['score']:.4f} | {r['text']}")

Best Practices

1. Pilih Model yang Tepat

# Untuk bahasa Inggris - cepat dan efisien
embeddings = Embeddings(path="sentence-transformers/all-MiniLM-L6-v2")

Untuk kualitas lebih tinggi
embeddings = Embeddings(path="sentence-transformers/all-mpnet-base-v2")

Untuk multilingual (termasuk Bahasa Indonesia)
embeddings = Embeddings(path="sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2")

Untuk domain spesifik, gunakan model yang di-fine-tune
embeddings = Embeddings(path="your-org/custom-finetuned-model")

2. Optimasi Indexing untuk Data Besar

from txtai.embeddings import Embeddings

embeddings = Embeddings(
    path="sentence-transformers/all-MiniLM-L6-v2",
    content=True,
    batch=32,       # Ukuran batch untuk encoding
    encodebatch=128, # Batch size untuk index encoding
    faiss={
        "components": "IVF100,Flat",  # Gunakan IVF untuk dataset besar
        "nprobe": 10
    }
)

Untuk dataset sangat besar, gunakan upsert secara bertahap
def indexinbatches(embeddings, data, batchsize=1000):

    for i in range(0, len(data), batchsize):
        batch = data[i:i + batchsize]

        embeddings.upsert([(item["id"], item) for item in batch])
        print(f"Indexed {min(i + batchsize, len(data))}/{len(data)} documents")

indexinbatches(embeddings, largedataset)

# Simpan ke disk
embeddings.save("/path/to/index")

Muat kembali
embeddings = Embeddings()
embeddings.load("/path/to/index")

Gunakan cloud storage (S3, GCS)
embeddings.save("s3://bucket/path/to/index")
embeddings.load("s3://bucket/path/to/index")

import logging
import time

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger("txtai")

def timedsearch(embeddings, query, limit=5):
    start = time.time()
    results = embeddings.search(query, limit)
    elapsed = time.time() - start
    logger.info(f"Search '{query}' returned {len(results)} results in {elapsed:.3f}s")
    return results

5. Error Handling yang Baik

from txtai.embeddings import Embeddings

def safeindexandsearch(data, query):

    try:
        embeddings = Embeddings(
            path="sentence-transformers/all-MiniLM-L6-v2",
            content=True
        )
        embeddings.index([(d["id"], d) for d in data])
        results = embeddings.search(query, 5)
        return results
    except FileNotFoundError:
        print("Model tidak ditemukan. Pastikan model sudah didownload.")
        return []
    except Exception as e:
        print(f"Error: {e}")
        return []

from txtai.embeddings import Embeddings
from txtai.pipeline import Summary
import json

class DocSearchEngine:
    def init(self, model="sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2"):
        self.embeddings = Embeddings(
            path=model,
            content=True,
            hybrid=True,
            scoring={"method": "bm25", "terms": True}
        )
        self.summary = Summary()
        self.doccount = 0

    def adddocuments(self, documents):

        """Tambahkan dokumen ke index."""
        indexed = []
        for doc in documents:
            self.doccount += 1
            indexed.append((self.doccount, {

                "text": doc["content"],
                "title": doc.get("title", ""),
                "source": doc.get("source", ""),
                "category": doc.get("category", "general"),
            }))
        self.embeddings.index(indexed)
        print(f"Total dokumen terindex: {self.doccount}")

    def search(self, query, limit=5, category=None):
        """Cari dokumen berdasarkan query."""
        if category:
            sql = f"SELECT id, text, title, source, score FROM txtai WHERE similar('{query}') AND category = '{category}' LIMIT {limit}"
        else:
            sql = f"SELECT id, text, title, source, score FROM txtai WHERE similar('{query}') LIMIT {limit}"

        return self.embeddings.search(sql)

    def summarizeresults(self, results):

        """Ringkas hasil pencarian."""
        combined = " ".join([r["text"] for r in results[:3]])
        return self.summary(combined, maxlength=100)

    def save(self, path):
        self.embeddings.save(path)

    def load(self, path):
        self.embeddings.load(path)


Penggunaan
engine = DocSearchEngine()

docs = [
    {"title": "Instalasi Python", "content": "Python bisa diinstal melalui python.org atau menggunakan pyenv untuk manajemen versi.", "category": "setup"},
    {"title": "Virtual Environment", "content": "Gunakan venv atau conda untuk membuat environment Python yang terisolasi.", "category": "setup"},
    {"title": "Pandas Basics", "content": "Pandas menyediakan DataFrame dan Series untuk manipulasi data tabular secara efisien.", "category": "data"},
    {"title": "Model Training", "content": "Training model machine learning melibatkan pemilihan algoritma, hyperparameter tuning, dan evaluasi.", "category": "ml"},
    {"title": "Model Deployment", "content": "Model bisa di-deploy menggunakan FastAPI, Flask, atau platform managed seperti SageMaker.", "category": "ml"},
]

engine.adddocuments(docs)

results = engine.search("cara setup project Python", limit=3, category="setup")
for r in results:
    print(f"[{r['title']}] Score: {r['score']:.4f}")
    print(f"  {r['text']}\n")

summary = engine.summarize_results(results)
print(f"Ringkasan: {summary}")

Kesimpulan

txtai adalah framework yang sangat powerful untuk membangun aplikasi AI berbasis semantic search dan embeddings. Keunggulan utamanya adalah:

• Simplicity: API yang bersih dan mudah digunakan, cocok untuk prototyping cepat maupun production
• Versatility: Menggabungkan embeddings database, NLP pipelines, dan workflows dalam satu platform
• SQL Support: Kemampuan menjalankan SQL query pada vector database membuat filtering dan analisis data menjadi sangat fleksibel
• Hybrid Search: Kombinasi semantic dan keyword search memberikan hasil pencarian yang lebih akurat
• API Server: Built-in server memudahkan deployment tanpa perlu menulis boilerplate code

Untuk memulai, cukup install txtai, buat embeddings index dari data Anda, dan mulai bereksperimen dengan semantic search. Dari situ, Anda bisa menambahkan pipeline NLP, workflow orchestration, dan fitur lanjutan lainnya sesuai kebutuhan.

Dokumentasi resmi txtai tersedia di repositori GitHub NeuML/txtai dan sangat lengkap dengan contoh-contoh penggunaan yang bisa langsung dipraktekkan.