FlashRAG

Use this skill when a task asks for help with FlashRAG, the Python toolkit for Retrieval-Augmented Generation research, benchmark reproduction, custom RAG pipelines, retriever/index setup, generator/refiner configuration, evaluation, or the FlashRAG UI.

Start Here

• Check staleness first: Read repo-provenance.md before using this skill with a local checkout; refresh the skill if the commit, dirty state, package version, or public evidence paths changed.
• Install minimally: Public package name is flashrag-dev; install with pip install flashrag-dev --pre or install a checkout with pip install -e . when editing the repo.
• Verify import: Run python -c "import flashrag, importlib.metadata as md; print(md.version('flashrag_dev'))" after install. If metadata lookup fails, try flashrag-dev because Python tools normalize underscores and hyphens differently.
• Check optional dependencies: Run check_flashrag_environment.py before loading models, building indexes, or launching services.
• Read troubleshooting: Use troubleshooting.md for cross-cutting install/import, optional dependency, data, hardware, credential, and stale-skill failures.

Route by Task

• Config, dataset, corpus schemas, and safe input checks: Use data-and-config for Config, Dataset, YAML/dict override behavior, JSONL schemas, and validation helpers.
• Corpus preparation, retrieval, reranking, and index building: Use retrieval-and-indexing for BM25s/Pyserini, dense Faiss, CLIP/multimodal retrieval, Serper/web retrieval, rerankers, and multi-retriever fusion.
• Generators, prompt templates, refiners, compressors, and judgers: Use generation-and-refinement for HF/FastChat/vLLM/OpenAI generation, multimodal generators, PromptTemplate, refiners, and judgers.
• End-to-end pipelines and method reproduction: Use pipelines-and-methods for quick-start demos, SequentialPipeline, active/branching/adaptive/reasoning RAG, multimodal RAG, and experiment-runner planning.
• Evaluation metrics and WebUI: Use evaluation-and-webui for Evaluator, metrics, prediction parsing, WebUI chat/evaluate setup, and service troubleshooting.

Capability Map

Read capability-map.md when a request spans multiple FlashRAG areas or when you need to choose the right sub-skill owner for a source artifact, helper, or failure mode.

Safe Workflow Defaults

1. Validate config/data with the data/config helper before running retrieval or pipelines.
2. For retrieval, validate corpus JSONL and build command arguments before starting index construction.
3. For generation or methods, inspect config keys and optional dependency requirements before loading models or contacting APIs.
4. Treat benchmark reproduction, model downloads, vLLM serving, WebUI launch, and large index builds as explicit user-approved runtime actions.
5. Keep API keys, model paths, dataset locations, and machine-specific paths out of generated notes unless the user explicitly asks for local operational commands.

Optional Dependency Surface

FlashRAG core workflows commonly need torch, transformers, PyYAML, numpy, tqdm, and related runtime packages. Optional workflows add more constraints:

• Dense retrieval: faiss plus embedding model packages.
• BM25 retrieval: bm25s for lightweight CPU use, or pyserini plus Java for Lucene-backed indexes.
• Generator acceleration: vllm requires a compatible PyTorch/CUDA stack.
• OpenAI generation or LLMJudge-style evaluation: openai, tiktoken, and credentials.
• Multimodal RAG: image packages and model-specific utilities such as Qwen-VL helpers.
• WebUI: service/UI dependencies such as Streamlit or Gradio plus valid model/index configs.

When Editing a FlashRAG Checkout

• Prefer focused changes in the owning module and update nearby docs/examples when public behavior changes.
• Use package source and installed-package inspection to confirm APIs; docs/examples show intended workflows but source resolves defaults and edge behavior.
• If modifying public config keys, retriever/generator factories, pipeline names, or metric names, refresh this skill after the code change so routing and references stay aligned.