R2R 概览与系统架构

一、项目定位与核心能力

R2R（Retrieval-Augmented Generation to Riches）是一个开源的 RAG 答案引擎，旨在桥接本地 LLM 实验与生产级检索增强生成系统。R2R 通过 RESTful API 提供多模态内容摄取、混合搜索、知识图谱构建以及完整的文档管理能力，并内置一个名为 Deep Research API 的多步推理系统，可在本地知识库与互联网数据之间进行检索与综合推理。资料来源：py/README.md。

在官方 README 中，R2R 强调四大亮点：多模态摄取、Hybrid Search、知识图谱、Deep Research Agent。资料来源：js/sdk/README.md。

安装与运行

• Python 轻量模式：pip install r2r → export OPENAI_API_KEY=... → python -m r2r.serve。资料来源：py/README.md。
• Docker 全量模式：克隆仓库后，通过 R2R_CONFIG_NAME=full 配合 compose.full.yaml --profile postgres 启动 Postgres 与 R2R 容器。资料来源：py/README.md。
• JavaScript SDK：npm install r2r-js，随后通过 new r2rClient("http://localhost:7272") 连接。资料来源：js/sdk/package.json、js/sdk/README.md。

二、系统架构与组件分布

R2R 仓库天然划分为 Python 服务端、Python/JS 客户端 SDK，以及可独立部署的仪表盘项目。下图展示了仓库的主要代码层次。

flowchart TB
    subgraph Client["客户端 SDK"]
        PySDK["py/sdk (R2RClient)"]
        JSSDK["js/sdk (r2rClient)"]
    end
    subgraph Server["服务端（py/core）"]
        API["FastAPI 路由层<br/>v3/* routers"]
        RetRouter["retrieval_router"]
        DocRouter["documents_router"]
        IdxRouter["indices_router"]
        Models["shared/api/models<br/>Pydantic 响应模型"]
    end
    subgraph External["外部依赖"]
        Postgres[("Postgres + pgvector")]
        LLM["OpenAI / Anthropic<br/>兼容端点"]
    end
    PySDK -->|HTTP| API
    JSSDK -->|HTTP| API
    RetRouter --> Models
    DocRouter --> Models
    IdxRouter --> Models
    API --> Postgres
    API --> LLM

核心 API 路由集中在 py/core/main/api/v3/ 下，按业务域切分：

资料来源：py/core/main/api/v3/retrieval_router.py、py/core/main/api/v3/documents_router.py、py/core/main/api/v3/indices_router.py。

响应模型层 py/shared/api/models/ 统一对外暴露 RAGResponse、AgentResponse、AgentEvent、ChunkSearchResult 等类型，确保多语言 SDK 的契约一致。资料来源：py/shared/api/models/retrieval/responses.py、py/shared/api/models/__init__.py。

三、关键能力详解

摄取与文档管理

documents_router.py 在 x-codeSamples 中展示了 Python/JS/cURL 三种调用形态，覆盖列表、检索、删除、列出关系等操作。createSample 在 JS 客户端可一键下载示例 PDF 并完成摄取，便于快速验证流水线。资料来源：js/sdk/src/v3/clients/documents.ts。

检索与 RAG

retrieval_router.py 中的 /retrieval/rag 端点默认使用 config.app.quality_llm 作为生成模型，并支持流式输出；当 rag_generation_config.stream 为真时返回 text/event-stream。响应体中包含 generated_answer、search_results 与 citations。资料来源：py/core/main/api/v3/retrieval_router.py。

Deep Research Agent

/retrieval/agent 提供 RAG 模式与 Research 模式两种运行模式：RAG 模式负责基于知识库的快速问答，Research 模式额外启用 reasoning、critique、python_executor 等工具进行多步推理。流式事件类型包括 thinking、tool_call、tool_result、citation、message、final_answer。资料来源：py/core/main/api/v3/retrieval_router.py。

JS 客户端 retrieval.ts 通过 axios 的流式响应将这些事件传递给前端。资料来源：js/sdk/src/v3/clients/retrieval.ts。

