### Build and Run MiniRAG with Docker Compose

Source: https://context7.com/hkuds/minirag/llms.txt

Deploy MiniRAG using Docker Compose for a streamlined setup. Copy the example environment file, edit it with your configurations (e.g., LLM_BINDING, OPENAI_API_KEY), and then start the services.

```bash
# Build and start with docker-compose (uses environment variables from .env)
cp minirag/api/.env.aoi.example .env
# Edit .env to set LLM_BINDING, LLM_MODEL, OPENAI_API_KEY, etc.

docker-compose up -d
```

--------------------------------

### Install MiniRAG from PyPI or Source

Source: https://context7.com/hkuds/minirag/llms.txt

Install the base MiniRAG package or with API support from PyPI. For development, clone the repository and install from source.

```bash
pip install minirag-hku
```

```bash
pip install "minirag-hku[api]"
```

```bash
git clone https://github.com/HKUDS/MiniRAG.git
cd MiniRAG
pip install -e .
```

```bash
pip install -e ".[api]"
```

--------------------------------

### Install and Manage MiniRAG Service on Ubuntu

Source: https://github.com/hkuds/minirag/blob/main/minirag/api/README.md

Commands to install, start, check status, and enable the MiniRAG service on an Ubuntu system using systemd. Replace 'lightrag-server.service' with your actual service file name if different.

```shell
sudo cp lightrag-server.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl start lightrag-server.service
sudo systemctl status lightrag-server.service
sudo systemctl enable lightrag-server.service
```

--------------------------------

### Run MiniRAG with Ollama Defaults

Source: https://github.com/hkuds/minirag/blob/main/minirag/api/README.md

Starts the MiniRAG server using Ollama as the default backend for both LLM and embedding. Ensure Ollama is installed, running, and has the default models downloaded.

```bash
# Run minirag with ollama, mistral-nemo:latest for llm, and bge-m3:latest for embedding
minirag-server
```

--------------------------------

### Run MiniRAG with Ollama and Lollms Backends

Source: https://github.com/hkuds/minirag/blob/main/minirag/api/README.md

Starts the MiniRAG server using Ollama for embedding and Lollms for the LLM. Ensure Lollms is installed and running.

```bash
# Using lollms for llm and ollama for embedding
minirag-server --llm-binding lollms
```

--------------------------------

### Install MiniRAG with API Support from PyPI

Source: https://github.com/hkuds/minirag/blob/main/minirag/api/README.md

Use this command to install the MiniRAG package with API support from the Python Package Index. This is the recommended method for most users.

```bash
pip install "lightrag-hku[api]"
```

--------------------------------

### Starting the REST API Server

Source: https://context7.com/hkuds/minirag/llms.txt

Instructions on how to launch the MiniRAG FastAPI server using the `minirag-server` CLI, with various configuration options.

```APIDOC
## Starting the REST API Server

Launch the MiniRAG FastAPI server using the `minirag-server` CLI. It supports various LLM/embedding backends and emulates the Ollama API.

```bash
# Start with default Ollama backend
minirag-server

# Start with OpenAI backend
minirag-server \
  --llm-binding openai \
  --llm-model gpt-4o-mini \
  --embedding-binding openai \
  --embedding-model text-embedding-3-small \
  --working-dir ./rag_storage \
  --input-dir ./documents \
  --port 9721 \
  --key my-secret-api-key

# Start with Ollama LLM + OpenAI embeddings
minirag-server \
  --llm-binding ollama \
  --llm-model phi3.5:latest \
  --embedding-binding openai \
  --embedding-model text-embedding-3-small \
  --embedding-dim 1536

# Auto-index all documents in --input-dir at startup
minirag-server --auto-scan-at-startup --input-dir ./documents

# Start with SSL enabled
minirag-server --ssl --ssl-certfile ./cert.pem --ssl-keyfile ./key.pem
```
```

--------------------------------

### Install MiniRAG with API Support from Source (Development)

Source: https://github.com/hkuds/minirag/blob/main/minirag/api/README.md

Clone the MiniRAG repository and install it in editable mode with API support. This is useful for development purposes.

```bash
# Clone the repository
git clone https://github.com/HKUDS/minirag.git

# Change to the repository directory
cd minirag

# create a Python virtual enviroment if neccesary
# Install in editable mode with API support
pip install -e ".[api]"
```

--------------------------------

### Get Server Help

Source: https://github.com/hkuds/minirag/blob/main/minirag/api/README.md

Display help information for the minirag-server command, listing all available flags and options.

```bash
minirag-server --help
```

--------------------------------

### Create MiniRAG Service Startup Script

Source: https://github.com/hkuds/minirag/blob/main/minirag/api/README.md

Create the startup script for the MiniRAG service. Remember to adjust the Python virtual environment activation path as needed for your setup.

```shell
#!/bin/bash

# python virtual environment activation
source /home/netman/minirag-xyj/venv/bin/activate
# start lightrag api server
lightrag-server
```

--------------------------------

### Install MiniRAG from PyPI

Source: https://github.com/hkuds/minirag/blob/main/README.md

Installs the MiniRAG package directly from the Python Package Index (PyPI). This is the standard way to install the library for use in projects.

```bash
pip install lightrag-hku
```

--------------------------------

### Run MiniRAG Server in Development (Ollama)

Source: https://github.com/hkuds/minirag/blob/main/minirag/api/README.md

Start the MiniRAG server in development mode using uvicorn with the Ollama backend.

```bash
uvicorn ollama_minirag_server:app --reload --port 9721
```

--------------------------------

### Install MiniRAG from Source

Source: https://github.com/hkuds/minirag/blob/main/README.md

