MCP: Regenerate Vector Database untuk update content documents

From OnnoWiki
Jump to navigation Jump to search
  1. Teknik memperbarui vector database AnythingLLM
    1. Prinsip utama
    • Tidak perlu me-reset seluruh vector database setiap kali ada file `.md` baru.**

Gunakan dua pola:

| Perubahan folder | Tindakan | | --------------------------- | -------------------------------------------------------- | | Ada file `.md` baru | Upload dan embed file baru saja | | Isi file `.md` lama berubah | Hapus embedding versi lama, lalu upload ulang | | File `.md` dihapus | Hapus dari workspace dan hapus permanen dari AnythingLLM | | Ganti embedding model | Rebuild seluruh vector database | | Ganti vector database | Rebuild seluruh vector database | | Ubah chunking secara besar | Sebaiknya rebuild seluruh database |

AnythingLLM menetapkan embedding model dan vector database secara system-wide. Ketika embedder atau vector database diganti, dokumen lama perlu dihapus dan di-embed ulang; AnythingLLM tidak otomatis memindahkan vector lama. ([AnythingLLM][1])

---

  1. 1. Folder `documents` bukan vector database

Misalnya perpustakaan berada di:

```text /opt/ai-stack/documents ```

Menambahkan file:

```text /opt/ai-stack/documents/AI/buku-baru.md ```

    • tidak otomatis membuat embedding baru di AnythingLLM.**

Folder tersebut sebaiknya dianggap sebagai:

```text Source Library / Master Documents ```

Sedangkan database AnythingLLM berada pada storage internal AnythingLLM, misalnya:

```text /opt/ai-stack/anythingllm/storage ```

Fitur Automatic Document Sync AnythingLLM belum dapat mengawasi satu direktori lokal secara keseluruhan. Pada instalasi Docker, file lokal yang hanya disalin ke folder host juga tidak otomatis disinkronkan sebagai dokumen baru. ([docs.anythingllm.com][2])

Arsitektur yang direkomendasikan:

```text /opt/ai-stack/ ├── documents/ # Dokumen master │ ├── AI/ │ ├── CYBER-SECURITY/ │ └── ONNO-PDF/ │ ├── anythingllm/ │ └── storage/ # Database internal AnythingLLM │ └── batch/ 

   ├── sync-anythingllm.sh
   └── .anythingllm-sync/

```

---

  1. 2. Metode manual untuk file baru

Untuk jumlah file sedikit:

1. Masuk ke AnythingLLM. 2. Buka workspace tujuan. 3. Buka pengelolaan dokumen workspace. 4. Upload file `.md` baru. 5. Pindahkan file ke workspace. 6. Klik **Save and Embed** atau tombol embedding yang tersedia. 7. Tunggu sampai proses embedding selesai. 8. Uji dengan pertanyaan yang hanya dapat dijawab oleh file baru.

Metode ini hanya menambah vector untuk file baru. Dokumen lama tidak perlu diproses ulang.

---

  1. 3. Metode API untuk banyak file `.md`

AnythingLLM menyediakan Developer API untuk meng-upload, mengelola, meng-embed, dan memperbarui dokumen workspace. Dokumentasi API instance tersedia pada `/api/docs`. API key harus dirahasiakan karena siapa pun yang memilikinya dapat menggunakan API instance. ([AnythingLLM][3])

Misalnya alamat AnythingLLM:

```text http://127.0.0.1:3001 ```

Dokumentasi API:

```text http://127.0.0.1:3001/api/docs ```

    1. Membuat API key

Di AnythingLLM:

```text Settings → Developer API → API Keys → New API Key ```

Simpan key, misalnya:

```bash export ANYTHINGLLM_API_KEY='MASUKKAN_API_KEY' ```

Jangan memasukkan API key ke Git repository.

---

    1. Tentukan konfigurasi

```bash export ANYTHINGLLM_URL="http://127.0.0.1:3001" export WORKSPACE_SLUG="perpustakaan" export DOCUMENT_ROOT="/opt/ai-stack/documents" ```

