Skip to content

AGENTS.md

Latest commit

 

History

History
92 lines (69 loc) · 4.9 KB

AGENTS.md

File metadata and controls

92 lines (69 loc) · 4.9 KB
Raw

LightRAG4j — Agent Guide

Project Overview

Java port of LightRAG (港大原版). Implements graph-based RAG: document → chunk → LLM entity/relation extraction → Neo4j graph + Qdrant vectors → dual-level retrieval → answer generation.

Tech Stack

  • Java 25, Spring Boot 4.0.6, Maven (single module, no multi-module)
  • Lombok (use @RequiredArgsConstructor + final, not @Autowired)
  • Jackson 3.x (tools.jackson.databind.*, not com.fasterxml.jackson)
  • Neo4j 5.x (requires APOC plugin — apoc.coll.toSet used in Cypher)
  • Qdrant (REST API, not gRPC client)
  • OpenAI-compatible LLM API (SiliconFlow by default)

Build & Run

mvn clean compile          # compile
mvn clean test              # run all tests (most require external services)
mvn spring-boot:run         # start app on :8080

Infrastructure

Start Neo4j + Qdrant before running the app:

docker-compose up -d

Neo4j: bolt://localhost:7687 (neo4j/lightrag), Qdrant: http://localhost:6333

Running a Single Unit Test

mvn test -Dtest=LightRAGServiceChunkTest -pl .

Most tests in src/test are integration tests that need Neo4j/Qdrant/LLM API. The only pure unit test is LightRAGServiceChunkTest (tests chunkDocument logic without Spring context).

Architecture

com.github.lightrag
├── controller/LightRAGController   REST API entry (/api/v1/rag/*)
├── service/LightRAGService         Orchestration: insert/query/retrieve + chunking
├── service/FileParser              .txt/.md/.doc file parsing
├── core/GraphIndexer               LLM extraction → Neo4j + Qdrant upsert
├── core/DualLevelRetriever         Low-level (entity vector) + High-level (relation vector) + neighbor expansion
├── core/AnswerGenerator            Build context from retrieve result → LLM answer
├── llm/LlmClient                   OpenAI-compatible HTTP client (complete + embed)
├── storage/Neo4jGraphStorage       Cypher-based graph store (MERGE for dedup)
├── storage/QdrantVectorStorage     REST-based vector store (lazy-init collections)
├── storage/VectorStorage           Interface
├── prompt/Prompts                  Prompt templates (graph construct, keyword extract, answer)
├── model/                          Data classes: Entity, Relation, Chunk, Keywords, RetrieveResult, R, dto/ImportResult
└── config/AppConfig                Spring beans: Neo4j driver, VectorStorage, LlmClient

Data Flow

  1. Import: Controller → LightRAGService.insert() → chunkDocument() → GraphIndexer.index(List<Chunk>) → parallel LLM extraction → Neo4jGraphStorage.upsert* + QdrantVectorStorage.upsert*
  2. Query: Controller → LightRAGService.query() → DualLevelRetriever.retrieve() (keyword extract → vector search → neighbor expand) → AnswerGenerator.generate()

Key Conventions & Gotchas

  • DI: Use @RequiredArgsConstructor + final fields. Do NOT use @Autowired.
  • Log format: Key operations use log.info("[kxj: ...]") pattern.
  • Jackson: Project uses Jackson 3.x (tools.jackson.databind), not Jackson 2.x (com.fasterxml.jackson).
  • Config prefix: lightrag.* in application.yml (e.g., lightrag.neo4j.uri, lightrag.llm.model).
  • LLM jsonMode: LlmClient.complete(prompt, true) sends response_format: json_object. Not all API providers honor this; code strips markdown fences as fallback.
  • Neo4j APOC dependency: upsertEntity and upsertRelation use apoc.coll.toSet() — Neo4j must have APOC plugin installed.
  • Qdrant lazy init: Vector collection dimension is determined by the first embedding call. Changing the embedding model requires deleting and recreating collections.
  • Entity dedup: Relies on MERGE by entity name, but LLM may produce inconsistent names (e.g., "布鲁克斯" vs "Brooks").
  • Relation direction: Treated as undirected despite LLM potentially reversing source/target.
  • Language detection: containsChinese() is heuristic; mixed-language text may be misclassified, affecting prompt language choice.

API Endpoints

Method Path Description
POST /api/v1/rag/import Upload files (multipart), params: chunkSize, overlapRatio
POST /api/v1/rag/query Body: {"query": "..."} → returns answer string
POST /api/v1/rag/retrieve Body: {"query": "..."} → returns entities/relations/chunks

Test Categories

  • Unit (no infra needed): LightRAGServiceChunkTest — tests chunking logic
  • Integration (needs Neo4j+Qdrant+LLM API): LightRAGBookTest, LlmOutputDebugTest, PromptDebugTest
  • Standalone (main method, no Spring): ModelJsonOutputQuickTest — benchmarks LLM JSON quality across models
  • Model eval (needs LLM API only): ModelJsonOutputTest — JUnit-based multi-model JSON output quality test