Installs the MiniRAG package in editable mode from the local source code. This is recommended for development or when making changes to the library.

```bash
cd MiniRAG
pip install -e .
```

--------------------------------

### Run MiniRAG with Authentication Key

Source: https://github.com/hkuds/minirag/blob/main/minirag/api/README.md

Starts the MiniRAG server with a specified API key for authentication. This protects the server against unauthorized access.

```bash
# Using an authentication key
minirag-server --key my-key
```

--------------------------------

### Run MiniRAG Server in Development (OpenAI)

Source: https://github.com/hkuds/minirag/blob/main/minirag/api/README.md

Start the MiniRAG server in development mode using uvicorn with the OpenAI backend.

```bash
uvicorn openai_minirag_server:app --reload --port 9721
```

--------------------------------

### Start MiniRAG REST API Server

Source: https://context7.com/hkuds/minirag/llms.txt

Launch the MiniRAG FastAPI server using the `minirag-server` CLI. Supports various LLM/embedding backends and Ollama API emulation. Configure port, working directory, and API keys as needed.

```bash
# Start with default Ollama backend (mistral-nemo:latest for LLM, bge-m3:latest for embeddings)
minirag-server
```

```bash
# Start with OpenAI backend
minirag-server \
  --llm-binding openai \
  --llm-model gpt-4o-mini \
  --embedding-binding openai \
  --embedding-model text-embedding-3-small \
  --working-dir ./rag_storage \
  --input-dir ./documents \
  --port 9721 \
  --key my-secret-api-key
```

```bash
# Start with Ollama LLM + OpenAI embeddings
minirag-server \
  --llm-binding ollama \
  --llm-model phi3.5:latest \
  --embedding-binding openai \
  --embedding-model text-embedding-3-small \
  --embedding-dim 1536
```

```bash
# Auto-index all documents in --input-dir at startup
minirag-server --auto-scan-at-startup --input-dir ./documents
```

```bash
# Start with SSL enabled
minirag-server --ssl --ssl-certfile ./cert.pem --ssl-keyfile ./key.pem
```

--------------------------------

### Run MiniRAG Server in Development (LoLLMs)

Source: https://github.com/hkuds/minirag/blob/main/minirag/api/README.md

Start the MiniRAG server in development mode using uvicorn with the LoLLMs backend.

```bash
uvicorn lollms_minirag_server:app --reload --port 9721
```

--------------------------------

### Configuration Priority Example

Source: https://github.com/hkuds/minirag/blob/main/minirag/api/README.md

Illustrates how command-line arguments and environment variables override default configuration values. Command-line arguments have the highest priority.

```bash
# This command-line argument will override both the environment variable and default value
python minirag.py --port 8080

# The environment variable will override the default value but not the command-line argument
PORT=7000 python minirag.py
```

--------------------------------

### Run MiniRAG with Lollms for Both Backends

Source: https://github.com/hkuds/minirag/blob/main/minirag/api/README.md

Launches the MiniRAG server using Lollms for both LLM and embedding. Ensure Lollms is installed and running.

```bash
# Run minirag with lollms, mistral-nemo:latest for llm, and bge-m3:latest for embedding, use lollms for both llm and embedding
minirag-server --llm-binding lollms --embedding-binding lollms
```

--------------------------------

### Run MiniRAG Server in Development (Azure OpenAI)

Source: https://github.com/hkuds/minirag/blob/main/minirag/api/README.md

Start the MiniRAG server in development mode using uvicorn with the Azure OpenAI backend.

```bash
uvicorn azure_openai_minirag_server:app --reload --port 9721
```

--------------------------------

### Run MiniRAG Server with OpenAI Backends

Source: https://github.com/hkuds/minirag/blob/main/minirag/api/README.md

Start the MiniRAG server using OpenAI for both language models and embeddings. Supports specifying models and authentication keys.

```bash
minirag-server --llm-binding openai --llm-model GPT-4o-mini --embedding-binding openai --embedding-model text-embedding-3-small
```

```bash
# Using an authentication key
minirag-server --llm-binding openai --llm-model GPT-4o-mini --embedding-binding openai --embedding-model text-embedding-3-small --key my-key
```

```bash
# Using lollms for llm and openai for embedding
minirag-server --llm-binding lollms --embedding-binding openai --embedding-model text-embedding-3-small
```

--------------------------------

### Get Ollama Available Models

Source: https://github.com/hkuds/minirag/blob/main/minirag/api/README.md

Fetch a list of available models from the Ollama emulation endpoint.

```bash
curl http://localhost:9721/api/tags
```

--------------------------------

### Get Ollama API Version

Source: https://github.com/hkuds/minirag/blob/main/minirag/api/README.md

Retrieve version information from the Ollama emulation endpoint.

```bash
curl http://localhost:9721/api/version
```

--------------------------------

### Run MiniRAG with Specific Ollama Models

Source: https://github.com/hkuds/minirag/blob/main/minirag/api/README.md

Launches the MiniRAG server with specified LLM and embedding models from Ollama. Verify that these models are installed in your Ollama instance.

```bash
# Using specific models (ensure they are installed in your ollama instance)
minirag-server --llm-model adrienbrault/nous-hermes2theta-llama3-8b:f16 --embedding-model nomic-embed-text --embedding-dim 1024
```

--------------------------------

### Ollama-Compatible Chat Completion (Streaming)

Source: https://context7.com/hkuds/minirag/llms.txt

Interact with MiniRAG as an Ollama model using the `/api/chat` endpoint. This example demonstrates streaming responses for chat completions, allowing for real-time output. Query mode can be selected via prefixes like `/mini`.

