Skip to content

LightRAG + OpenSearch

Knowledge graph RAG engine with OpenSearch storage backend.

Source: extracted from AGENTS.md

LightRAG + OpenSearch

LightRAG (container: lightrag) — Knowledge graph RAG engine trên development server.

Detail Value
API http://100.126.172.96:9621
Web UI Built-in (same port)
Image ghcr.io/hkuds/lightrag:latest
Stack stacks/llm/lightrag/compose.yaml
Server development (100.126.172.96)
Workspace obsidian
Core version 1.4.16

Architecture:

Document → LightRAG API → MiniMax-M2.7 (entity extraction) → OpenSearch (storage)
                                        ↘ skylark-embedding-vision (1024d) → OpenSearch (vector)

OpenSearch (shared service on unraid):

  • Endpoint: http://100.68.251.84:9200
  • Stack: stacks/database/opensearch/compose.yaml
  • Version: 2.19.1, single-node, DISABLE_SECURITY_PLUGIN=true
  • Volume: /mnt/user/appdata/opensearch/data (UID 1000)

All 4 storage backends → OpenSearch:

Storage Type OpenSearch Index Prefix
KV obsidian_full_docs, obsidian_llm_response_cache
Vector obsidian_text_chunks, obsidian_chunks
Graph obsidian_entities, obsidian_relationships, obsidian_*_entity_relation-*
DocStatus obsidian_doc_status

Config:

  • LLM: MiniMax-M2.7 via LiteLLM (http://100.68.251.84:4001/v1)
  • Embedding: skylark-embedding-vision (1024d) via LiteLLM
  • Reranking: qwen3-reranker-small (Cohere binding)
  • API key: [[LITELLM_MASTER_KEY]] Komodo Variable
  • Summary language: Vietnamese

API endpoints (key): | Method | Endpoint | Purpose | |--------|----------|---------| | POST | /documents/text | Insert text document | | POST | /documents/texts | Batch insert | | POST | /documents/upload | Upload file | | GET | /documents/track_status/{track_id} | Check processing status | | DELETE | /documents | Clear all documents | | GET | /documents/status_counts | Status overview | | GET | /health | Health + config dump |

Test insert:

# Insert document
RESULT=$(curl -s -X POST "http://100.126.172.96:9621/documents/text" \
  -H "Content-Type: application/json" \
  -d '{"text": "Your document text here."}')
TRACK_ID=$(echo "$RESULT" | python3 -c "import sys,json; print(json.load(sys.stdin).get('track_id',''))")

# Check status (wait 30-60s for processing)
curl -s "http://100.126.172.96:9621/documents/track_status/$TRACK_ID" | python3 -c "
import sys,json; d=json.load(sys.stdin)
for doc in d.get('documents',[]): print(f'Status: {doc.get(\"status\")}')"

# Verify OpenSearch indices
curl -s "http://100.68.251.84:9200/_cat/indices?v" | grep obsidian

Pitfalls:

  • LLM model name must match exactly: MiniMax-M2.7 (không phải MiniMax-M2.7-Highspeed) — check GET /v1/models trên LiteLLM
  • API key phải là Komodo Variable [[LITELLM_MASTER_KEY]] — hardcoded key sk-nJVBlz-... KHÔNG work (401)
  • OpenSearch volume ownership: UID 1000 (chown -R 1000:1000), KHÔNG phải 99:100
  • Processing takes 30-60s cho small document — LLM calls cho entity extraction + embedding
  • destroy_before_deploy = true sẽ xóa container nhưng OpenSearch data giữ nguyên (separate service)
  • LightRAG MCP (daniel-lightrag-mcp) configured trên LiteLLM — 22 tools, connects to http://100.126.172.96:9621