LightningRAG: a Vue + Gin starter with RAG and agent orchestration built in

The gap LightningRAG is trying to fill

Most RAG demos stop at a Python script that embeds a folder of PDFs. The hard part starts after that: who uploads documents, who owns a knowledge base, which model answers, and how an answer gets back to a user in Slack. LightningRAG takes the position that this plumbing belongs in one repository, with a Go backend and a Vue admin UI, rather than in a notebook plus three services.

The target reader is a small team that already knows it wants retrieval-augmented generation and would rather start from an existing admin shell than build login, roles and menus from scratch. The repository ships JWT and Casbin authorization, dynamic routes and menus, a form builder, and a code generator, all of which are unrelated to RAG but take time to write. The RAG layer sits on top: knowledge bases with document parsing and chunking, vector retrieval, and an agent canvas with Begin, Retrieval, LLM, Message and Agent nodes.

The README is candid about the project's stage. Version numbers are in the v0.0.x range, the most recent release in the repository is v0.0.7 from 2026-04-17, and the online demo link is struck through with a note that the public preview is not deployed yet. That is a starter kit posture, not a product posture, and the README does not pretend otherwise.

How the pieces fit: knowledge bases, retrievers and the agent canvas

The data flow described in the README is conventional for this class of tool. A document is uploaded into a knowledge base, parsed to plain text, chunked, embedded, and the vectors are written to whichever VectorStore is configured. Chunk metadata stays in the application database, in tables named `rag_knowledge_bases`, `rag_documents` and `rag_chunks`. Vector storage is separate: the README names PostgreSQL with pgvector and Elasticsearch `dense_vector` as examples.

Retrieval is behind a `Retriever` interface under `server/rag/`, with vector, keyword and PageIndex kinds, and the README mentions hybrid and multi-path retrieval. Conversation is exposed over `/rag/conversation/chat` and a streaming `chatStream` endpoint that uses SSE; the README notes the final frame may carry the retrieval mode, the queries issued, and `references`. There is also a `queryData` endpoint that returns structured retrieval with no LLM call and no message persistence, which is the one to reach for when you want to debug why a query returned what it did. Casbin has to allow that path, so a fresh install may return a permission error until the policy is updated.

Agent orchestration is a separate layer on the same backend. Flows are drawn on a canvas and can branch, which distinguishes them from a single fixed knowledge-base chat. Tools are registered through an extensible registry described in `server/rag/tools/README.md`. Optional channel connectors bind a published agent to a webhook URL for Feishu, DingTalk, WeChat, Slack, Teams and others, authenticated by an `X-Webhook-Secret` header or vendor signatures, with per-channel `extra` JSON edited in the admin UI.

Tuning lives in two places. Per-request body fields such as `queryMode`, `chunkTopK`, `topK`, `enableRerank`, `maxRagContextTokens`, `cosineThreshold` and `minRerankScore` are defined in `server/model/rag/request/conversation.go`. Global defaults sit under the `rag:` key in `config.yaml`, covering top-k values, candidate pool sizes, hybrid fusion weights and knowledge-graph settings. The README warns that a value of `0` usually means use built-in defaults, which is a trap worth remembering when a setting appears to have no effect.

Installing LightningRAG and running a first retrieval

The repository does not present a one-command quickstart in the README. What it does provide is a Makefile whose targets wrap the build in Docker images, so the toolchain versions are pinned rather than assumed. The Makefile sets `BUILD_IMAGE_SERVER = golang:1.24` and `BUILD_IMAGE_WEB = node:20`, and comments note those should match `go.mod` and CI respectively.

The full build runs the web and server builds inside containers and assembles a `build` directory containing `web/dist`, the `server` binary and `server/resource`. Run it from the repository root:

make build

What you should see is a `build` directory appear at the top level. The Makefile removes any existing `build` directory first, then copies the frontend output, the compiled server binary and the resource folder into it. If Docker is not available, the target fails at the first `docker run`.

For iterating on one side only, the Makefile exposes the halves separately. The frontend target uses npm, and the comment notes CI uses pnpm while both read `package-lock.json` or `pnpm-lock.yaml`:

make build-web-local
make build-server-local

The web target deletes `web/dist` if present, then runs `npm install --no-audit --no-fund` and `npm run build` inside `web/`. Container images can also be built per side with `make build-image-web` and `make build-image-server`, which tag into the registry namespace `lightningrag` defined near the top of the Makefile.