```bash
# Chat completion (streaming, Ollama format)
curl -N -X POST "http://localhost:9721/api/chat" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "minirag:latest",
    "messages": [{"role": "user", "content": "/mini Who are the key people at Acme Corp?"}],
    "stream": true
  }'
```

--------------------------------

### Run MiniRAG with Specific Lollms and Ollama Models

Source: https://github.com/hkuds/minirag/blob/main/minirag/api/README.md

Starts the MiniRAG server with specific models for Lollms (LLM) and Ollama (embedding). Verify model availability in respective services.

```bash
# Using specific models (ensure they are installed in your ollama instance)
minirag-server --llm-binding lollms --llm-model adrienbrault/nous-hermes2theta-llama3-8b:f16 --embedding-binding lollms --embedding-model nomic-embed-text --embedding-dim 1024
```

--------------------------------

### Configure HuggingFace LLM Backend

Source: https://context7.com/hkuds/minirag/llms.txt

Enable fully offline RAG using HuggingFace Transformers models. This setup is suitable for on-device inference with smaller models. Requires `transformers` library and pre-downloaded models.

```python
from minirag import MiniRAG, QueryParam
from minirag.llm.hf import hf_model_complete, hf_embed
from minirag.utils import EmbeddingFunc
from transformers import AutoModel, AutoTokenizer

EMBEDDING_MODEL = "sentence-transformers/all-MiniLM-L6-v2"
LLM_MODEL = "microsoft/Phi-3.5-mini-instruct"

tokenizer = AutoTokenizer.from_pretrained(EMBEDDING_MODEL)
embed_model = AutoModel.from_pretrained(EMBEDDING_MODEL)

rag = MiniRAG(
    working_dir="./hf_rag",
    llm_model_func=hf_model_complete,
    llm_model_name=LLM_MODEL,
    llm_model_max_token_size=200,    # Keep small for SLMs to avoid OOM
    embedding_func=EmbeddingFunc(
        embedding_dim=384,
        max_token_size=1000,
        func=lambda texts: hf_embed(texts, tokenizer=tokenizer, embed_model=embed_model),
    ),
)

rag.insert("MiniRAG enables on-device RAG using small language models efficiently.")
answer = rag.query(
    "What does MiniRAG enable?",
    param=QueryParam(mode="mini", max_token_for_node_context=200),
)
print(answer)
```

--------------------------------

### Verify MiniRAG Docker Deployment

Source: https://context7.com/hkuds/minirag/llms.txt

After starting the MiniRAG server in a Docker container, use the `/health` endpoint to confirm that the server is running correctly and accessible.

```bash
# Check server is running
curl http://localhost:9721/health
```

--------------------------------

### Create MiniRAG Linux Service File

Source: https://github.com/hkuds/minirag/blob/main/minirag/api/README.md

Configure the systemd service file for the MiniRAG server. Ensure the WorkingDirectory and ExecStart paths are correctly set to your MiniRAG installation.

```text
Description=MiniRAG Ollama Service
WorkingDirectory=<minirag installed directory>
ExecStart=<minirag installed directory>/minirag/api/start_minirag.sh
```

--------------------------------

### Get Ollama Version Info

Source: https://context7.com/hkuds/minirag/llms.txt

Retrieve the current version information of the MiniRAG server, which emulates Ollama endpoints. This is useful for compatibility checks and debugging.

```bash
# Get Ollama version info
curl "http://localhost:9721/api/version"
```

--------------------------------

### Get Available Ollama Models

Source: https://context7.com/hkuds/minirag/llms.txt

Query the `/api/tags` endpoint to retrieve a list of available models in a format compatible with Ollama's tagging system. This helps in identifying the models MiniRAG can emulate.

```bash
# Get available models (Ollama tags format)
curl "http://localhost:9721/api/tags"
```

--------------------------------

### Get Ollama Version

Source: https://context7.com/hkuds/minirag/llms.txt

Retrieves the current version of the Ollama-compatible API server.

```APIDOC
## GET /api/version

### Description
Returns the version information for the Ollama-compatible API server.

### Method
GET

### Endpoint
/api/version

### Response
#### Success Response (200)
- **version** (string) - The current version of the API server.

### Request Example
```bash
curl "http://localhost:9721/api/version"
```

### Response Example
```json
{"version": "0.5.4"}
```
```

--------------------------------

### Configure OpenAI Alike Server Connection

Source: https://github.com/hkuds/minirag/blob/main/minirag/api/README.md

Set these environment variables or use command-line arguments to configure the connection to an OpenAI-alike server. The default connection is https://api.openai.com/v1.

```bash
LLM_BINDING=ollama
LLM_BINDING_HOST
LLM_MODEL
LLM_BINDING_API_KEY
```

--------------------------------

### Index Dataset and Run QA

Source: https://github.com/hkuds/minirag/blob/main/README.md

Executes the Python scripts to index a dataset and then perform Question Answering using the MiniRAG framework. Ensure the dataset is placed in the correct directory.

```bash
python ./reproduce/Step_0_index.py
python ./reproduce/Step_1_QA.py
```

--------------------------------

### Configure OpenAI LLM Backend

Source: https://context7.com/hkuds/minirag/llms.txt

Set up MiniRAG to use OpenAI or compatible APIs. Includes automatic retries for rate limiting and connection errors. Ensure OPENAI_API_KEY and OPENAI_API_BASE environment variables are set.

