DOCSEARCHbyAlgolia
Submit Docs

PathRAG Documentation

repository·main·Indexed 18 days ago

https://github.com/bupt-gamma/pathrag

PathRAG is a Knowledge Graph-based Retrieval-Augmented Generation (RAG) system that combines vector similarity with graph traversal to enable multi-hop reasoning and relational understanding. It features a full-stack suite including a FastAPI backend, a React-based UI with D3.js visualization, and support for various LLM backends via RAGRunner (HuggingFace, vLLM, Ollama, ModelScope). The system supports hybrid search across vector and graph structures and provides a comprehensive API for document management, chat threads, and knowledge graph querying.

Tokens
12.4K
Snippets
34
Records
54
Agent score
63%

What's inside PathRAG

  1. Overview of PathRAG features

    main

    PathRAG provides a full-stack suite for managing knowledge-based RAG workflows:

    Core Functionality

    • Document Management: Support for uploading and processing PDF, DOCX, MD, TXT, and HTML files.
    • Chat Interface: A thread-based chat system providing context-aware responses.
    • Knowledge Graph: Interactive visualization and querying of the graph built from documents.
    • User Management: Authentication and personalization features.

    Technical Features

    • Automatic Document Reloading: The system polls document status every 15 seconds and reloads automatically once processing is complete.
    • Interactive Visualization: Uses D3.js for knowledge graph exploration.
    • Theme Customization: Supports multiple UI themes (blue, red, violet).

  2. What is PathRAG and how does it work?

    main

    PathRAG (Path-based Retrieval Augmented Generation) is a RAG system that enhances retrieval by combining vector similarity with knowledge graph traversal.

    Core Concepts

    • Knowledge Graph Integration: Documents are transformed into a graph where Nodes are entities (people, concepts, etc.), Edges are relationships, and Properties store metadata.
    • Path-based Retrieval: Instead of just finding similar text chunks, PathRAG identifies logical paths through the graph to connect entities, enabling multi-hop reasoning.
    • Hybrid Search: Combines Vector search (semantic similarity), Graph traversal (relationship connections), and Entity-centric retrieval (focused entity info).

    Workflow

    1. Document Processing: Documents are chunked, entities/relationships are extracted via NLP, and a knowledge graph is constructed.
    2. Query Processing: Queries are analyzed for entities/intents; the system retrieves information using both vector similarity and graph structure.
    3. Response Generation: The LLM synthesizes context from multiple paths to generate grounded responses.

  3. Understand the PathRAG project structure

    main

    Backend Structure

    • /api/auth: Authentication logic (jwt_handler.py, routes.py, schemas.py).
    • /api/features: Modularized features including /users, /chats, /documents, and /knowledge_graph.
    • /models: Database setup and SQLite models (database.py).
    • main.py: The application entry point.

    Frontend Structure (/pathrag-ui)

    • /src/components: Reusable UI parts for auth, chat, documents, and knowledge-graph.
    • /src/context: React context providers for state management.
    • /src/services: API service layers.
    • /src/pages: Application view pages.

  4. PathRAG Use Cases and Limitations

    main

    Recommended Use Cases

    PathRAG is optimized for:

    • Knowledge-Intensive Applications: Research assistance, legal document analysis, and medical knowledge systems.
    • Complex Information Retrieval: Multi-hop question answering, contextual understanding, and exploratory research.
    • Enterprise Knowledge Management: Corporate knowledge bases, compliance/regulation tracking, and institutional memory.

    Limitations and Considerations

    • Knowledge graph quality: Effectiveness depends on the quality of entity and relationship extraction.
    • Computational complexity: Graph operations can be more resource-intensive than simple vector searches.
    • Domain specificity: Specialized fields may require domain-specific entity extraction.
    • Storage limitations: The default storage options (NanoVectorDB, NetworkX) are not suitable for large-scale production use.

  5. Configure PathRAG as a systemd service

    main

    To ensure the API starts automatically on boot and is managed by the system, create a systemd service file at /etc/systemd/system/pathrag.service.

    Example configuration using Gunicorn:

    [Unit]
Description=PathRAG API
After=network.target

[Service]
User=your_user
Group=your_group
WorkingDirectory=/path/to/pathrag
Environment="PATH=/path/to/pathrag/.venv/bin"
EnvironmentFile=/path/to/pathrag/.env
ExecStart=/path/to/pathrag/.venv/bin/gunicorn -w 4 -k uvicorn.workers.UvicornWorker -b 0.0.0.0:8000 --timeout 120 main:app
Restart=always
RestartSec=5
StartLimitIntervalSec=0

