Skip to main content

LightRAG Web UI — Operator Guide

Status: Phase 1 (adopted) · ADR-010 · MET-392 / MET-393

The LightRAG Web UI is a standalone React + Sigma.js single-page app served by LightRAG's own FastAPI backend. We mount it via docker-compose so engineers can dogfood the L1 knowledge layer during the MET-346 spike with zero new MetaForge frontend code.

It is separate from the Kinetic Console. The integrated /knowledge page in the dashboard arrives in Phase 2; until then, this UI is the canonical visual surface for the knowledge graph.

What it is​

ComponentWhere it lives
LightRAG FastAPI serverlightrag-ui docker-compose service
React + Sigma.js front-endserved at /
Storage backendsshares the same pgvector Postgres the gateway uses, in workspace lightrag_ui
Embeddingslocal nomic-embed-text via ollama sidecar (no API key)
LLMlocal llama3.2:3b via ollama sidecar — overridable to Gemini via .env

Documents you ingest through this UI live in their own pgvector workspace (lightrag_ui), separate from the gateway's primary knowledge data. That's intentional — it keeps engineer experiments out of the production knowledge stream while still exercising the real backend.

How to start it​

The UI is opt-in via a docker-compose profile. The first start also pulls ~2.5 GB of ollama models (one-time):

Terminal
docker compose --profile lightrag up -d

That brings up three containers:

ContainerPurpose
metaforge-lightrag-ui-1LightRAG FastAPI server + React UI
metaforge-lightrag-ui-ollama-1Ollama runtime serving embeddings + LLM
metaforge-lightrag-ui-ollama-bootstrap-1One-shot — pulls nomic-embed-text and llama3.2:3b, then exits

Once lightrag-ui is healthy, open:

Code
http://localhost:9621

If you set LIGHTRAG_API_KEY in your .env, the UI will require that token in the Authorization: Bearer <key> header (use the "Login" panel). Leave it unset for local dev.

Switching to Gemini for the LLM (optional)​

The published LightRAG image only ships the ollama and gemini bindings — there is no OpenAI binding. To use Gemini for chat (still keep ollama for embeddings):

DOTENV
LIGHTRAG_LLM_BINDING=gemini
LIGHTRAG_LLM_MODEL=gemini-2.5-flash
LIGHTRAG_LLM_API_KEY=...your-gemini-api-key...
LIGHTRAG_LLM_HOST=                    # leave blank for gemini

To use Gemini for both embeddings and the LLM:

DOTENV
LIGHTRAG_EMBEDDING_BINDING=gemini
LIGHTRAG_EMBEDDING_MODEL=text-embedding-004
LIGHTRAG_EMBEDDING_DIM=768
LIGHTRAG_EMBEDDING_API_KEY=...your-gemini-api-key...
LIGHTRAG_EMBEDDING_HOST=

LIGHTRAG_LLM_BINDING=gemini
LIGHTRAG_LLM_MODEL=gemini-2.5-flash
LIGHTRAG_LLM_API_KEY=...your-gemini-api-key...
LIGHTRAG_LLM_HOST=

Optional UI-lock-down env vars (add to your .env if needed):

DOTENV
LIGHTRAG_API_KEY=                     # leave blank for local dev
LIGHTRAG_UI_PORT=9621                 # override the host port mapping

What each tab does​

TabPurpose
GraphInteractive knowledge-graph canvas. Click a node to see its neighbours and the documents it appears in.
DocumentsUpload markdown / PDF / plain-text files; see chunk counts, processing status, and last-modified time.
ChatStreamed retrieval testing. Query → see the answer, citations, and the KG canvas highlight matched entities. Requires LLM env vars set.
Swagger/docs — full FastAPI route reference. Useful for poking the underlying API by hand.

When to use it vs the future /knowledge page​

Use this UI when…Use the integrated /knowledge page when…
You're iterating on chunking / embedding / extraction logicYou're an end-user reviewing your own design's knowledge
You need to inspect the raw knowledge graph (entities, edges)Phase 2 lands the embedded view (date TBD)
You're debugging a poor retrieval resultYou want fragment search alongside the rest of the dashboard's controls
You're verifying MET-346 spike adoption criteria—

MET-346 spike adoption checklist​

