Fin-RAG

一个纯 Python 的金融问答 RAG 项目，全部能力通过命令行接口（cli.py）暴露。检索采用 BM25 + Faiss 混合召回，再用 BGE-Reranker 重排，最后交给 OpenAI 兼容的 LLM（默认 DeepSeek）生成答案。

• 无前端、无 Web 服务，纯 Python + CLI
• LLM 密钥从环境变量读取，不写死在源码里
• 配置集中在 config.py
• 在线检索逻辑拆成 resources / retrieval / generation / storage
• 离线脚本与交互式问答共享同一套路径和模型配置
• row_id / chunk_id / docs.db 契约已统一
• Python 依赖以 pyproject.toml 为唯一来源，由 uv 管理

Project Layout

E:/Fin-RAG
|- cli.py                         # 唯一 CLI 入口（parse / index / batch / query / chat / check）
|- config.py                      # 集中配置
|- pyproject.toml                 # uv 依赖定义
|- .python-version                # uv 默认 Python 版本
|- app/
|  |- index_contract.py           # chunk_id / row_id 元数据契约
|  |- resources.py                # 模型与索引生命周期
|  |- retrieval.py                # 混合检索与重排
|  |- generation.py               # LLM 生成与降级逻辑
|  |- storage.py                  # SQLite 契约与读取
|  |- schemas.py                  # Source 数据模型（frozen dataclass）
|- parse_and_chunk.py             # 文档解析与切块
|- build_index.py                 # 构建 BM25 / Faiss 索引并重建 docs.db
|- run_retrieval.py               # 批量离线检索
|- tests/                         # 单元测试
|- artifacts/
|  |- chunks/                     # chunks.jsonl
|  |- indexes/                    # docs.db / faiss.index / bm25.index
|  |- metadata/                   # metadata 文件
|- outputs/                       # 离线结果文件

Requirements

• uv
• 可访问模型下载源，或提前把模型缓存到本地

Environment Setup

本地 CPU 默认环境：

uv sync

云端 / GPU 扩展环境：

uv sync --group yun --no-default-groups

说明：

• 默认 uv sync 安装 cpu 依赖组（含 faiss-cpu）
• yun 组用于云端或 GPU 场景，含 faiss-gpu、paddleocr、paddlepaddle-gpu 等
• requirements.txt 与 requirements-yun.txt 仅作历史参考，pyproject.toml 才是依赖来源

复制环境变量模板并填入自己的密钥：

Copy-Item .env.example .env.local

项目不会自动加载 .env.local，请在运行前手动设置关键环境变量：

$env:LLM_API_KEY="your-api-key"
$env:LLM_BASE_URL="https://api.deepseek.com"

CLI

所有功能通过 cli.py 调用，统一入口：

uv run python cli.py <command> [args]

Command	说明
parse	解析 data/ 下的文档，输出 artifacts/chunks/chunks.jsonl
index	构建 BM25 / Faiss 索引并重建 docs.db
batch	对测试集批量检索，输出 outputs/result.json
query "<问题>"	单次问答（检索 + 重排 + 生成），打印答案与来源
chat	交互式问答 REPL，模型只加载一次
check	检查索引产物与配置是否就绪

查看帮助：

uv run python cli.py --help
uv run python cli.py query --help

Build Retrieval Artifacts

如果还没有索引文件，先准备原始文档并构建产物。

1. 将原始文档放入 data/
2. 切块：uv run python cli.py parse（默认输出 artifacts/chunks/chunks.jsonl）
3. 构建索引：uv run python cli.py index，默认输出：
   • artifacts/indexes/docs.db
   • artifacts/indexes/faiss.index
   • artifacts/indexes/bm25.index
   • artifacts/metadata/chunks.metadata.json
4. 检查就绪状态：uv run python cli.py check

这些命令都会读取 config.py 中定义的默认路径，以及你在环境变量里覆盖的值。

Ask Questions

单次问答：

uv run python cli.py query "公司2023年的净利润是多少？"

交互式问答（模型只加载一次，适合连续提问）：

uv run python cli.py chat

若未配置 LLM_API_KEY，query / chat 仍可运行，会降级为返回检索片段预览。

Offline Evaluation

对测试集（默认 test_100.xlsx）批量检索并写出结果：

uv run python cli.py batch

默认输出：outputs/result.json

Run Tests

uv run python -m unittest discover -s tests -p "test_*.py"