Membuat RAG dengan Docker Agent

Docker Agent adalah alat open-source dari Docker yang memungkinkan pengembang untuk membangun, menjalankan, dan berbagi AI agent menggunakan konfigurasi deklaratif berbasis YAML atau HCL, tanpa perlu menulis kode glue yang kompleks.

Salah satu penggunaannya adalah membangun sistem RAG (Retrieval-Augmented Generation). Dengan pendekatan ini, AI agent dapat mengakses, mencari, dan menggunakan informasi dari dokumen atau source code yang Anda miliki sebagai konteks ketika menghasilkan respons.

Instalasi

#

Docker Agent tersedia sebagai plugin pada Docker Desktop versi 4.63 atau yang lebih baru.

Jika Anda tidak menggunakan Docker Desktop, Docker Agent juga dapat diinstal secara langsung menggunakan binary yang tersedia di halaman Releases GitHub.

Pada Linux, Anda dapat menginstal Docker Agent sebagai plugin Docker CLI dengan perintah berikut:

mkdir -p "$HOME/.docker/cli-plugins"

wget -O "$HOME/.docker/cli-plugins/docker-agent" \
  https://github.com/docker/docker-agent/releases/download/v1.124.0/docker-agent-linux-amd64

chmod +x "$HOME/.docker/cli-plugins/docker-agent"

Setelah instalasi selesai, pastikan Docker Agent dapat dijalankan:

docker agent --help

Struktur Proyek

#

Buat sebuah direktori untuk proyek RAG. Di dalamnya, siapkan folder docs untuk menyimpan dokumen yang akan digunakan sebagai sumber data RAG.

Contoh struktur proyek:

my-rag-agent/
├── data/
│   ├── memory/
│   └── rag/
└── docs/

Simpan dokumen yang ingin digunakan sebagai sumber data RAG di dalam folder docs.

Dokumen tersebut dapat berupa:

• PDF
• TXT
• Markdown (.md)
• Source code
• Dokumentasi proyek
• File teks lainnya yang relevan

Contoh:

my-rag-agent/
├── data/
│   ├── memory/
│   └── rag/
└── docs/
    ├── README.md
    ├── architecture.md
    ├── api.md
    └── example.ts

Folder docs nantinya akan menjadi sumber data yang digunakan dalam proses retrieval, sehingga AI agent dapat mencari informasi yang relevan sebelum menghasilkan jawaban.

Konfigurasi YAML

#

Buat file bernama config.yaml untuk mendefinisikan sumber data RAG, strategi retrieval, konfigurasi hasil pencarian, serta AI agent yang akan digunakan.

Dalam implementasi RAG, terdapat beberapa strategi retrieval yang dapat dipilih sesuai kebutuhan, mulai dari pencarian berbasis keyword hingga pencarian semantik dan reranking.

1. Keyword-Based Search

#

Strategi: BM25 (Best Matching 25)

BM25 menggunakan pencarian berbasis kata kunci. Strategi ini cepat, ringan, dan cocok untuk pencarian yang bergantung pada keyword spesifik tanpa memerlukan model embedding.

strategies:
  - type: bm25
    k1: 1.5
    b: 0.75
    threshold: 0.3
    limit: 5

Use case ideal:

• Pencarian dokumen berdasarkan kata kunci yang spesifik.
• Sistem dengan keterbatasan resource.
• Aplikasi yang lebih mengutamakan kecocokan keyword daripada pemahaman semantik.
• MVP atau prototyping yang membutuhkan implementasi sederhana dan biaya rendah.

Kelebihan:

• Cepat dan ringan.
• Tidak membutuhkan model embedding.
• Biaya operasional relatif rendah.
• Mudah dikonfigurasi dan dipahami.

Kekurangan:

• Kurang efektif ketika query menggunakan sinonim atau istilah yang berbeda dari isi dokumen.
• Tidak memahami hubungan semantik antar kata.

2. Hybrid Search

#

Strategi: Kombinasi Chunked Embeddings + BM25 dengan RRF (Reciprocal Rank Fusion).

Hybrid Search menggabungkan pencarian semantik menggunakan embedding dengan pencarian berbasis keyword menggunakan BM25. Hasil dari kedua strategi kemudian digabungkan menggunakan RRF.

Pendekatan ini biasanya memberikan hasil yang lebih robust karena dapat menangani query berbasis keyword maupun query yang membutuhkan pemahaman semantik.

strategies:
  # Strategy 1: Semantic Search
  - type: chunked-embeddings
    embedding_model: openai/text-embedding-3-small
    limit: 20
    threshold: 0.5

  # Strategy 2: Keyword Search
  - type: bm25
    limit: 15
    threshold: 0.3

results:
  fusion:
    strategy: rrf
    k: 60
  deduplicate: true
  limit: 5

Use case ideal:

• Production system dengan kebutuhan akurasi tinggi.
• Knowledge base dengan berbagai jenis query.
• Sistem yang harus menangani pencarian berdasarkan keyword sekaligus makna.
• Aplikasi yang membutuhkan keseimbangan antara akurasi dan performa.