`WORKSPACE_SLUG` bukan selalu nama tampilan workspace.

Contoh:

```text Nama workspace : Perpustakaan Onno Slug : perpustakaan-onno ```

---

    1. Uji API key

```bash curl --fail --silent --show-error \ 

 -H "Authorization: Bearer ${ANYTHINGLLM_API_KEY}" \
 "${ANYTHINGLLM_URL}/api/v1/auth"

```

Hasil yang benar:

```json { 

 "authenticated": true

} ```

---

    1. Upload satu file dan langsung embed

```bash curl --fail --silent --show-error \ 

 -X POST \
 -H "Authorization: Bearer ${ANYTHINGLLM_API_KEY}" \
 -F "file=@/opt/ai-stack/documents/AI/buku-baru.md" \
 -F "addToWorkspaces=${WORKSPACE_SLUG}" \
 "${ANYTHINGLLM_URL}/api/v1/document/upload"

```

Endpoint upload resmi menerima file multipart dan parameter `addToWorkspaces`, yaitu daftar slug workspace tempat dokumen akan langsung di-embed setelah upload. Responsnya mengembalikan lokasi dokumen internal AnythingLLM. ([GitHub][4])

Contoh respons:

```json { 

 "success": true,
 "error": null,
 "documents": [
   {
     "location": "custom-documents/buku-baru.md-uuid.json",
     "title": "buku-baru.md"
   }
 ]

} ```

Nilai `location` perlu disimpan karena digunakan saat menghapus atau mengganti dokumen.

---

  1. 4. Script untuk folder yang hanya bertambah

Metode ini cocok jika:

  • File yang sudah masuk tidak diedit.
  • File tidak diganti dengan nama yang sama.
  • Folder hanya mendapatkan file baru.

Instal `jq`:

```bash sudo apt update sudo apt install -y jq ```

Buat folder script:

```bash sudo mkdir -p /opt/ai-stack/batch sudo chown -R "$USER":"$USER" /opt/ai-stack/batch ```

Buat script:

```bash nano /opt/ai-stack/batch/sync-new-md-anythingllm.sh ```

Isi:

```bash

  1. !/usr/bin/env bash

set -Eeuo pipefail

DOCUMENT_ROOT="${DOCUMENT_ROOT:-/opt/ai-stack/documents}" ANYTHINGLLM_URL="${ANYTHINGLLM_URL:-http://127.0.0.1:3001}" WORKSPACE_SLUG="${WORKSPACE_SLUG:-perpustakaan}" STATE_DIR="${STATE_DIR:-/opt/ai-stack/batch/.anythingllm-sync}" MARKER_FILE="${STATE_DIR}/last-successful-sync" LOG_FILE="${STATE_DIR}/sync.log"

"${ANYTHINGLLM_API_KEY:?ANYTHINGLLM_API_KEY belum di-set}"

mkdir -p "$STATE_DIR" touch "$LOG_FILE"

log() { 

   printf '[%s] %s\n' "$(date '+%F %T')" "$*" | tee -a "$LOG_FILE"

}

if ! -d "$DOCUMENT_ROOT" ; then 

   log "ERROR: folder tidak ditemukan: $DOCUMENT_ROOT"
   exit 1

fi

  1. Marker sangat lama untuk proses pertama.

if ! -e "$MARKER_FILE" ; then 

   touch -t 197001010000 "$MARKER_FILE"

fi

TEMP_MARKER="$(mktemp "${STATE_DIR}/sync-marker.XXXXXX")"

success_count=0 failed_count=0

while IFS= read -r -d file; do 

   log "Upload: $file"

   response="$(
       curl --fail --silent --show-error \
           -X POST \
           -H "Authorization: Bearer ${ANYTHINGLLM_API_KEY}" \
           -F "file=@${file}" \
           -F "addToWorkspaces=${WORKSPACE_SLUG}" \
           "${ANYTHINGLLM_URL}/api/v1/document/upload"
   )" || {
       log "GAGAL upload: $file"
       failed_count=$((failed_count + 1))
       continue
   }

   success="$(jq -r '.success // false' <<<"$response")"
   error="$(jq -r '.error // empty' <<<"$response")"
   location="$(jq -r '.documents[0].location // empty' <<<"$response")"

   if | -n "$error" || -z "$location" ; then
       log "GAGAL diproses: $file"
       log "Respons: $response"
       failed_count=$((failed_count + 1))
       continue
   fi

   log "BERHASIL: $file"
   log "AnythingLLM location: $location"
   success_count=$((success_count + 1))

done < <( 

   find "$DOCUMENT_ROOT" \
       -type f \
       -iname '*.md' \
       -newer "$MARKER_FILE" \
       -print0

)

if (( failed_count == 0 )); then 

   mv "$TEMP_MARKER" "$MARKER_FILE"
   log "Sinkronisasi selesai. Berhasil=$success_count Gagal=0"

else 

   rm -f "$TEMP_MARKER"
   log "Sinkronisasi belum ditandai selesai karena ada kegagalan."
   log "Berhasil=$success_count Gagal=$failed_count"
   exit 1

fi ```

