File size: 4,293 Bytes
4f8feb6
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
# Configuration

Every setting is an environment variable, read once at startup by `lumen_rag/config.py` (a `.env`
file in the working directory is loaded too; [`.env.example`](../.env.example) lists them with
comments). Everything new is **opt-in**: leaving a variable unset keeps the default behaviour.
Back to the [README](../README.md).

## Models and providers

| Variable | Default | What it does |
|---|---|---|
| `LUMEN_EMBEDDER` | `auto` | `hashing` (offline, no model), `fastembed` (local `BAAI/bge-small-en-v1.5`, needs the `embed` extra), `openai`, or `auto` (OpenAI when `OPENAI_API_KEY` is set, else hashing). Re-ingest after changing it. |
| `LUMEN_FASTEMBED_MODEL` | `BAAI/bge-small-en-v1.5` | Model for `LUMEN_EMBEDDER=fastembed`. |
| `OPENAI_API_KEY` | β€” | Enables hosted embeddings (`auto`/`openai`) and LLM-generated answers. Without it answers are extractive. |
| `OPENAI_BASE_URL` | β€” | Any OpenAI-compatible endpoint. |
| `EMBED_MODEL` | `text-embedding-3-small` | OpenAI embedding model. |
| `CHAT_MODEL` | `gpt-4o-mini` | OpenAI chat model for generated answers. |

## Retrieval

| Variable | Default | What it does |
|---|---|---|
| `LUMEN_RERANKER` | β€” | Cross-encoder for second-stage reranking, e.g. `BAAI/bge-reranker-base` (`rerank` extra). |
| `LUMEN_RERANK_POOL` | `4` | Candidates fed to the reranker: `k Γ— this`. |
| `LUMEN_CONTEXTUAL` | β€” | `1` embeds and BM25-indexes each chunk with a document/section header. Helps keyword search; shifts abstention scores ([benchmarks](benchmarks.md#contextual-chunk-headers)). |
| `LUMEN_DECOMPOSE` | β€” | `1` splits compound questions into sub-queries. Measured no gain ([benchmarks](benchmarks.md)). |
| `LUMEN_DOCLING` | β€” | `1` parses PDF/DOCX/PPTX/HTML with Docling (`docling` extra). |

## Abstention

Calibrated values for bge-small in vector mode are in [abstention](abstention.md); recalibrate for
another embedder or corpus with `scripts/benchmark.py --abstain`.

| Variable | Default | What it does |
|---|---|---|
| `LUMEN_ABSTAIN_THRESHOLD` | β€” | Refuse when retrieval confidence is below this (e.g. `0.66`). |
| `LUMEN_READER` | β€” | Extractive answerability reader, e.g. `onnx-community/roberta-base-squad2-ONNX` (`reader` extra). |
| `LUMEN_READER_THRESHOLD` | `0` | Refuse when the reader's answerability is below this (e.g. `-3.5`). |
| `LUMEN_READER_FILE` | `onnx/model_quantized.onnx` | ONNX weights file inside the reader repository. |
| `LUMEN_READER_ANSWERS` | β€” | `1` answers offline with the reader's sentence instead of the top passages. |

## Storage

| Variable | Default | What it does |
|---|---|---|
| `LUMEN_STORE` | `memory` | `memory` (files in `LUMEN_INDEX_DIR`) or `pgvector` (`pgvector` extra). |
| `LUMEN_INDEX_DIR` | `.lumen_index` | Where the in-memory store is persisted. |
| `LUMEN_PG_DSN` | β€” | `postgresql://…` connection string for `pgvector`. |
| `LUMEN_PG_TABLE` | `lumen_chunks` | Table for `pgvector`. |
| `LUMEN_NAMESPACE` | `default` | Isolates collections on a shared `pgvector` table. |

## Server and observability

| Variable | Default | What it does |
|---|---|---|
| `ADMIN_KEY` | β€” | When set, `/ingest`, `/ingest/upload`, `/ingest/sample` and `/reset` require it in the `X-Admin-Key` header (401 otherwise). Unset: open locally, refused with 403 when `SPACE_ID` is set (Hugging Face Spaces). `GET /health` reports `ingest_locked`. |
| `LUMEN_SEED_SAMPLE` | on if `SPACE_ID` is set | `1` loads the bundled sample corpus at startup when the index is empty. |
| `LUMEN_MAX_UPLOAD_BYTES` | `10485760` | Per-file cap for `/ingest/upload` (413 past it). |
| `LUMEN_MAX_UPLOAD_FILES` | `20` | Files per `/ingest/upload` request (413 past it). |
| `LUMEN_MIN_CHUNK_SIZE` / `LUMEN_MAX_CHUNK_SIZE` | `20` / `1000` | Allowed `chunk_size` (words) on the ingest routes; `overlap` must be `0..chunk_size-1` (422 otherwise). |
| `LUMEN_TRACING` | β€” | `console` or `otlp` OpenTelemetry export (`tracing` extra). |
| `LUMEN_TRACE_CONTENT` | β€” | `1` also records question and answer text on spans (off by default for privacy). |

## Optional extras

`pip install -e ".[<extra>]"`: `embed`, `reader`, `rerank`, `pdf`, `docx`, `loaders`, `docling`,
`openai`, `answer-eval`, `pgvector`, `tracing`, `dev`. None of them pulls in torch; models run on ONNX.