知识图谱与社区

graphs.ts 提供 createCommunity 这样的手动入口，用于在自动构建之外注入业务定义的社区结构，并能与自动检测结果融合。资料来源：js/sdk/src/v3/clients/graphs.ts。

四、部署与社区关注点

社区中频繁出现的几个问题与本页描述的架构直接相关：

1. OPENAI_API_BASE 配置（Issue #2020）：用户希望通过环境变量替换 OpenAI base_url，但默认 OPENAI_API_BASE 未被识别。这是配置层面的兼容性问题，需要确认 R2R 配置文件中的对应字段。资料来源：py/README.md。
2. Docker 自托管搜索不可用（Issue #2085）：在 Docker 模式下摄取 PDF 后 RAG 检索失败，提示需要确认 Postgres/向量索引在容器化环境中是否正确初始化、配置中是否启用了默认嵌入模型。资料来源：py/README.md。
3. HTML 摄取能力（Issue #2182）：目前缺少直接传入 URL 进行抓取并摄取的工作流，需要结合外部抓取脚本与 R2R 摄取端点手动串联。资料来源：js/sdk/src/v3/clients/documents.ts。
4. 跳过图谱抽取（Issue #2243）：用户希望仅生成 chunks 与 embeddings，跳过知识图谱抽取；这要求在摄取时通过 ingestion 配置禁用图谱管线。资料来源：py/core/main/api/v3/documents_router.py。
5. 官方文档站点故障（Issue #2276）：r2r-docs.sciphi.ai 出现 DEPLOYMENT_NOT_FOUND 错误，本仓库源码本身不直接受影响，但建议通过 py/README.md 与 js/sdk/README.md 中的内嵌示例学习使用方法。资料来源：py/README.md。

最新发布 v3.6.5 增强了 rag 工具的上下文处理，支持非 Claude 模型的 extended_thinking，并改进了 collection_id 在 chunk 创建中的传递。资料来源：py/core/main/api/v3/retrieval_router.py。

See Also

• Python SDK 入门：py/sdk/README.md
• JavaScript SDK 入门：js/sdk/README.md
• 检索与 Agent 路由：py/core/main/api/v3/retrieval_router.py
• 文档路由：py/core/main/api/v3/documents_router.py
• 索引路由：py/core/main/api/v3/indices_router.py
• 响应模型定义：py/shared/api/models/retrieval/responses.py

概述

R2R（Reason to Retrieve）是一个面向检索增强生成（RAG）场景的全栈应用框架。其核心能力之一是多模态数据摄取（Ingestion）、解析（Parsing）和数据管理（Data Management）。系统通过统一的 RESTful API 暴露文档处理能力，支持文本、PDF、JSON、PNG、MP3 等多种格式，并自动构建知识图谱和向量索引以支撑混合检索与智能体问答 资料来源：py/README.md。

R2R 提供两套语言 SDK：

资料来源：js/sdk/package.json、js/sdk/README.md。

摄取与解析流水线

支持的数据格式

R2R 的摄取入口覆盖结构化、半结构化与非结构化数据：

• 文本类：.txt、.html（社区已提出对 HTML 在线页面摄取的诉求 资料来源：Issue #2182）
• 文档类：.pdf（自托管 Docker 模式下上传 PDF 失败的常见报错见 Issue #2085）
• 结构化类：.json、.csv
• 多媒体类：.png、.mp3

摄取工作流

flowchart LR
    A[客户端 SDK] --> B[POST /ingest]
    B --> C{解析器分发}
    C -->|文本| D[Text Parser]
    C -->|PDF| E[PDF Parser]
    C -->|JSON/CSV| F[Structured Parser]
    D --> G[分块 & Embedding]
    E --> G
    F --> G
    G --> H[向量索引]
    G --> I[知识图谱抽取]
    I --> J[Entity / Relationship / Community]
    H --> K[(Postgres + pgvector)]
    J --> K
    K --> L[检索 / RAG / Agent]

资料来源：py/core/main/api/v3/retrieval_router.py、py/README.md。