Simpan lalu beri izin:

```bash chmod +x /opt/ai-stack/batch/sync-new-md-anythingllm.sh ```

Jalankan:

```bash export ANYTHINGLLM_API_KEY='MASUKKAN_API_KEY' export WORKSPACE_SLUG='perpustakaan-onno'

/opt/ai-stack/batch/sync-new-md-anythingllm.sh ```

Lihat log:

```bash tail -f /opt/ai-stack/batch/.anythingllm-sync/sync.log ```

      1. Peringatan

Script marker ini akan menganggap file yang diedit sebagai file baru. AnythingLLM dapat membuat dokumen baru dengan UUID baru sehingga embedding versi lama masih ada.

Karena itu, metode ini hanya aman untuk perpustakaan **append-only**.

---

  1. 5. Teknik yang benar ketika isi `.md` diperbarui

Misalnya:

```text /opt/ai-stack/documents/AI/pengenalan-rag.md ```

sudah pernah di-embed, kemudian isinya diedit.

Jangan langsung upload ulang tanpa menghapus versi lama karena dapat menghasilkan:

```text Embedding lama + Embedding baru ```

Akibatnya, hasil RAG dapat mengambil informasi lama dan baru sekaligus.

Gunakan urutan berikut:

```text 1. Remove embedding lama dari workspace 2. Delete dokumen lama secara permanen 3. Upload file versi terbaru 4. Embed file baru ke workspace 5. Simpan mapping UUID/location yang baru ```

---

    1. Menghapus embedding lama dari workspace

Misalnya lokasi internal dokumen lama:

```text custom-documents/pengenalan-rag.md-abc123.json ```

Jalankan:

```bash curl --fail --silent --show-error \ 

 -X POST \
 -H "Authorization: Bearer ${ANYTHINGLLM_API_KEY}" \
 -H "Content-Type: application/json" \
 -d '{
       "adds": [],
       "deletes": [
         "custom-documents/pengenalan-rag.md-abc123.json"
       ]
     }' \
 "${ANYTHINGLLM_URL}/api/v1/workspace/${WORKSPACE_SLUG}/update-embeddings"

```

Endpoint `update-embeddings` memang digunakan untuk menambah atau menghapus dokumen dari vector namespace sebuah workspace. Nilainya harus berupa path internal seperti `custom-documents/nama-file-uuid.json`, bukan nama file asli pada host.

---

    1. Menghapus dokumen lama secara permanen

```bash curl --fail --silent --show-error \ 

 -X DELETE \
 -H "Authorization: Bearer ${ANYTHINGLLM_API_KEY}" \
 -H "Content-Type: application/json" \
 -d '{
       "names": [
         "custom-documents/pengenalan-rag.md-abc123.json"
       ]
     }' \
 "${ANYTHINGLLM_URL}/api/v1/system/remove-documents"

```

