Integrasi Large Language Models (LLM) Lokal dengan Arsitektur Microservices Node.js

1. Konteks Industri & Analisis Akar Masalah

Dalam lanskap pengembangan perangkat lunak enterprise modern, adopsi Large Language Models (LLM) telah bergeser dari sekadar eksperimen inovatif menjadi kebutuhan arsitektural inti. Namun, arsitektur yang mengandalkan API pihak ketiga (seperti OpenAI, Anthropic, atau Cohere) menghadirkan tantangan besar dalam hal kepatuhan regulasi data (data compliance seperti GDPR dan HIPAA), latensi jaringan lintas benua, serta biaya operasional (OPEX) yang membengkak secara eksponensial seiring bertambahnya volume permintaan enterprise.

Bottleneck utama di dunia nyata terletak pada ketidakmampuan arsitektur tradisional menangani beban tinggi asinkron saat berinteraksi dengan model inferensi yang membutuhkan sumber daya komputasi masif (GPU VRAM, RAM sistem, dan siklus CPU). Ketergantungan pada API publik juga membuka celah keamanan berupa potensi kebocoran data sensitif perusahaan ke infrastruktur eksternal.

Sebelum penerapan LLM lokal yang terintegrasi dengan ekosistem Node.js dan PostgreSQL (pgvector), organisasi sering kali mengalami:

• Latensi tinggi (>1200ms) akibat round-trip time ke penyedia API eksternal.
• Kegagalan sistem total (cascading failure) ketika layanan pihak ketiga mengalami pemadaman (outage).
• Risiko kepatuhan hukum karena data finansial dan identitas pelanggan dikirim ke server pihak ketiga.

Sesudah penerapan arsitektur lokal:

• Latensi inferensi terkontrol dan dapat diprediksi (on-premise/private cloud).
• Isolasi data penuh di dalam perimeter jaringan privat enterprise.
• Efisiensi biaya jangka panjang dengan memaksimalkan utilisasi hardware internal (NVIDIA GPU clusters atau CPU high-core).

2. Konsep Inti & Deep Dive Arsitektur

Integrasi LLM lokal ke dalam backend Node.js memerlukan pendekatan rekayasa sistem yang memisahkan lapisan aplikasi (API Gateway & Microservices), lapisan antrian (Queue & Worker), lapisan penyimpanan Vektor (PostgreSQL dengan ekstensi pgvector), serta mesin inferensi lokal (Ollama yang berjalan di atas container Docker).

+-----------------------------------------------------------------------------------+
|                           Node.js Enterprise API Gateway                          |
+-----------------------------------------------------------------------------------+
          |                                                      ^
          v (HTTP / JSON)                                        | (Real-time WS)
+-----------------------------------+             +---------------------------------+
|  BullMQ / Redis Asynchronous      |             |  PostgreSQL + pgvector          |
|  Queue & Worker Processor         |             |  (Semantic Search & Embeddings) |
+-----------------------------------+             +---------------------------------+
          |                                                      ^
          v (RPC / Internal HTTP)                                | (SQL Embeddings)
+-----------------------------------------------------------------------------------+
|                     Ollama Local LLM Inference Engine (Docker)                    |
+-----------------------------------------------------------------------------------+

Alur eksekusi data (data flow) bekerja sebagai berikut:

1. Klien mengirimkan payload teks melalui HTTP POST ke Node.js API Gateway.
2. Gateway memasukkan tugas pemrosesan ke dalam Redis-backed queue (BullMQ) untuk menjamin keandalan jika terjadi lonjakan lalu lintas.
3. Worker Node.js mengambil tugas dari antrian, melakukan embedding teks melalui pemanggilan model embedding lokal, lalu melakukan query kemiripan kosinus (cosine similarity) ke PostgreSQL dengan pgvector.
4. Konteks relevan digabungkan dengan prompt asli dan dikirimkan ke server Ollama lokal melalui HTTP/JSON-RPC.
5. Ollama mengeksekusi inferensi menggunakan model yang dimuat di VRAM/RAM, lalu mengembalikan respons kembali ke worker Node.js untuk diteruskan ke sistem klien.

3. Perbandingan Komparatif / Analisis Pendekatan

4. Prasyarat Sistem & Persiapan Lingkungan

Sebelum melakukan deploy, pastikan infrastruktur memenuhi standar spesifikasi enterprise minimum:

