# https://github.com/SciPhi-AI/R2R 项目说明书

生成时间：2026-06-23 08:20:56 UTC

## 目录

- [R2R Overview and System Architecture](#page-1)
- [Ingestion, Parsers, and Data Management](#page-2)
- [Retrieval, Hybrid Search, RAG, and Agentic Workflows](#page-3)
- [Deployment, SDKs, Authentication, and Extensibility](#page-4)

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

## R2R Overview and System Architecture

### 相关页面

相关主题：[Ingestion, Parsers, and Data Management](#page-2), [Retrieval, Hybrid Search, RAG, and Agentic Workflows](#page-3), [Deployment, SDKs, Authentication, and Extensibility](#page-4)

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

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

- [py/README.md](https://github.com/SciPhi-AI/R2R/blob/main/py/README.md)
- [py/sdk/README.md](https://github.com/SciPhi-AI/R2R/blob/main/py/sdk/README.md)
- [js/sdk/README.md](https://github.com/SciPhi-AI/R2R/blob/main/js/sdk/README.md)
- [py/core/main/api/v3/retrieval_router.py](https://github.com/SciPhi-AI/R2R/blob/main/py/core/main/api/v3/retrieval_router.py)
- [py/core/main/api/v3/documents_router.py](https://github.com/SciPhi-AI/R2R/blob/main/py/core/main/api/v3/documents_router.py)
- [py/core/main/api/v3/indices_router.py](https://github.com/SciPhi-AI/R2R/blob/main/py/core/main/api/v3/indices_router.py)
- [py/shared/api/models/retrieval/responses.py](https://github.com/SciPhi-AI/R2R/blob/main/py/shared/api/models/retrieval/responses.py)
- [py/shared/api/models/__init__.py](https://github.com/SciPhi-AI/R2R/blob/main/py/shared/api/models/__init__.py)
- [js/sdk/src/v3/clients/retrieval.ts](https://github.com/SciPhi-AI/R2R/blob/main/js/sdk/src/v3/clients/retrieval.ts)
- [js/sdk/src/v3/clients/documents.ts](https://github.com/SciPhi-AI/R2R/blob/main/js/sdk/src/v3/clients/documents.ts)
- [js/sdk/src/v3/clients/graphs.ts](https://github.com/SciPhi-AI/R2R/blob/main/js/sdk/src/v3/clients/graphs.ts)
- [js/sdk/src/types.ts](https://github.com/SciPhi-AI/R2R/blob/main/js/sdk/src/v3/types.ts)
- [js/sdk/package.json](https://github.com/SciPhi-AI/R2R/blob/main/js/sdk/package.json)
</details>

# 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，以及可独立部署的仪表盘项目。下图展示了仓库的主要代码层次。

```mermaid
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/` 下，按业务域切分：

| 路由模块 | 主要职责 | 关键端点 |
|----------|---------|---------|
| `retrieval_router.py` | 检索、RAG 生成与 Agent | `/retrieval/search`、`/retrieval/rag`、`/retrieval/agent` |
| `documents_router.py` | 文档与图谱关系查询 | `documents/search`、`documents/{id}/relationships` |
| `indices_router.py` | 向量索引管理 | `indices/{table}/{index}` |

资料来源：[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](https://github.com/SciPhi-AI/R2R/blob/main/py/sdk/README.md)
- JavaScript SDK 入门：[js/sdk/README.md](https://github.com/SciPhi-AI/R2R/blob/main/js/sdk/README.md)
- 检索与 Agent 路由：[py/core/main/api/v3/retrieval_router.py](https://github.com/SciPhi-AI/R2R/blob/main/py/core/main/api/v3/retrieval_router.py)
- 文档路由：[py/core/main/api/v3/documents_router.py](https://github.com/SciPhi-AI/R2R/blob/main/py/core/main/api/v3/documents_router.py)
- 索引路由：[py/core/main/api/v3/indices_router.py](https://github.com/SciPhi-AI/R2R/blob/main/py/core/main/api/v3/indices_router.py)
- 响应模型定义：[py/shared/api/models/retrieval/responses.py](https://github.com/SciPhi-AI/R2R/blob/main/py/shared/api/models/retrieval/responses.py)

---

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

## Ingestion, Parsers, and Data Management

### 相关页面

相关主题：[R2R Overview and System Architecture](#page-1), [Retrieval, Hybrid Search, RAG, and Agentic Workflows](#page-3)

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

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

- [py/README.md](https://github.com/SciPhi-AI/R2R/blob/main/py/README.md)
- [py/core/main/api/v3/retrieval_router.py](https://github.com/SciPhi-AI/R2R/blob/main/py/core/main/api/v3/retrieval_router.py)
- [py/shared/api/models/retrieval/responses.py](https://github.com/SciPhi-AI/R2R/blob/main/py/shared/api/models/retrieval/responses.py)
- [py/shared/api/models/__init__.py](https://github.com/SciPhi-AI/R2R/blob/main/py/shared/api/models/__init__.py)
- [js/sdk/README.md](https://github.com/SciPhi-AI/R2R/blob/main/js/sdk/README.md)
- [js/sdk/src/v3/clients/documents.ts](https://github.com/SciPhi-AI/R2R/blob/main/js/sdk/src/v3/clients/documents.ts)
- [js/sdk/src/v3/clients/graphs.ts](https://github.com/SciPhi-AI/R2R/blob/main/js/sdk/src/v3/clients/graphs.ts)
- [js/sdk/src/v3/clients/retrieval.ts](https://github.com/SciPhi-AI/R2R/blob/main/js/sdk/src/v3/clients/retrieval.ts)
- [js/sdk/src/types.ts](https://github.com/SciPhi-AI/R2R/blob/main/js/sdk/src/types.ts)
- [js/sdk/package.json](https://github.com/SciPhi-AI/R2R/blob/main/js/sdk/package.json)
</details>

# Ingestion, Parsers, and Data Management

## 概述

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

R2R 提供两套语言 SDK：

| SDK | 安装方式 | 主要用途 |
| --- | --- | --- |
| Python (`r2r`) | `pip install r2r` | 服务端部署、Python 客户端调用 |
| JavaScript (`r2r-js`) | `npm install r2r-js` | 浏览器 / Node.js 客户端调用 |

资料来源：[js/sdk/package.json](https://github.com/SciPhi-AI/R2R/blob/main/js/sdk/package.json)、[js/sdk/README.md](https://github.com/SciPhi-AI/R2R/blob/main/js/sdk/README.md)。

## 摄取与解析流水线

### 支持的数据格式

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

- **文本类**：`.txt`、`.html`（社区已提出对 HTML 在线页面摄取的诉求 资料来源：[Issue #2182](https://github.com/SciPhi-AI/R2R/issues/2182)）
- **文档类**：`.pdf`（自托管 Docker 模式下上传 PDF 失败的常见报错见 [Issue #2085](https://github.com/SciPhi-AI/R2R/issues/2085)）
- **结构化类**：`.json`、`.csv`
- **多媒体类**：`.png`、`.mp3`

### 摄取工作流

```mermaid
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](https://github.com/SciPhi-AI/R2R/blob/main/py/core/main/api/v3/retrieval_router.py)、[py/README.md](https://github.com/SciPhi-AI/R2R/blob/main/py/README.md)。

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

## 文档与集合管理

### 文档（Document）模型

`CollectionResponse` 与 `DocumentResponse` 是数据管理的核心模型，它们定义了拥有者、集合归属、用户数、文档数等元信息 资料来源：[js/sdk/src/types.ts](https://github.com/SciPhi-AI/R2R/blob/main/js/sdk/src/types.ts)。

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

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

资料来源：[js/sdk/src/v3/clients/documents.ts](https://github.com/SciPhi-AI/R2R/blob/main/js/sdk/src/v3/clients/documents.ts)。

### 提取（Extract）操作

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

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

资料来源：[js/sdk/src/v3/clients/documents.ts](https://github.com/SciPhi-AI/R2R/blob/main/js/sdk/src/v3/clients/documents.ts)。

### 集合（Collection）与社区（Community）

集合级别的图谱包含实体（Entity）、关系（Relationship）和社区（Community）。`createCommunity` 允许用户手动创建自定义社区，用于领域知识驱动的实体分组 资料来源：[js/sdk/src/v3/clients/graphs.ts](https://github.com/SciPhi-AI/R2R/blob/main/js/sdk/src/v3/clients/graphs.ts)。

## 检索、智能体与响应模型

R2R 的检索层提供三种入口：`search`（基础搜索）、`rag`（带引用的 RAG）、`agent`（多步推理智能体） 资料来源：[py/README.md](https://github.com/SciPhi-AI/R2R/blob/main/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](https://github.com/SciPhi-AI/R2R/blob/main/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](https://github.com/SciPhi-AI/R2R/blob/main/py/core/main/api/v3/retrieval_router.py)。对应的响应包装类型在 `py/shared/api/models/__init__.py` 中通过 `WrappedRAGResponse`、`WrappedAgentResponse` 等泛型统一对外暴露 资料来源：[py/shared/api/models/__init__.py](https://github.com/SciPhi-AI/R2R/blob/main/py/shared/api/models/__init__.py)。

## 已知问题与最佳实践

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

## See Also

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

---

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

## Retrieval, Hybrid Search, RAG, and Agentic Workflows

### 相关页面

相关主题：[R2R Overview and System Architecture](#page-1), [Ingestion, Parsers, and Data Management](#page-2)

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

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

- [py/core/main/api/v3/retrieval_router.py](https://github.com/SciPhi-AI/R2R/blob/main/py/core/main/api/v3/retrieval_router.py)
- [py/core/main/api/v3/documents_router.py](https://github.com/SciPhi-AI/R2R/blob/main/py/core/main/api/v3/documents_router.py)
- [py/shared/api/models/retrieval/responses.py](https://github.com/SciPhi-AI/R2R/blob/main/py/shared/api/models/retrieval/responses.py)
- [py/shared/api/models/__init__.py](https://github.com/SciPhi-AI/R2R/blob/main/py/shared/api/models/__init__.py)
- [js/sdk/src/v3/clients/retrieval.ts](https://github.com/SciPhi-AI/R2R/blob/main/js/sdk/src/v3/clients/retrieval.ts)
- [js/sdk/src/v3/clients/documents.ts](https://github.com/SciPhi-AI/R2R/blob/main/js/sdk/src/v3/clients/documents.ts)
- [py/README.md](https://github.com/SciPhi-AI/R2R/blob/main/py/README.md)
- [js/sdk/README.md](https://github.com/SciPhi-AI/R2R/blob/main/js/sdk/README.md)
</details>

# Retrieval, Hybrid Search, RAG, and Agentic Workflows

## 概述与设计目标

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/main/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/main/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/main/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/main/py/core/main/api/v3/documents_router.py)。

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

| 端点 | 主要用途 | 关键输入 |
| --- | --- | --- |
| `POST /retrieval/search` | 片段级/聚合级召回 | `query`, `search_mode`, `search_settings` |
| `POST /documents/search` | 文档摘要级搜索 | `query`, `search_mode`, `search_settings` |
| `POST /retrieval/rag` | 检索 + 答案生成 | `query`, `rag_generation_config` |
| `POST /retrieval/agent` | 多步代理/研究 | `message`, `mode`, `tools`, `generation_config` |

## 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/main/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/main/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/main/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/main/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/main/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/main/py/core/main/api/v3/retrieval_router.py)。

### 流程示意

```mermaid
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/main/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`

---

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

## Deployment, SDKs, Authentication, and Extensibility

### 相关页面

相关主题：[R2R Overview and System Architecture](#page-1), [Ingestion, Parsers, and Data Management](#page-2), [Retrieval, Hybrid Search, RAG, and Agentic Workflows](#page-3)

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

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

- [py/README.md](https://github.com/SciPhi-AI/R2R/blob/main/py/README.md)
- [js/sdk/README.md](https://github.com/SciPhi-AI/R2R/blob/main/js/sdk/README.md)
- [js/sdk/package.json](https://github.com/SciPhi-AI/R2R/blob/main/js/sdk/package.json)
- [js/sdk/src/types.ts](https://github.com/SciPhi-AI/R2R/blob/main/js/sdk/src/types.ts)
- [js/sdk/src/v3/clients/retrieval.ts](https://github.com/SciPhi-AI/R2R/blob/main/js/sdk/src/v3/clients/retrieval.ts)
- [js/sdk/src/v3/clients/documents.ts](https://github.com/SciPhi-AI/R2R/blob/main/js/sdk/src/v3/clients/documents.ts)
- [py/core/main/api/v3/retrieval_router.py](https://github.com/SciPhi-AI/R2R/blob/main/py/core/main/api/v3/retrieval_router.py)
- [py/core/main/api/v3/documents_router.py](https://github.com/SciPhi-AI/R2R/blob/main/py/core/main/api/v3/documents_router.py)
- [py/core/main/api/v3/graph_router.py](https://github.com/SciPhi-AI/R2R/blob/main/py/core/main/api/v3/graph_router.py)
- [py/core/main/api/v3/prompts_router.py](https://github.com/SciPhi-AI/R2R/blob/main/py/core/main/api/v3/prompts_router.py)
- [py/shared/api/models/retrieval/responses.py](https://github.com/SciPhi-AI/R2R/blob/main/py/shared/api/models/retrieval/responses.py)
- [py/shared/api/models/management/responses.py](https://github.com/SciPhi-AI/R2R/blob/main/py/shared/api/models/management/responses.py)
- [py/shared/api/models/__init__.py](https://github.com/SciPhi-AI/R2R/blob/main/py/shared/api/models/__init__.py)
</details>

# 部署、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），便于在容器编排平台中部署

```mermaid
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 项目主页](https://github.com/SciPhi-AI/R2R)
- [Python SDK 文档](https://github.com/SciPhi-AI/R2R/blob/main/py/README.md)
- [JavaScript SDK 文档](https://github.com/SciPhi-AI/R2R/blob/main/js/sdk/README.md)
- 相关 wiki 页面：检索与生成 API、知识图谱与摄取流水线

---

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

---

## Doramagic 踩坑日志

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

<!-- canonical_name: SciPhi-AI/R2R; human_manual_source: deepwiki_human_wiki -->