Developer API menyediakan endpoint `DELETE /v1/system/remove-documents` untuk menghapus dokumen internal secara permanen.

---

    1. Upload versi baru

```bash curl --fail --silent --show-error \ 

 -X POST \
 -H "Authorization: Bearer ${ANYTHINGLLM_API_KEY}" \
 -F "file=@/opt/ai-stack/documents/AI/pengenalan-rag.md" \
 -F "addToWorkspaces=${WORKSPACE_SLUG}" \
 "${ANYTHINGLLM_URL}/api/v1/document/upload"

```

Simpan `documents[0].location` dari respons sebagai mapping baru.

---

  1. 6. Gunakan hash untuk mendeteksi perubahan

Untuk perpustakaan yang sering berubah, teknik terbaik adalah menyimpan:

```text path file SHA-256 AnythingLLM document location workspace slug last sync ```

Contoh database manifest:

```json { 

 "/opt/ai-stack/documents/AI/pengenalan-rag.md": {
   "sha256": "1d2af7...",
   "location": "custom-documents/pengenalan-rag.md-abc123.json",
   "workspace": "perpustakaan-onno",
   "last_sync": "2026-07-26T09:30:00+07:00"
 }

} ```

Saat sinkronisasi:

```text File belum ada di manifest → Upload dan embed

Hash sama → Tidak melakukan apa-apa

Hash berubah → Hapus embedding lama → Hapus dokumen lama → Upload dan embed versi baru → Update manifest

File ada di manifest tetapi hilang dari folder → Hapus embedding → Hapus dokumen internal → Hapus entry dari manifest ```

Hitung hash:

```bash sha256sum "/opt/ai-stack/documents/AI/pengenalan-rag.md" ```

Keuntungan metode hash:

  • Tidak melakukan embedding berulang tanpa alasan.
  • Tidak membuat vector duplikat.
  • Bisa menangani file yang berubah.
  • Bisa menangani file yang dihapus.
  • Bisa melakukan audit dokumen.
  • Bisa melanjutkan proses setelah kegagalan.

---

  1. 7. Kapan melakukan full regenerate

Lakukan rebuild total jika:

  • Embedding model diganti.
  • Provider embedder diganti.
  • Vector database diganti, misalnya LanceDB menjadi Qdrant.
  • Chunk size atau chunk overlap diubah secara signifikan.
  • Banyak dokumen lama sudah tidak sinkron.
  • Terjadi banyak embedding duplikat.
  • Retrieval masih menampilkan isi dokumen yang sudah dihapus.
  • Struktur koleksi diubah secara besar.

AnythingLLM menyatakan bahwa penggantian embedder atau vector database membutuhkan penghapusan dan embedding ulang dokumen. ([AnythingLLM][1])

---

  1. 8. Prosedur full regenerate yang aman
    1. Langkah 1 — Hentikan proses upload

Jangan menambah atau mengedit dokumen selama rebuild.

---

    1. Langkah 2 — Backup storage AnythingLLM

Cari mount container:

```bash docker inspect anythingllm \ 

 --format 'Template:Range .Mounts{{println .Source "->" .Destination}}Template:End'

```

Misalnya hasil:

```text /opt/ai-stack/anythingllm/storage -> /app/server/storage ```

Backup:

```bash cd /opt/ai-stack

sudo tar \ 

 -czf "anythingllm-storage-$(date +%F-%H%M%S).tar.gz" \
 anythingllm/storage

```

Periksa:

```bash ls -lh /opt/ai-stack/anythingllm-storage-*.tar.gz ```

---

    1. Langkah 3 — Reset melalui AnythingLLM

Untuk tiap workspace:

```text Workspace → Settings → Vector Database → Reset Vector Database ```