```python
import os
import asyncio
from minirag import MiniRAG, QueryParam
from minirag.llm.openai import gpt_4o_mini_complete, openai_embed, openai_complete_if_cache
from minirag.utils import EmbeddingFunc

os.environ["OPENAI_API_KEY"] = "sk-..."
os.environ["OPENAI_API_BASE"] = "https://api.openai.com/v1"

rag = MiniRAG(
    working_dir="./openai_rag",
    llm_model_func=gpt_4o_mini_complete,
    llm_model_name="gpt-4o-mini",
    embedding_func=EmbeddingFunc(
        embedding_dim=1536,
        max_token_size=8192,
        func=lambda texts: openai_embed(texts, model="text-embedding-3-small"),
    ),
)

# Direct LLM call (bypassing RAG, useful for testing connectivity)
async def test_llm():
    response = await openai_complete_if_cache(
        model="gpt-4o-mini",
        prompt="Summarize the role of graph databases in RAG systems.",
        system_prompt="You are a helpful AI assistant.",
        base_url="https://api.openai.com/v1",
        api_key=os.environ["OPENAI_API_KEY"],
    )
    print(response)

asyncio.run(test_llm())
# Expected: A concise paragraph about graph databases in RAG systems.
```

--------------------------------

### Initialize MiniRAG with OpenAI Models

Source: https://context7.com/hkuds/minirag/llms.txt

Initialize the MiniRAG engine with OpenAI's GPT-4o-mini completion and embedding functions. Ensure the working directory exists and configure storage backends as needed.

```python
import os
from minirag import MiniRAG, QueryParam
from minirag.llm.openai import gpt_4o_mini_complete, openai_embed
from minirag.utils import EmbeddingFunc

WORKING_DIR = "./my_rag_storage"
os.makedirs(WORKING_DIR, exist_ok=True)

# Initialize with OpenAI GPT-4o-mini + text-embedding-3-small
rag = MiniRAG(
    working_dir=WORKING_DIR,
    llm_model_func=gpt_4o_mini_complete,
    llm_model_name="gpt-4o-mini",
    llm_model_max_token_size=32768,
    llm_model_max_async=4,
    embedding_func=EmbeddingFunc(
        embedding_dim=1536,
        max_token_size=8192,
        func=lambda texts: openai_embed(texts),
    ),
    # Storage backends (defaults: NetworkX + NanoVectorDB + JSON)
    kv_storage="JsonKVStorage",
    vector_storage="NanoVectorDBStorage",
    graph_storage="NetworkXStorage",
    chunk_token_size=1200,
    chunk_overlap_token_size=100,
    enable_llm_cache=True,  # Cache LLM responses for repeated queries
)
# Expected: MiniRAG instance ready to insert and query documents.
# A working directory is created with log file at ./my_rag_storage/minirag.log
```

--------------------------------

### Build and Run MiniRAG Manually with Docker

Source: https://context7.com/hkuds/minirag/llms.txt

Manually build the MiniRAG Docker image and run it as a container. This method allows for detailed configuration via environment variables and volume mounts for persistent storage.

```bash
# Or build and run manually
docker build -t minirag .
docker run -d \
  -p 9721:9721 \
  -v $(pwd)/rag_storage:/app/rag_storage \
  -v $(pwd)/documents:/app/documents \
  -e LLM_BINDING=openai \
  -e LLM_MODEL=gpt-4o-mini \
  -e OPENAI_API_KEY=sk-... \
  -e EMBEDDING_BINDING=openai \
  -e EMBEDDING_MODEL=text-embedding-3-small \
  minirag
```

--------------------------------

### Check MiniRAG Server Health

Source: https://context7.com/hkuds/minirag/llms.txt

Use the health check endpoint to inspect server status, configuration, and the number of indexed files. This is useful for verifying the server is running and understanding its current setup.

```bash
# Health check (returns server config and indexed file list)
curl "http://localhost:9721/health"
```

--------------------------------

### Run MiniRAG Server with Azure OpenAI Backends

Source: https://github.com/hkuds/minirag/blob/main/minirag/api/README.md

Configure the MiniRAG server to use Azure OpenAI services for language models and embeddings. Includes options for authentication and different backend combinations.

```bash
# Run minirag with lollms, GPT-4o-mini  for llm, and text-embedding-3-small for embedding, use openai for both llm and embedding
minirag-server --llm-binding azure_openai --llm-model GPT-4o-mini --embedding-binding openai --embedding-model text-embedding-3-small
```

```bash
# Using an authentication key
minirag-server --llm-binding azure_openai --llm-model GPT-4o-mini --embedding-binding azure_openai --embedding-model text-embedding-3-small --key my-key
```

```bash
# Using lollms for llm and azure_openai for embedding
minirag-server --llm-binding lollms --embedding-binding azure_openai --embedding-model text-embedding-3-small
```

--------------------------------

### Azure OpenAI Server Creation Commands

Source: https://github.com/hkuds/minirag/blob/main/minirag/api/README.md

Use these Azure CLI commands to create an Azure OpenAI resource, including deployments for models and embeddings. Remember to replace placeholders with your specific values.

```bash
# Change the resource group name, location and OpenAI resource name as needed
RESOURCE_GROUP_NAME=MiniRAG
LOCATION=swedencentral
RESOURCE_NAME=MiniRAG-OpenAI

az login
az group create --name $RESOURCE_GROUP_NAME --location $LOCATION
az cognitiveservices account create --name $RESOURCE_NAME --resource-group $RESOURCE_GROUP_NAME  --kind OpenAI --sku S0 --location swedencentral
az cognitiveservices account deployment create --resource-group $RESOURCE_GROUP_NAME  --model-format OpenAI --name $RESOURCE_NAME --deployment-name gpt-4o --model-name gpt-4o --model-version "2024-08-06"  --sku-capacity 100 --sku-name "Standard" 
az cognitiveservices account deployment create --resource-group $RESOURCE_GROUP_NAME  --model-format OpenAI --name $RESOURCE_NAME --deployment-name text-embedding-3-large --model-name text-embedding-3-large --model-version "1"  --sku-capacity 80 --sku-name "Standard"
az cognitiveservices account show --name $RESOURCE_NAME --resource-group $RESOURCE_GROUP_NAME --query "properties.endpoint"
az cognitiveservices account keys list --name $RESOURCE_NAME -g $RESOURCE_GROUP_NAME
```