# Security options
PrivateTmp=true
ProtectSystem=full
NoNewPrivileges=true

[Install]
WantedBy=multi-user.target

    Enable and start the service:

    sudo systemctl daemon-reload
sudo systemctl enable pathrag
sudo systemctl start pathrag

  6. Manual Backend Setup and Environment Variables

    main

    To set up the backend manually:

    1. Create and activate a virtual environment: python -m venv .venv and activate it.
    2. Install dependencies: pip install -r requirements.txt.
    3. Configure environment variables by copying sample.env to .env.
    4. Start the server: python main.py.

    Key Environment Variables

    VariableDescription
    SECRET_KEYJWT Authentication secret (use openssl rand -hex 32)
    WORKING_DIRApplication working directory
    DATABASE_URLDatabase connection string (default: sqlite:///./pathrag.db)
    OPENAI_API_KEYOpenAI API key
    OPENAI_API_BASEOpenAI API base URL
    AZURE_OPENAI_API_KEYAzure OpenAI API key
    TOP_KNumber of nodes retrieved
    CHUNK_SIZESize of text chunks
    CHUNK_OVERLAPOverlap between chunks
    TEMPERATURELLM temperature
    CORS_ORIGINSAllowed CORS origins (e.g., http://localhost:3000)

  7. Set up the PathRAG Frontend Development Environment

    main

    To set up the frontend for development:

    1. Navigate to the UI directory:
      cd pathrag-ui
    2. Install dependencies:
      npm install
    3. Configure API endpoint: If your backend is running on a different URL, update the baseURL in src/services/api.js.
    4. Run the development server:
      npm start
      The application will be available at http://localhost:3000.
    5. Build for production:
      npm run build
      Build files are located in the build directory.
    cd pathrag-ui
npm install
npm start

  8. Access PathRAG via Default Accounts

    main

    To quickly access the application, you can use the following pre-configured default credentials:

    • User 1: user1 / Pass@123
    • User 2: user2 / Pass@123
    • User 3: user3 / Pass@123

    Alternatively, you can create a new account using the 'Register' option on the login page.

  9. Deploy the Frontend with Docker

    main

    The frontend is built as a static site using Node.js and served via Nginx. The build process uses a multi-stage Dockerfile: first building the application, then copying the build artifacts to an nginx:alpine image.

    An nginx.conf is required to handle routing and proxy API requests from /api/ to the backend service.

    # Frontend Dockerfile
FROM node:16-alpine as build
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
RUN npm run build

FROM nginx:alpine
COPY --from=build /app/build /usr/share/nginx/html
COPY nginx.conf /etc/nginx/conf.d/default.conf
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]
    # nginx.conf
server {
    listen 80;
    location / {
        root /usr/share/nginx/html;
        index index.html index.htm;
        try_files $uri $uri/ /index.html;
    }
    location /api/ {
        proxy_pass http://backend:8000/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

  10. Explore the Knowledge Graph Visualization

    main

    The Knowledge Graph view provides a visual representation of the entities and relationships extracted from your documents.

    • Nodes: Represent entities (people, organizations, concepts, etc.). Colors indicate different entity types.
    • Edges: Represent relationships. The thickness of the line indicates the strength of the relationship.

    Interactions:

    • Rearrange: Drag nodes to move them.
    • Zoom: Use the mouse wheel to zoom in/out.
    • Inspect: Hover over nodes to see specific details.
    • Search: Use the search box to find specific parts of the graph.

  11. Upload and Manage Documents

    main

    PathRAG builds its knowledge graph by extracting entities and relationships from uploaded files.

    1. Navigate to Documents in the sidebar.
    2. Click Upload Document.
    3. Drag and drop or select a file.

    Supported Formats:

    • PDF
    • DOCX
    • MD

    Best Practices:

    • Upload related documents together to create a richer, more connected knowledge graph.
    • Note that larger documents require more processing time for entity and relationship extraction.

  12. Run PathRAG with GUI (API and UI)

    main

    1. Start the Backend API

    Unix/Linux/macOS:

    chmod +x start-api.sh
./start-api.sh

    Windows:

    start-api.bat

    This creates a .venv, installs dependencies, and starts the API on port 8000. Documentation is available at http://localhost:8000/docs.

    2. Start the Frontend UI

    cd ui
npm install
npm start

    The UI will be available at http://localhost:3000.