Each criterion below is verified by the automated test coverage that landed in main during the L1 implementation loop. Booting the LightRAG UI live remains a useful spot-check for engineers, but the contract itself is owned by the listed test files — those are the source of truth.

  • Ingest works — verified by tests/uat/scenarios/tier1/ingest.md (HP-INGEST-01..10, ten scenarios covering markdown, recursive directories, PDF, CSV, and event-driven paths).
  • Graph extraction works — verified by tests/integration/test_pdf_ingest.py and tests/integration/test_knowledge_citation_roundtrip.py (the citation chain — heading-aware chunking + metadata round-trip — is proven end-to-end). Note: graph entity/edge extraction itself is LLM-driven inside LightRAG and is validated only when the LightRAG UI is booted with an LLM key (Gemini or Ollama llama3.2:3b); the gateway path doesn't run that extraction step in Phase-1 (engineer-dogfood scope).
  • Vector retrieval works — verified by tests/uat/scenarios/tier1/retrieval.md (HP-RETR-01..12), exercising sentence-transformers embeddings + the L1-A2 hybrid reranker (PR #164).
  • Hybrid retrieval works — verified by HP-RETR-05 (BM25 literal MPN match across paraphrased query) plus the L1-A2 reranker fusing vector + lexical scores.
  • Citation chain complete — verified by tests/integration/test_knowledge_citation_roundtrip.py (L1-F4, PR #188) — all four cases (h2, h1→h2, chunk_index, caller metadata) round-trip byte-for-byte — and exercised end-to-end by tests/uat/scenarios/tier1/full-capability.md (L1-F1a, PR #177).

If a criterion regresses in main, file a P1 ticket against MET-346 referencing the broken test rather than a UI screenshot.

Phase-1 adoption status (MET-346)​

  • Workspace separation policy is pinned. Per L1-A5 / L1-D1 in docs/plans/l1-implementation.md, the gateway and the LightRAG UI keep separate pgvector workspaces in Phase-1 (lightrag and lightrag_ui respectively). This is intentional — the LightRAG UI is engineer-dogfood scope and must not pollute the gateway's primary knowledge stream.
  • Cross-workspace bridging is deferred to Phase-2. The integrated /knowledge page and any data bridging are tracked under the L1-E2 sources-table line item (and the broader L1-E sequence). ADR-010's Phase-2 plan is the binding spec.
  • Live UI verification is recommended, not gated. Booting docker compose --profile lightrag up is still the fastest way to poke the chunking/retrieval pipeline interactively, and the checklist above remains useful as a manual smoke test. But the PR-merge gate is the automated test coverage cited in each checklist row — those tests are the source of truth for the L1 contract.

Migration to Phase 2​

L1-D2 (PR #192) flipped every MET-346 adoption-checklist row to ✅, which means the standalone localhost:9621 UI has done its Phase-1 job. The Phase-2 surface for sources browsing now lives in the Kinetic Console:

  • L1-E2 — integrated /knowledge page (PR #193, just merged) supersedes the standalone localhost:9621 UI for sources browsing. The integrated page reads from the gateway's metaforge://knowledge/sources resource (L1-B1) and is the canonical v1 sources surface going forward. The LightRAG UI stays in place as an engineer-only debugging tool for the chunking/extraction pipeline, but day-to-day "what sources does my project have?" lives in /knowledge.
  • L1-E3 (search bar) and L1-E4 (graph embed) are deferred per the L1-E1 v1 pin — the v1 /knowledge page is intentionally sources table only. Search and the Sigma.js graph embed move to v2; in the meantime, the LightRAG UI's Chat and Graph tabs remain the way to exercise those flows interactively.
  • L1-E5 (sidebar relabel) is the final cleanup that retires the legacy /files "Knowledge" mislabel: the sidebar entry currently pointing at /files will be renamed back to "Files," and the new "Knowledge" entry will point at /knowledge. After L1-E5 lands, the sidebar matches the routing, and the LightRAG UI is no longer referenced from the dashboard chrome.

See the L1 status board and the MET-346 adoption record for the full sequencing:

Cross-references​

MetaForge documentationGateway schema

ON THIS PAGE

See it end to end

A 4-layer PCB around the STM32F405RGT6, walked through six engineering disciplines on mock adapters.

Open the example