--------------------------------

### Import Libraries and Set Environment Variables

Source: https://github.com/hkuds/minirag/blob/main/dataset/LiHua-World/evaluation.ipynb

Imports necessary libraries for the evaluation and sets the OpenAI API key. Ensure 'AAA' is replaced with your actual API key.

```python
from huggingface_hub import login
import os
import sys
import csv
from tqdm import trange
from transformers import AutoModel,AutoTokenizer
FILE_PATH = './QA_results_GT.csv'
os.environ["OPENAI_API_KEY"] = AAA
```

--------------------------------

### Configure MiniRAG Server with Environment Variables

Source: https://github.com/hkuds/minirag/blob/main/minirag/api/README.md

Define these environment variables in a .env file to configure the MiniRAG server. Command-line arguments will override these settings.

```env
# Server Configuration
HOST=0.0.0.0
PORT=9721
```

--------------------------------

### Configure Neo4j Storage Backend in MiniRAG

Source: https://context7.com/hkuds/minirag/llms.txt

Set graph_storage to Neo4JStorage and provide connection credentials via environment variables to use Neo4j. Ensure necessary imports and LLM/embedding functions are configured.

```python
import os
from minirag import MiniRAG, QueryParam
from minirag.llm.openai import gpt_4o_mini_complete, openai_embed
from minirag.utils import EmbeddingFunc

os.environ["NEO4J_URI"] = "bolt://localhost:7687"
os.environ["NEO4J_USERNAME"] = "neo4j"
os.environ["NEO4J_PASSWORD"] = "password"

rag = MiniRAG(
    working_dir="./neo4j_rag",
    llm_model_func=gpt_4o_mini_complete,
    llm_model_name="gpt-4o-mini",
    embedding_func=EmbeddingFunc(
        embedding_dim=1536,
        max_token_size=8192,
        func=lambda texts: openai_embed(texts),
    ),
    graph_storage="Neo4JStorage",          # Use Neo4j for graph
    kv_storage="JsonKVStorage",            # Keep JSON for KV
    vector_storage="NanoVectorDBStorage",  # Keep NanoVectorDB for vectors
)

rag.insert("Graph databases store data as nodes and relationships, enabling rich traversals.")
answer = rag.query("What are graph databases good for?", param=QueryParam(mode="mini"))
print(answer)
```

--------------------------------

### Run MiniRAG with Lollms LLM and OpenAI Embedding

Source: https://github.com/hkuds/minirag/blob/main/minirag/api/README.md

Launches the MiniRAG server using Lollms for the LLM and OpenAI for embeddings. Configure the OpenAI embedding model and ensure API keys are set if necessary.

```bash
# Using lollms for llm and openai for embedding
minirag-server --llm-binding lollms --embedding-binding openai --embedding-model text-embedding-3-small
```

--------------------------------

### Configure Ollama LLM Backend

Source: https://context7.com/hkuds/minirag/llms.txt

Integrate MiniRAG with a local Ollama server for LLM and embedding tasks. Supports automatic retries for connection and rate-limit errors. Specify the Ollama host and model details.

```python
from minirag import MiniRAG, QueryParam
from minirag.llm.ollama import ollama_model_complete, ollama_embed
from minirag.utils import EmbeddingFunc

rag = MiniRAG(
    working_dir="./ollama_rag",
    llm_model_func=ollama_model_complete,
    llm_model_name="phi3.5:latest",           # Any model installed in Ollama
    llm_model_kwargs={
        "host": "http://localhost:11434",
        "timeout": 120,
        "options": {"num_ctx": 4096},         # Ollama context window
    },
    embedding_func=EmbeddingFunc(
        embedding_dim=1024,
        max_token_size=8192,
        func=lambda texts: ollama_embed(
            texts,
            embed_model="bge-m3:latest",
            host="http://localhost:11434",
        ),
    ),
)

rag.insert("The Eiffel Tower is located in Paris, France. It was built in 1889.")
answer = rag.query("Where is the Eiffel Tower?", param=QueryParam(mode="mini"))
print(answer)
# Expected: "The Eiffel Tower is located in Paris, France."
```

--------------------------------

### Configure Ollama Server Connection

Source: https://github.com/hkuds/minirag/blob/main/minirag/api/README.md

Set these environment variables or use command-line arguments to configure the connection to an Ollama server. The default connection is http://localhost:11434.

```bash
LLM_BINDING=ollama
LLM_BINDING_HOST
LLM_MODEL
```

--------------------------------

### Run QA Evaluation on LiHua-World Dataset

Source: https://context7.com/hkuds/minirag/llms.txt

Execute the `Step_1_QA.py` script to perform question-answering evaluation on the LiHua-World dataset. This script saves results to a CSV file and automatically resumes if interrupted.

```python
# Step 1: Run Q&A evaluation and save results to CSV
python ./reproduce/Step_1_QA.py \
  --model PHI \
  --workingdir ./LiHua-World \
  --querypath ./dataset/LiHua-World/qa/query_set.csv \
  --outputpath ./logs/phi_results.csv
```

--------------------------------

### POST /query

Source: https://context7.com/hkuds/minirag/llms.txt

Query the RAG system via HTTP. Send a natural language question to the running MiniRAG server and receive a generated answer.

