一个面向生产的 RAG Agent 服务，支持多检索器集成（BM25/FAISS/标题摘要）、可插拔重排器（Hugging Face/FlagEmbedding），并提供 REST API 与日志/反馈管理。

2025/04/20 → 2025/08/13 🔥 We released and iterated the FinSage paper on arXiv (arXiv:2504.14493), from v1 (2025/04/20) to v4 (2025/08/13).

2025/08/11 🎉 Our paper was accepted to ACM CIKM 2025 (Applied Research Track) (notification date).

• Usage
• 配置
• API
• 生产环境部署
  • 开启API服务器
  • 关闭服务
  • 查看日志
  • 模块测试
• Results
• Citation

“Avg Num Retrieved" represents the average number of chunks in the retrieved set. Recall, Precision, and F1 scores are calculated based on the relevant chunks retrieved. The bold denotes the best Recall, Precision and F1 produced from FinSage.

graph TD
  A[Client / SDK]
  B[Flask API / Gunicorn]
  C[ChatService]
  D[RAGManager]
  D1[BM25]
  D2[FAISS]
  D3[Chroma Title Summary]
  E[Reranker: HF FlagEmbedding]
  F[LLM: OpenAI compatible]
  G[SQLite feedback.db]
  H[Persist: bm25_index]
  I[Persist: chroma]
  J[Persist: ts_chroma]

  A --> B
  B --> C
  C --> D
  D --> D1
  D --> D2
  D --> D3
  C --> E
  C --> F
  C --> G
  D1 --> H
  D2 --> I
  D3 --> J

• 快速开始
  1. 准备配置：复制 config/example.yaml 为 config/production.yaml，或设置环境变量 CONFIG_PATH 指向你的配置文件。
  2. 启动外部LLM服务：确保有一个兼容 OpenAI API 的推理服务（如 vLLM），并在配置中设置 llm_base_url 和 llm_model_name。
  3. 启动API服务：

cd src
gunicorn -w 1 -b 0.0.0.0:6005 --timeout 180 server:app

4. 调用接口：见下方 API 小节。

• Reranker 权重
  • 将你的重排模型发布到 Hugging Face，并在配置中将 rerank_model 设置为仓库ID（或本地路径）。例如：BAAI/bge-reranker-v2-gemma。
  • 通过 rerank_topk 控制最终参与答案生成的 chunk 数量。

服务默认从环境变量 CONFIG_PATH 指向的文件加载配置；若未设置，则在 src/server.py 中默认读取 ../config/production.yaml。

persist_directory: "/path/to/database_root"

embeddings_model_name: "BAAI/bge-m3"

llm_model_name: "Qwen/Qwen2.5-72B-Instruct-AWQ"
llm_base_url: "http://127.0.0.1:8000/v1"  # 需要外部OpenAI兼容推理服务
llm_api_key: "EMPTY"

rerank_model: "BAAI/bge-reranker-v2-gemma"  # 可填写你的HF仓库ID
rerank_topk: 5

frequent_qa_directory: "/path/to/frequentQA.db"         # 可选
qa_table_directory: "/path/to/qa_table.db"               # 可选
qa_table_persist_directory: "/path/to/qa_chroma_dir"     # 可选

log_level: "INFO"  # DEBUG/INFO/WARNING/ERROR/CRITICAL
bearer_token: "<your_token>"  # 或通过环境变量 BEARER_TOKEN 提供

注意：

• persist_directory 下应包含已构建的检索索引：chroma/、ts_chroma/ 和 bm25_index/<collection_name>/。
• 代码当前默认注册集合为 {'lotus': 10}（见 src/server.py）；如需变更集合或 topk，请在代码中修改或扩展为配置项。

• 健康检查

curl http://127.0.0.1:6005/health

• Token校验

curl -H "Authorization: Bearer <your_token>" http://127.0.0.1:6005/api/check_token | cat

• 同步问答

curl -X POST http://127.0.0.1:6005/api_chat \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{"question":"你好","session_id":"test-session"}' | cat

• 流式问答（SSE）

curl -N -X POST http://127.0.0.1:6005/api_chat_stream \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{"question":"你好","session_id":"test-session"}'

1. 进入或创建screen会话（可选） screen -S gunicorn / screen -r gunicorn
2. 启动服务（从项目根执行）：cd src && gunicorn -w 1 -b 0.0.0.0:6005 --timeout 180 server:app
3. 使用 Ctrl-a 和 d 从会话中分离

1. lsof -i :6005 找到app的PID
2. kill [pid]

1. ps aux | grep vllm 找到和启动vllm对应的进程
2. kill -2 [pid] 发送SIGINT，完成cleanup

1. src/server.log
2. 备份目录（收到退出信号或进程结束时会尝试拷贝）：/root/autodl-tmp/server_logs

请参考你部署的 OpenAI 兼容服务（如 vLLM）自身的日志路径与说明。

• log/error: 用户反馈问题和session log
• log/feedback.db: 用户反馈评分和session log

cd src
python -m utils.ensembleRetriever

FinSage 通过多路径稀疏-稠密检索架构显著优于单路径方案。相较单一路径的 FAISS 或 BM25，多路径（FAISS/BM25/标题摘要检索等）在相同候选规模下取得更高的召回与更稳定的精度，体现出 Mix-of-Retrievers 的优势。

与通用重排器（bge-reranker-v2-Gemma）相比，经过任务自适应训练的专用重排器在 Top-5/Top-10 配置下均显著更优，召回约提升 ~15%，且能有效过滤无关片段，Precision 明显上升。同时，随着输出 chunk 数增加，Precision/MRR/nDCG 呈下降趋势，印证“5～10 个 chunk 通常足够”的经验。

R=5（每个检索器5条候选）：

R=10（每个检索器10条候选）：

带“∗”为我们的实验；其他来自原论文。

响应时延（秒）：

Faithful 评分：

注：n 为子问题数。

• RAG-based Financial Question Answering
• MLC LLM

If you use FinSage in your research, please cite the paper:

@article{FinSage,
  title={FinSage: A Multi-aspect RAG System for Financial Filings Question Answering},
  author={Wang, Xinyu and Chi, Jijun and Tai, Zhenghan and Kwok, Tung Sum Thomas and Li, Muzhi and others},
  journal={arXiv preprint arXiv:2504.14493},
  year={2025}
}