• OS: Ubuntu Server 22.04 LTS / RHEL 9
• CPU: Minimal 8 Cores, 32GB RAM
• GPU: NVIDIA GPU (opsional tapi sangat disarankan) dengan VRAM minimum 16GB (misal: NVIDIA RTX 4090 / A10G) dan driver CUDA terbaru.
• Runtime: Node.js v20.x LTS, Docker Engine v24+, Docker Compose v2+
• Database: PostgreSQL 15+ dengan ekstensi pgvector terpasang.

Verifikasi instalasi Docker dan dukungan GPU NVIDIA di host:

nvidia-smi
docker run --gpus all nvidia/cuda:12.2.0-base-ubuntu22.04 nvidia-smi

5. Panduan Implementasi Langkah demi Langkah

A. Konfigurasi Infrastruktur menggunakan Docker Compose

Buat file docker-compose.yml untuk menjalankan Ollama, PostgreSQL dengan pgvector, dan Redis.

version: '3.8'

services:
  ollama:
    image: ollama/ollama:latest
    container_name: enterprise_ollama
    ports:
      - "11434:11434"
    volumes:
      - ollama_data:/root/.ollama
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]
    restart: unless-stopped

  postgres:
    image: pgvector/pgvector:pg15
    container_name: enterprise_postgres
    environment:
      POSTGRES_DB: enterprise_ai
      POSTGRES_USER: ai_admin
      POSTGRES_PASSWORD: secure_database_password_2024
    ports:
      - "5432:5432"
    volumes:
      - pg_data:/var/lib/postgresql/data
    restart: unless-stopped

  redis:
    image: redis:7-alpine
    container_name: enterprise_redis
    ports:
      - "6379:6379"
    command: redis-server --save 60 1 --loglevel warning
    volumes:
      - redis_data:/data
    restart: unless-stopped

volumes:
  ollama_data:
  pg_data:
  redis_data:

Jalankan stack infrastruktur:

docker-compose up -d

Tarik model LLM dan model Embedding yang dibutuhkan ke dalam container Ollama:

docker exec -it enterprise_ollama ollama pull llama3
docker exec -it enterprise_ollama ollama pull nomic-embed-text

B. Inisialisasi Database Schema untuk Vector Search

Hubungkan ke PostgreSQL dan buat tabel yang mendukung penyimpanan embeddings berdimensi tinggi.

CREATE EXTENSION IF NOT EXISTS vector;

CREATE TABLE IF NOT EXISTS document_embeddings (
    id SERIAL PRIMARY KEY,
    content TEXT NOT NULL,
    embedding VECTOR(768),
    created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
);

-- Buat indeks HNSW untuk pencarian semantik berkecepatan tinggi
CREATE INDEX ON document_embeddings USING hnsw (embedding vector_cosine_ops);

C. Implementasi Backend Node.js

Inisialisasi proyek Node.js baru dan instal dependensi wajib:

mkdir node-llm-enterprise && cd node-llm-enterprise
npm init -y
npm install express pg bullmq ioredis axios dotenv

Buat file konfigurasi koneksi database db.js:

const { Pool } = require('pg');
require('dotenv').config();

const pool = new Pool({
    connectionString: process.env.DATABASE_URL || 'postgresql://ai_admin:secure_database_password_2024@localhost:5432/enterprise_ai',
});

module.exports = {
    query: (text, params) => pool.query(text, params),
    pool,
};

Buat file worker asinkron worker.js menggunakan BullMQ:

const { Worker } = require('bullmq');
const axios = require('axios');
const db = require('./db');

const OLLAMA_HOST = process.env.OLLAMA_HOST || 'http://localhost:11434';