```APIDOC
## POST /query

Query the RAG system via HTTP. Send a natural language question to the running MiniRAG server and receive a generated answer.

### Method
POST

### Endpoint
/query

### Request Body
- **query** (string) - Required - The natural language question to ask.
- **mode** (string) - Optional - The query mode (e.g., "mini", "naive", "light").
- **only_need_context** (boolean) - Optional - If true, skips LLM generation and returns raw context.
- **stream** (boolean) - Optional - If true, enables streaming of the response.

### Request Example
```bash
# Basic query (mini mode)
curl -X POST "http://localhost:9721/query" \
  -H "Content-Type: application/json" \
  -d '{"query": "Who works at Acme Corp?", "mode": "mini"}'

# Query with only_need_context (skip LLM generation, return raw context)
curl -X POST "http://localhost:9721/query" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: my-secret-api-key" \
  -d '{"query": "What is the founding date?", "mode": "naive", "only_need_context": true}'
```

### Response
#### Success Response (200)
- **response** (string) - The generated answer or context.

#### Response Example
```json
{"response": "Alice and Bob both work at Acme Corp..."}
```

### Streaming Response Example
```bash
# Streaming query
curl -X POST "http://localhost:9721/query/stream" \
  -H "Content-Type: application/json" \
  -d '{"query": "Explain the AI team structure", "mode": "light", "stream": true}'
```

#### Streaming Response Example Output
```json
{"response": "The AI "}
{"response": "team..."}
```
```

--------------------------------

### Async Document Insertion

Source: https://context7.com/hkuds/minirag/llms.txt

Indexes text files asynchronously from a specified directory. Ensure the 'rag' object is initialized and necessary imports are present.

```python
import asyncio
import os

async def index_files(directory: str):
    for fname in os.listdir(directory):
        if fname.endswith(".txt"):
            with open(os.path.join(directory, fname)) as f:
                await rag.ainsert(f.read())

asyncio.run(index_files("./documents"))
```

--------------------------------

### Query MiniRAG Server via POST /query

Source: https://context7.com/hkuds/minirag/llms.txt

Send natural language questions to the MiniRAG server to receive generated answers. Supports different query modes and context retrieval options.

```bash
# Basic query (mini mode)
curl -X POST "http://localhost:9721/query" \
  -H "Content-Type: application/json" \
  -d '{"query": "Who works at Acme Corp?", "mode": "mini"}'
# Response: {"response": "Alice and Bob both work at Acme Corp..."}
```

```bash
# Query with only_need_context (skip LLM generation, return raw context)
curl -X POST "http://localhost:9721/query" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: my-secret-api-key" \
  -d '{"query": "What is the founding date?", "mode": "naive", "only_need_context": true}'
```

```bash
# Streaming query
curl -X POST "http://localhost:9721/query/stream" \
  -H "Content-Type: application/json" \
  -d '{"query": "Explain the AI team structure", "mode": "light", "stream": true}'
# Response: newline-delimited JSON chunks: {"response": "The AI "} \
{"response": "team..."} \

```

--------------------------------

### Check Server Health

Source: https://github.com/hkuds/minirag/blob/main/minirag/api/README.md

Verify the health and configuration status of the MiniRAG server.

```bash
curl "http://localhost:9721/health"
```

--------------------------------

### Index LiHua-World Dataset

Source: https://context7.com/hkuds/minirag/llms.txt

Use the `Step_0_index.py` script to index the LiHua-World chat dataset. Specify the desired model, working directory, and data path. This is the first step in reproducing experiments.

```python
# Step 0: Index the LiHua-World chat dataset with a specific model
python ./reproduce/Step_0_index.py \
  --model PHI \
  --workingdir ./LiHua-World \
  --datapath ./dataset/LiHua-World/data/
```

--------------------------------

### Query OpenAI GPT-4o Model

Source: https://github.com/hkuds/minirag/blob/main/dataset/LiHua-World/evaluation.ipynb

Iterates through the loaded data, formats the prompt for each entry, and sends it to the OpenAI GPT-4o model. Results are stored in 'chat_list'.

```python
#openai
from openai import OpenAI
from tqdm import trange
chatbot = OpenAI()
chat_list = []
for i in trange(filelength):
    p = PROMPT.format(question = QUESTION_LIST[i], ga = GA_LIST[i], naive = naiveanswer_LIST[i], light = lightraganswer_LIST[i], mini = minianswer_LIST[i])
    chat_completion = chatbot.chat.completions.create(
        messages=[
            {
                "role": "system",
                "content":p,
            },
        ],
        model="gpt-4o",
    )
    chat_list.append(chat_completion.choices[0].message.content.strip())
```

--------------------------------

### QueryParam Configuration

Source: https://context7.com/hkuds/minirag/llms.txt

Configures detailed retrieval and generation parameters for queries. Use 'only_need_context=True' to retrieve raw context without LLM generation, useful for debugging.

```python
from minirag.base import QueryParam

param = QueryParam(
    mode="mini",            # "mini" | "light" | "naive"
    top_k=60,               # Number of entities/relationships to retrieve
    only_need_context=True, # Return raw context without LLM generation
    only_need_prompt=False, # Return the assembled prompt string only
    stream=False,           # Enable streaming LLM responses
    max_token_for_text_unit=4000,       # Token budget for raw text chunks
    max_token_for_global_context=4000,  # Token budget for relationship context
    max_token_for_local_context=4000,   # Token budget for entity context
    max_token_for_node_context=500,     # Per-node token limit (important for SLMs)
    response_type="Single Paragraph",  # Hint for LLM output format
    conversation_history=[             # Multi-turn chat history
        {"role": "user", "content": "What is MiniRAG?"},
        {"role": "assistant", "content": "MiniRAG is a lightweight RAG framework."},
    ],
    history_turns=3,        # Number of history turns to include
)

# Retrieve only context without calling the LLM (useful for debugging)
context = rag.query("Who founded Acme Corp?", param=QueryParam(mode="mini", only_need_context=True))
print(context)  # Returns the assembled context string passed to the LLM
```