社区用户希望跳过知识图谱抽取、仅生成分块与 Embedding 以提升性能 资料来源：Issue #2243。该需求与 R2R 的可配置摄取管道方向一致——通过在摄取请求中按需启用/禁用图谱相关步骤即可实现。

文档与集合管理

文档（Document）模型

CollectionResponse 与 DocumentResponse 是数据管理的核心模型，它们定义了拥有者、集合归属、用户数、文档数等元信息 资料来源：js/sdk/src/types.ts。

文档级元数据可被追加或更新：

await client.documents.appendMetadata({
    id: "9fbe403b-c11c-5aae-8ade-ef22980c3ad1",
    metadata: [{ key: "new_key", value: "new_value" }],
});

资料来源：js/sdk/src/v3/clients/documents.ts。

提取（Extract）操作

extract 方法支持对已上传文档触发实体/关系抽取流程，并可选择是否使用编排（orchestration）异步执行：

await client.documents.extract({
  id: "...",
  settings: { /* 覆盖默认抽取配置 */ },
  runWithOrchestration: true,
});

资料来源：js/sdk/src/v3/clients/documents.ts。

集合（Collection）与社区（Community）

集合级别的图谱包含实体（Entity）、关系（Relationship）和社区（Community）。createCommunity 允许用户手动创建自定义社区，用于领域知识驱动的实体分组 资料来源：js/sdk/src/v3/clients/graphs.ts。

检索、智能体与响应模型

R2R 的检索层提供三种入口：search（基础搜索）、rag（带引用的 RAG）、agent（多步推理智能体） 资料来源：py/README.md。agent 端点支持 rag 与 research 两种模式：

• RAG 模式：使用 search_file_knowledge、web_search、web_scrape 等工具；
• Research 模式：额外启用 reasoning、critique、python_executor 工具 资料来源：py/core/main/api/v3/retrieval_router.py。

流式响应事件类型包括 thinking、tool_call、tool_result、citation、message、final_answer 资料来源：py/core/main/api/v3/retrieval_router.py。对应的响应包装类型在 py/shared/api/models/__init__.py 中通过 WrappedRAGResponse、WrappedAgentResponse 等泛型统一对外暴露 资料来源：py/shared/api/models/__init__.py。

已知问题与最佳实践

• 自托管 Docker 下检索失败（Issue #2085）：PDF 上传成功后聊天/搜索不返回结果，需检查向量库迁移与 OPENAI_API_KEY 配置。
• 自定义 OpenAI Base URL（Issue #2020）：使用 OPENAI_API_BASE 环境变量未生效，建议核对 SDK 是否正确转发 base_url 字段。
• HTML 在线页面摄取（Issue #2182）：当前需借助 web_scrape 工具或预抓取后通过文件上传。
• 跳过图谱抽取（Issue #2243）：在摄取配置中按需关闭图谱相关步骤，仅保留分块与 Embedding。

See Also

• R2R GitHub 仓库：SciPhi-AI/R2R
• Python SDK 入口：py/README.md
• JavaScript SDK 入口：js/sdk/README.md
• 检索与智能体 API：py/core/main/api/v3/retrieval_router.py
• 响应模型索引：py/shared/api/models/__init__.py

概述与设计目标