const aiWorker = new Worker('ai-processing-queue', async (job) => {
    const { prompt, taskId } = job.data;
    console.log(`[Worker] Memproses Task ID: ${taskId} dengan prompt: "${prompt}"`);

    try {
        // 1. Generate embedding untuk query input
        const embeddingResponse = await axios.post(`${OLLAMA_HOST}/api/embeddings`, {
            model: 'nomic-embed-text',
            prompt: prompt
        });
        const queryEmbedding = embeddingResponse.data.embedding;

        // 2. Lakukan Semantic Search ke PostgreSQL
        const vectorString = `[${queryEmbedding.join(',')}]`;
        const similarityQuery = `
            SELECT content, 1 - (embedding <=> $1::vector) AS similarity
            FROM document_embeddings
            ORDER BY embedding <=> $1::vector
            LIMIT 3;
        `;
        const searchResult = await db.query(similarityQuery, [vectorString]);
        
        const context = searchResult.rows.map(row => row.content).join('\n\n');

        // 3. Susun Augmented Prompt (RAG)
        const finalPrompt = `Gunakan konteks berikut untuk menjawab pertanyaan:\n\nKonteks:\n${context}\n\nPertanyaan: ${prompt}`;

        // 4. Kirim ke LLM Lokal (Llama 3)
        const llmResponse = await axios.post(`${OLLAMA_HOST}/api/generate`, {
            model: 'llama3',
            prompt: finalPrompt,
            stream: false
        });

        console.log(`[Worker] Selesai memproses Task ID: ${taskId}`);
        return { success: true, response: llmResponse.data.response };

    } catch (error){
        console.error(`[Worker Error] Gagal memproses Task ID ${taskId}:`, error.message);
        throw error;
    }
}, {
    connection: {
        host: 'localhost',
        port: 6379
    }
});

aiWorker.on('completed', (job) => {
    console.log(`Job ${job.id} berhasil diselesaikan.`);
});

aiWorker.on('failed', (job, err) => {
    console.error(`Job ${job.id} gagal dengan error: ${err.message}`);
});

Buat file API Gateway utama index.js:

const express = require('express');
const { Queue } = require('bullmq');
const { v4: uuidv4 } = require('uuid');
require('dotenv').config();

const app = express();
app.use(express.json());

const aiQueue = new Queue('ai-processing-queue', {
    connection: {
        host: 'localhost',
        port: 6379
    }
});

app.post('/api/v1/generate', async (req, res) => {
    const { prompt } = req.body;
    if (!prompt) {
        return res.status(400).json({ error: 'Prompt wajib diisi.' });
    }

    const taskId = uuidv4();

    try {
        await aiQueue.add('process-ai', { prompt, taskId });
        return res.status(202).json({
            message: 'Permintaan berhasil dimasukkan ke dalam antrian.',
            taskId,
            status: 'queued'
        });
    } catch (error) {
        console.error('Gagal menambahkan ke antrian:', error);
        return res.status(500).json({ error: 'Internal Server Error' });
    }
});

const PORT = process.env.PORT || 3000;
app.sterm = app.listen(PORT, () => {
    console.log(`[Gateway] Enterprise AI Gateway berjalan di port ${PORT}`);
});

6. Bedah Kode & Penjelasan Detail Baris Kunci

• Ekstensi HNSW pada PostgreSQL (USING hnsw (embedding vector_cosine_ops)): Indeks Hierarchical Navigable Small World (HNSW) sangat krusial untuk performa enterprise. Tanpa indeks ini, pencarian kemiripan vektor pada jutaan baris data akan melakukan Sequential Scan yang memakan waktu lama dan melumpuhkan CPU database.
• BullMQ Queue Management: Penggunaan BullMQ dengan Redis memastikan bahwa lonjakan beban (traffic spike) ribuan request per detik tidak langsung menghantam model Ollama secara bersamaan, yang dapat menyebabkan kehabisan VRAM (Out of VRAM error) atau crash server.
• RAG (Retrieval-Augmented Generation) Payload Construction: Menggabungkan hasil pencarian semantik dari database (searchResult.rows) sebelum dilempar ke llama3 meminimalisir halusinasi AI dan memastikan model merespons berdasarkan dokumen internal perusahaan yang valid.

7. Skenario Produksi & Studi Kasus Dunia Nyata

Dalam lingkungan produksi skala enterprise (misalnya sistem Customer Support Knowledge Base otomatis yang melayani 50.000 karyawan internal), lonjakan trafik harian dapat mencapai 200 permintaan per detik.

Strategi mitigasi beban tinggi:

1. Horizontal Worker Scaling: Pisahkan instance Node.js worker ke dalam beberapa container Docker terpisah yang terhubung ke satu message broker (Redis) yang sama.
2. Connection Pooling: Atur ukuran pool PostgreSQL secara ketat (max: 20, idleTimeoutMillis: 30000) agar koneksi database tidak habis terkuras oleh worker yang berjalan bersamaan.
3. Reverse Proxy & Load Balancing: Tempatkan Nginx di depan aplikasi Node.js untuk menangani terminasi SSL, proteksi rate-limiting, dan buffering request masuk.

