[Feature] Add LightRAG (API) retriever implementation #582
Conversation
Add new LightRAG retriever as an alternative RAG strategy alongside standard and HippoRAG retrievers. This implementation provides another option for retrieval-augmented generation with different performance characteristics. - Add LightRAG retriever implementation in packages/service-vector-store/src/rag/lightrag/ - Update RAG retriever type system to support 'light_rag' type - Integrate LightRAG into RAG service factory with computed ref support - Update documentation links to point to chatluna.chat domain - Remove unused @e2b/code-interpreter dependency from extension-tools - Add WebFetch localhost permission to Claude settings
Summary of ChangesHello @dingyi222666, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This PR primarily adds the LightRAG retriever, a new graph-based RAG strategy, to the system. It includes the full implementation of LightRAG, its integration into the existing RAG type system and service factory, and updates to documentation links for vector databases. Minor changes include removing an unused dependency and updating Claude permissions. Highlights
Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here. You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension. Footnotes
|
|
Note Other AI code review bot(s) detectedCodeRabbit has detected other AI code review bot(s) in this pull request and will avoid duplicating their findings in the review comments. This may lead to a less comprehensive review. Walkthrough此次变更在向量存储包中新增 LightRAG 检索器实现与完整类型定义，扩展 RAG 类型与导出并在 ChatLunaRAGService 中接入创建逻辑；同时调整顶层使用示例文本与安全声明，并在核心/扩展中添加若干中间件与插件接入。 Changes
Sequence Diagram(s)sequenceDiagram
autonumber
participant Caller as 调用方
participant Service as ChatLunaRAGService
participant RAGIndex as rag/index
participant LR as LightRAGRetriever
participant Server as LightRAG Server (HTTP)
rect rgb(245,248,255)
note over Caller,Service: 创建 light_rag 检索器
Caller->>Service: createRAGRetriever(type="light_rag", cfg)
Service->>RAGIndex: 请求 createLightRAGRetriever
RAGIndex->>LR: new LightRAGRetriever(cfg)
LR-->>Service: ComputedRef<Retriever>
Service-->>Caller: 返回检索器引用
end
rect rgb(245,255,245)
note over Caller,LR: 相似度检索流程（懒初始化 + HTTP 查询）
Caller->>LR: similaritySearch(query, k)
LR->>LR: lazy init -> GET /health (若未初始化)
LR->>Server: POST /query/data (query payload)
Server-->>LR: QueryDataResponse (200)
LR-->>Caller: 映射为 Documents（含图谱片段/元数据）
end
Estimated code review effort🎯 4 (Complex) | ⏱️ ~60 minutes Possibly related PRs
Poem
Pre-merge checks and finishing touches❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
✨ Finishing touches
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
dingyi222666
changed the title
![gemini-code-assist[bot]](https://waps.l3s.uni-hannover.de/live/im_/https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This is a great feature addition, introducing the LightRAG retriever. The implementation is well-structured and follows the existing patterns in the codebase. I have a few suggestions to improve performance, consistency, and clarity in the new LightRAGRetriever implementation.
![coderabbitai[bot]](https://waps.l3s.uni-hannover.de/live/im_/https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🧹 Nitpick comments (6)
packages/service-vector-store/src/index.ts (2)
72-74: 文档链接更新看起来合理，但请确认可用性与 i18n 一致性
- 请确认 3 个链接均已发布且可访问，避免用户点击 404。
- 使用提示全部为中文，是否需要在 en-US usage 中同步英文指引？
76-76: 安全声明表述建议更明确当前“可能导致 koishi 环境不安全/不负直接责任”的措辞较笼统。建议说明具体风险点与缓解措施（如编译依赖、系统库、Node 升级影响范围），并将免责声明放入文档而非 usage 弹窗，减少用户困惑。
packages/service-vector-store/src/rag/lightrag/type.ts (1)
12-21: 补充单条文本插入请求类型以对齐实现实现侧使用的是单条插入端点
/documents/text且字段为file_source，而此处仅有批量InsertTextsRequest（file_sources）。为降低歧义，建议新增：export interface InsertTextRequest { text: string file_source?: string }并在注释中标注两个端点的差异与适用场景。
packages/service-vector-store/src/service/rag.ts (1)
61-73: 接入逻辑正确，行为与其他检索器一致新增的 light_rag 分支与既有 hippo_rag/standard 路径一致，计算依赖与类型映射正确。
可选：两处分支（hippo_rag/light_rag）构造配置的样板代码可提取为小工具函数以减少重复。
packages/service-vector-store/src/rag/lightrag/index.ts (2)
177-182: 实体/关系仅附加到首条文档，可能导致调用方遗漏上下文若调用方逐条消费文档，建议将
entities/relationships（以及可选的query_metadata）附加到每条返回文档，或者在返回结构中单独返回一份全局元数据，避免信息丢失。- // Attach entities and relationships to the metadata of the first document - if (returnedDocs.length > 0) { - returnedDocs[0].metadata.entities = result.data.entities - returnedDocs[0].metadata.relationships = result.data.relationships - returnedDocs[0].metadata.query_metadata = result.metadata - } + if (returnedDocs.length > 0) { + for (const d of returnedDocs) { + d.metadata.entities = result.data.entities + d.metadata.relationships = result.data.relationships + d.metadata.query_metadata = result.metadata + } + }
87-121: 批量插入顺序串行，吞吐较低；可选：增加并发上限以提升性能当前逐条 POST 保存了元数据，但在大批量导入时会较慢。建议增加可配置并发（如 4～8）并使用 Promise.allSettled 控制失败不阻塞整体。
是否需要我提交一个带有限流（不引入新依赖）的实现草案？
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
⛔ Files ignored due to path filters (2)
.claude/settings.local.jsonis excluded by!**/*.jsonpackages/extension-tools/package.jsonis excluded by!**/*.json
📒 Files selected for processing (5)
packages/service-vector-store/src/index.ts(1 hunks)packages/service-vector-store/src/rag/index.ts(2 hunks)packages/service-vector-store/src/rag/lightrag/index.ts(1 hunks)packages/service-vector-store/src/rag/lightrag/type.ts(1 hunks)packages/service-vector-store/src/service/rag.ts(2 hunks)
🧰 Additional context used
🧬 Code graph analysis (3)
packages/service-vector-store/src/service/rag.ts (2)
packages/service-vector-store/src/rag/index.ts (3)
RAGRetrieverConfig(20-27)createLightRAGRetriever(15-15)RAGRetrieverInstance(29-37)packages/service-vector-store/src/rag/lightrag/index.ts (1)
createLightRAGRetriever(438-443)
packages/service-vector-store/src/rag/lightrag/index.ts (2)
packages/core/src/utils/request.ts (1)
chatLunaFetch(99-120)packages/service-vector-store/src/rag/lightrag/type.ts (16)
InsertResponse(17-21)QueryRequest(31-47)QueryDataResponse(103-108)DocStatus(5-5)DocumentsRequest(139-145)PaginatedDocsResponse(133-137)DeleteDocRequest(147-150)StatusCountsResponse(152-154)PopularLabel(187-190)KnowledgeGraph(182-185)EntityExistsResponse(200-202)EntityUpdateRequest(157-161)GraphEntity(169-173)DeletionResult(192-198)RelationUpdateRequest(163-167)GraphRelation(175-180)
packages/service-vector-store/src/rag/index.ts (1)
packages/service-vector-store/src/rag/lightrag/index.ts (2)
LightRAGRetrieverConfig(426-433)LightRAGRetriever(39-421)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)
- GitHub Check: lint
- GitHub Check: build
🔇 Additional comments (1)
packages/service-vector-store/src/rag/index.ts (1)
3-3: 类型与导出扩展合理
- 成功将
light_rag加入公开类型、实例与导出面。- 与 service/rag.ts 泛型分发匹配良好。
Also applies to: 15-17, 18-27, 29-37
…d document insertion Fix service initialization and document insertion logic for LightRAG retriever to ensure proper configuration propagation and batch document processing. - Pass config to ChatLunaRAGService to enable proper plugin initialization - Mark ChatLunaRAGService as immediate service for faster initialization - Refactor addDocuments to use batch API instead of sequential single insertions - Simplify baseUrl validation logic in initialize method - Remove unnecessary metadata handling that wasn't supported by the API
Improve type safety across all RAG retriever implementations by adding generic type parameters to BaseRAGRetriever class and adding configurable query mode support for LightRAG. - Add generic type parameter to BaseRAGRetriever for strongly typed config access - Update HippoRAGRetriever, LightRAGRetriever, and StandardRAGRetriever to use typed base class - Add defaultQueryMode configuration option to LightRAGRetrieverConfig - Support mode parameter in similaritySearch options for LightRAG - Remove unnecessary type casting in StandardRAGRetriever initialization
There was a problem hiding this comment.
Actionable comments posted: 1
♻️ Duplicate comments (1)
packages/service-vector-store/src/rag/lightrag/index.ts (1)
67-69: ...
......
Need in Chinese. Example: "**修正 catch 变量类型导致的编译错误**" Explain: TS catch variable is unknown, `error.message` compile error. Provide fix. In diff we show modifications. Ok. But also we might want to produce recommended comment for metadata attached to first doc? Should we? The existing comment referencing previously. Should we add? It's optional but we might mention. But we must ensure we avoid duplication: There is existing comment (Gemini) complaining about metadata attached to first doc. They recommended to attach to all or doc comment. Should we re-raise? It's still unresolved. Maybe we should to show we noticed. For instructions: If we generate new comment similar to past review comment, we must tag with . But we can also provide new reasoning maybe more precise? But to avoid conflict we can maybe escalate even more? previous comment from gemini flagged as medium. Since not resolved, we can mention? In our review we can mention we agree with previous comment? But to avoid duplication we can note referencing existing comment and tag . But we only produce new comments when necessary. We can maybe mention: "I agree with previous feedback" and supply but instructions? The instructions mention if you generate comment similar to past comment, tag . That may be appropriate to show we support? Do we need to? Not necessary if we don't comment. Focus on ensuring we have at least the critical comment. But we also need to abide by instructions: Comments must be in Chinese (zh-CN). Should we mention glimpsed for the fix. Provide diff as per instructions. Let's craft comment. Need to record scratchpad. Also we should ensure we mention comment referencing we not referencing other contexts. Let's craft. Need review_comment_start with line ranges. Possible line range: 67-69 (makes sense). Provide comment. In diff propose modifications. Ok. Also we should finish with file_end. Let's craft final response. But before final, update scratchpad for lightrag. Need to note tasks done. Add to scratchpad: highlight bug. Let's update scratchpad accordingly. Need to add to scratchpad to mention we flagged. Then produce comment. Proceed. Update scratchpad block. We'll create scratchpad entry, note issue. Need to ensure scratchpad restful. Let's produce. After comment, mark done. At the end, provide file_end marker. Ok. Let's craft comment in final. Need to produce start marker, comment, end marker. Remember to include diff code block with +/-. (No suggestion identifier). Provide recommended fix. Also include short explanation. Let's craft comment:
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (3)
packages/service-vector-store/src/index.ts(2 hunks)packages/service-vector-store/src/rag/lightrag/index.ts(1 hunks)packages/service-vector-store/src/service/rag.ts(3 hunks)
🧰 Additional context used
🧬 Code graph analysis (3)
packages/service-vector-store/src/rag/lightrag/index.ts (3)
packages/service-vector-store/src/rag/index.ts (3)
LightRAGRetriever(15-15)LightRAGRetrieverConfig(16-16)createLightRAGRetriever(15-15)packages/core/src/utils/request.ts (1)
chatLunaFetch(99-120)packages/service-vector-store/src/rag/lightrag/type.ts (16)
InsertResponse(17-21)QueryRequest(31-47)QueryDataResponse(103-108)DocStatus(5-5)DocumentsRequest(139-145)PaginatedDocsResponse(133-137)DeleteDocRequest(147-150)StatusCountsResponse(152-154)PopularLabel(187-190)KnowledgeGraph(182-185)EntityExistsResponse(200-202)EntityUpdateRequest(157-161)GraphEntity(169-173)DeletionResult(192-198)RelationUpdateRequest(163-167)GraphRelation(175-180)
packages/service-vector-store/src/service/rag.ts (2)
packages/service-vector-store/src/rag/index.ts (3)
RAGRetrieverConfig(20-27)createLightRAGRetriever(15-15)RAGRetrieverInstance(29-37)packages/service-vector-store/src/rag/lightrag/index.ts (1)
createLightRAGRetriever(427-432)
packages/service-vector-store/src/index.ts (1)
packages/service-vector-store/src/service/rag.ts (1)
ChatLunaRAGService(15-78)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)
- GitHub Check: build
- GitHub Check: lint
…n RAG type definitions Replace 'never' type fallbacks with base RetrieverConfig and BaseRAGRetriever types to improve type system flexibility and allow for future retriever implementations. - Change RAGRetrieverConfig fallback from 'never' to 'RetrieverConfig' - Change RAGRetrieverInstance fallback from 'never' to 'BaseRAGRetriever' - Import BaseRAGRetriever and RetrieverConfig for type definitions
There was a problem hiding this comment.
Actionable comments posted: 0
♻️ Duplicate comments (5)
packages/service-vector-store/src/rag/lightrag/index.ts (5)
291-328: 重构：避免使用 await + .then() 混合模式在 lines 303、316、327 等多处使用了
await与.then()的混合模式，这种写法不常见且降低了代码可读性。建议统一使用
await模式：async getGraphLabels(): Promise<string[]> { if (!this._initialized) await this.initialize() const response = await chatLunaFetch( `${this._baseUrl}/graph/label/list`, { headers: this._getHeaders() } ) if (!response.ok) throw new Error( `Failed to get graph labels: ${response.statusText}` ) - return response.json().then((labels: string[]) => labels) + return (await response.json()) as string[] }对
getPopularLabels和searchLabels方法应用类似的重构。
330-408: 重构：统一异步模式并保持一致性在这些图相关方法中（lines 344, 359, 375, 390, 407），同样存在
await + .then()混合模式。为了代码一致性，建议统一使用await模式。示例重构（适用于所有相关方法）：
async checkEntityExists(name: string): Promise<boolean> { if (!this._initialized) await this.initialize() const response = await chatLunaFetch( `${this._baseUrl}/graph/entity/exists?name=${encodeURIComponent(name)}`, { headers: this._getHeaders() } ) if (!response.ok) throw new Error( `Failed to check entity existence: ${response.statusText}` ) - const result = await response - .json() - .then((data) => data as EntityExistsResponse) + const result = (await response.json()) as EntityExistsResponse return result.exists }
418-425: 考虑移除未使用的 llm 属性或添加说明配置接口中定义了
llm属性，但在LightRAGRetriever类中并未使用。这可能会让开发者在配置检索器时感到困惑。如果该属性计划用于未来功能，请添加注释说明其用途。否则，应将其移除以避免混淆。
50-74: 修复错误处理中的类型问题在 TypeScript 中，
catch变量的类型是unknown，直接访问error.message会导致编译错误。应用此差异修复类型问题：
} catch (error) { - throw new Error( - `Failed to connect to LightRAG server: ${error.message}` - ) + const message = error instanceof Error ? error.message : String(error) + throw new Error( + `Failed to connect to LightRAG server: ${message}` + ) }
115-177: 图数据仅附加到第一个文档，设计不一致在 lines 169-174，实体和关系数据仅附加到返回的第一个文档的 metadata 中。这使得第一个文档的结构与其他文档不同，可能会让使用此方法的开发者感到困惑和容易出错。
由于更改返回类型
Promise<Document[]>会破坏BaseRAGRetriever的契约，请考虑以下改进方案之一：
- 一致性：将元数据附加到所有返回的文档，使它们的结构保持一致。
- 清晰的文档说明：如果附加到所有文档过于冗余，请在
similaritySearch方法上添加详细的 JSDoc 注释，明确警告使用者这种特殊行为以及如何从第一个文档访问额外数据。
🧹 Nitpick comments (2)
packages/service-vector-store/src/rag/standard/index.ts (1)
89-89: 移除不必要的类型断言由于类已经使用了泛型参数
BaseRAGRetriever<StandardRAGRetrieverConfig>，this.config的类型已经是StandardRAGRetrieverConfig，不需要再进行类型断言。应用此差异移除类型断言：
- const config = this.config as StandardRAGRetrieverConfig + const config = this.configpackages/service-vector-store/src/rag/lightrag/index.ts (1)
418-425: 建议添加请求超时配置所有网络请求（如
initialize、addDocuments、similaritySearch等）都缺少超时控制。遇到网络抖动或后端无响应时，请求会无限期挂起，影响用户体验和资源占用。建议在配置接口中添加超时选项：
export interface LightRAGRetrieverConfig extends RetrieverConfig { /** Base URL of the LightRAG server */ baseUrl?: string /** API Key for the LightRAG server */ apiKey?: string defaultQueryMode?: QueryMode + /** Request timeout in milliseconds (default: 15000) */ + requestTimeoutMs?: number llm?: ChatLunaChatModel }然后在发起请求时使用超时控制：
const timeout = this.config.requestTimeoutMs ?? 15000 const response = await chatLunaFetch(`${this._baseUrl}/health`, { headers: this._getHeaders(), signal: AbortSignal.timeout(timeout) })将此模式应用于文件中的所有
chatLunaFetch调用。
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (4)
packages/service-vector-store/src/rag/base.ts(1 hunks)packages/service-vector-store/src/rag/hipporag/index.ts(1 hunks)packages/service-vector-store/src/rag/lightrag/index.ts(1 hunks)packages/service-vector-store/src/rag/standard/index.ts(2 hunks)
🧰 Additional context used
🧬 Code graph analysis (3)
packages/service-vector-store/src/rag/base.ts (1)
packages/core/src/llm-core/platform/client.ts (1)
config(91-93)
packages/service-vector-store/src/rag/standard/index.ts (1)
packages/core/src/llm-core/platform/client.ts (1)
config(91-93)
packages/service-vector-store/src/rag/lightrag/index.ts (3)
packages/core/src/utils/request.ts (1)
chatLunaFetch(99-120)packages/service-vector-store/src/rag/base.ts (6)
AddDocumentsOptions(113-121)SearchOptions(126-131)ListDocumentsOptions(136-148)DeleteDocumentsOptions(153-158)RetrieverStats(163-175)RetrieverConfig(96-108)packages/service-vector-store/src/rag/lightrag/type.ts (17)
InsertResponse(17-21)QueryMode(23-29)QueryRequest(31-47)QueryDataResponse(103-108)DocStatus(5-5)DocumentsRequest(139-145)PaginatedDocsResponse(133-137)DeleteDocRequest(147-150)StatusCountsResponse(152-154)PopularLabel(187-190)KnowledgeGraph(182-185)EntityExistsResponse(200-202)EntityUpdateRequest(157-161)GraphEntity(169-173)DeletionResult(192-198)RelationUpdateRequest(163-167)GraphRelation(175-180)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)
- GitHub Check: lint
- GitHub Check: build
🔇 Additional comments (7)
packages/service-vector-store/src/rag/base.ts (1)
13-22: LGTM！泛型设计良好引入泛型参数
T extends RetrieverConfig使得子类可以拥有类型安全的配置对象，同时默认类型参数确保了向后兼容性。这为 LightRAG 和其他检索器的强类型配置奠定了基础。packages/service-vector-store/src/rag/hipporag/index.ts (1)
18-18: LGTM！与泛型模式保持一致类签名正确更新为使用泛型参数
BaseRAGRetriever<HippoRAGRetrieverConfig>，与StandardRAGRetriever和新的LightRAGRetriever保持一致。packages/service-vector-store/src/rag/lightrag/index.ts (5)
44-48: LGTM！构造函数实现正确构造函数正确初始化了基础 URL 和 API 密钥，提供了合理的默认值
http://localhost:9621。
86-113: LGTM！批量添加文档的实现使用批量端点添加文档是正确的方法，相比逐个添加文档可以显著提高性能。
179-223: LGTM！文档列表功能实现正确正确实现了分页、过滤和排序功能，并将 API 响应转换为
Document对象。
225-257: LGTM！文档删除功能实现正确正确处理了全部删除和按 ID 删除两种场景，错误处理也很完善。
259-288: LGTM！统计信息获取实现正确正确聚合了不同状态的文档计数，并返回了符合
RetrieverStats接口的统计信息。
…rsion Reorganize middleware imports for better readability and register missing prompt_variable plugin in long-memory extension. Bump service-vector-store to alpha.1 for LightRAG release. - Reorder middleware imports to group preset-related middlewares together - Register prompt_varaiable plugin in extension-long-memory - Bump service-vector-store version from 1.3.0-alpha.0 to 1.3.0-alpha.1
There was a problem hiding this comment.
Actionable comments posted: 2
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
⛔ Files ignored due to path filters (1)
packages/service-vector-store/package.jsonis excluded by!**/*.json
📒 Files selected for processing (3)
packages/core/src/middleware.ts(2 hunks)packages/extension-long-memory/src/plugin.ts(2 hunks)packages/service-vector-store/src/rag/index.ts(2 hunks)
🚧 Files skipped from review as they are similar to previous changes (1)
- packages/service-vector-store/src/rag/index.ts
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (2)
- GitHub Check: build
- GitHub Check: lint
🔇 Additional comments (2)
packages/core/src/middleware.ts (2)
33-37: 预设中间件导入正确。新增的五个预设相关中间件导入遵循了现有模式，代码结构清晰。
97-101: 中间件注册已验证并通过
所有预设中间件文件存在且正确导出 apply 函数，注册列表中无重复项。
This PR adds LightRAG as a new RAG (Retrieval-Augmented Generation) retriever implementation, expanding the available RAG strategies beyond the existing standard and HippoRAG retrievers.
New Features
Other Changes
@e2b/code-interpreterdependency from extension-tools packageTechnical Details
The LightRAG implementation follows the same pattern as existing retrievers:
packages/service-vector-store/src/rag/lightrag/index.ts(443 lines)packages/service-vector-store/src/rag/lightrag/type.ts(202 lines)src/service/rag.ts