paper-qa 项目说明书

Doramagic 项目包 · 项目说明书

paper-qa 项目

高精度 RAG，用于基于科学文献回答问题并给出引用来源

PaperQA2 概览与快速开始

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

章节 相关页面

继续阅读本节完整说明和来源证据。

章节 安装主包与基础使用

继续阅读本节完整说明和来源证据。

章节 选择 PDF 解析后端

继续阅读本节完整说明和来源证据。

章节 集成文献来源

继续阅读本节完整说明和来源证据。

简介与核心能力

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

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。

快速开始

安装主包与基础使用

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

随后通过环境变量提供 LLM 凭据，例如 OPENAI_API_KEY，并在 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。

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

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

章节 相关页面

继续阅读本节完整说明和来源证据。

一、整体架构概览

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

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

层级	职责	关键模块
入口层	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

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

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

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

三、数据流：从 PDF 到答案

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

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[最终答案 + 引用]

各阶段关键实现：

paper-qa-docling 则基于 StandardPdfPipeline，支持 dpi、images_scale、parse_media 等参数，并能识别 PictureItem 与 TableItem。资料来源：packages/paper-qa-docling/src/paperqa_docling/reader.py:1-60 paper-qa-nemotron 则通过 NVIDIA nemotron-parse VLM 完成版面理解，并在 NemotronParseBBox 中以归一化坐标进行几何建模。资料来源：packages/paper-qa-nemotron/src/paperqa_nemotron/api.py:1-50

解析阶段：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

索引阶段：agent_index 通过 make_index_from_csv-式入口扫描 paper_directory，按 files_filter 过滤并写入 Tantivy 索引，字段包含 title、year 与必备字段。资料来源：src/paperqa/agents/search.py:1-50

SimpleProfiler 则记录各阶段耗时，用于性能追踪。资料来源：src/paperqa/agents/models.py:1-60

Agent 阶段：PQASession 维护 question、answer、cost 等运行时状态；EnvironmentState 在 reset() 时初始化 docs 与可选的临床试验状态函数。资料来源：src/paperqa/agents/env.py:40-90

OpenReviewPaperHelper 则异步下载 OpenReview 提交 PDF，与主索引共享 paper_directory。资料来源：src/paperqa/contrib/openreview_paper_helper.py:1-40

集成数据源：ZoteroDB 继承 pyzotero，通过 ZOTERO_USER_ID / ZOTERO_API_KEY 自动认证，并把 PDF 下载到 ~/.paperqa/zotero 后再走解析管线。资料来源：src/paperqa/contrib/zotero.py:1-60

四、常见失败模式

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
解析失败：docling 解析器对跨页 TableItem 抛出 NotImplementedError，需在自定义 pipeline 中预先拆分。资料来源：packages/paper-qa-docling/src/paperqa_docling/reader.py:40-70

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

PaperQA 通过 LiteLLM 抽象层来对接 LLM 和嵌入模型提供方。agents/models.py 中的代码 LiteLLMModel(name=llmmodel) if isinstance(llmmodel, str) else llmmodel 显示,只要传入字符串模型名称,框架就会自动构造 LiteLLM 适配器,因此任何 LiteLLM 支持的提供方(...

章节 相关页面

继续阅读本节完整说明和来源证据。

概述

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 加载该文件。

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 集成》

资料来源:src/paperqa/agents/models.py

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

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

章节 相关页面

继续阅读本节完整说明和来源证据。

章节 pypdf 后端

继续阅读本节完整说明和来源证据。

章节 PyMuPDF 后端

继续阅读本节完整说明和来源证据。

章节 Docling 后端

继续阅读本节完整说明和来源证据。

概述与架构

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

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 或调大阈值规避。

失败模式与踩坑日记

保留 Doramagic 在发现、验证和编译中沉淀的项目专属风险，不把社区讨论只当作装饰信息。

medium 来源证据：Is it possible to choose which articles to index and query in the paper directory?

可能影响升级、迁移或版本选择。

medium 来源证据：CMYK images in PDFs crash indexing with OSError

可能阻塞安装或首次运行。

medium 能力判断依赖假设

假设不成立时，用户拿不到承诺的能力。

medium 维护活跃度未知

新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。

Pitfall Log / 踩坑日志

项目：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

来源：Doramagic 发现、验证与编译记录

paper-qa 项目

PaperQA2 概览与快速开始

简介与核心能力

架构与数据流

快速开始

安装主包与基础使用

选择 PDF 解析后端

集成文献来源

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

常见问题与故障排查

See Also

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

一、整体架构概览

二、设置系统（Settings & Prompts）

三、数据流：从 PDF 到答案

四、常见失败模式

See Also

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

概述

配置文件层级与默认模型

Azure OpenAI 与本地 LLM 配置

速率限制与并发控制

常见失败模式

嵌入模型与解析后端选择

参见

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

概述与架构

PDF 解析器实现

pypdf 后端

PyMuPDF 后端

Docling 后端

Nemotron-parse VLM 后端

外部元数据源集成

Zotero

OpenReview

其他元数据客户端

配置预设

常见故障与社区反馈

See Also

失败模式与踩坑日记

Pitfall Log / 踩坑日志

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

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

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

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

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

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

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

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

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