R2R（Retrieval-Augmented Generation with RESTful API）将检索、混合搜索、知识图谱增强与多轮智能体（Agent）能力整合为一套统一的工作流。其核心入口由 RetrievalRouter 暴露的 HTTP 端点以及对应的服务层承担，覆盖从「单次语义搜索」到「多步推理研究」的多层级用例 资料来源：[py/core/main/api/v3/retrieval_router.py:1-3](https://github.com/SciPhi-AI/R2R/blob/9c5a94d151f90876bd7eb860f300a8fd662dc481/py/core/main/api/v3/retrieval_router.py)。

从仓库描述中可以看到，R2R 同时提供三种使用方式：

• 基础语义/混合搜索（/retrieval/search），用于直接召回文档片段或文件摘要；
• RAG 生成（/retrieval/rag），在召回之上拼接上下文，由 LLM 生成带引用（citations）的回答；
• Agent 智能体（/retrieval/agent），支持 rag 与 research 两种模式，可进行多步工具调用与推理 资料来源：[py/README.md]()。

整体目标是让开发者既能像调用普通搜索引擎一样使用 R2R，也能在不切换 SDK 的前提下扩展为复杂研究型代理。

搜索模式与混合检索

RetrievalRouter 通过 SearchMode 枚举区分三种预置行为：basic、advanced 与 custom。_prepare_search_settings 负责将模式默认值与用户提供的 SearchSettings 进行合并，再叠加基于身份认证的过滤条件 资料来源：[py/core/main/api/v3/retrieval_router.py:19-39](https://github.com/SciPhi-AI/R2R/blob/9c5a94d151f90876bd7eb860f300a8fd662dc481/py/core/main/api/v3/retrieval_router.py)。

• basic：纯语义搜索（基于向量嵌入）；
• advanced：混合搜索，结合语义检索与全文检索，使用 Reciprocal Rank Fusion（RRF）进行结果融合；
• custom：完全由调用方控制 search_settings，常用于自定义权重、过滤器和图谱开关。

混合搜索的可调参数包括 full_text_weight、semantic_weight、full_text_limit、rrf_k 等，可在 SearchSettings 中按请求覆盖 资料来源：[py/core/main/api/v3/retrieval_router.py:160-220](https://github.com/SciPhi-AI/R2R/blob/9c5a94d151f90876bd7eb860f300a8fd662dc481/py/core/main/api/v3/retrieval_router.py)。知识图谱增强默认开启，可通过 graph_search_settings.use_graph_search 与 kg_search_type（local / global）控制。documents_router 中还提供了 /documents/search 端点，专注于自动生成的文件摘要检索 资料来源：[py/core/main/api/v3/documents_router.py:1-40](https://github.com/SciPhi-AI/R2R/blob/9c5a94d151f90876bd7eb860f300a8fd662dc481/py/core/main/api/v3/documents_router.py)。

下表概括了搜索相关端点与典型用途：

RAG 端点与生成配置

/retrieval/rag 在搜索结果之上调用 LLM 进行生成。rag_generation_config 支持 model、temperature、max_tokens、stream 等字段，模型来源可为 OpenAI、Anthropic（需 ANTHROPIC_API_KEY）或任何 LiteLLM 兼容的本地/远端服务 资料来源：[py/core/main/api/v3/retrieval_router.py:60-130](https://github.com/SciPhi-AI/R2R/blob/9c5a94d151f90876bd7eb860f300a8fd662dc481/py/core/main/api/v3/retrieval_router.py)。

RAGResponse 同时携带 generated_answer、search_results 与结构化的 citations（每条 citation 含有 id、object 与 payload，payload 可为 ChunkSearchResult、GraphSearchResult、WebPageSearchResult 或 DocumentResponse）资料来源：[py/shared/api/models/retrieval/responses.py:1-60](https://github.com/SciPhi-AI/R2R/blob/9c5a94d151f90876bd7eb860f300a8fd662dc481/py/shared/api/models/retrieval/responses.py)。

当 stream=true 时，端点以 text/event-stream（SSE）形式返回，可能事件类型包括 search_results、message（增量 token）、citation 和 final_answer；非流式响应则是同步 JSON 资料来源：[py/core/main/api/v3/retrieval_router.py:130-180](https://github.com/SciPhi-AI/R2R/blob/9c5a94d151f90876bd7eb860f300a8fd662dc481/py/core/main/api/v3/retrieval_router.py)。

Agentic Workflows：RAG 与 Research 双模式

/retrieval/agent 是 R2R 智能体能力的核心，区分两种运行模式 资料来源：[py/core/main/api/v3/retrieval_router.py:180-260](https://github.com/SciPhi-AI/R2R/blob/9c5a94d151f90876bd7eb860f300a8fd662dc481/py/core/main/api/v3/retrieval_router.py)：

• rag 模式：默认模式，强调快速知识检索与生成，模型默认为 config.app.quality_llm；
• research 模式：在 RAG 之上叠加 reasoning（专门推理模型）、critique（自检偏差与逻辑漏洞）、python_executor（执行 Python 做计算分析），并通过 research_generation_config 单独配置生成参数；模型默认为 config.app.planning_llm。

可用工具集在两种模式下分别维护（rag_tools / research_tools），并通过 mode 字段自动选通。RAG 模式下可使用 search_file_knowledge、search_file_descriptions、content、web_search、web_scrape；Research 模式下则可使用 rag、reasoning、critique、python_executor 资料来源：[js/sdk/src/v3/clients/retrieval.ts:1-80](https://github.com/SciPhi-AI/R2R/blob/9c5a94d151f90876bd7eb860f300a8fd662dc481/js/sdk/src/v3/clients/retrieval.ts)。

对话上下文通过 conversation_id 维持；首次调用后由服务端自动分配 ID 并在响应中回传，后续请求必须带上该字段以保留多轮记忆 资料来源：[py/core/main/api/v3/retrieval_router.py:230-260](https://github.com/SciPhi-AI/R2R/blob/9c5a94d151f90876bd7eb860f300a8fd662dc481/py/core/main/api/v3/retrieval_router.py)。

流程示意

sequenceDiagram
    participant Client
    participant Router as /retrieval/agent
    participant Service as RetrievalService
    participant LLM as 规划/质量模型
    participant Tools as 工具集
    Client->>Router: POST message + mode=research
    Router->>Service: 构造 effective_settings 与 config
    Service->>Tools: 调用 rag/reasoning/python_executor
    Tools-->>Service: 返回检索/计算结果
    Service->>LLM: 汇总上下文并请求生成
    LLM-->>Service: 增量 tokens / thinking
    Service-->>Router: SSE 事件流
    Router-->>Client: thinking/tool_call/tool_result/citation/final_answer

流式事件类型

代理端点启用 stream=true 时输出统一的 AgentEvent 联合类型，按出现顺序大致为 资料来源：[py/shared/api/models/retrieval/responses.py:10-30](https://github.com/SciPhi-AI/R2R/blob/9c5a94d151f90876bd7eb860f300a8fd662dc481/py/shared/api/models/retrieval/responses.py)：

• thinking：模型逐步推理（仅在 extended_thinking=true 时出现）；
• tool_call / tool_result：智能体调用工具的输入与输出；
• citation：在回答中插入新的引用；
• message：增量文本 token；
• final_answer：包含完整答案和结构化 citations 的结束事件。

常见使用陷阱与社区反馈

• 自托管 Docker 模式 Q&A 无响应（issue #2085）：安装并上传 PDF 后 RAG/搜索不可用。常见原因是 OPENAI_API_KEY 未注入容器或检索向量库未初始化。R2R 在启动期会校验关键环境变量，缺失时 _prepare_search_settings 仍可执行，但后续 LLM 调用会失败。
• 自定义 OPENAI_API_BASE 不生效（issue #2020）：仅设置 OPENAI_API_BASE 无法改变 LLM 路由，需同时配置 LiteLLM 兼容参数（如 OPENAI_BASE_URL），并在 rag_generation_config.model 中使用 provider 前缀（如 openai/...）。
• 仅嵌入与切片、不要图谱（issue #2243）：可在摄取时关闭 graph_search_settings 或在自定义 ingestion pipeline 中跳过实体抽取，使 RAG 阶段只消费向量结果。
• HTML 摄取（issue #2182）：当前 SDK 文档未提供 documents.create 的 URL 模式，需要先用 web_scrape 抓取内容后写入临时文件再走常规摄取流程，或结合 web_search + web_scrape 工具在 Agent 内动态抓取。

See Also

• Documents & Collections 文档管理：参考 py/core/main/api/v3/documents_router.py
• Ingestion 流水线与图谱抽取：参考 py/shared/abstractions/vector.py 与 py/core/main/services/ingestion_service.py
• JS/TS SDK 客户端：参考 js/sdk/src/v3/clients/retrieval.ts 与 js/sdk/src/v3/clients/documents.ts

部署、SDK、身份认证与扩展性

R2R（SciPhi-AI/R2R）是一个面向检索增强生成（RAG）的多模态智能检索框架，本页面汇总其部署形态、官方 SDK、身份认证机制以及关键扩展点，便于开发者快速上手并按业务需求进行定制。

一、部署模式

R2R 提供"轻量模式（light）"与"完整模式（full）"两种部署形态，以适配不同的运行场景。

• 轻量模式：通过 pip install r2r 后执行 python -m r2r.serve 即可启动，适用于本地开发与快速验证，只需配置 OPENAI_API_KEY 等关键环境变量即可使用 资料来源：py/README.md
• 完整模式：通过仓库根目录的 docker compose -f compose.full.yaml --profile postgres up -d 启动，会拉起 Postgres、外部向量库以及可选服务（知识图谱、深度研究 Agent 等），适合生产环境 资料来源：py/README.md
• Kubernetes 部署：v3.6.5 版本引入了基于 Kustomize 的 k8s 清单（PR #2150），便于在容器编排平台中部署

graph LR
  A[开发者] -->|pip install| B[Light 模式]
  A -->|docker compose| C[Full 模式]
  A -->|kustomize| D[k8s 集群]
  B --> E[(本地向量库)]
  C --> F[(Postgres)]
  C --> G[(外部向量库)]
  C --> H[知识图谱服务]
  C --> I[深度研究 Agent]

环境变量集中维护在 docker/env/r2r.env 与 docker/env/r2r-full.env 中。社区问题 #2020 反馈 OPENAI_API_BASE 未被识别，按 R2R 文档应统一使用该变量指向兼容 OpenAI 协议的网关；若异常，需确认是否启用了 R2R_CONFIG_NAME=full 完整配置。社区问题 #2085 反馈 Docker 自托管模式下检索失败，多因环境变量未正确注入 Postgres 容器，建议参照 r2r-full.env 重建后再启动。

二、官方 SDK

R2R 同时提供 Python 与 JavaScript/TypeScript 两套官方客户端，均通过 RESTful API 与后端通信。

Python SDK

安装命令为 pip install r2r，典型用法包括 client.retrieval.search、client.retrieval.rag 与 client.retrieval.agent 资料来源：py/README.md。其完整流程涵盖登录（client.login）、文档摄取（client.documents.create）、列表查询（client.documents.list）等。

JavaScript SDK

通过 npm install r2r-js 安装 资料来源：js/sdk/README.md，依赖 axios（^1.8.4）与 uuid（^10.0.0）资料来源：js/sdk/package.json。SDK 在 js/sdk/src/v3/clients/ 下组织各领域客户端，例如 retrieval.ts 的 agent() 方法同时支持 RAG mode 与 Research mode，允许传入 searchMode、ragGenerationConfig 等参数；documents.ts 则封装了文档导出（exportEntities）、抽取（extract）等操作 资料来源：js/sdk/src/v3/clients/documents.ts。

两套 SDK 的响应结构保持一致，遵循 R2RResults[T] 包装模型。核心响应类型（如 RAGResponse、AgentResponse、DocumentSearchResult）分别在 py/shared/api/models/retrieval/responses.py 与 js/sdk/src/types.ts 中声明 资料来源：py/shared/api/models/__init__.py。

三、身份认证

R2R 的认证基于"用户账户 + API Key"双轨机制：

• 账户登录：调用 client.login(email, password) 即可换取访问令牌，后续请求通过 auth_wrapper() 注入当前用户上下文 资料来源：js/sdk/README.md
• API Key：ApiKey 模型（在 js/sdk/src/types.ts 中定义）包含 publicKey、keyId 以及仅在创建时返回一次的私有 apiKey，可在 Dashboard 或后端 API 中生成，用于服务间调用 资料来源：js/sdk/src/types.ts
• 权限模型：路由层在调用服务前会检查 auth_user.is_superuser。例如 prompts_router.py 中创建 prompt 仅允许超级用户；graph_router.py 中创建关系同样限制为超级用户 资料来源：py/core/main/api/v3/graph_router.py

四、扩展性

R2R 通过检索模式、Agent 工具与自定义 Prompt 三类扩展点支持业务定制：

• 检索模式：SearchMode 枚举提供 basic（纯语义）、advanced（语义 + 全文混合）和 custom（完全可控）三档；若同时传入 filters 或 limit，将覆盖对应模式的默认配置 资料来源：py/core/main/api/v3/documents_router.py
• Agent 工具集：RAG 模式工具包括 search_file_knowledge、search_file_descriptions、content、web_search、web_scrape；Research 模式额外提供 reasoning、critique、python_executor 资料来源：py/core/main/api/v3/retrieval_router.py
• 自定义 Prompt：通过 POST /prompts 注册模板并指定 input_types，由超级用户管理 资料来源：py/core/main/api/v3/prompts_router.py
• 流式响应：当 rag_generation_config.stream=True 时，/retrieval/rag 切换为 SSE 流式输出；未显式指定 model 时会回退到 self.config.app.quality_llm

针对社区需求（如 #2243 "无图谱摄取"），可在摄取接口中跳过图谱提取，仅生成 chunks 与 embeddings，从而精简流水线。

See Also

• R2R 项目主页
• Python SDK 文档
• JavaScript SDK 文档
• 相关 wiki 页面：检索与生成 API、知识图谱与摄取流水线

Pitfall Log / 踩坑日志

项目：SciPhi-AI/R2R

摘要：发现 14 个潜在踩坑项，其中 3 个为 high/blocking；最高优先级：安装坑 - 来源证据：r2r-docs.sciphi.ai Website Down。

1. 安装坑 · 来源证据：r2r-docs.sciphi.ai Website Down

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：r2r-docs.sciphi.ai Website Down
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/SciPhi-AI/R2R/issues/2276 | 来源类型 github_issue 暴露的待验证使用条件。

2. 安全/权限坑 · 来源证据：Docs suggestion: add a compact RAG failure mode taxonomy checklist for incident triage

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Docs suggestion: add a compact RAG failure mode taxonomy checklist for incident triage
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/SciPhi-AI/R2R/issues/2279 | 来源类型 github_issue 暴露的待验证使用条件。

3. 安全/权限坑 · 来源证据：[Security][High] SQL injection in vector index management (create_index / delete_index)

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Security][High] SQL injection in vector index management (create_index / delete_index)
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/SciPhi-AI/R2R/issues/2290 | 来源类型 github_issue 暴露的待验证使用条件。

4. 安装坑 · 来源证据：Broken Link For Installation Guide

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Broken Link For Installation Guide
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/SciPhi-AI/R2R/issues/1820 | 来源类型 github_issue 暴露的待验证使用条件。

5. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 证据：capability.host_targets | https://github.com/SciPhi-AI/R2R | host_targets=claude, chatgpt

6. 配置坑 · 来源证据：The search fails on huge query

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：The search fails on huge query
• 对用户的影响：可能阻塞安装或首次运行。
• 证据：community_evidence:github | https://github.com/SciPhi-AI/R2R/issues/2293 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

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

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

8. 维护坑 · 来源证据：Entity UUID Mismatch After Graph Pul

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：Entity UUID Mismatch After Graph Pul
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/SciPhi-AI/R2R/issues/2289 | 来源类型 github_issue 暴露的待验证使用条件。

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

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

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/SciPhi-AI/R2R | no_demo; severity=medium

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

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

12. 安全/权限坑 · 来源证据：[Security] CRITICAL auth bypass (default admin superuser for unauthenticated requests) + JWT type confusion + password…

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Security] CRITICAL auth bypass (default admin superuser for unauthenticated requests) + JWT type confusion + password change doesn't revoke tokens
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/SciPhi-AI/R2R/issues/2295 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

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

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

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

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