# https://github.com/Future-House/paper-qa 项目说明书

生成时间：2026-06-23 03:56:00 UTC

## 目录

- [PaperQA2 概览与快速开始](#page-1)
- [核心架构、设置系统与数据流](#page-2)
- [LLM 与嵌入模型配置 (含 Azure / 本地 LLM)](#page-3)
- [文档读取、PDF 解析与外部元数据源](#page-4)

<a id='page-1'></a>

## PaperQA2 概览与快速开始

### 相关页面

相关主题：[核心架构、设置系统与数据流](#page-2), [LLM 与嵌入模型配置 (含 Azure / 本地 LLM)](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/paperqa/configs/contracrow.json](https://github.com/Future-House/paper-qa/blob/main/src/paperqa/configs/contracrow.json)
- [src/paperqa/configs/wikicrow.json](https://github.com/Future-House/paper-qa/blob/main/src/paperqa/configs/wikicrow.json)
- [src/paperqa/agents/__init__.py](https://github.com/Future-House/paper-qa/blob/main/src/paperqa/agents/__init__.py)
- [src/paperqa/agents/helpers.py](https://github.com/Future-House/paper-qa/blob/main/src/paperqa/agents/helpers.py)
- [src/paperqa/agents/search.py](https://github.com/Future-House/paper-qa/blob/main/src/paperqa/agents/search.py)
- [src/paperqa/contrib/zotero.py](https://github.com/Future-House/paper-qa/blob/main/src/paperqa/contrib/zotero.py)
- [src/paperqa/contrib/openreview_paper_helper.py](https://github.com/Future-House/paper-qa/blob/main/src/paperqa/contrib/openreview_paper_helper.py)
- [packages/paper-qa-pypdf/README.md](https://github.com/Future-House/paper-qa/blob/main/packages/paper-qa-pypdf/README.md)
- [packages/paper-qa-pymupdf/README.md](https://github.com/Future-House/paper-qa/blob/main/packages/paper-qa-pymupdf/README.md)
- [packages/paper-qa-docling/README.md](https://github.com/Future-House/paper-qa/blob/main/packages/paper-qa-docling/README.md)
- [packages/paper-qa-nemotron/README.md](https://github.com/Future-House/paper-qa/blob/main/packages/paper-qa-nemotron/README.md)
</details>

# PaperQA2 概览与快速开始

## 简介与核心能力

PaperQA2 是一个面向科学文献检索与问答的系统，由 `paperqa` 主包与多个可选的 PDF 解析后端插件组成。它使用 LLM 在一组本地或远程文献上完成检索、证据收集与生成式回答，并通过 `ToolSelector` 智能体循环自动决定何时终止流程 资料来源：[src/paperqa/configs/wikicrow.json:1-40]()。

项目提供几种开箱即用的预设配置，分别针对不同的质量/速度权衡：

| 预设配置文件 | 主要用途 |
| --- | --- |
| `wikicrow.json` | 默认的维基百科风格回答，使用 `gpt-4-turbo-2024-04-09` |
| `contracrow.json` | 矛盾检测导向，强调事实一致性 |
| `fast.json` / `high_quality.json` | 用户自定义速度与质量档位 |

每个配置都覆盖了 `agent.agent_llm`、`agent.agent_type`、`agent.search_count` 与提示词模板等关键字段 资料来源：[src/paperqa/configs/wikicrow.json:1-40]()、资料来源：[src/paperqa/configs/contracrow.json:1-40]()。

## 架构与数据流

PaperQA2 的执行流程可以分为「检索 → 解析 → 证据收集 → 生成」四个阶段，并由智能体在循环中调度：

```mermaid
flowchart LR
    A[用户问题] --> B[ToolSelector Agent]
    B --> C[Tantivy 全文检索]
    C --> D[PDF 解析后端]
    D --> E[Chunk 切分与摘要]
    E --> F[LLM 证据评分]
    F --> G[生成最终回答]
    G --> H{证据是否充分?}
    H -- 否 --> B
    H -- 是 --> I[complete_tool]
```

- 智能体入口与 `ask()` 工具方法均封装在 `paperqa.agents` 中 资料来源：[src/paperqa/agents/__init__.py:1-40]()。
- Tantivy 索引构建由 `paperqa.agents.search` 负责，可读取整目录文本 资料来源：[src/paperqa/agents/search.py:1-30]()。
- 搜索查询改写与年份注入由 `litellm_get_search_query` 实现，会在模板中自动填入 `{count}`、`{question}`、`{date}` 三个变量 资料来源：[src/paperqa/agents/helpers.py:1-40]()。

## 快速开始

### 安装主包与基础使用

```bash
git clone https://github.com/Future-House/paper-qa.git
cd paper-qa
pip install -e .
```

随后通过环境变量提供 LLM 凭据，例如 `OPENAI_API_KEY`，并在 Python 中调用智能体入口：

```python
from paperqa.agents import ask
answer = await ask("What is the evidence for X?", settings={"llm": "gpt-4o-mini"})
```

智能体默认类型为 `ToolSelector`，允许其在每次迭代中自主选择 `search` / `gather_evidence` / `complete` 等工具 资料来源：[src/paperqa/configs/wikicrow.json:1-40]()。

### 选择 PDF 解析后端

PaperQA2 将 PDF 解析解耦为独立插件，用户可以按需安装：

| 后端包 | 适用场景 | 备注 |
| --- | --- | --- |
| `paper-qa-pypdf` | 纯文本解析，可选 `media` / `enhanced` 扩展支持图像与表格 | Apache-2.0 |
| `paper-qa-pymupdf` | 高性能文本块解析，支持实验性布局分析 | AGPLv3 |
| `paper-qa-docling` | 复杂版式（公式、表格、图片）解析 | Apache-2.0 |
| `paper-qa-nemotron` | 使用 NVIDIA nemotron-parse VLM 解析版面 | Apache-2.0 |

资料来源：[packages/paper-qa-pypdf/README.md:1-15]()、资料来源：[packages/paper-qa-pymupdf/README.md:1-15]()、资料来源：[packages/paper-qa-docling/README.md:1-15]()、资料来源：[packages/paper-qa-nemotron/README.md:1-15]()。

`pypdf` 后端还提供 `MediaMode` 枚举，用于在「不抽取」「整页截图」「按聚类抽取图像」「逐个抽取图像」之间切换 资料来源：[packages/paper-qa-pypdf/src/paperqa_pypdf/reader.py:1-30]()。

### 集成文献来源

除了本地目录之外，PaperQA2 还提供 Zotero 与 OpenReview 的贡献模块：

- `ZoteroDB` 会自动读取 `ZOTERO_USER_ID` 与 `ZOTERO_API_KEY`，并将 PDF 下载到 `~/.paperqa/zotero`，最终返回 `paperqa.Docs` 对象 资料来源：[src/paperqa/contrib/zotero.py:1-40]()。
- `OpenReviewPaperHelper` 通过 OpenReview API 检索候选论文，调用 LLM 选出最相关的若干 submission，再异步下载 PDF 资料来源：[src/paperqa/contrib/openreview_paper_helper.py:1-40]()。

## 配置多 LLM 提供商（社区高频问题）

社区讨论中频繁出现「如何切换到 Azure OpenAI / Gemini / 本地 llamafile」的困惑。PaperQA2 的所有 LLM 调用都经由 `lmi.LiteLLMModel`，因此任何被 LiteLLM 支持的提供方都可通过修改 `agent_llm` 字段切换：

- **Azure OpenAI**：在配置中提供 `api_base`、`api_version` 等 LiteLLM 参数，并在环境变量中配置 `AZURE_API_KEY` 即可；Issue #393 中用户已确认该路径可行。
- **Gemini**：需要显式传入 `llm` 设置字符串，例如 `"gemini/gemini-1.5-pro"`，并设置 `GEMINI_API_KEY`；Issue #1044 提醒 CLI 默认仍会校验 `OPENAI_API_KEY`，请使用显式 settings 文件覆盖。
- **本地 llamafile / Ollama**：通过 LiteLLM 的 `openai/` 兼容端点暴露后，将 `agent_llm` 指向该端点即可，Issue #378、#428 中讨论了具体的 `litellm` 冲突解决方法。

智能体提示词也会随之被自动注入当前年份（`get_year()`），从而保证搜索查询的时间相关性 资料来源：[src/paperqa/agents/helpers.py:1-40]()。

## 常见问题与故障排查

- **CLI 拒绝使用非 OpenAI 模型**：检查是否设置了 `OPENAI_API_KEY`，因为 CLI 在没有显式 settings 时会以默认值探测；提供自定义 settings 文件可解决该问题（参见 Issue #1044）。
- **本地 LLM 与 litellm 冲突**：Issue #428 显示，安装 `paper-qa` 时若与全局 `litellm` 版本不一致会触发错误，建议使用干净的 conda 环境重装。
- **Tantivy 索引为空**：`build_index` 在 `build=False` 时若发现 `index_files` 为空，会直接抛出 `RuntimeError`，此时需重建索引 资料来源：[src/paperqa/agents/search.py:1-30]()。
- **PDF 解析失败**：`pypdf` 后端提供 `page_size_limit`，超出阈值时抛出 `ImpossibleParsingError`，可据此判断是文件本身损坏还是解析器配置问题 资料来源：[packages/paper-qa-pypdf/src/paperqa_pypdf/reader.py:1-30]()。
- **Zotero 集成无法导入**：需安装可选依赖 `pip install paper-qa[zotero]`，否则 `pyzotero` 不会被引入 资料来源：[src/paperqa/contrib/zotero.py:1-40]()。

## See Also

- [PaperQA2 智能体与提示词模板]()
- [PDF 解析后端对比（pypdf / PyMuPDF / Docling / nemotron）]()
- [本地 LLM 与多提供商配置指南]()
- [Zotero 与 OpenReview 集成]()
- [GitHub Issue #378（Open Source LLM Server）](https://github.com/Future-House/paper-qa/issues/378)
- [GitHub Issue #1044（CLI 中配置其他模型）](https://github.com/Future-House/paper-qa/issues/1044)

---

<a id='page-2'></a>

## 核心架构、设置系统与数据流

### 相关页面

相关主题：[PaperQA2 概览与快速开始](#page-1), [LLM 与嵌入模型配置 (含 Azure / 本地 LLM)](#page-3), [文档读取、PDF 解析与外部元数据源](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/paperqa/agents/__init__.py](https://github.com/Future-House/paper-qa/blob/main/src/paperqa/agents/__init__.py)
- [src/paperqa/agents/env.py](https://github.com/Future-House/paper-qa/blob/main/src/paperqa/agents/env.py)
- [src/paperqa/agents/search.py](https://github.com/Future-House/paper-qa/blob/main/src/paperqa/agents/search.py)
- [src/paperqa/agents/models.py](https://github.com/Future-House/paper-qa/blob/main/src/paperqa/agents/models.py)
- [src/paperqa/configs/contracrow.json](https://github.com/Future-House/paper-qa/blob/main/src/paperqa/configs/contracrow.json)
- [src/paperqa/configs/wikicrow.json](https://github.com/Future-House/paper-qa/blob/main/src/paperqa/configs/wikicrow.json)
- [src/paperqa/configs/debug.json](https://github.com/Future-House/paper-qa/blob/main/src/paperqa/configs/debug.json)
- [src/paperqa/contrib/zotero.py](https://github.com/Future-House/paper-qa/blob/main/src/paperqa/contrib/zotero.py)
- [src/paperqa/contrib/openreview_paper_helper.py](https://github.com/Future-House/paper-qa/blob/main/src/paperqa/contrib/openreview_paper_helper.py)
- [packages/paper-qa-pypdf/src/paperqa_pypdf/reader.py](https://github.com/Future-House/paper-qa/blob/main/packages/paper-qa-pypdf/src/paperqa_pypdf/reader.py)
- [packages/paper-qa-docling/src/paperqa_docling/reader.py](https://github.com/Future-House/paper-qa/blob/main/packages/paper-qa-docling/src/paperqa_docling/reader.py)
- [packages/paper-qa-nemotron/src/paperqa_nemotron/api.py](https://github.com/Future-House/paper-qa/blob/main/packages/paper-qa-nemotron/src/paperqa_nemotron/api.py)
</details>

# 核心架构、设置系统与数据流

## 一、整体架构概览

paper-qa 是一个面向科学论文的检索增强问答（RAG）系统，采用**多包 + 插件式**的架构组织方式。核心入口位于 `src/paperqa/agents/__init__.py`，通过 CLI 暴露 `view`、`ask`、`search`、`index` 四个子命令，同时对外提供 `ask` 等 Python API。资料来源：[src/paperqa/agents/__init__.py:1-50](https://github.com/Future-House/paper-qa/blob/main/src/paperqa/agents/__init__.py)

系统的逻辑层次可划分为：

| 层级 | 职责 | 关键模块 |
|---|---|---|
| 入口层 | CLI、日志、RichHandler | `agents/__init__.py` |
| Agent 层 | 工具选择、状态机、Session | `agents/env.py`、`agents/models.py` |
| 检索层 | Tantivy 索引、嵌入、匹配 | `agents/search.py` |
| 解析层 | PDF → `ParsedText` / `ParsedMedia` | `paper-qa-pypdf` / `paper-qa-docling` / `paper-qa-nemotron` |
| 集成层 | Zotero、OpenReview 数据源 | `contrib/zotero.py`、`contrib/openreview_paper_helper.py` |
| 配置层 | JSON 配置 + 提示词模板 | `configs/*.json` |

## 二、设置系统（Settings & Prompts）

设置系统通过 `Settings` Pydantic 模型聚合 LLM、embedding、解析、提示词等子配置，并在运行时由 `make_tools()` 转换为 agent 可用的工具列表。资料来源：[src/paperqa/agents/env.py:1-60](https://github.com/Future-House/paper-qa/blob/main/src/paperqa/agents/env.py)

仓库内置多套 JSON 配置，覆盖不同应用场景：

- **`contracrow.json`**：声明式 Fact-Check 风格，启用 JSON 模式（`use_json: true`），并为 `summary_json` / `summary_json_system` 提供结构化输出模板；agent 配置为 `ToolSelector` 类型，最多 12 次搜索。资料来源：[src/paperqa/configs/contracrow.json:1-40](https://github.com/Future-House/paper-qa/blob/main/src/paperqa/configs/contracrow.json)
- **`wikicrow.json`**：面向 Wikipedia 引用风格的精简提示词（`summary`、`qa`），并附带结构化引文抽取提示。资料来源：[src/paperqa/configs/wikicrow.json:1-30](https://github.com/Future-House/paper-qa/blob/main/src/paperqa/configs/wikicrow.json)
- **`debug.json`**：极简调试配置，使用 `claude-3-haiku-20240307`，关闭 `use_doc_details` 并启用 `defer_embedding`，将 `evidence_k` 降低到 2 以加快迭代。资料来源：[src/paperqa/configs/debug.json:1-15](https://github.com/Future-House/paper-qa/blob/main/src/paperqa/configs/debug.json)

社区中关于"如何切换 Azure / Gemini / 本地 llamafile"的多个问题（#393、#378、#428、#1044）根源即在于 Settings 模型提供了 `llm` / `summary_llm` / `agent_llm` 等字段，但默认仍假定 OpenAI 兼容协议——切换 provider 时需要在配置层显式声明模型名或借助 LiteLLM 路由。

## 三、数据流：从 PDF 到答案

下图展示了 paper-qa 从原始 PDF 到最终答复的核心数据通路：

```mermaid
flowchart LR
    A[PDF 文件] --> B{解析器}
    B -->|pypdf| P1[parse_pdf_to_pages]
    B -->|docling| P2[Docling Pipeline]
    B -->|nemotron-parse| P3[Nemotron VLM]
    P1 --> C[ParsedText / ParsedMedia]
    P2 --> C
    P3 --> C
    C --> D[Tantivy 索引 + Embedding]
    D --> E[ToolSelector Agent]
    E --> F[搜索 / 收集 / 证据汇总]
    F --> G[最终答案 + 引用]
```

各阶段关键实现：

1. **解析阶段**：`paper-qa-pypdf` 暴露 `parse_pdf_to_pages`，通过可选的 `pdfium` / `pdfplumber` 扩展支持 `MediaMode.FULL_PAGE`、`INDIVIDUAL` 与 `INDIVIDUAL_CLUSTERING` 等图像抽取模式。资料来源：[packages/paper-qa-pypdf/src/paperqa_pypdf/reader.py:1-60](https://github.com/Future-House/paper-qa/blob/main/packages/paper-qa-pypdf/src/paperqa_pypdf/reader.py)  
   `paper-qa-docling` 则基于 `StandardPdfPipeline`，支持 `dpi`、`images_scale`、`parse_media` 等参数，并能识别 `PictureItem` 与 `TableItem`。资料来源：[packages/paper-qa-docling/src/paperqa_docling/reader.py:1-60](https://github.com/Future-House/paper-qa/blob/main/packages/paper-qa-docling/src/paperqa_docling/reader.py)  
   `paper-qa-nemotron` 则通过 NVIDIA nemotron-parse VLM 完成版面理解，并在 `NemotronParseBBox` 中以归一化坐标进行几何建模。资料来源：[packages/paper-qa-nemotron/src/paperqa_nemotron/api.py:1-50](https://github.com/Future-House/paper-qa/blob/main/packages/paper-qa-nemotron/src/paperqa_nemotron/api.py)

2. **索引阶段**：`agent_index` 通过 `make_index_from_csv`-式入口扫描 `paper_directory`，按 `files_filter` 过滤并写入 Tantivy 索引，字段包含 `title`、`year` 与必备字段。资料来源：[src/paperqa/agents/search.py:1-50](https://github.com/Future-House/paper-qa/blob/main/src/paperqa/agents/search.py)

3. **Agent 阶段**：`PQASession` 维护 question、answer、cost 等运行时状态；`EnvironmentState` 在 `reset()` 时初始化 docs 与可选的临床试验状态函数。资料来源：[src/paperqa/agents/env.py:40-90](https://github.com/Future-House/paper-qa/blob/main/src/paperqa/agents/env.py)  
   `SimpleProfiler` 则记录各阶段耗时，用于性能追踪。资料来源：[src/paperqa/agents/models.py:1-60](https://github.com/Future-House/paper-qa/blob/main/src/paperqa/agents/models.py)

4. **集成数据源**：`ZoteroDB` 继承 `pyzotero`，通过 `ZOTERO_USER_ID` / `ZOTERO_API_KEY` 自动认证，并把 PDF 下载到 `~/.paperqa/zotero` 后再走解析管线。资料来源：[src/paperqa/contrib/zotero.py:1-60](https://github.com/Future-House/paper-qa/blob/main/src/paperqa/contrib/zotero.py)  
   `OpenReviewPaperHelper` 则异步下载 OpenReview 提交 PDF，与主索引共享 `paper_directory`。资料来源：[src/paperqa/contrib/openreview_paper_helper.py:1-40](https://github.com/Future-House/paper-qa/blob/main/src/paperqa/contrib/openreview_paper_helper.py)

## 四、常见失败模式

- **CLI 切换模型困难**：`pqa` CLI 默认加载 Settings 后仍要求 OpenAI key，问题根因是没有显式注入 `OPENAI_API_BASE` / `AZURE_OPENAI_*` 等环境变量（对应 #1044）。
- **本地 LLM 与 LiteLLM 冲突**：使用 llamafile / Ollama 时常因 litellm 路由未配置导致解析失败（对应 #428），需要在 Settings 中显式设置 `llm` 模型名。
- **索引为空**：`make_index` 在 `build=False` 时会显式抛出 `RuntimeError`，提示先重建索引。资料来源：[src/paperqa/agents/search.py:30-45](https://github.com/Future-House/paper-qa/blob/main/src/paperqa/agents/search.py)
- **解析失败**：`docling` 解析器对跨页 `TableItem` 抛出 `NotImplementedError`，需在自定义 pipeline 中预先拆分。资料来源：[packages/paper-qa-docling/src/paperqa_docling/reader.py:40-70](https://github.com/Future-House/paper-qa/blob/main/packages/paper-qa-docling/src/paperqa_docling/reader.py)

## See Also

- 配置与提示词模板：`src/paperqa/configs/*.json`
- PDF 解析可选后端：`paper-qa-pypdf`、`paper-qa-docling`、`paper-qa-pymupdf`、`paper-qa-nemotron`
- 数据源集成：`contrib/zotero.py`、`contrib/openreview_paper_helper.py`

---

<a id='page-3'></a>

## LLM 与嵌入模型配置 (含 Azure / 本地 LLM)

### 相关页面

相关主题：[PaperQA2 概览与快速开始](#page-1), [核心架构、设置系统与数据流](#page-2)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/paperqa/agents/models.py](https://github.com/Future-House/paper-qa/blob/main/src/paperqa/agents/models.py)
- [src/paperqa/agents/env.py](https://github.com/Future-House/paper-qa/blob/main/src/paperqa/agents/env.py)
- [src/paperqa/agents/search.py](https://github.com/Future-House/paper-qa/blob/main/src/paperqa/agents/search.py)
- [src/paperqa/configs/contracrow.json](https://github.com/Future-House/paper-qa/blob/main/src/paperqa/configs/contracrow.json)
- [src/paperqa/configs/wikicrow.json](https://github.com/Future-House/paper-qa/blob/main/src/paperqa/configs/wikicrow.json)
- [src/paperqa/configs/debug.json](https://github.com/Future-House/paper-qa/blob/main/src/paperqa/configs/debug.json)
- [src/paperqa/configs/tier2_limits.json](https://github.com/Future-House/paper-qa/blob/main/src/paperqa/configs/tier2_limits.json)
- [src/paperqa/configs/tier4_limits.json](https://github.com/Future-House/paper-qa/blob/main/src/paperqa/configs/tier4_limits.json)
- [src/paperqa/configs/tier5_limits.json](https://github.com/Future-House/paper-qa/blob/main/src/paperqa/configs/tier5_limits.json)
- [src/paperqa/contrib/openreview_paper_helper.py](https://github.com/Future-House/paper-qa/blob/main/src/paperqa/contrib/openreview_paper_helper.py)
- [src/paperqa/contrib/zotero.py](https://github.com/Future-House/paper-qa/blob/main/src/paperqa/contrib/zotero.py)
- [packages/paper-qa-docling/README.md](https://github.com/Future-House/paper-qa/blob/main/packages/paper-qa-docling/README.md)
- [packages/paper-qa-pymupdf/README.md](https://github.com/Future-House/paper-qa/blob/main/packages/paper-qa-pymupdf/README.md)
- [packages/paper-qa-pypdf/README.md](https://github.com/Future-House/paper-qa/blob/main/packages/paper-qa-pypdf/README.md)
- [packages/paper-qa-pypdf/src/paperqa_pypdf/reader.py](https://github.com/Future-House/paper-qa/blob/main/packages/paper-qa-pypdf/src/paperqa_pypdf/reader.py)
- [packages/paper-qa-nemotron/README.md](https://github.com/Future-House/paper-qa/blob/main/packages/paper-qa-nemotron/README.md)
</details>

# LLM 与嵌入模型配置 (含 Azure / 本地 LLM)

## 概述

PaperQA 通过 **LiteLLM** 抽象层来对接 LLM 和嵌入模型提供方。`agents/models.py` 中的代码 `LiteLLMModel(name=llm_model) if isinstance(llm_model, str) else llm_model` 显示,只要传入字符串模型名称,框架就会自动构造 LiteLLM 适配器,因此任何 LiteLLM 支持的提供方(OpenAI、Azure OpenAI、Anthropic、Gemini、本地 Ollama/llamafile 等)都可以直接接入。配置入口位于 `Settings` 对象,顶层字段包括 `llm`、`summary_llm`、`embedding`,并可通过 `llm_config` / `summary_llm_config` / `embedding_config` 进一步传递底层参数。

资料来源:[src/paperqa/agents/models.py]()

## 配置文件层级与默认模型

仓库自带多份 JSON 配置文件,可作为预设参考:

| 配置文件 | 主要 LLM | 嵌入模型 | 典型用途 |
|---|---|---|---|
| `contracrow.json` | `gpt-4o-2024-08-06` | `hybrid-text-embedding-3-large` | 反证/支持抽取场景 |
| `wikicrow.json` | `claude-3-5-sonnet-20240620` | `hybrid-text-embedding-3-large` | 维基风格长文回答 |
| `debug.json` | `claude-3-haiku-20240307` | (默认) | 本地调试,减少 token |

每个配置都覆盖了 `answer`、`parsing`、`prompts` 子段,可以整体替换,也可以只覆盖其中一部分。`agent` 子段定义了智能体自身使用的 `agent_llm` 与 `agent_type`(`ToolSelector`)。

资料来源:[src/paperqa/configs/contracrow.json]()、[src/paperqa/configs/wikicrow.json]()、[src/paperqa/configs/debug.json]()

## Azure OpenAI 与本地 LLM 配置

由于 PaperQA 完全依赖 LiteLLM 解析模型名称,Azure、本地服务等只需在 `Settings` 中将 `llm`、`summary_llm`、`embedding` 改为 LiteLLM 约定的字符串即可:

- **Azure OpenAI**:模型名写作 `azure/<your-deployment>`,并通过 `OPENAI_API_TYPE`、`OPENAI_API_BASE`、`OPENAI_API_KEY`、`OPENAI_API_VERSION` 环境变量(或对应 LiteLLM 变量)注入凭据。这是社区 #393 的标准解决方案。
- **本地 LLM(Ollama / llamafile)**:模型名写作 `ollama/<model>` 或 `openai/<model>`,并把 `api_base` 指向本地服务地址(如 `http://localhost:11434`)。社区 #378、#428 报告的 `litellm` 冲突通常来自未安装/版本不匹配的 `litellm` 依赖,需用 `pip install "paper-qa[local]"` 或显式 `pip install litellm` 解决。
- **CLI 配置**:社区 #1044 反馈 CLI 默认仍校验 OpenAI key,解决办法是在用户目录下放置一份 `settings.json` 把 `llm` 改成目标模型(如 `gemini/gemini-1.5-pro`),CLI 启动时会按 `Settings` 加载该文件。

```mermaid
flowchart LR
    A[用户配置 Settings] --> B[llm / summary_llm / embedding]
    B --> C[LiteLLMModel]
    C --> D{提供方路由}
    D -->|gpt-4o| E[OpenAI]
    D -->|azure/...| F[Azure OpenAI]
    D -->|claude-...| G[Anthropic]
    D -->|ollama/...| H[本地服务]
```

`agents/env.py` 中 `make_tools` 会调用 `settings_to_tools` 把上述设置包装成工具;`agents/search.py` 则在 `SearchIndex` 构造时同样读取 `Settings`,因此切换模型无需改动调用代码。

资料来源:[src/paperqa/agents/env.py]()、[src/paperqa/agents/search.py]()、[src/paperqa/agents/models.py]()

## 速率限制与并发控制

`tier2_limits.json`、`tier4_limits.json`、`tier5_limits.json` 三档配置演示了如何按账户等级对每个模型声明 RPM/TPM。例如 `tier5_limits.json` 中 `gpt-4o` 被限制为 `30000000 per 1 minute`,而 `tier2_limits.json` 中仅 `450000 per 1 minute`。这些键写入 `llm_config.rate_limit`,LiteLLM 会据此自动节流。`Settings.answer.max_concurrent_requests` 则控制并发评估请求数,典型默认值为 4–8。

资料来源:[src/paperqa/configs/tier2_limits.json]()、[src/paperqa/configs/tier4_limits.json]()、[src/paperqa/configs/tier5_limits.json]()

## 常见失败模式

- **CLI 报 “需要 OpenAI key”**:实际是没有读到自定义 `settings.json`,或 JSON 中 `llm` 字段仍为空字符串;确保覆盖到 `llm`、`summary_llm`、`embedding` 三项。
- **本地 llamafile 启动后无响应**:通常是 LiteLLM 未安装或版本冲突,需 `pip install -U litellm` 并确认服务地址(默认 `http://localhost:8080/v1`)。
- **Azure 部署报 404**:部署名需与 Azure 门户中的 *Deployment name* 完全一致,且 `OPENAI_API_BASE` 形如 `https://<resource>.openai.azure.com/`。
- **Zotero / OpenReview 集成使用了额外 LLM**:`contrib/zotero.py` 与 `contrib/openreview_paper_helper.py` 都直接接收 `llm_model` 参数,会沿用全局 `Settings.llm`,因此切换模型时它们也会同步变化。

资料来源:[src/paperqa/contrib/zotero.py]()、[src/paperqa/contrib/openreview_paper_helper.py]()

## 嵌入模型与解析后端选择

`embedding` 字段默认是 OpenAI 的文本嵌入;`contracrow.json` / `wikicrow.json` 都使用 `hybrid-text-embedding-3-large`,说明支持 OpenAI 的混合检索嵌入。PDF 解析后端与 LLM 解耦:`paper-qa-pypdf` 基于 PyPDF(`packages/paper-qa-pypdf/README.md`),`paper-qa-pymupdf` 基于 PyMuPDF,`paper-qa-docling` 基于 Docling,`paper-qa-nemotron` 基于 Nvidia nemotron-parse VLM;选哪个解析器由 `Settings.parsing.reader` 决定,不影响 LLM 选型。

资料来源:[packages/paper-qa-pypdf/README.md]()、[packages/paper-qa-pymupdf/README.md]()、[packages/paper-qa-docling/README.md]()、[packages/paper-qa-nemotron/README.md]()

## 参见

- 《构建索引与文档检索》
- 《智能体工具与 ToolSelector》
- 《Zotero 与 OpenReview 集成》

---

<a id='page-4'></a>

## 文档读取、PDF 解析与外部元数据源

### 相关页面

相关主题：[核心架构、设置系统与数据流](#page-2)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/paperqa/contrib/zotero.py](https://github.com/Future-House/paper-qa/blob/main/src/paperqa/contrib/zotero.py)
- [src/paperqa/contrib/openreview_paper_helper.py](https://github.com/Future-House/paper-qa/blob/main/src/paperqa/contrib/openreview_paper_helper.py)
- [packages/paper-qa-pypdf/src/paperqa_pypdf/reader.py](https://github.com/Future-House/paper-qa/blob/main/packages/paper-qa-pypdf/src/paperqa_pypdf/reader.py)
- [packages/paper-qa-pymupdf/src/paperqa_pymupdf/reader.py](https://github.com/Future-House/paper-qa/blob/main/packages/paper-qa-pymupdf/src/paperqa_pymupdf/reader.py)
- [packages/paper-qa-docling/src/paperqa_docling/reader.py](https://github.com/Future-House/paper-qa/blob/main/packages/paper-qa-docling/src/paperqa_docling/reader.py)
- [packages/paper-qa-docling/src/paperqa_docling/__init__.py](https://github.com/Future-House/paper-qa/blob/main/packages/paper-qa-docling/src/paperqa_docling/__init__.py)
- [packages/paper-qa-pypdf/README.md](https://github.com/Future-House/paper-qa/blob/main/packages/paper-qa-pypdf/README.md)
- [packages/paper-qa-pymupdf/README.md](https://github.com/Future-House/paper-qa/blob/main/packages/paper-qa-pymupdf/README.md)
- [packages/paper-qa-docling/README.md](https://github.com/Future-House/paper-qa/blob/main/packages/paper-qa-docling/README.md)
- [packages/paper-qa-nemotron/README.md](https://github.com/Future-House/paper-qa/blob/main/packages/paper-qa-nemotron/README.md)
- [src/paperqa/agents/search.py](https://github.com/Future-House/paper-qa/blob/main/src/paperqa/agents/search.py)
- [src/paperqa/agents/env.py](https://github.com/Future-House/paper-qa/blob/main/src/paperqa/agents/env.py)
- [src/paperqa/agents/helpers.py](https://github.com/Future-House/paper-qa/blob/main/src/paperqa/agents/helpers.py)
- [src/paperqa/agents/models.py](https://github.com/Future-House/paper-qa/blob/main/src/paperqa/agents/models.py)
- [src/paperqa/configs/contracrow.json](https://github.com/Future-House/paper-qa/blob/main/src/paperqa/configs/contracrow.json)
- [src/paperqa/configs/wikicrow.json](https://github.com/Future-House/paper-qa/blob/main/src/paperqa/configs/wikicrow.json)
- [src/paperqa/configs/debug.json](https://github.com/Future-House/paper-qa/blob/main/src/paperqa/configs/debug.json)
</details>

# 文档读取、PDF 解析与外部元数据源

## 概述与架构

PaperQA 通过**可插拔 PDF 解析后端**与**外部元数据/文献源**两条流水线，将本地 PDF 文档转化为可被 LLM 检索、引用与综合的证据片段。整体流程可概括为：解析器把 PDF 切成 `ParsedText` / `ParsedMedia` 页面对象，`Docs` 聚合这些对象生成 chunk，再由检索/嵌入/Agent 工具链消费。

```mermaid
flowchart LR
    A[PDF 文件] --> B[PDF 解析器]
    B1[pypdf]:::bk --> B
    B2[PyMuPDF]:::bk --> B
    B3[Docling]:::bk --> B
    B4[nemotron-parse VLM]:::bk --> B
    B --> C[ParsedText + ParsedMedia]
    C --> D[Docs.add_docs]
    D --> E[Tantivy 索引 + Embeddings]
    E --> F[Agent 检索/回答]
    M[外部元数据源] --> D
    M1[Zotero]:::ext --> M
    M2[OpenReview]:::ext --> M
    M3[Crossref / Semantic Scholar / OpenAlex / Unpaywall]:::ext --> M
    classDef bk fill:#eef,stroke:#446
    classDef ext fill:#fee,stroke:#a44
```

资料来源：[packages/paper-qa-docling/src/paperqa_docling/__init__.py:1-3]()；[src/paperqa/agents/search.py:1-50]()。

## PDF 解析器实现

### pypdf 后端

`paper-qa-pypdf` 提供 `parse_pdf_to_pages`，返回 `ParsedText`/`ParsedMedia`/`ParsedMetadata` 三元组。`MediaMode` 枚举支持 `NONE`、`FULL_PAGE`（整页截图）、`INDIVIDUAL`（提取单图）与 `INDIVIDUAL_CLUSTERING`（聚类为图集）。安装 `media` 额外依赖后启用 `pypdfium2`/`pdfplumber` 提供截图与表格/聚类支持。资料来源：[packages/paper-qa-pypdf/src/paperqa_pypdf/reader.py:1-60]()；[packages/paper-qa-pypdf/README.md:1-15]()。

### PyMuPDF 后端

`paper-qa-pymupdf` 在 `_extract_page_text` 中提供两种文本抽取模式：实验性的 `blocks` 排序保持模式（`use_block_parsing=True`）与默认 `text` 模式。`_parse_single_page_screenshot` 负责并行整页截图，被 `ProcessPoolExecutor` 调度，因此必须是顶层可 pickle 函数。资料来源：[packages/paper-qa-pymupdf/src/paperqa_pymupdf/reader.py:1-90]()；[packages/paper-qa-pymupdf/README.md:1-10]()。

### Docling 后端

`paper-qa-docling` 通过 `DocumentConverter` + `StandardPdfPipeline` + `DoclingParseDocumentBackend` 解析 PDF，可输出 `TextItem`、`TableItem`、`FormulaItem`、`PictureItem` 等结构化 `DocItem`，并支持 `DescriptionAnnotation` 与 DPI 缩放（`DOCLING_IMAGES_SCALE_PER_DPI = 72`）。`parse_media=True` 时抽取表格与公式媒体。资料来源：[packages/paper-qa-docling/src/paperqa_docling/reader.py:1-60]()；[packages/paper-qa-docling/README.md:1-10]()。

### Nemotron-parse VLM 后端

`paper-qa-nemotron` 包装 Nvidia 的 `nemotron-parse` 视觉语言模型，通过 NIM 端点处理复杂版面。资料来源：[packages/paper-qa-nemotron/README.md:1-15]()。

## 外部元数据源集成

### Zotero

`ZoteroDB` 继承自 `pyzotero.zotero.Zotero`，从 `ZOTERO_USER_ID` / `ZOTERO_API_KEY` 环境变量读取凭据，默认下载到 `~/.paperqa/zotero`。`ZoteroPaper` Pydantic 模型保存 `key`、`title`、`pdf`、`num_pages`、`zotero_key`、`details`。`iterate()` 返回 `paperqa.Docs` 对象。安装方式：`pip install paper-qa[zotero]`。资料来源：[src/paperqa/contrib/zotero.py:1-60]()。

### OpenReview

`OpenReviewPaperHelper` 利用 LLM 从用户问题中筛选相关 submission，下载 PDF 至 `settings.agent.index.paper_directory`。提示模板将用户问题追加到 chunk 末尾，要求返回 `submission_id` 列表。资料来源：[src/paperqa/contrib/openreview_paper_helper.py:1-30]()。

### 其他元数据客户端

`agent.search_count`（默认 12）控制检索轮数；`litellm_get_search_query` 接收含 `{count}/{question}/{date}` 占位符的模板生成关键词检索。资料来源：[src/paperqa/agents/helpers.py:1-40]()；[src/paperqa/agents/env.py:1-50]()；[src/paperqa/agents/search.py:1-40]()。

## 配置预设

`PaperQA` 通过 `src/paperqa/configs/` 下的 JSON 预设快速切换行为：例如 `debug.json` 用 `claude-3-haiku-20240307`、`evidence_k=2`、`use_doc_details=false`、`defer_embedding=true` 启用最小调试路径；`contracrow.json` 与 `wikicrow.json` 定义专用 `summary_json`/`summary_json_system` 提示（含 `relevance_score`），前者使用 `gpt-4o-2024-08-06`，后者使用 `gpt-4-turbo-2024-04-09`。资料来源：[src/paperqa/configs/debug.json:1-15]()；[src/paperqa/configs/contracrow.json:1-40]()；[src/paperqa/configs/wikicrow.json:1-40]()。

## 常见故障与社区反馈

- **本地/开源 LLM 集成**（Issue #378、#428）：解析器与 LLM 解耦，问题通常源于 `litellm` 模型名称/路由，而非解析器本身。
- **Zotero 导入**：缺少 `ZOTERO_*` 环境变量时 `ZoteroDB` 初始化即失败；需先 `pip install paper-qa[zotero]`。
- **解析失败**：`page_size_limit` 超限会抛出 `ImpossibleParsingError`，可通过 `page_range` 或调大阈值规避。

## See Also

- [Agent 与工具链](agent-tools.md)
- [索引与嵌入](indexing-embedding.md)
- [配置系统](configuration.md)

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：Future-House/paper-qa

摘要：发现 10 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：安装坑 - 来源证据：Is it possible to choose which articles to index and query in the paper directory?。

## 1. 安装坑 · 来源证据：Is it possible to choose which articles to index and query in the paper directory?

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Is it possible to choose which articles to index and query in the paper directory?
- 对用户的影响：可能影响升级、迁移或版本选择。
- 证据：community_evidence:github | https://github.com/Future-House/paper-qa/issues/1330 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 2. 配置坑 · 来源证据：CMYK images in PDFs crash indexing with OSError

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：CMYK images in PDFs crash indexing with OSError
- 对用户的影响：可能阻塞安装或首次运行。
- 证据：community_evidence:github | https://github.com/Future-House/paper-qa/issues/1310 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 3. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/Future-House/paper-qa | README/documentation is current enough for a first validation pass.

## 4. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/Future-House/paper-qa | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/Future-House/paper-qa | no_demo; severity=medium

## 6. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/Future-House/paper-qa | no_demo; severity=medium

## 7. 安全/权限坑 · 来源证据：Dependency Dashboard

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Dependency Dashboard
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/Future-House/paper-qa/issues/399 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 8. 安全/权限坑 · 来源证据：Insecure pickle deserialization in PaperQA2 persisted search indexes can lead to code execution when querying a poisone…

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Insecure pickle deserialization in PaperQA2 persisted search indexes can lead to code execution when querying a poisoned index
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/Future-House/paper-qa/issues/1325 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 9. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/Future-House/paper-qa | issue_or_pr_quality=unknown

## 10. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/Future-House/paper-qa | release_recency=unknown

<!-- canonical_name: Future-House/paper-qa; human_manual_source: deepwiki_human_wiki -->