Konfigurasi Nginx upstream untuk load balancing gateway Node.js:

upstream node_ai_cluster {
    server 127.0.0.1:3000 max_fails=3 fail_timeout=10s;
    server 127.0.0.1:3001 max_fails=3 fail_timeout=10s;
    keepalive 32;
}

server {
    listen 80;
    server_name ai.internal.enterprise.com;

    location / {
        proxy_pass http://node_ai_cluster;
        proxy_http_version 1.1;
        proxy_set_header Connection "";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_connect_timeout 60s;
        proxy_send_timeout 60s;
        proxy_read_timeout 60s;
    }
}

8. Common Pitfalls, Anti-Patterns & Solusi

[!WARNING] Anti-Pattern Berbahaya: Mengirimkan permintaan inferensi LLM secara sinkron langsung di dalam Request Lifecycle HTTP Express.js tanpa sistem antrian. Dampak: Koneksi HTTP akan mengalami gateway timeout (biasanya 30-60 detik) karena inferensi LLM lokal membutuhkan waktu komputasi yang lebih lama dibandingkan query database biasa. Solusi: Selalu gunakan pola Asynchronous Job Processing (seperti BullMQ) dan kembalikan response 202 Accepted beserta ID tugas, lalu biarkan klien melakukan polling atau menerima pembaruan via WebSocket.

[!IMPORTANT] Kesalahan Umum Manajemen Memori GPU: Gagal membatasi jumlah concurrent requests yang dikirimkan ke Ollama. Solusi: Atur batasan konkurensi di level Worker BullMQ menggunakan parameter concurrency: 2 (disesuaikan dengan kapasitas VRAM GPU Anda) agar Ollama tidak menerima prompt secara masif secara bersamaan.

9. Benchmark, Metrik Kinerja & Tuning Performa

Untuk mengukur performa sistem, gunakan tool pengujian beban seperti k6 atau autocannon. Buat file skrip load-test.js untuk menguji endpoint API gateway:

import http from 'k6/http';
import { check, sleep } from 'k6';

export const options = {
    stages: [
        { duration: '30s', target: 20 },
        { duration: '1m', target: 50 },
        { duration: '30s', target: 0 },
    ],
};

export default function () {
    const url = 'http://localhost/api/v1/generate';
    const payload = JSON.stringify({
        prompt: 'Bagaimana prosedur klaim asuransi kesehatan karyawan?'
    });

    const params = {
        headers: { 'Content-Type': 'application/json' },
    };

    const res = http.post(url, payload, params);
    check(res, {
        'status adalah 202': (r) => r.status === 202,
        'waktu respons < 200ms': (r) => r.timings.duration < 200,
    });
    sleep(1);
}

Jalankan benchmark:

k6 run load-test.js

Hasil Analisis Metrik Tuning:

• Jika metrik menunjukkan tingginya Queue Wait Time, tambahkan worker Node.js baru atau optimalkan parameter model Ollama (OLLAMA_NUM_PARALLEL).
• Pastikan indeks HNSW di PostgreSQL tidak mengalami bloat; jalankan REINDEX INDEX secara berkala melalui cron job terjadwal.

10. Checklist Penerapan Produksi & Kesimpulan

Sebelum meluncurkan arsitektur integrasi LLM lokal ke lingkungan produksi final, verifikasi seluruh item pemeriksaan berikut:

• Enkripsi data aktif (SSL/TLS Let's Encrypt terpasang di Nginx Reverse Proxy).
• Konfigurasi Database Backup otomatis untuk tabel document_embeddings dan data PostgreSQL.
• Batasan sumber daya Docker container terdefinisi dengan jelas (deploy.resources.reservations).
• Sistem monitoring metrik infrastruktur (Prometheus & Grafana) aktif mengawasi penggunaan VRAM, CPU, dan RAM.
• Log rotasi diatur dengan benar menggunakan logrotate untuk mencegah disk penuh akibat log Ollama/Node.js yang masif.

Dengan menerapkan arsitektur terpadu ini, organisasi Anda tidak hanya mendapatkan keunggulan performa dan privasi data yang mutlak, tetapi juga fondasi sistem backend enterprise yang tangguh, scalable, dan siap menghadapi evolusi kecerdasan buatan di masa depan.