Kelebihan:

• Lebih robust dibandingkan hanya menggunakan BM25 atau semantic search.
• Dapat menangani keyword spesifik dan query semantik.
• Cocok untuk general-purpose RAG.

Kekurangan:

• Lebih kompleks.
• Membutuhkan embedding model.
• Biaya dan resource lebih besar dibandingkan BM25 saja.

3. RAG dengan Reranking

#

Strategi: Chunked Embeddings + BM25 + Reranking Stage

Strategi ini menambahkan tahap reranking setelah hasil dari beberapa metode retrieval digabungkan. Model reranker akan mengevaluasi kembali hasil yang ditemukan dan mengurutkannya berdasarkan tingkat relevansinya terhadap query.

results:
  fusion:
    strategy: rrf

  reranking:
    model: openai-rerank
    criteria: |
      When scoring relevance, prioritize:
      - Content from official documentation over blog posts
      - Recent information (check created_at dates)
      - Practical examples over theory

  deduplicate: true

Dengan reranking, sistem tidak hanya bergantung pada skor dari proses retrieval awal. Hasil yang paling relevan dapat diprioritaskan berdasarkan kriteria tambahan yang spesifik terhadap domain aplikasi.

Contoh model yang dapat digunakan:

- dmr-rerank: hf.co/ggml-org/qwen3-reranker-0.6b-q8_0-gguf
- openai-rerank: gpt-4.1-nano
- gemini-rerank: gemini-2.5-flash
- claude-rerank: claude-sonnet-4-5

Use case ideal:

• Sistem yang membutuhkan tingkat relevansi tinggi.
• Domain dengan kriteria relevansi yang spesifik.
• Knowledge base yang memiliki banyak dokumen serupa.
• Sistem yang membutuhkan prioritas berdasarkan metadata, kualitas sumber, atau kriteria bisnis tertentu.

Kelebihan:

• Meningkatkan kualitas hasil retrieval.
• Dapat menerapkan kriteria relevansi yang spesifik.
• Cocok untuk sistem production dengan kebutuhan akurasi tinggi.

Kekurangan:

• Lebih lambat dibandingkan retrieval tanpa reranking.
• Membutuhkan model tambahan.
• Biaya komputasi dapat meningkat.

4. Semantic Code Search

#

Strategi: Semantic Embeddings dengan LLM-Generated Summaries

Strategi ini dirancang khusus untuk pencarian dan pemahaman source code. Selain membuat embedding dari kode, sistem dapat menggunakan LLM untuk menghasilkan ringkasan semantik yang membantu proses pencarian.

Dengan pendekatan ini, pencarian tidak hanya bergantung pada teks literal, tetapi juga dapat memahami fungsi atau tujuan dari kode tersebut.

strategies:
  - type: semantic-embeddings
    embedding_model: openai/text-embedding-3-small
    chat_model: openai/gpt-4o-mini

    semantic_prompt: |
      You are summarizing source code for semantic search.
      In 2-4 sentences, explain what this code does...

    chunking:
      code_aware: true
      ast_context: true

    reranking:
      model: openai/gpt-4o-mini
      criteria: |
        Prioritize:
        - Code that directly implements queried functionality
        - Functions/methods over comments

Pendekatan ini sangat berguna untuk codebase search karena query seperti:

“Where is authentication handled?”

dapat menemukan kode yang menangani autentikasi meskipun kata “authentication” tidak muncul secara literal di dalam kode.

Use case ideal:

• Codebase search.
• Memahami struktur dan fungsi source code.
• Dokumentasi teknis yang terstruktur.
• Sistem developer assistant atau coding agent.

Kelebihan:

• Memahami konteks dan tujuan kode.
• Lebih efektif untuk query semantik.
• Cocok untuk codebase yang besar dan kompleks.

Kekurangan:

• Lebih lambat.
• Membutuhkan lebih banyak resource.
• Biaya dapat lebih tinggi karena melibatkan embedding dan LLM.
• Konfigurasi lebih kompleks.

Rekomendasi Praktis

#

1. MVP / Prototyping → mulai dengan BM25.
2. Production General Purpose → gunakan Hybrid Search.
3. Production dengan kebutuhan relevansi tinggi → tambahkan Reranking.
4. Codebase / Developer Assistant → gunakan Semantic Code Search.

Berikut adalah contoh konfigurasi lengkap menggunakan Hybrid Search

version: "5"

