内容
# 🔬 人工智能研究助手 — RAG赋能的论文发现、分析和生成
一个智能研究助手，使用检索增强生成（RAG）流程搜索、分析和撰写学术论文。基于LangGraph、FAISS向量数据库、FastAPI、MCP和谷歌Gemini构建。
> 该系统实现了从论文发现到LaTeX论文生成的全研究工作流程，涵盖两大学术搜索来源、向量索引分析和带有真实引用的LaTeX论文生成。
## 架构
```mermaid
flowchart LR
subgraph 用户界面
UI[Streamlit 应用 / FastAPI]
end
subgraph LangGraph 代理
A[ReAct 代理\nGemini 2.5 Flash]
end
subgraph 工具
T1[🔎 语义搜索]
T2[🔍 arXiv 搜索]
T3[📄 读取 PDF]
T4[💾 索引论文]
T5[🗂️ 搜索论文]
T6[📝 渲染 LaTeX PDF]
end
subgraph 存储
VDB[(FAISS\n向量数据库)]
EMB[Gemini\n嵌入向量]
end
subgraph 外部
SS[语义学者 API]
AX[arXiv API]
TEX[Tectonic\nLaTeX 编译器]
end
UI <--> A
A --> T1 --> SS
A --> T2 --> AX
A --> T3
A --> T4 --> EMB --> VDB
A --> T5 --> VDB
A --> T6 --> TEX
```
### RAG 流程
```mermaid
flowchart TD
P[PDF 论文] -->|读取 PDF| R[原始文本\n~40K 字符]
R -->|递归字符文本分割器| C[分段\n~49 分段 × 1000 字符]
C -->|Gemini 嵌入向量 API| E[向量嵌入向量\n3072 维度]
E -->|索引论文| F[(FAISS 索引)]
Q[用户查询] -->|搜索论文| F
F -->|L2 相似度搜索| TOP[前 K 个相关分段]
TOP -->|上下文| LLM[Gemini 2.5 Flash]
LLM -->|渲染 LaTeX PDF| PDF[研究论文 PDF]
```
## 主要功能
🔎 **双源论文发现** — 在语义学者（semantic relevance ranking）和 arXiv（keyword matching with PDF links）中搜索，以获取两者的优势
📄 **PDF ingestion & 分段** — 从 PDF 中提取文本，使用递归字符分割成语义上有意义的分段
💾 **向量索引** — 使用谷歌的Gemini 嵌入向量 API 对分段进行嵌入，并存储在 FAISS 中以进行高效的相似度搜索
🗂️ **RAG 检索** — 使用基于 L2 距离的语义搜索从索引论文中检索相关段落，而不是将整个论文塞入上下文
📝 **论文生成** — 编写完整的学术论文，包含数学方程，通过 Tectonic LaTeX 引擎编译成 PDF
📊 **评估框架** — 使用可导出的 JSON 指标衡量检索质量、忠实度和工具可靠性
🌐 **双界面** — 用于交互式演示的 Streamlit UI 和用于程序化访问的 FastAPI 后端
🔌 **MCP 服务器** — 通过模型上下文协议暴露搜索工具，可在 Claude Desktop 或任何 MCP 兼容客户端中使用
## 评估结果
使用“注意力是你要的全部”（Vaswani 等，2017）论文进行评估：
| 指标 | 值 |
|--------|-------|
| 生成的分段 | 49（平均 957 字符每个） |
| 检索命中率 | 100%（5 个测试查询） |
| 平均相关性得分（L2） | 0.519 |
| 忠实度基础 | 59.6%（31/52 技术术语） |
| 测试查询 | 多头注意力、编码器-解码器、自注意力、位置编码、层归一化 |
> **忠实度说明：** 基础得分使用关键词重叠分析 — 一个故意简单透明的方法。关键词方法确保不会夸大指标，同时仍然证明源材料的依据。
<details>
<summary>📋 完整评估 JSON</summary>
```json
{
"session_duration_seconds": 2.6,
"papers_indexed": 1,
"total_chunks_stored": 49,
"retrieval_metrics": {
"total_queries": 5,
"avg_relevance_score": 0.519,
"hit_rate_percent": 100.0
},
"generation_checks": [
{
"check_type": "faithfulness",
"score": 0.596,
"details": "31/52 terms grounded"
}
]
}
```
</details>
## 技术栈
| 组件 | 技术 | 选择原因 |
|-----------|-----------|-----------------|
| **代理框架** | LangGraph（LangChain） | ReAct 循环与工具调用、状态管理、检查点 |
| **LLM** | 谷歌 Gemini 2.5 Flash | 1M 上下文窗口、免费层、强大的工具调用 |
| **嵌入向量** | 谷歌 Gemini 嵌入向量 API | 免费、3072 维向量、多语言支持 |
| **向量数据库** | FAISS（本地） | 无需外部服务、无需配置、快速 L2 搜索 |
| **文本分割** | 递归字符文本分割器 | 在段落和句子之间保留语义边界 |
| **搜索来源** | 语义学者 + arXiv | 语义排名来自语义学者、PDF 链接来自 arXiv |
| **PDF 渲染** | Tectonic（LaTeX） | 轻量级、单二进制 LaTeX 编译器，自动依赖获取 |
| **前端** | Streamlit | 快速原型设计，实时流媒体和会话状态 |
| **后端 API** | FastAPI | 生产就绪的 REST API，交互式 Swagger 文档 |
| **包管理器** | uv | 现代 Python 工具 — 快速、确定性依赖解析 |
| **MCP 服务器** | FastMCP（MCP Python SDK） | 将搜索工具暴露为可重用的基础设施，供任何 MCP 客户端使用 |
## 工作原理
### 1. 搜索阶段
```
用户：“我对注意力机制感兴趣”
→ 代理调用语义搜索(“注意力机制”)以获取最佳相关性
→ 如果需要，退后到 arXiv 搜索
→ 返回 5 篇论文，包含标题、作者、摘要、PDF 链接
```
### 2. 分析阶段
```
用户：“阅读变换器论文”
→ read_pdf(url) 提取 ~40K 字符文本
→ index_paper(title) 将其分成 ~49 个部分，通过 Gemini 嵌入，存储在 FAISS 中
→ 代理提供详细分析：问题、方法、结果、局限性
```
### 3. 写作阶段（RAG 在行动）
```
用户：“写一篇关于自注意力改进的论文”
→ search_papers(“自注意力改进”) 查询 FAISS
→ 返回前 K 个相关分段（不是整个论文！）
→ 代理使用检索的上下文编写 LaTeX
→ render_latex_pdf(latex) 通过 Tectonic 编译成 PDF
```
**为什么 RAG 在这里很重要：** 与其将 40K 字符的论文塞进 LLM 的上下文（这会超出令牌限制），我们将其存储在 FAISS 中，只检索与当前任务相关的 ~5K 字符。这样减少了 87% 的上下文使用，使系统可扩展 — 索引多篇论文，仍能保持在令牌限制内。
## MCP 服务器集成
学术搜索工具（arXiv + 语义学者）也作为一个独立的 **模型上下文协议（MCP）** 服务器公开，使它们可重用于 Claude Desktop 或任何 MCP 兼容客户端 — 不局限于此项目。
### 独立运行
```bash
uv run python mcp_server.py
```
### 安装到 Claude Desktop
添加到您的 `claude_desktop_config.json`：
```json
{
"mcpServers": {
"academic-research": {
"command": "uv",
"args": ["run", "--directory", "/path/to/project", "python", "mcp_server.py"]
}
}
}
```
配置完成后，搜索工具直接出现在 Claude Desktop 中 — 演示 MCP 的核心价值：一次构建的工具，可在任何客户端中重复使用。
## 项目结构
```
research-agent/
├── src/
│ ├── config.py # LLM、嵌入和应用程序配置
│ ├── evaluation.py # 检索、忠实度和覆盖度指标
│ ├── graph.py # LangGraph ReAct 代理编排
│ ├── app.py # Streamlit UI，流媒体 + 工具状态
│ ├── api.py # FastAPI 后端，会话管理
├── test_eval.py # 独立评估脚本
│ └── tools/
│ ├── arxiv_tool.py # arXiv API 搜索，XML 解析
│ ├── semantic_scholar_tool.py # 语义学者搜索，相关性排名
│ ├── read_pdf.py # PDF 文本提取，内部缓存
│ ├── vector_store.py # FAISS 索引 + Gemini 嵌入 + 搜索
│ └── write_pdf.py # LaTeX 净化 + Tectonic 编译
├── output/ # 生成的 .tex、.pdf 和指标 JSON
├── pyproject.toml
├── mcp_server.py # MCP 服务器，公开搜索工具
├── .env.example
└── README.md
```
## 设置
### 先决条件
- Python 3.10+
- [uv](https://docs.astral.sh/uv/) 包管理器
- [Tectonic](https://tectonic-typesetting.github.io/) LaTeX 编译器（用于 PDF 生成）
- 免费的 [谷歌 AI Studio API 密钥](https://aistudio.google.com/apikey)
- 可选：[语义学者 API 密钥](https://www.semanticscholar.org/product/api) 以获取更高的速率限制
### 安装
```bash
# 克隆仓库
git clone https://github.com/ameeta18/ai-research-assistant.git
cd ai-research-assistant
# 安装依赖
uv sync
# 配置环境
cp .env.example .env
# 将您的 GOOGLE_API_KEY（和可选的 SEMANTIC_SCHOLAR_API_KEY）添加到 .env
```
### 运行 Streamlit 应用
```bash
uv run streamlit run src/app.py
```
### 运行 FastAPI 后端
```bash
uv run uvicorn src.api:app --reload
# 交互式文档：http://127.0.0.1:8000/docs
```
### 运行评估
```bash
uv run python test_eval.py
# 结果保存到 output/evaluation_results.json
```