Configuration comes from `config.yaml`, which the README says can also be modified from the admin UI, with the caveat that this may be disabled on a public demo instance. Before expecting retrieval to work you need a vector store configured and at least one LLM and embedding provider registered, either in the admin tables `rag_llm_providers`, `rag_embedding_providers` and `rag_vector_store_configs`, or per user through `rag_user_llms`. The README does not document a seed dataset, so the first knowledge base is something you create yourself.

Where LightningRAG will frustrate you

The version number is the first honest signal. v0.0.7 arrived on 2026-04-17, and the releases before it were v0.0.5 and v0.0.3 earlier the same month. That cadence suggests the API surface is still moving, and anything you build against the request structs or the `rag:` config keys should be expected to change.

The README leaves operational questions open. There is no documented rollback procedure, no migration guide between releases, and no stated upgrade path for the database schema that holds `rag_chunks` and the provider tables. The demo link is disabled with a note that the server is not ready, so there is no hosted instance to compare your deployment against.

The provider list is broad on purpose, and breadth has a cost. LLM, embedding, rerank, speech, TTS, OCR and CV providers are all mentioned as pluggable, which means the configuration surface is large and the README defers authoritative detail to `server/rag/README.md`. If your team wants a tool with one blessed model and one blessed vector store, this is more knobs than you need.

Finally, the starter framing cuts both ways. The authorization, menu and code-generation features are useful if you want them and dead weight if you already have an admin system. LightningRAG is the wrong tool when the requirement is a thin retrieval library you can call from an existing Go service; the RAG code here is coupled to the application's database models and its Casbin policies.

LightningRAG compared with RAGFlow and Dify

The repository's own topics list `ragflow` and `dify` alongside `gin`, `vue` and `rag`, which is a fair indication of the neighborhood it sees itself in. The difference is in what you receive. RAGFlow and Dify are applications you deploy and use, with their own UI and their own opinions about document parsing and workflow. LightningRAG is a codebase you fork and extend, with the admin shell, the Go handlers and the Vue views all present in the tree.

That distinction matters for the document parsing layer specifically. The README points to `docs/DOCUMENT_PARSE_RAGFLOW_ALIGNMENT.md`, a document whose name suggests the project has aligned its parsing behavior with RAGFlow's and recorded the differences. If parsing fidelity is your main concern, that file is the one to read before choosing, because it is the place where the two projects are explicitly compared by the maintainers.

On the orchestration side, the canvas with Begin, Retrieval, LLM, Message and Agent nodes covers ground that Dify also covers, and the README points to `docs/AGENT_IMPLEMENTATION_PLAN.md` and `docs/AGENT_COMPONENTS_DEVELOPMENT_PLAN.md` rather than to finished documentation. Those filenames say plan, not reference, and you should read them as such. A team that wants a workflow editor today, with documentation behind it, is better served by a project whose agent features are past the planning stage. A team that wants to own the orchestration code in Go has a reason to look here instead.

Licence, maintenance and the cost of upgrading

LightningRAG is licensed under Apache-2.0. That is a permissive licence, and it is the same licence used by a large share of Go infrastructure, so it is unlikely to be the deciding factor. The practical implication is that you can modify and redistribute the code, including in a commercial product, provided you keep the licence and notices intact and state significant changes. The repository ships `LICENSE`, `SECURITY.md` and `CONTRIBUTING.md` in both English and Chinese, which is a reasonable sign of process. None of this is legal advice; if you plan to redistribute a modified version, have someone qualified read the notice requirements.

Maintenance is where the arithmetic gets uncomfortable. The last push to the default branch was on 2026-04-17, which is more than five months before today. The repository is not archived, so it has not been formally retired, but the recent release history ends at v0.0.7 on the same day as that push. Treat it as a project that may resume rather than one with a steady cadence, and check whether new commits have landed since before you commit to it.

Upgrade cost follows from the version numbers. Between v0.0.3 and v0.0.7 in a single week, the request structs and config keys were plausibly still being settled. If you fork and modify the RAG layer, every upstream change becomes a merge you own. The absence of a documented schema migration path for the `rag_*` tables means any upgrade that touches chunk or provider storage is manual work. Budget for reading `server/rag/README.md` and the `rag:` block of `config.yaml` at each release rather than assuming compatibility.

Editorial conclusion

Adopt LightningRAG if you want a Go and Vue codebase you can extend, with RAG tables, provider configs and an agent canvas already wired up. Skip it if you need a stable API surface: it is at v0.0.7, the online demo is not deployed, and the README leaves deployment and rollback undocumented. Verify first that the Dockerfile.goreleaser build path works on your machine and that your target vector store (pgvector or Elasticsearch dense_vector) is reachable from the server.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. LightningRAG/LightningRAG on GitHub
3. Project website
4. README
5. Releases