Kemudian hapus dokumen lama dari daftar dokumen apabila memang akan membangun ulang semuanya.

    • Jangan langsung menghapus folder LanceDB secara manual** sementara AnythingLLM berjalan. Database vector, database aplikasi, cache dokumen, dan relasi workspace dapat menjadi tidak konsisten.

---

    1. Langkah 4 — Pastikan konfigurasi embedder final

Contoh:

```text Embedding provider : Ollama Embedding model : nomic-embed-text Vector database : LanceDB ```

Jangan mengganti model embedding di tengah proses ingest.

Model chat dan model embedding adalah dua hal berbeda:

```text Model chat: qwen3:8b

Model embedding: nomic-embed-text atau model embedding lain ```

---

    1. Langkah 5 — Upload semua `.md`

```bash find /opt/ai-stack/documents \ 

 -type f \
 -iname '*.md' \
 -print0 |

while IFS= read -r -d file; do 

   echo "Embedding: $file"

   curl --fail --silent --show-error \
     -X POST \
     -H "Authorization: Bearer ${ANYTHINGLLM_API_KEY}" \
     -F "file=@${file}" \
     -F "addToWorkspaces=${WORKSPACE_SLUG}" \
     "${ANYTHINGLLM_URL}/api/v1/document/upload" |
     jq .

done ```

---

    1. Langkah 6 — Pantau log

```bash cd /opt/ai-stack docker compose logs -f anythingllm ```

Atau:

```bash docker logs -f anythingllm ```

Perhatikan error seperti:

```text failed to embed failed to vectorize document processing API is not online fetch failed out of memory connection refused ```

---

    1. Langkah 7 — Verifikasi RAG

Buat satu file pengujian:

```markdown --- title: Dokumen Uji Sinkronisasi document_id: TEST-RAG-20260726 version: 1 ---

Kode verifikasi perpustakaan adalah MERAH-7261. ```

Upload lalu tanyakan:

```text Apa kode verifikasi perpustakaan dari dokumen TEST-RAG-20260726? ```

Jawaban yang benar:

```text MERAH-7261 ```

Setelah berhasil, ubah file menjadi:

```markdown version: 2 ```

dan:

```text Kode verifikasi perpustakaan adalah BIRU-9928. ```

Lakukan prosedur replace, lalu tanyakan kembali. Jawaban seharusnya hanya:

```text BIRU-9928 ```

Jika masih muncul `MERAH-7261`, embedding lama belum benar-benar dihapus.

---

  1. 9. Rekomendasi operasional

Untuk perpustakaan Anda, gunakan:

```text /opt/ai-stack/documents 

   ↓

SHA-256 scanner 

   ↓

AnythingLLM Developer API 

   ↓

Workspace 

   ↓

Embedding model 

   ↓

LanceDB ```

Aturan sinkronisasi:

```text File baru → ADD File berubah → DELETE OLD + ADD NEW File hilang → DELETE Embedder berubah → FULL REBUILD ```

Jadwal yang masuk akal:

```text Perpustakaan sering diperbarui : setiap malam Perpustakaan jarang diperbarui : dijalankan manual Update besar : full rebuild terjadwal ```

Untuk kondisi Anda, pilihan paling aman adalah **incremental sync berbasis SHA-256**, bukan reset vector database setiap kali ada `.md` baru.

[1]: https://docs.anythingllm.com/setup/embedder-configuration/overview "Overview ~ AnythingLLM" [2]: https://docs.anythingllm.com/beta-preview/active-features/live-document-sync "Automatic document sync ~ AnythingLLM" [3]: https://docs.anythingllm.com/features/api "API Access & Keys ~ AnythingLLM" [4]: https://raw.githubusercontent.com/Mintplex-Labs/anything-llm/master/server/swagger/openapi.json "raw.githubusercontent.com"

Retrieved from "https://onnocenter.or.id/wiki/index.php?title=MCP:_Regenerate_Vector_Database_untuk_update_content_documents&oldid=73725"