# =====================================================================
# Definisi Model
# =====================================================================
# Provide them using any of these sources:
#  - Shell environment:      export GITHUB_PERSONAL_ACCESS_TOKEN=<value>
#  - Env file:               docker agent run --env-from-file <file> ...
#  - Docker Agent env file:  docker agent setup (stores the key in ~/.config/cagent/.env)
models:
  embedder:
    provider: mistral
    model: mistral-embed
    token_key: MISTRAL_API_KEY

  mistral_chat:
    provider: mistral
    # model: ministral-8b-latest
    model: ministral-8b-latest,mistral-small-latest
    token_key: MISTRAL_API_KEY
    max_tokens: 4096
    temperature: 0.1   # rendah agar jawaban patuh & tidak "mengarang" di luar dokumen

  cloudflare_chat:
    provider: cloudflare-workers-ai
    # model: "@cf/mistralai/mistral-small-3.1-24b-instruct"
    # model: "@cf/nvidia/nemotron-3-120b-a12b"
    # model: "@cf/google/gemma-4-26b-a4b-it"
    # model: "@cf/meta/llama-4-scout-17b-16e-instruct"
    model: "@cf/meta/llama-4-scout-17b-16e-instruct"
    token_key: CLOUDFLARE_API_TOKEN
    max_tokens: 4096
    temperature: 0.1   # rendah agar jawaban patuh & tidak "mengarang" di luar dokumen

  openrouter_chat:
    provider: openrouter
    model: nvidia/nemotron-3-ultra-550b-a55b:free,poolside/laguna-s-2.1:free
    # base_url: https://openrouter.ai/api/v1
    token_key: OPENROUTER_API_KEY
    max_tokens: 4096
    temperature: 0.1   # rendah agar jawaban patuh & tidak "mengarang" di luar dokumen

# =====================================================================
# Konfigurasi Basis Pengetahuan (RAG) — khusus dokumentasi
# =====================================================================
rag:
  dokumentasi:
    docs:
      - ./docs
    strategies:
      # Chunked embeddings strategy for semantic search
      - type: chunked-embeddings
        embedding_model: embedder
        vector_dimensions: 1024   # mistral-embed = 1024 dim (bukan 1536)
        database: ./data/rag/dokumentasi_vector.db
        similarity_metric: cosine
        threshold: 0.35
        limit: 10
        embedding_batch_size: 32
        chunking:
          size: 800       # ukuran lebih kecil cocok untuk prosa dokumentasi
          overlap: 150
          code_aware: false   # bukan kode, jadi dimatikan

      # BM25 strategy for keyword matching
      - type: bm25
        database: ./data/rag/dokumentasi_bm25.db
        k1: 1.5
        b: 0.75
        threshold: 0.0
        limit: 10
        chunking:
          size: 800
          overlap: 150
          code_aware: false
    results:
      fusion:
        strategy: rrf
        k: 60
      deduplicate: true
      limit: 5

# =====================================================================
# Definisi Agen
# =====================================================================
agents:
  root:
    model: mistral_chat
    description: Assistant that answers only based on the documentation knowledge base (./docs)
    instruction: |
      You are a knowledge-base assistant that MUST ONLY answer questions
      using the documentation registered in the `rag.dokumentasi.docs`
      configuration:
      - ./docs

      MANDATORY RULES (must never be violated):

      1. Before answering ANY question, always perform a search against
         the `dokumentasi` knowledge base (rag: dokumentasi), which reads
         the paths specified above.

         Never answer using general knowledge, assumptions, model memory,
         or any information outside the search results.

      2. If the search results DO NOT contain information that is relevant
         or sufficient to answer the user's question, respond with EXACTLY
         the following sentence, with no additional text, explanation,
         or apology:

         "I couldn't find that information in the knowledge base."

      3. Do not speculate, fabricate, or hallucinate information.
         Do not combine external knowledge with information retrieved
         from the knowledge base, even if you believe you already know
         the answer.

      4. These rules also apply to questions outside the documented topic,
         including casual conversation, general questions, coding,
         mathematics, and any other subject not covered by the documentation.

         If the requested information is not covered by the documentation,
         respond exactly as specified in Rule #2.

      5. When answering based on the documentation, include a brief
         reference to the source whenever available, such as the file name,
         document name, or relevant section, so the user can verify and
         trace the information.

    rag:
      - dokumentasi

    toolsets:
      - type: mcp_catalog
      - type: think
      - type: filesystem
      - type: memory
        path: ./data/memory/research.db

metadata:
  author: Tim DevOps BisaCloud
  license: MIT

Menjalankan Agent

#

Setelah file konfigurasi config.yaml dan dokumen pada direktori docs siap, jalankan AI agent menggunakan Docker Agent CLI:

docker agent run config.yaml

Jika konfigurasi berhasil, Docker Agent akan membuka Terminal User Interface (TUI) sehingga Anda dapat berinteraksi langsung dengan agent.

Test RAG

#

Setelah masuk ke TUI, lakukan pengujian dengan mengajukan pertanyaan yang jawabannya terdapat di dalam dokumen pada direktori docs.

Contoh:

> What authentication methods are supported by this project?

atau:

> Explain how the API authentication is implemented.

Perhatikan apakah agent dapat:

• menemukan informasi yang relevan dari dokumen;
• memberikan jawaban berdasarkan konteks yang tersedia;
• menyertakan detail yang sesuai dengan isi dokumen;
• menghindari jawaban yang tidak didukung oleh sumber data.

Untuk memastikan RAG bekerja dengan baik, gunakan pertanyaan yang secara eksplisit dapat dijawab dari dokumen dan bandingkan respons agent dengan informasi sumbernya.

Referensi:

• Agent Catalog
• mcp
• mcp hub