--------------------------------

### Upload Batch Files

Source: https://github.com/hkuds/minirag/blob/main/minirag/api/README.md

Upload multiple files simultaneously to the RAG system using the /documents/batch endpoint.

```bash
curl -X POST "http://localhost:9721/documents/batch" \
    -F "files=@/path/to/doc1.txt" \
    -F "files=@/path/to/doc2.txt"
```

--------------------------------

### Configure Azure OpenAI Server Connection

Source: https://github.com/hkuds/minirag/blob/main/minirag/api/README.md

Set these environment variables using the output from the Azure CLI commands to configure the connection to your Azure OpenAI service.

```env
LLM_BINDING=azure_openai
LLM_BINDING_HOST=endpoint_of_azure_ai
LLM_MODEL=model_name_of_azure_ai
LLM_BINDING_API_KEY=api_key_of_azure_ai
```

--------------------------------

### List Available Models (Ollama Tags)

Source: https://context7.com/hkuds/minirag/llms.txt

Retrieves a list of models available on the server, formatted similarly to the Ollama `/api/tags` endpoint.

```APIDOC
## GET /api/tags

### Description
Returns a list of available models on the server, mimicking the Ollama API's `/api/tags` endpoint.

### Method
GET

### Endpoint
/api/tags

### Response
#### Success Response (200)
- **models** (array of objects) - A list of model objects, each containing details like name and size.
  - **name** (string) - The name of the model.
  - **model** (string) - The model identifier.
  - **size** (integer) - The size of the model in bytes.

### Request Example
```bash
curl "http://localhost:9721/api/tags"
```

### Response Example
```json
{"models": [{"name": "minirag:latest", "model": "minirag:latest", "size": 7365960935, ...}]}
```
```

--------------------------------

### Query DeepSeek Chat Model

Source: https://github.com/hkuds/minirag/blob/main/dataset/LiHua-World/evaluation.ipynb

Iterates through the loaded data, formats the prompt for each entry, and sends it to the DeepSeek chat model. Results are stored in 'chat_list'. Requires 'My_deepseek_key' to be set.

```python
#deepseek
from openai import OpenAI
chatbot = OpenAI(api_key=My_deepseek_key, base_url="https://api.deepseek.com")

chat_list = []
for i in range(filelength):
    p = PROMPT.format(question = QUESTION_LIST[i], ga = GA_LIST[i], naive = naiveanswer_LIST[i], light = lightraganswer_LIST[i], mini = minianswer_LIST[i])
    chat_completion = chatbot.chat.completions.create(
        messages=[
            {
                "role": "system",
                "content":p,
            },
            

        ],
        model="deepseek-chat",
        stream = False
    )
    chat_list.append(chat_completion.choices[0].message.content.strip())
```

--------------------------------

### Load Data from CSV

Source: https://github.com/hkuds/minirag/blob/main/dataset/LiHua-World/evaluation.ipynb

Reads question-answer data from a CSV file into separate lists. This prepares the data for prompt generation.

```python
ANA_FILE_PATH = './mthp_output.csv'

naiveanswer_LIST = []
lightraganswer_LIST = []
minianswer_LIST = []
QUESTION_LIST = []
GA_LIST = []
filelength = 0
with open(ANA_FILE_PATH, mode='r', encoding='utf-8') as question_file:
    reader = csv.DictReader(question_file)
    for row in reader:
        QUESTION_LIST.append(row['Question'])
        GA_LIST.append(row['Gold Answer'])
        naiveanswer_LIST.append(row['naive'])
        lightraganswer_LIST.append(row['lightrag'])
        minianswer_LIST.append(row['minirag'])
        filelength = filelength+1
```

--------------------------------

### Define Prompt Template

Source: https://github.com/hkuds/minirag/blob/main/dataset/LiHua-World/evaluation.ipynb

A template for constructing prompts to be sent to language models. It includes instructions for scoring answers based on correctness and relevance.

```python
PROMPT = """
Now, I'll give you a question, a gold answer to this question, and three answers provided by different students.

Determine the answer according to the following rules:
If the answer is correct, get 1 point.
If the answer is irrelevant to the question, it will receive 0 points.
If the answer is incorrect, get -1 point.

Return your answer in JSON mode.

For example:

Question:
When does Li Hua arrive to the city?

Gold Answer:
20260105

Answer1: LiHua arrived on the afternoon of January 5th
Answer2: Sorry, there is no information about LiHua's arrival in the information you provided
Answer3: There is no accurate answer in the information you provided, but according to the first information found, LiHua arrived on April 17th

output:
{{
"Score1": 1,
"Score2": 0,
"Score3": -1,
}}



Real data:

Question:
{question}
Gold Answer:
{ga}

Answer1: {naive}
Answer2: {light}
Answer3: {mini}

output:

"""
```

--------------------------------

### Upload Single File Document

Source: https://github.com/hkuds/minirag/blob/main/minirag/api/README.md

Upload a single file to the RAG system via the /documents/file endpoint. Supports adding an optional description.

```bash
curl -X POST "http://localhost:9721/documents/file" \
    -F "file=@/path/to/your/document.txt" \
    -F "description=Optional description"
```

--------------------------------

### Handle Ollama Chat Completion

