PolyRAG：小语言模型的智能检索增强生成平台

场景切入：一个医学研究员的日常困境

深夜，一位医学研究员正对着一份 200 页的 PDF 文献苦寻答案——"过去五年间，针对某一靶点的临床试验趋势如何？"她需要知道趋势图、具体段落引用、相关数据库记录，任何单一工具都无法同时满足。她逐个打开浏览器、数据库、PDF 阅读器，手动复制粘贴，结果耗时两小时，答案还可能遗漏。

PolyRAG 正是为解决这类问题而生：它让用户用自然语言发起复杂研究请求，系统自动协调 PDF 检索、数据库查询、可视化生成，全链路返回带来源标注的答案。核心定位是——专为小语言模型（SLM）设计，在有限上下文窗口下依然保持高效、准确。

项目背景与起源

PolyRAG 由开发者 Joshua Carroll 创建（carroll.joshk@gmail.com），首个版本发布于 2025 年 4 月。这是一个专注 Agentic RAG（智能体式检索增强生成）架构的开源框架，与传统 RAG 的"向量检索 → LLM 生成"单一流水线不同，PolyRAG 将整个问答流程建模为多个专业智能体的协作网络。

项目当前 95 Stars、13 Forks，采用 MIT 许可证，Python 3.12+ 环境，使用 MedRxiv 医学预印本平台的数据作为演示数据集。创始动机明确：让本地部署的研究辅助工具在资源受限环境下依然可用，不依赖庞大的云端模型。

核心架构：从单链到多智能体协作

PolyRAG 的设计哲学是"管道化输出、自动纠错、减轻主 Agent 上下文负担"。架构上分为两层：

Agent 层（位于 src/agents/）：

• chatbot.py — 对话管理，管理多轮对话状态
• research_assistant.py — 核心研究助手，协调各工具
• pg_rag_assistant.py — PostgreSQL 向量/全文检索助手
• graphing_agent.py — 自然语言生成图表（调用 Plotly）
• llama_guard.py — 内容安全过滤

工具层（位于 src/tools_*.py）：

• tools_pg.py — PostgreSQL 查询工具（SQL 生成 + 执行）
• tools_plotly.py — Plotly 图表渲染工具
• rag_tool.py — 文档块检索工具

一个典型的查询流程：chatbot 接收自然语言请求 → research_assistant 规划任务 → 调用 pg_rag_assistant 检索数据库 + rag_tool 检索 PDF → graphing_agent 生成图表 → 所有结果汇总返回。

技术栈与核心依赖

智能体间通过 LangGraph 的状态图（StateGraph）实现有向无环图（DAG）调度，支持断点续传（langgraph-checkpoint-postgres）。

功能体验：四个典型场景

对话式研究助手

用户用自然语言提问，系统自动拆解为子任务，调用检索工具返回带来源段落和文献元数据的答案。MedRxiv 演示数据涵盖 2025 年上半年医学预印本。

PDF 上下文高亮

上传或系统内已有的 PDF 文献，PolyRAG 自动识别与当前问题相关的文本块，在 PDF 可视化界面中高亮展示，读者可直接定位到关键段落。

自然语言数据可视化

"过去三年某靶点的临床试验数量趋势"——这类请求经过 graphing_agent 解析后，自动生成 SQL 查询数据库，Plotly 渲染趋势图返回给用户，全程无需手动写代码或 SQL。

端到端 Agent 编排

src/agents/agents.py 负责协调 SQL 工具、RAG 工具、PDF 工具的链式调用，结果通过流式响应（Streaming）逐段展示给用户。

部署分析：一键启动完整栈

项目提供 compose.yaml，包含三个服务：

• agent-service — 核心推理服务（端口 8080），基于 Dockerfile.service
• streamlit-app — Web UI（端口 8501），基于 Dockerfile.app
• postgres-db — PostgreSQL 15 数据库（端口 5433）

两个 Dockerfile 均基于 python:3.12.3-slim，使用 uv 包管理器加速依赖安装（uv sync --frozen），生产级镜像体积可控。compose 中配置了热重载（develop: watch），修改 src/agents/、src/schema/ 等目录后自动同步重启容器。

部署前需配置 .env 文件（参考 .env.example），至少包含数据库连接信息和一个 LLM API Key（支持 OpenAI / Azure OpenAI / DeepSeek）。

局限性与挑战

1. 依赖外部 LLM API：项目本身不包含模型，所有推理依赖第三方 API Key，存在隐私和成本风险
2. 无本地 embedding：使用 PostgreSQL TSVector 而非向量检索，对模糊语义匹配能力有限
3. 仅支持英文：PostgreSQL 全文检索配置为法语（french），中文文档支持需额外配置
4. 测试覆盖有限：虽有 pytest + pytest-cov 配置，但 codecov.yml 显示未启用自动覆盖率追踪

行业意义

PolyRAG 代表了 RAG 领域的一个新兴方向——从"单点检索"到"多智能体协作"。随着小语言模型（SLM）能力提升，在本地/边缘设备上运行复杂 RAG 流程成为可能。PolyRAG 的 LangGraph 架构为此类场景提供了可扩展的蓝图，值得关注其在医疗、法律、科研等垂直领域的落地潜力。