R2R 快速入门从 SDK 安装到 Streaming Agentic RAG 的完整实践指南【免费下载链接】R2RSoTA production-ready AI retrieval system. Agentic Retrieval-Augmented Generation (RAG) with a RESTful API.项目地址: https://gitcode.com/GitHub_Trending/r2/R2R本篇技术指南以 R2R 官方入门文档docs/documentation/README.md为主体系统讲解如何搭建 R2R 环境、安装 Python/JavaScript SDK、初始化客户端、摄取文档、执行向量检索以及通过标准 RAG、流式 RAG 与 Agentic RAG 构建 AI 文档理解应用。文章结合当前仓库的 SDK 与 API 路由源码补充了客户端默认配置、摄取模式、检索模式、过滤语法与流式事件类型等底层细节读者读完即可上手写出可运行的检索与问答代码。一、开始之前账号、API Key 与本地部署R2R 的官方入门文档建议先创建账号以使用托管服务同时明确指出需要本地部署的用户应参阅本地安装指南。在当前仓库中与本地部署直接相关的资源包括docker/compose.yaml 与 docker/compose.full.yamlDocker Compose 编排文件覆盖单机与完整含 Hatchet 编排、PostgreSQL/PGVector 等两种形态py/DockerfilePython 服务端镜像构建文件py/r2r/r2r.tomlR2R 服务端核心配置文件模型、嵌入、数据库等。无论是使用托管服务还是本地实例后续代码示例都通过 RESTful API默认地址http://localhost:7272与服务端通信因此只需一个可访问的 R2R 端点即可跟随本文实践。关于认证R2R 提供完整的用户认证能力。从 py/core/providers/auth 目录的源码结构看认证层包含多种实现基于 JWT 的内置认证jwt.py、r2r_auth.py以及可选的 Clerk、Supabase 等第三方提供商集成。使用 API Key 认证时客户端会通过环境变量读取密钥详见下文。二、安装 SDKR2R 官方提供 Python 与 JavaScript 两套 SDK用于与 REST API 交互。Python SDKpip install r2rPython SDK 的源码位于仓库 py/sdk 目录包入口 py/sdk/init.py 同时导出了R2RClient同步与R2RAsyncClient异步两个客户端类分别定义于 py/sdk/sync_client.py 与 py/sdk/async_client.py。JavaScript SDKnpm i r2r-jsJS SDK 源码位于仓库 js/sdk/src 目录核心类r2rClient定义于 js/sdk/src/r2rClient.ts并从 js/sdk/src/index.ts 导出。三、初始化客户端初始化客户端时需要先设置 API Key。文档推荐通过环境变量注入密钥避免将凭据硬编码在代码中# Python / JS 通用 export R2R_API_KEY...Python 同步客户端from r2r import R2RClient client R2RClient() # 可通过 R2RClient(base_url...) 指向远程实例 # 或者如果使用账号密码认证 # client.users.login(myemail.com, my_strong_password)JavaScript// export R2R_API_KEY... const { r2rClient } require(r2r-js); const client new r2rClient(); // 可通过设置 baseURL 指向远程实例 // 或者如果使用账号密码认证 // client.users.login(myemail.com, my_strong_password)从源码看客户端的默认行为由 py/sdk/base/base_client.py 中的BaseClient决定值得注意的默认值包括base_url默认取环境变量R2R_API_BASE未设置时回退为http://localhost:7272api_key默认从环境变量R2R_API_KEY读取无需手动传入认证头有两种形态设置 access token 时发送Authorization: Bearer token仅设置 API Key 时发送x-api-key头base_client.py请求默认超时时间为 300 秒。同时客户端按资源领域划分了多个子模块documents、retrieval、chunks、collections、conversations、graphs、indices、prompts、system、users本文涉及的是其中的documents与retrieval两部分。四、摄取文件Ingesting Files向 R2R 摄取文件时服务端会接受任务、对文件进行解析与分块chunking并生成文档摘要。官方文档给出了一行示例Pythonclient.documents.create_sample(hi_resTrue) # 摄取你自己的文档client.documents.create(file_path/path/to/file)JavaScriptclient.documents.createSample({ ingestionMode: hi-res }) // 摄取你自己的文档client.documents.create({filePath: /path/to/file})示例返回IngestionResponse(messageDocument created and ingested successfully., task_idNone, document_idUUID(e43864f5-a36f-548e-aacd-6f8d48b30c7f))4.1 create 方法的多形态输入从 py/sdk/asnyc_methods/documents.py 的DocumentsSDK.create源码documents.py可以看到实际的生产级入口支持四种互斥的内容来源且必须且只能提供其中一种参数含义file_path本地文件路径SDK 以multipart/form-data上传raw_text直接传入原始文本内容chunks传入已经预处理好的文本块列表跳过服务端分块s3_url预签名 S3 URLSDK 会先下载再上传此外还支持id自定义文档 ID不传则服务端生成metadata文档元数据如 title、自定义字段以 JSON 字符串随请求提交collection_ids关联的集合 ID 列表默认放入用户默认集合ingestion_mode摄取模式预设ingestion_config自定义摄取配置配合custom模式使用run_with_orchestration是否走编排系统异步执行默认True设为False时同步执行并直接返回结果。4.2 四种摄取模式服务端在 py/core/main/api/v3/documents_router.py 中定义了摄取模式的官方语义documents_router.pyhi-res高质量摄取生成完整摘要并做文档丰富化enrichmentocr通过 Mistral OCR 处理扫描件/图片类文档并生成完整摘要fast快速摄取最小化丰富化、不生成摘要custom完全通过ingestion_config自定义控制。当选择非custom模式时服务端会以该模式的默认配置为起点再与用户传入的ingestion_config合并覆盖documents_router.py。五、获取文件状态摄取完成后异步场景下任务可能仍在执行通过列出文档即可查看状态。Python / JavaScriptclient.documents.list()client.documents.list()cURLcurl -X GET http://localhost:7272/v3/documents \ -H Content-Type: application/json示例输出[ DocumentResponse( idUUID(e43864f5-a36f-548e-aacd-6f8d48b30c7f), collection_ids[UUID(122fdf6a-e116-546b-a8f6-e4cb2e2c0a09)], owner_idUUID(2acb499e-8428-543b-bd85-0d9098718220), document_typeDocumentType.PDF: pdf, metadata{title: DeepSeek_R1.pdf, version: v0}, versionv0, size_in_bytes1768572, ingestion_statusIngestionStatus.SUCCESS: success, extraction_statusGraphExtractionStatus.PENDING: pending, created_atdatetime.datetime(2025, 2, 8, 3, 31, 39, 126759, tzinfoTzInfo(UTC)), updated_atdatetime.datetime(2025, 2, 8, 3, 31, 39, 160114, tzinfoTzInfo(UTC)), ingestion_attempt_numberNone, summaryThe document contains a comprehensive overview of DeepSeek-R1..., summary_embeddingNone, total_tokens29673 ), ... ]这份响应字段值得逐一解读document_type文档类型如pdf仓库 py/core 下的parsers目录按文本、结构化、媒体三类实现了 30 余种格式解析器PDF、DOCX、XLSX、EPUB、HTML、CSV、音频、图片等可在 py/core/parsers 中查看ingestion_status摄取状态如successextraction_status知识图谱抽取状态如pending后续可使用图搜索的前提是完成实体/关系抽取summary摄取阶段自动生成的文档摘要total_tokens文档累计消耗的 token 数。documents.list()还支持分页与过滤参数如offset默认 0、limit默认 100上限 1000、ids、owner_only等详见 py/sdk/asnyc_methods/documents.py。六、执行检索Search摄取完成后即可对文档内容进行语义检索。Pythonclient.retrieval.search( queryWhat is DeepSeek R1?, )JavaScriptclient.retrieval.search({ query: What is DeepSeek R1?, })cURLcurl -X POST http://localhost:7272/v3/retrieval/search \ -H Content-Type: application/json \ -d { query: What is DeepSeek R1? }示例输出AggregateSearchResult( chunk_search_results[ ChunkSearchResult( score0.643, textDocument Title: DeepSeek_R1.pdf Text: could achieve an accuracy of over 70%. DeepSeek-R1 also delivers impressive results on IF-Eval... ), ... ], graph_search_results[], web_search_results[], context_document_results[] )6.1 检索模式与高级配置默认情况下这是基础的向量相似度检索。官方文档提示可以按需切换到更高级的检索方式混合检索hybrid search或知识图谱检索graph search。从服务端路由 py/core/main/api/v3/retrieval_router.py 的接口定义retrieval_router.py可以看到search端点支持三种search_modebasic纯语义搜索简单易用advanced语义搜索 全文搜索的混合检索结果更全面custom默认完全通过search_settings精细控制。同时search_settings支持以下高频配置均有官方 API 语义支撑元数据过滤支持$eq、$neq、$gt、$gte、$lt、$lte、$like、$ilike、$in、$nin等比较运算符以及$and/$or组合逻辑{ search_settings: { filters: {document_id: {$eq: e43864f5-a36f-548e-aacd-6f8d48b30c7f}} } }复杂条件示例{ search_settings: { filters: { $and: [ {document_type: {$eq: pdf}}, {metadata.year: {$gt: 2020}} ] } } }混合检索开关设置use_hybrid_search: true并用hybrid_settings调节权重{ search_settings: { use_hybrid_search: true, hybrid_settings: { full_text_weight: 1.0, semantic_weight: 5.0, full_text_limit: 200, rrf_k: 50 } } }图谱增强检索默认开启可显式控制kg_search_type如local{ search_settings: { graph_search_settings: { use_graph_search: true, kg_search_type: local } } }检索返回的AggregateSearchResult聚合了四类结果chunk_search_results分块命中、graph_search_results图谱命中、web_search_results联网命中、context_document_results上下文文档每条结果包含匹配文本、文档 ID 与相关性分数。七、RAGRetrieval-Augmented GenerationRAG 端点在检索的基础上叠加 LLM 生成产出带引用来源的答案。Pythonclient.retrieval.rag( queryWhat is DeepSeek R1?, )JavaScriptclient.retrieval.rag({ query: What is DeepSeek R1?, })cURLcurl -X POST http://localhost:7272/v3/retrieval/rag \ -H Content-Type: application/json \ -d { query: What is DeepSeek R1? }示例输出RAGResponse( generated_answerDeepSeek-R1 is a model that demonstrates impressive performance across various tasks, leveraging reinforcement learning (RL) and supervised fine-tuning (SFT) to enhance its capabilities..., search_resultsAggregateSearchResult(...), citations[Citation(idcit_3a35e39, objectcitation, ...)], metadata{...} )7.1 生成配置详解rag端点支持通过rag_generation_config微调生成行为retrieval_router.py{ rag_generation_config: { model: openai/gpt-4.1-mini, temperature: 0.7, max_tokens: 1500, stream: true } }model使用的模型。若不指定服务端默认使用配置中的quality_llmretrieval_router.py。服务端支持 OpenAI、Anthropic Claude、Ollama 本地模型以及任何 LiteLLM 支持的提供商对应 py/core/providers/llm 下的多厂商实现temperature控制随机性0-1max_tokens最大输出长度stream是否开启流式输出。此外rag端点还支持task_prompt自定义提示词覆盖默认、include_title_if_available可用时将文档标题并入 LLM 上下文、include_web_search将联网搜索结果提供给 LLM。默认的 RAG 提示词模板可在 py/core/providers/database/prompts/rag.yaml 中查看。八、Streaming RAG流式事件驱动当rag_generation_config中设置stream: True时服务端以 Server-Sent EventsSSE逐段推送事件客户端 SDK 会将原始 SSE 行解析为类型化事件对象。Python SDK 的流式解析逻辑位于 py/sdk/asnyc_methods/retrieval.pyrag方法中根据stream分支返回异步生成器同步客户端的 SSE 解析按event:/data:字段累积多行事件见 py/sdk/sync_client.py。Pythonfrom r2r import ( CitationEvent, FinalAnswerEvent, MessageEvent, SearchResultsEvent, R2RClient, ) result_stream client.retrieval.rag( queryWhat is DeepSeek R1?, search_settings{limit: 25}, rag_generation_config{stream: True}, ) # 也可以按事件类型字段type做 switch 分发 for event in result_stream: if isinstance(event, SearchResultsEvent): print(Search results:, event.data) elif isinstance(event, MessageEvent): print(Partial message:, event.data.delta) elif isinstance(event, CitationEvent): print(New citation detected:, event.data) elif isinstance(event, FinalAnswerEvent): print(Final answer:, event.data.generated_answer)JavaScript// 1) 发起流式 RAG 请求 const resultStream await client.retrieval.rag({ query: What is DeepSeek R1?, searchSettings: { limit: 25 }, ragGenerationConfig: { stream: true }, }); // 2) 判断返回的是异步迭代器流式 if (Symbol.asyncIterator in resultStream) { // 2a) 逐事件消费服务端推送 for await (const event of resultStream) { switch (event.event) { case search_results: console.log(Search results:, event.data); break; case message: console.log(Partial message delta:, event.data.delta); break; case citation: console.log(New citation event:, event.data); break; case final_answer: console.log(Final answer:, event.data.generated_answer); break; default: console.log(Unknown or unhandled event:, event); } } } else { // 2b) 未开启流式或服务端未走 SSE 时返回单个响应对象 console.log(Non-streaming RAG response:, resultStream); }示例输出Search results: idrun_1 objectrag.search_results data{chunk_search_results: [...]} Partial message: {content: [MessageDelta(typetext, text{value: Deep, annotations: []})]} Partial message: {content: [MessageDelta(typetext, text{value: Seek, annotations: []})]} New Citation Detected: cit_3a35e39 Final answer: DeepSeek-R1 is a large language model developed by the DeepSeek-AI research team...流式 RAG 的完整事件类型SearchResultsEvent、MessageEvent、CitationEvent、FinalAnswerEvent以及 Agent 场景新增的ThinkingEvent、ToolCallEvent、ToolResultEvent、UnknownEvent均在 Python SDK 的 py/sdk/models.py 中导出服务端对四类核心事件search_results/message/citation/final_answer的语义描述见 retrieval_router.py。九、Streaming Agentic RAG智能体模式R2R 提供强大的agentic检索模式它不再是一次性检索 生成而是通过迭代式研究与推理对文档做深度分析并可调用多种工具同时调研你的数据和互联网。Pythonfrom r2r import ( ThinkingEvent, ToolCallEvent, ToolResultEvent, CitationEvent, FinalAnswerEvent, MessageEvent, R2RClient, ) results client.retrieval.agent( message{role: user, content: What does deepseek r1 imply for the future of AI?}, rag_generation_config{ model: anthropic/claude-3-7-sonnet-20250219, extended_thinking: True, thinking_budget: 4096, temperature: 1, top_p: None, max_tokens_to_sample: 16000, stream: True }, ) # 处理流式事件 for event in results: if isinstance(event, ThinkingEvent): print(f Thinking: {event.data.delta.content[0].payload.value}) elif isinstance(event, ToolCallEvent): print(f Tool call: {event.data.name}({event.data.arguments})) elif isinstance(event, ToolResultEvent): print(f Tool result: {event.data.content[:60]}...) elif isinstance(event, CitationEvent): print(f Citation: {event.data}) elif isinstance(event, MessageEvent): print(f Message: {event.data.delta.content[0].payload.value}) elif isinstance(event, FinalAnswerEvent): print(f✅ Final answer: {event.data.generated_answer[:100]}...) print(f Citations: {len(event.data.citations)} sources referenced)JavaScriptconst resultStream await client.retrieval.agent({ message: {role: user, content: What does deepseek r1 imply for the future of AI?}, generationConfig: { stream: true } }); // 处理流式事件 if (Symbol.asyncIterator in resultStream) { for await (const event of resultStream) { switch(event.event) { case thinking: console.log( Thinking: ${event.data.delta.content[0].payload.value}); break; case tool_call: console.log( Tool call: ${event.data.name}(${JSON.stringify(event.data.arguments)})); break; case tool_result: console.log( Tool result: ${event.data.content.substring(0, 60)}...); break; case citation: console.log( Citation event: ${event.data}); break; case message: console.log( Message: ${event.data.delta.content[0].payload.value}); break; case final_answer: console.log(✅ Final answer: ${event.data.generated_answer.substring(0, 100)}...); console.log( Citations: ${event.data.citations.length} sources referenced); break; } } }示例输出 Thinking: Analyzing the query about DeepSeek R1 implications... Tool call: search_file_knowledge({query:DeepSeek R1 capabilities advancements}) Tool result: DeepSeek-R1 is a reasoning-focused LLM that uses reinforcement learning... Thinking: The search provides valuable information about DeepSeek R1s capabilities Tool call: web_search({query:AI reasoning capabilities future development}) Tool result: Advanced reasoning capabilities are considered a key milestone toward... Message: DeepSeek-R1 has several important implications for the future of AI development: Message: 1. **Reinforcement Learning as a Key Approach**: DeepSeek-R1s success demonstrates... ✅ Final answer: DeepSeek-R1 has several important implications for the future of AI development... Citations: 3 sources referenced9.1 两种工作模式与工具集服务端agent端点retrieval_router.py定义了两种模式RAG 模式默认提供快速、基于知识库的应答可选启用以下 RAG 工具rag_tools参数search_file_knowledge对已摄取文档做语义/混合检索search_file_descriptions检索文件级元数据描述get_file_content拉取整篇文档或分块结构web_search调用外部搜索引擎获取最新信息web_scrape抓取并抽取指定网页内容。对应工具的源码实现在 py/core/base/agent/tools/built_in 目录包括web_search.py、web_scrape.py、search_file_knowledge.py、search_file_descriptions.py、get_file_content.py、tavily_search.py等。Research 模式mode: research在 RAG 基础上叠加深度推理能力可用research_tools指定rag复用底层 RAG 智能体做信息检索reasoning调用专门模型做复杂分析推理critique分析对话历史以识别偏见或逻辑谬误python_executor执行 Python 代码做计算分析。服务端会根据模式自动选择默认模型RAG 模式使用quality_llmResearch 模式使用planning_llmretrieval_router.py。Agent 相关的事件流还支持conversation_id实现多轮对话上下文保持第一轮调用后保存返回的conversation_id后续轮次传入即可续接对话若未指定名称系统会自动为会话命名。十、更多进阶能力10.1 知识图谱Knowledge GraphsR2R 具备强大的实体与关系抽取能力系统能自动识别实体、构建实体间关系并从文档集合中生成富知识图谱进而支撑图谱增强检索Graph Search与 GraphRAG 场景。相关知识详见 Knowledge Graphs。抽取产生的实体、关系可通过documents.extract()、documents.list_entities()、documents.list_relationships()等接口管理见 py/sdk/asnyc_methods/documents.py。10.2 用户与集合Users and CollectionsR2R 提供完整的用户认证与管理功能既可开箱即用地实现安全的认证系统也可对接你偏好的认证提供商Collections集合则用于对用户和文档进行细粒度的访问控制与组织。详见User AuthenticationCollections十一、下一步学习路径完成本篇入门实践后可以按官方文档的进阶路线继续深入深入 document ingestion掌握摄取、分块与解析细节系统学习 search and RAG对比不同检索策略尝试高级检索技术如 hybrid search 与 knowledge graphs了解 user authentication 与 collections为你的应用接入多用户与细粒度权限控制。仓库中的对应源码也可作为深度参考服务端各 v3 路由定义于 py/core/main/api/v3检索路由见 retrieval_router.py文档路由见 documents_router.pySDK 方法位于 py/sdk 与 js/sdk/src集成测试用例可在 py/tests/integration 与 js/sdk/tests中找到可作为理解各接口行为的最佳样例。【免费下载链接】R2RSoTA production-ready AI retrieval system. Agentic Retrieval-Augmented Generation (RAG) with a RESTful API.项目地址: https://gitcode.com/GitHub_Trending/r2/R2R创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考