Source: https://github.com/hkuds/minirag/blob/main/minirag/api/README.md

Send chat completion requests to the Ollama emulation endpoint, supporting streaming responses.

```bash
curl -N -X POST http://localhost:9721/api/chat -H "Content-Type: application/json" -d 
  '{"model":"minirag:latest","messages":[{"role":"user","content":"猪八戒是谁"}],"stream":true}'
```

--------------------------------

### Insert Text Document

Source: https://github.com/hkuds/minirag/blob/main/minirag/api/README.md

Add text content directly to the RAG system using the /documents/text endpoint. An optional description can be provided.

```bash
curl -X POST "http://localhost:9721/documents/text" \
    -H "Content-Type: application/json" \
    -d '{"text": "Your text content here", "description": "Optional description"}'
```

--------------------------------

### List Graph Labels in MiniRAG

Source: https://context7.com/hkuds/minirag/llms.txt

Retrieve a list of all entity and relationship labels present in the knowledge graph. This helps in understanding the types of data the graph contains.

```bash
# List all entity/relationship labels in the graph
curl "http://localhost:9721/graph/label/list"
```

--------------------------------

### Insert Documents using MiniRAG with Ollama

Source: https://context7.com/hkuds/minirag/llms.txt

Index single or multiple documents into the MiniRAG graph using Ollama models for completion and embeddings. The `insert` method handles deduplication and storage automatically.

```python
import os
from minirag import MiniRAG, QueryParam
from minirag.llm.ollama import ollama_model_complete, ollama_embed
from minirag.utils import EmbeddingFunc

rag = MiniRAG(
    working_dir="./rag_storage",
    llm_model_func=ollama_model_complete,
    llm_model_name="mistral-nemo:latest",
    embedding_func=EmbeddingFunc(
        embedding_dim=1024,
        max_token_size=8192,
        func=lambda texts: ollama_embed(texts, embed_model="bge-m3:latest"),
    ),
)

# Insert a single string
rag.insert("Alice is a software engineer at Acme Corp. She works with Bob on the AI team.")

# Insert multiple documents (duplicates are automatically filtered)
docs = [
    "Bob is a data scientist at Acme Corp.",
    "Acme Corp was founded in 2010 in San Francisco.",
]
rag.insert(docs)

```

--------------------------------

### Chat Completion (Ollama Compatible)

Source: https://context7.com/hkuds/minirag/llms.txt

Provides chat completions by interacting with the MiniRAG model, supporting streaming responses and Ollama-compatible formatting.

```APIDOC
## POST /api/chat

### Description
Emulates the Ollama `/api/chat` endpoint to provide chat completions. Supports streaming responses and query modes specified by message prefixes.

### Method
POST

### Endpoint
/api/chat

### Parameters
#### Request Body
- **model** (string) - Required - The model to use (e.g., "minirag:latest").
- **messages** (array of objects) - Required - An array of message objects, each with a `role` (user/assistant) and `content`.
  - **role** (string) - The role of the message sender.
  - **content** (string) - The message content. Can be prefixed with `/mini`, `/light`, or `/naive` to select query mode.
- **stream** (boolean) - Optional - If true, responses are streamed as ndjson.

### Request Example
```json
{
  "model": "minirag:latest",
  "messages": [{"role": "user", "content": "/mini Who are the key people at Acme Corp?"}],
  "stream": true
}
```

### Response
#### Success Response (200)
- **(ndjson stream)** - If `stream` is true, responses are sent as newline-delimited JSON objects. Each object contains model information, timestamps, message content, and a `done` flag.
- **(JSON object)** - If `stream` is false, a single JSON object with the chat completion details.

### Response Example (Streaming)
```
{"model":"minirag:latest","created_at":"...","message":{"role":"assistant","content":"Alice "},"done":false}
{"model":"minirag:latest","created_at":"...","message":{"role":"assistant","content":"and Bob"},"done":false}
{"model":"minirag:latest","created_at":"...","done":true,"total_duration":1234567890,...}
```
```

--------------------------------

### Synchronous and Asynchronous Querying

Source: https://context7.com/hkuds/minirag/llms.txt

Queries the knowledge graph using 'query' (sync) or 'aquery' (async). The 'mode' parameter in QueryParam selects the retrieval strategy: 'mini' for topology-enhanced traversal, 'light' for hybrid retrieval, and 'naive' for pure vector search. Supports conversation history for chat-like interactions.

```python
from minirag import MiniRAG, QueryParam

# Assuming `rag` is already initialized and documents are inserted (see above)

# --- Mini mode (graph topology-enhanced, recommended for small models) ---
answer = rag.query(
    "Who works at Acme Corp?",
    param=QueryParam(
        mode="mini",
        top_k=60,
        max_token_for_node_context=500,
        response_type="Multiple Paragraphs",
    ),
)
print(answer)
```

```python
# --- Naive mode (pure vector similarity, fastest) ---
answer_naive = rag.query(
    "When was Acme Corp founded?",
    param=QueryParam(mode="naive", top_k=10),
)
print(answer_naive)
```

```python
# --- Light mode (hybrid graph + vector) ---
answer_light = rag.query(
    "What does the AI team do?",
    param=QueryParam(mode="light", top_k=60),
)

```

```python
# --- Async query with conversation history ---
import asyncio
async def chat_session():
    history = [
        {"role": "user", "content": "Who is Alice?"},
        {"role": "assistant", "content": "Alice is a software engineer at Acme Corp."},
    ]
    response = await rag.aquery(
        "What team does she work on?",
        param=QueryParam(
            mode="mini",
            conversation_history=history,
            history_turns=3,
        ),
    )
    return response

print(asyncio.run(chat_session()))
```